1 /* keyutils.h: key utility library interface
3 * Copyright (C) 2005,2011 Red Hat, Inc. All Rights Reserved.
4 * Written by David Howells (dhowells@redhat.com)
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.
17 /* key serial number */
18 typedef int32_t key_serial_t;
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 */
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
39 /* key handle permissions mask */
40 typedef uint32_t key_perm_t;
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
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
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
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
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 */
100 extern key_serial_t add_key(const char *type,
101 const char *description,
104 key_serial_t ringid);
106 extern key_serial_t request_key(const char *type,
107 const char *description,
108 const char *callout_info,
109 key_serial_t destringid);
111 extern long keyctl(int cmd, ...);
114 * keyctl function wrappers
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,
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,
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);
144 extern long keyctl_instantiate_iov(key_serial_t id,
145 const struct iovec *payload_iov,
147 key_serial_t ringid);
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);
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);
161 #endif /* KEYUTILS_H */