keyutils.h

   1 /* keyutils.h: key utility library interface
   2  *
   3  * Copyright (C) 2005,2011 Red Hat, Inc. All Rights Reserved.
   4  * Written by David Howells (dhowells@redhat.com)
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public License
   8  * as published by the Free Software Foundation; either version
   9  * 2 of the License, or (at your option) any later version.
  10  */
  11
  12 #ifndef KEYUTILS_H
  13 #define KEYUTILS_H
  14
  15 #include <stdint.h>
  16
  17 /* key serial number */
  18 typedef int32_t key_serial_t;
  19
  20 /* special process keyring shortcut IDs */
  21 #define KEY_SPEC_THREAD_KEYRING         -1      /* - key ID for thread-specific keyring */
  22 #define KEY_SPEC_PROCESS_KEYRING        -2      /* - key ID for process-specific keyring */
  23 #define KEY_SPEC_SESSION_KEYRING        -3      /* - key ID for session-specific keyring */
  24 #define KEY_SPEC_USER_KEYRING           -4      /* - key ID for UID-specific keyring */
  25 #define KEY_SPEC_USER_SESSION_KEYRING   -5      /* - key ID for UID-session keyring */
  26 #define KEY_SPEC_GROUP_KEYRING          -6      /* - key ID for GID-specific keyring */
  27 #define KEY_SPEC_REQKEY_AUTH_KEY        -7      /* - key ID for assumed request_key auth key */
  28
  29 /* request-key default keyrings */
  30 #define KEY_REQKEY_DEFL_NO_CHANGE               -1
  31 #define KEY_REQKEY_DEFL_DEFAULT                 0
  32 #define KEY_REQKEY_DEFL_THREAD_KEYRING          1
  33 #define KEY_REQKEY_DEFL_PROCESS_KEYRING         2
  34 #define KEY_REQKEY_DEFL_SESSION_KEYRING         3
  35 #define KEY_REQKEY_DEFL_USER_KEYRING            4
  36 #define KEY_REQKEY_DEFL_USER_SESSION_KEYRING    5
  37 #define KEY_REQKEY_DEFL_GROUP_KEYRING           6
  38
  39 /* key handle permissions mask */
  40 typedef uint32_t key_perm_t;
  41
  42 #define KEY_POS_VIEW    0x01000000      /* possessor can view a key's attributes */
  43 #define KEY_POS_READ    0x02000000      /* possessor can read key payload / view keyring */
  44 #define KEY_POS_WRITE   0x04000000      /* possessor can update key payload / add link to keyring */
  45 #define KEY_POS_SEARCH  0x08000000      /* possessor can find a key in search / search a keyring */
  46 #define KEY_POS_LINK    0x10000000      /* possessor can create a link to a key/keyring */
  47 #define KEY_POS_SETATTR 0x20000000      /* possessor can set key attributes */
  48 #define KEY_POS_ALL     0x3f000000
  49
  50 #define KEY_USR_VIEW    0x00010000      /* user permissions... */
  51 #define KEY_USR_READ    0x00020000
  52 #define KEY_USR_WRITE   0x00040000
  53 #define KEY_USR_SEARCH  0x00080000
  54 #define KEY_USR_LINK    0x00100000
  55 #define KEY_USR_SETATTR 0x00200000
  56 #define KEY_USR_ALL     0x003f0000
  57
  58 #define KEY_GRP_VIEW    0x00000100      /* group permissions... */
  59 #define KEY_GRP_READ    0x00000200
  60 #define KEY_GRP_WRITE   0x00000400
  61 #define KEY_GRP_SEARCH  0x00000800
  62 #define KEY_GRP_LINK    0x00001000
  63 #define KEY_GRP_SETATTR 0x00002000
  64 #define KEY_GRP_ALL     0x00003f00
  65
  66 #define KEY_OTH_VIEW    0x00000001      /* third party permissions... */
  67 #define KEY_OTH_READ    0x00000002
  68 #define KEY_OTH_WRITE   0x00000004
  69 #define KEY_OTH_SEARCH  0x00000008
  70 #define KEY_OTH_LINK    0x00000010
  71 #define KEY_OTH_SETATTR 0x00000010
  72 #define KEY_OTH_ALL     0x0000003f
  73
  74 /* keyctl commands */
  75 #define KEYCTL_GET_KEYRING_ID           0       /* ask for a keyring's ID */
  76 #define KEYCTL_JOIN_SESSION_KEYRING     1       /* join or start named session keyring */
  77 #define KEYCTL_UPDATE                   2       /* update a key */
  78 #define KEYCTL_REVOKE                   3       /* revoke a key */
  79 #define KEYCTL_CHOWN                    4       /* set ownership of a key */
  80 #define KEYCTL_SETPERM                  5       /* set perms on a key */
  81 #define KEYCTL_DESCRIBE                 6       /* describe a key */
  82 #define KEYCTL_CLEAR                    7       /* clear contents of a keyring */
  83 #define KEYCTL_LINK                     8       /* link a key into a keyring */
  84 #define KEYCTL_UNLINK                   9       /* unlink a key from a keyring */
  85 #define KEYCTL_SEARCH                   10      /* search for a key in a keyring */
  86 #define KEYCTL_READ                     11      /* read a key or keyring's contents */
  87 #define KEYCTL_INSTANTIATE              12      /* instantiate a partially constructed key */
  88 #define KEYCTL_NEGATE                   13      /* negate a partially constructed key */
  89 #define KEYCTL_SET_REQKEY_KEYRING       14      /* set default request-key keyring */
  90 #define KEYCTL_SET_TIMEOUT              15      /* set timeout on a key */
  91 #define KEYCTL_ASSUME_AUTHORITY         16      /* assume authority to instantiate key */
  92 #define KEYCTL_GET_SECURITY             17      /* get key security label */
  93 #define KEYCTL_SESSION_TO_PARENT        18      /* set my session keyring on my parent process */
  94 #define KEYCTL_REJECT                   19      /* reject a partially constructed key */
  95 #define KEYCTL_INSTANTIATE_IOV          20      /* instantiate a partially constructed key */
  96
  97 /*
  98  * syscall wrappers
  99  */
 100 extern key_serial_t add_key(const char *type,
 101                             const char *description,
 102                             const void *payload,
 103                             size_t plen,
 104                             key_serial_t ringid);
 105
 106 extern key_serial_t request_key(const char *type,
 107                                 const char *description,
 108                                 const char *callout_info,
 109                                 key_serial_t destringid);
 110
 111 extern long keyctl(int cmd, ...);
 112
 113 /*
 114  * keyctl function wrappers
 115  */
 116 extern key_serial_t keyctl_get_keyring_ID(key_serial_t id, int create);
 117 extern key_serial_t keyctl_join_session_keyring(const char *name);
 118 extern long keyctl_update(key_serial_t id, const void *payload, size_t plen);
 119 extern long keyctl_revoke(key_serial_t id);
 120 extern long keyctl_chown(key_serial_t id, uid_t uid, gid_t gid);
 121 extern long keyctl_setperm(key_serial_t id, key_perm_t perm);
 122 extern long keyctl_describe(key_serial_t id, char *buffer, size_t buflen);
 123 extern long keyctl_clear(key_serial_t ringid);
 124 extern long keyctl_link(key_serial_t id, key_serial_t ringid);
 125 extern long keyctl_unlink(key_serial_t id, key_serial_t ringid);
 126 extern long keyctl_search(key_serial_t ringid,
 127                           const char *type,
 128                           const char *description,
 129                           key_serial_t destringid);
 130 extern long keyctl_read(key_serial_t id, char *buffer, size_t buflen);
 131 extern long keyctl_instantiate(key_serial_t id,
 132                                const void *payload,
 133                                size_t plen,
 134                                key_serial_t ringid);
 135 extern long keyctl_negate(key_serial_t id, unsigned timeout, key_serial_t ringid);
 136 extern long keyctl_set_reqkey_keyring(int reqkey_defl);
 137 extern long keyctl_set_timeout(key_serial_t key, unsigned timeout);
 138 extern long keyctl_assume_authority(key_serial_t key);
 139 extern long keyctl_get_security(key_serial_t key, char *buffer, size_t buflen);
 140 extern long keyctl_session_to_parent(void);
 141 extern long keyctl_reject(key_serial_t id, unsigned timeout, unsigned error,
 142                           key_serial_t ringid);
 143 struct iovec;
 144 extern long keyctl_instantiate_iov(key_serial_t id,
 145                                    const struct iovec *payload_iov,
 146                                    unsigned ioc,
 147                                    key_serial_t ringid);
 148
 149 /*
 150  * utilities
 151  */
 152 extern int keyctl_describe_alloc(key_serial_t id, char **_buffer);
 153 extern int keyctl_read_alloc(key_serial_t id, void **_buffer);
 154 extern int keyctl_get_security_alloc(key_serial_t id, char **_buffer);
 155
 156 typedef int (*recursive_key_scanner_t)(key_serial_t parent, key_serial_t key,
 157                                        char *desc, int desc_len, void *data);
 158 extern int recursive_key_scan(key_serial_t key, recursive_key_scanner_t func, void *data);
 159 extern int recursive_session_key_scan(recursive_key_scanner_t func, void *data);
 160
 161 #endif /* KEYUTILS_H */