Branch data Line data Source code
1 : : /* Authentication token and access key management
2 : : *
3 : : * Copyright (C) 2004, 2007 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 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 : : * See Documentation/security/keys.txt for information on keys/keyrings.
13 : : */
14 : :
15 : : #ifndef _LINUX_KEY_H
16 : : #define _LINUX_KEY_H
17 : :
18 : : #include <linux/types.h>
19 : : #include <linux/list.h>
20 : : #include <linux/rbtree.h>
21 : : #include <linux/rcupdate.h>
22 : : #include <linux/sysctl.h>
23 : : #include <linux/rwsem.h>
24 : : #include <linux/atomic.h>
25 : : #include <linux/assoc_array.h>
26 : :
27 : : #ifdef __KERNEL__
28 : : #include <linux/uidgid.h>
29 : :
30 : : /* key handle serial number */
31 : : typedef int32_t key_serial_t;
32 : :
33 : : /* key handle permissions mask */
34 : : typedef uint32_t key_perm_t;
35 : :
36 : : struct key;
37 : :
38 : : #ifdef CONFIG_KEYS
39 : :
40 : : #undef KEY_DEBUGGING
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 0x00000020
72 : : #define KEY_OTH_ALL 0x0000003f
73 : :
74 : : #define KEY_PERM_UNDEF 0xffffffff
75 : :
76 : : struct seq_file;
77 : : struct user_struct;
78 : : struct signal_struct;
79 : : struct cred;
80 : :
81 : : struct key_type;
82 : : struct key_owner;
83 : : struct keyring_list;
84 : : struct keyring_name;
85 : :
86 : : struct keyring_index_key {
87 : : struct key_type *type;
88 : : const char *description;
89 : : size_t desc_len;
90 : : };
91 : :
92 : : /*****************************************************************************/
93 : : /*
94 : : * key reference with possession attribute handling
95 : : *
96 : : * NOTE! key_ref_t is a typedef'd pointer to a type that is not actually
97 : : * defined. This is because we abuse the bottom bit of the reference to carry a
98 : : * flag to indicate whether the calling process possesses that key in one of
99 : : * its keyrings.
100 : : *
101 : : * the key_ref_t has been made a separate type so that the compiler can reject
102 : : * attempts to dereference it without proper conversion.
103 : : *
104 : : * the three functions are used to assemble and disassemble references
105 : : */
106 : : typedef struct __key_reference_with_attributes *key_ref_t;
107 : :
108 : : static inline key_ref_t make_key_ref(const struct key *key,
109 : : bool possession)
110 : : {
111 : 3 : return (key_ref_t) ((unsigned long) key | possession);
112 : : }
113 : :
114 : : static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)
115 : : {
116 : 10 : return (struct key *) ((unsigned long) key_ref & ~1UL);
117 : : }
118 : :
119 : : static inline bool is_key_possessed(const key_ref_t key_ref)
120 : : {
121 : 5 : return (unsigned long) key_ref & 1UL;
122 : : }
123 : :
124 : : /*****************************************************************************/
125 : : /*
126 : : * authentication token / access credential / keyring
127 : : * - types of key include:
128 : : * - keyrings
129 : : * - disk encryption IDs
130 : : * - Kerberos TGTs and tickets
131 : : */
132 : : struct key {
133 : : atomic_t usage; /* number of references */
134 : : key_serial_t serial; /* key serial number */
135 : : union {
136 : : struct list_head graveyard_link;
137 : : struct rb_node serial_node;
138 : : };
139 : : struct rw_semaphore sem; /* change vs change sem */
140 : : struct key_user *user; /* owner of this key */
141 : : void *security; /* security data for this key */
142 : : union {
143 : : time_t expiry; /* time at which key expires (or 0) */
144 : : time_t revoked_at; /* time at which key was revoked */
145 : : };
146 : : time_t last_used_at; /* last time used for LRU keyring discard */
147 : : kuid_t uid;
148 : : kgid_t gid;
149 : : key_perm_t perm; /* access permissions */
150 : : unsigned short quotalen; /* length added to quota */
151 : : unsigned short datalen; /* payload data length
152 : : * - may not match RCU dereferenced payload
153 : : * - payload should contain own length
154 : : */
155 : :
156 : : #ifdef KEY_DEBUGGING
157 : : unsigned magic;
158 : : #define KEY_DEBUG_MAGIC 0x18273645u
159 : : #define KEY_DEBUG_MAGIC_X 0xf8e9dacbu
160 : : #endif
161 : :
162 : : unsigned long flags; /* status flags (change with bitops) */
163 : : #define KEY_FLAG_INSTANTIATED 0 /* set if key has been instantiated */
164 : : #define KEY_FLAG_DEAD 1 /* set if key type has been deleted */
165 : : #define KEY_FLAG_REVOKED 2 /* set if key had been revoked */
166 : : #define KEY_FLAG_IN_QUOTA 3 /* set if key consumes quota */
167 : : #define KEY_FLAG_USER_CONSTRUCT 4 /* set if key is being constructed in userspace */
168 : : #define KEY_FLAG_NEGATIVE 5 /* set if key is negative */
169 : : #define KEY_FLAG_ROOT_CAN_CLEAR 6 /* set if key can be cleared by root without permission */
170 : : #define KEY_FLAG_INVALIDATED 7 /* set if key has been invalidated */
171 : : #define KEY_FLAG_TRUSTED 8 /* set if key is trusted */
172 : : #define KEY_FLAG_TRUSTED_ONLY 9 /* set if keyring only accepts links to trusted keys */
173 : :
174 : : /* the key type and key description string
175 : : * - the desc is used to match a key against search criteria
176 : : * - it should be a printable string
177 : : * - eg: for krb5 AFS, this might be "afs@REDHAT.COM"
178 : : */
179 : : union {
180 : : struct keyring_index_key index_key;
181 : : struct {
182 : : struct key_type *type; /* type of key */
183 : : char *description;
184 : : };
185 : : };
186 : :
187 : : /* type specific data
188 : : * - this is used by the keyring type to index the name
189 : : */
190 : : union {
191 : : struct list_head link;
192 : : unsigned long x[2];
193 : : void *p[2];
194 : : int reject_error;
195 : : } type_data;
196 : :
197 : : /* key data
198 : : * - this is used to hold the data actually used in cryptography or
199 : : * whatever
200 : : */
201 : : union {
202 : : union {
203 : : unsigned long value;
204 : : void __rcu *rcudata;
205 : : void *data;
206 : : void *data2[2];
207 : : } payload;
208 : : struct assoc_array keys;
209 : : };
210 : : };
211 : :
212 : : extern struct key *key_alloc(struct key_type *type,
213 : : const char *desc,
214 : : kuid_t uid, kgid_t gid,
215 : : const struct cred *cred,
216 : : key_perm_t perm,
217 : : unsigned long flags);
218 : :
219 : :
220 : : #define KEY_ALLOC_IN_QUOTA 0x0000 /* add to quota, reject if would overrun */
221 : : #define KEY_ALLOC_QUOTA_OVERRUN 0x0001 /* add to quota, permit even if overrun */
222 : : #define KEY_ALLOC_NOT_IN_QUOTA 0x0002 /* not in quota */
223 : : #define KEY_ALLOC_TRUSTED 0x0004 /* Key should be flagged as trusted */
224 : :
225 : : extern void key_revoke(struct key *key);
226 : : extern void key_invalidate(struct key *key);
227 : : extern void key_put(struct key *key);
228 : :
229 : : static inline struct key *__key_get(struct key *key)
230 : : {
231 : 3 : atomic_inc(&key->usage);
232 : : return key;
233 : : }
234 : :
235 : : static inline struct key *key_get(struct key *key)
236 : : {
237 [ # # ][ - + ]: 3496657 : return key ? __key_get(key) : key;
[ - + ][ - + ]
[ - + ][ # # ]
[ # # ]
[ # # # # ]
[ # # ][ # # ]
[ # # ][ # # ]
[ # # ]
238 : : }
239 : :
240 : : static inline void key_ref_put(key_ref_t key_ref)
241 : : {
242 : 2 : key_put(key_ref_to_ptr(key_ref));
243 : : }
244 : :
245 : : extern struct key *request_key(struct key_type *type,
246 : : const char *description,
247 : : const char *callout_info);
248 : :
249 : : extern struct key *request_key_with_auxdata(struct key_type *type,
250 : : const char *description,
251 : : const void *callout_info,
252 : : size_t callout_len,
253 : : void *aux);
254 : :
255 : : extern struct key *request_key_async(struct key_type *type,
256 : : const char *description,
257 : : const void *callout_info,
258 : : size_t callout_len);
259 : :
260 : : extern struct key *request_key_async_with_auxdata(struct key_type *type,
261 : : const char *description,
262 : : const void *callout_info,
263 : : size_t callout_len,
264 : : void *aux);
265 : :
266 : : extern int wait_for_key_construction(struct key *key, bool intr);
267 : :
268 : : extern int key_validate(const struct key *key);
269 : :
270 : : extern key_ref_t key_create_or_update(key_ref_t keyring,
271 : : const char *type,
272 : : const char *description,
273 : : const void *payload,
274 : : size_t plen,
275 : : key_perm_t perm,
276 : : unsigned long flags);
277 : :
278 : : extern int key_update(key_ref_t key,
279 : : const void *payload,
280 : : size_t plen);
281 : :
282 : : extern int key_link(struct key *keyring,
283 : : struct key *key);
284 : :
285 : : extern int key_unlink(struct key *keyring,
286 : : struct key *key);
287 : :
288 : : extern struct key *keyring_alloc(const char *description, kuid_t uid, kgid_t gid,
289 : : const struct cred *cred,
290 : : key_perm_t perm,
291 : : unsigned long flags,
292 : : struct key *dest);
293 : :
294 : : extern int keyring_clear(struct key *keyring);
295 : :
296 : : extern key_ref_t keyring_search(key_ref_t keyring,
297 : : struct key_type *type,
298 : : const char *description);
299 : :
300 : : extern int keyring_add_key(struct key *keyring,
301 : : struct key *key);
302 : :
303 : : extern struct key *key_lookup(key_serial_t id);
304 : :
305 : : static inline key_serial_t key_serial(const struct key *key)
306 : : {
307 : : return key ? key->serial : 0;
308 : : }
309 : :
310 : : extern void key_set_timeout(struct key *, unsigned);
311 : :
312 : : /**
313 : : * key_is_instantiated - Determine if a key has been positively instantiated
314 : : * @key: The key to check.
315 : : *
316 : : * Return true if the specified key has been positively instantiated, false
317 : : * otherwise.
318 : : */
319 : : static inline bool key_is_instantiated(const struct key *key)
320 : : {
321 [ # # ][ # # ]: 0 : return test_bit(KEY_FLAG_INSTANTIATED, &key->flags) &&
[ # # ][ # # ]
322 : : !test_bit(KEY_FLAG_NEGATIVE, &key->flags);
323 : : }
324 : :
325 : : #define rcu_dereference_key(KEY) \
326 : : (rcu_dereference_protected((KEY)->payload.rcudata, \
327 : : rwsem_is_locked(&((struct key *)(KEY))->sem)))
328 : :
329 : : #define rcu_assign_keypointer(KEY, PAYLOAD) \
330 : : do { \
331 : : rcu_assign_pointer((KEY)->payload.rcudata, (PAYLOAD)); \
332 : : } while (0)
333 : :
334 : : #ifdef CONFIG_SYSCTL
335 : : extern ctl_table key_sysctls[];
336 : : #endif
337 : : /*
338 : : * the userspace interface
339 : : */
340 : : extern int install_thread_keyring_to_cred(struct cred *cred);
341 : : extern void key_fsuid_changed(struct task_struct *tsk);
342 : : extern void key_fsgid_changed(struct task_struct *tsk);
343 : : extern void key_init(void);
344 : :
345 : : #else /* CONFIG_KEYS */
346 : :
347 : : #define key_validate(k) 0
348 : : #define key_serial(k) 0
349 : : #define key_get(k) ({ NULL; })
350 : : #define key_revoke(k) do { } while(0)
351 : : #define key_invalidate(k) do { } while(0)
352 : : #define key_put(k) do { } while(0)
353 : : #define key_ref_put(k) do { } while(0)
354 : : #define make_key_ref(k, p) NULL
355 : : #define key_ref_to_ptr(k) NULL
356 : : #define is_key_possessed(k) 0
357 : : #define key_fsuid_changed(t) do { } while(0)
358 : : #define key_fsgid_changed(t) do { } while(0)
359 : : #define key_init() do { } while(0)
360 : :
361 : : #endif /* CONFIG_KEYS */
362 : : #endif /* __KERNEL__ */
363 : : #endif /* _LINUX_KEY_H */
|
