Branch data Line data Source code
1 : : /* SPDX-License-Identifier: GPL-2.0-or-later */
2 : : /* Authentication token and access key management
3 : : *
4 : : * Copyright (C) 2004, 2007 Red Hat, Inc. All Rights Reserved.
5 : : * Written by David Howells (dhowells@redhat.com)
6 : : *
7 : : * See Documentation/security/keys/core.rst for information on keys/keyrings.
8 : : */
9 : :
10 : : #ifndef _LINUX_KEY_H
11 : : #define _LINUX_KEY_H
12 : :
13 : : #include <linux/types.h>
14 : : #include <linux/list.h>
15 : : #include <linux/rbtree.h>
16 : : #include <linux/rcupdate.h>
17 : : #include <linux/sysctl.h>
18 : : #include <linux/rwsem.h>
19 : : #include <linux/atomic.h>
20 : : #include <linux/assoc_array.h>
21 : : #include <linux/refcount.h>
22 : : #include <linux/time64.h>
23 : :
24 : : #ifdef __KERNEL__
25 : : #include <linux/uidgid.h>
26 : :
27 : : /* key handle serial number */
28 : : typedef int32_t key_serial_t;
29 : :
30 : : /* key handle permissions mask */
31 : : typedef uint32_t key_perm_t;
32 : :
33 : : struct key;
34 : : struct net;
35 : :
36 : : #ifdef CONFIG_KEYS
37 : :
38 : : #undef KEY_DEBUGGING
39 : :
40 : : #define KEY_POS_VIEW 0x01000000 /* possessor can view a key's attributes */
41 : : #define KEY_POS_READ 0x02000000 /* possessor can read key payload / view keyring */
42 : : #define KEY_POS_WRITE 0x04000000 /* possessor can update key payload / add link to keyring */
43 : : #define KEY_POS_SEARCH 0x08000000 /* possessor can find a key in search / search a keyring */
44 : : #define KEY_POS_LINK 0x10000000 /* possessor can create a link to a key/keyring */
45 : : #define KEY_POS_SETATTR 0x20000000 /* possessor can set key attributes */
46 : : #define KEY_POS_ALL 0x3f000000
47 : :
48 : : #define KEY_USR_VIEW 0x00010000 /* user permissions... */
49 : : #define KEY_USR_READ 0x00020000
50 : : #define KEY_USR_WRITE 0x00040000
51 : : #define KEY_USR_SEARCH 0x00080000
52 : : #define KEY_USR_LINK 0x00100000
53 : : #define KEY_USR_SETATTR 0x00200000
54 : : #define KEY_USR_ALL 0x003f0000
55 : :
56 : : #define KEY_GRP_VIEW 0x00000100 /* group permissions... */
57 : : #define KEY_GRP_READ 0x00000200
58 : : #define KEY_GRP_WRITE 0x00000400
59 : : #define KEY_GRP_SEARCH 0x00000800
60 : : #define KEY_GRP_LINK 0x00001000
61 : : #define KEY_GRP_SETATTR 0x00002000
62 : : #define KEY_GRP_ALL 0x00003f00
63 : :
64 : : #define KEY_OTH_VIEW 0x00000001 /* third party permissions... */
65 : : #define KEY_OTH_READ 0x00000002
66 : : #define KEY_OTH_WRITE 0x00000004
67 : : #define KEY_OTH_SEARCH 0x00000008
68 : : #define KEY_OTH_LINK 0x00000010
69 : : #define KEY_OTH_SETATTR 0x00000020
70 : : #define KEY_OTH_ALL 0x0000003f
71 : :
72 : : #define KEY_PERM_UNDEF 0xffffffff
73 : :
74 : : struct seq_file;
75 : : struct user_struct;
76 : : struct signal_struct;
77 : : struct cred;
78 : :
79 : : struct key_type;
80 : : struct key_owner;
81 : : struct key_tag;
82 : : struct keyring_list;
83 : : struct keyring_name;
84 : :
85 : : struct key_tag {
86 : : struct rcu_head rcu;
87 : : refcount_t usage;
88 : : bool removed; /* T when subject removed */
89 : : };
90 : :
91 : : struct keyring_index_key {
92 : : /* [!] If this structure is altered, the union in struct key must change too! */
93 : : unsigned long hash; /* Hash value */
94 : : union {
95 : : struct {
96 : : #ifdef __LITTLE_ENDIAN /* Put desc_len at the LSB of x */
97 : : u16 desc_len;
98 : : char desc[sizeof(long) - 2]; /* First few chars of description */
99 : : #else
100 : : char desc[sizeof(long) - 2]; /* First few chars of description */
101 : : u16 desc_len;
102 : : #endif
103 : : };
104 : : unsigned long x;
105 : : };
106 : : struct key_type *type;
107 : : struct key_tag *domain_tag; /* Domain of operation */
108 : : const char *description;
109 : : };
110 : :
111 : : union key_payload {
112 : : void __rcu *rcu_data0;
113 : : void *data[4];
114 : : };
115 : :
116 : : /*****************************************************************************/
117 : : /*
118 : : * key reference with possession attribute handling
119 : : *
120 : : * NOTE! key_ref_t is a typedef'd pointer to a type that is not actually
121 : : * defined. This is because we abuse the bottom bit of the reference to carry a
122 : : * flag to indicate whether the calling process possesses that key in one of
123 : : * its keyrings.
124 : : *
125 : : * the key_ref_t has been made a separate type so that the compiler can reject
126 : : * attempts to dereference it without proper conversion.
127 : : *
128 : : * the three functions are used to assemble and disassemble references
129 : : */
130 : : typedef struct __key_reference_with_attributes *key_ref_t;
131 : :
132 : 5936 : static inline key_ref_t make_key_ref(const struct key *key,
133 : : bool possession)
134 : : {
135 [ # # ]: 5936 : return (key_ref_t) ((unsigned long) key | possession);
136 : : }
137 : :
138 : 17640 : static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)
139 : : {
140 [ + + + - : 15484 : return (struct key *) ((unsigned long) key_ref & ~1UL);
+ - ]
141 : : }
142 : :
143 : 6776 : static inline bool is_key_possessed(const key_ref_t key_ref)
144 : : {
145 [ + - ]: 6776 : return (unsigned long) key_ref & 1UL;
146 : : }
147 : :
148 : : typedef int (*key_restrict_link_func_t)(struct key *dest_keyring,
149 : : const struct key_type *type,
150 : : const union key_payload *payload,
151 : : struct key *restriction_key);
152 : :
153 : : struct key_restriction {
154 : : key_restrict_link_func_t check;
155 : : struct key *key;
156 : : struct key_type *keytype;
157 : : };
158 : :
159 : : enum key_state {
160 : : KEY_IS_UNINSTANTIATED,
161 : : KEY_IS_POSITIVE, /* Positively instantiated */
162 : : };
163 : :
164 : : /*****************************************************************************/
165 : : /*
166 : : * authentication token / access credential / keyring
167 : : * - types of key include:
168 : : * - keyrings
169 : : * - disk encryption IDs
170 : : * - Kerberos TGTs and tickets
171 : : */
172 : : struct key {
173 : : refcount_t usage; /* number of references */
174 : : key_serial_t serial; /* key serial number */
175 : : union {
176 : : struct list_head graveyard_link;
177 : : struct rb_node serial_node;
178 : : };
179 : : struct rw_semaphore sem; /* change vs change sem */
180 : : struct key_user *user; /* owner of this key */
181 : : void *security; /* security data for this key */
182 : : union {
183 : : time64_t expiry; /* time at which key expires (or 0) */
184 : : time64_t revoked_at; /* time at which key was revoked */
185 : : };
186 : : time64_t last_used_at; /* last time used for LRU keyring discard */
187 : : kuid_t uid;
188 : : kgid_t gid;
189 : : key_perm_t perm; /* access permissions */
190 : : unsigned short quotalen; /* length added to quota */
191 : : unsigned short datalen; /* payload data length
192 : : * - may not match RCU dereferenced payload
193 : : * - payload should contain own length
194 : : */
195 : : short state; /* Key state (+) or rejection error (-) */
196 : :
197 : : #ifdef KEY_DEBUGGING
198 : : unsigned magic;
199 : : #define KEY_DEBUG_MAGIC 0x18273645u
200 : : #endif
201 : :
202 : : unsigned long flags; /* status flags (change with bitops) */
203 : : #define KEY_FLAG_DEAD 0 /* set if key type has been deleted */
204 : : #define KEY_FLAG_REVOKED 1 /* set if key had been revoked */
205 : : #define KEY_FLAG_IN_QUOTA 2 /* set if key consumes quota */
206 : : #define KEY_FLAG_USER_CONSTRUCT 3 /* set if key is being constructed in userspace */
207 : : #define KEY_FLAG_ROOT_CAN_CLEAR 4 /* set if key can be cleared by root without permission */
208 : : #define KEY_FLAG_INVALIDATED 5 /* set if key has been invalidated */
209 : : #define KEY_FLAG_BUILTIN 6 /* set if key is built in to the kernel */
210 : : #define KEY_FLAG_ROOT_CAN_INVAL 7 /* set if key can be invalidated by root without permission */
211 : : #define KEY_FLAG_KEEP 8 /* set if key should not be removed */
212 : : #define KEY_FLAG_UID_KEYRING 9 /* set if key is a user or user session keyring */
213 : :
214 : : /* the key type and key description string
215 : : * - the desc is used to match a key against search criteria
216 : : * - it should be a printable string
217 : : * - eg: for krb5 AFS, this might be "afs@REDHAT.COM"
218 : : */
219 : : union {
220 : : struct keyring_index_key index_key;
221 : : struct {
222 : : unsigned long hash;
223 : : unsigned long len_desc;
224 : : struct key_type *type; /* type of key */
225 : : struct key_tag *domain_tag; /* Domain of operation */
226 : : char *description;
227 : : };
228 : : };
229 : :
230 : : /* key data
231 : : * - this is used to hold the data actually used in cryptography or
232 : : * whatever
233 : : */
234 : : union {
235 : : union key_payload payload;
236 : : struct {
237 : : /* Keyring bits */
238 : : struct list_head name_link;
239 : : struct assoc_array keys;
240 : : };
241 : : };
242 : :
243 : : /* This is set on a keyring to restrict the addition of a link to a key
244 : : * to it. If this structure isn't provided then it is assumed that the
245 : : * keyring is open to any addition. It is ignored for non-keyring
246 : : * keys. Only set this value using keyring_restrict(), keyring_alloc(),
247 : : * or key_alloc().
248 : : *
249 : : * This is intended for use with rings of trusted keys whereby addition
250 : : * to the keyring needs to be controlled. KEY_ALLOC_BYPASS_RESTRICTION
251 : : * overrides this, allowing the kernel to add extra keys without
252 : : * restriction.
253 : : */
254 : : struct key_restriction *restrict_link;
255 : : };
256 : :
257 : : extern struct key *key_alloc(struct key_type *type,
258 : : const char *desc,
259 : : kuid_t uid, kgid_t gid,
260 : : const struct cred *cred,
261 : : key_perm_t perm,
262 : : unsigned long flags,
263 : : struct key_restriction *restrict_link);
264 : :
265 : :
266 : : #define KEY_ALLOC_IN_QUOTA 0x0000 /* add to quota, reject if would overrun */
267 : : #define KEY_ALLOC_QUOTA_OVERRUN 0x0001 /* add to quota, permit even if overrun */
268 : : #define KEY_ALLOC_NOT_IN_QUOTA 0x0002 /* not in quota */
269 : : #define KEY_ALLOC_BUILT_IN 0x0004 /* Key is built into kernel */
270 : : #define KEY_ALLOC_BYPASS_RESTRICTION 0x0008 /* Override the check on restricted keyrings */
271 : : #define KEY_ALLOC_UID_KEYRING 0x0010 /* allocating a user or user session keyring */
272 : :
273 : : extern void key_revoke(struct key *key);
274 : : extern void key_invalidate(struct key *key);
275 : : extern void key_put(struct key *key);
276 : : extern bool key_put_tag(struct key_tag *tag);
277 : : extern void key_remove_domain(struct key_tag *domain_tag);
278 : :
279 : 137393 : static inline struct key *__key_get(struct key *key)
280 : : {
281 : 137393 : refcount_inc(&key->usage);
282 [ + + ]: 137393 : return key;
283 : : }
284 : :
285 : 576784 : static inline struct key *key_get(struct key *key)
286 : : {
287 [ + + - + : 278565 : return key ? __key_get(key) : key;
- + - + #
# ]
288 : : }
289 : :
290 : 1876 : static inline void key_ref_put(key_ref_t key_ref)
291 : : {
292 : 1876 : key_put(key_ref_to_ptr(key_ref));
293 : 1876 : }
294 : :
295 : : extern struct key *request_key_tag(struct key_type *type,
296 : : const char *description,
297 : : struct key_tag *domain_tag,
298 : : const char *callout_info);
299 : :
300 : : extern struct key *request_key_rcu(struct key_type *type,
301 : : const char *description,
302 : : struct key_tag *domain_tag);
303 : :
304 : : extern struct key *request_key_with_auxdata(struct key_type *type,
305 : : const char *description,
306 : : struct key_tag *domain_tag,
307 : : const void *callout_info,
308 : : size_t callout_len,
309 : : void *aux);
310 : :
311 : : /**
312 : : * request_key - Request a key and wait for construction
313 : : * @type: Type of key.
314 : : * @description: The searchable description of the key.
315 : : * @callout_info: The data to pass to the instantiation upcall (or NULL).
316 : : *
317 : : * As for request_key_tag(), but with the default global domain tag.
318 : : */
319 : 0 : static inline struct key *request_key(struct key_type *type,
320 : : const char *description,
321 : : const char *callout_info)
322 : : {
323 : 0 : return request_key_tag(type, description, NULL, callout_info);
324 : : }
325 : :
326 : : #ifdef CONFIG_NET
327 : : /**
328 : : * request_key_net - Request a key for a net namespace and wait for construction
329 : : * @type: Type of key.
330 : : * @description: The searchable description of the key.
331 : : * @net: The network namespace that is the key's domain of operation.
332 : : * @callout_info: The data to pass to the instantiation upcall (or NULL).
333 : : *
334 : : * As for request_key() except that it does not add the returned key to a
335 : : * keyring if found, new keys are always allocated in the user's quota, the
336 : : * callout_info must be a NUL-terminated string and no auxiliary data can be
337 : : * passed. Only keys that operate the specified network namespace are used.
338 : : *
339 : : * Furthermore, it then works as wait_for_key_construction() to wait for the
340 : : * completion of keys undergoing construction with a non-interruptible wait.
341 : : */
342 : : #define request_key_net(type, description, net, callout_info) \
343 : : request_key_tag(type, description, net->key_domain, callout_info);
344 : :
345 : : /**
346 : : * request_key_net_rcu - Request a key for a net namespace under RCU conditions
347 : : * @type: Type of key.
348 : : * @description: The searchable description of the key.
349 : : * @net: The network namespace that is the key's domain of operation.
350 : : *
351 : : * As for request_key_rcu() except that only keys that operate the specified
352 : : * network namespace are used.
353 : : */
354 : : #define request_key_net_rcu(type, description, net) \
355 : : request_key_rcu(type, description, net->key_domain);
356 : : #endif /* CONFIG_NET */
357 : :
358 : : extern int wait_for_key_construction(struct key *key, bool intr);
359 : :
360 : : extern int key_validate(const struct key *key);
361 : :
362 : : extern key_ref_t key_create_or_update(key_ref_t keyring,
363 : : const char *type,
364 : : const char *description,
365 : : const void *payload,
366 : : size_t plen,
367 : : key_perm_t perm,
368 : : unsigned long flags);
369 : :
370 : : extern int key_update(key_ref_t key,
371 : : const void *payload,
372 : : size_t plen);
373 : :
374 : : extern int key_link(struct key *keyring,
375 : : struct key *key);
376 : :
377 : : extern int key_move(struct key *key,
378 : : struct key *from_keyring,
379 : : struct key *to_keyring,
380 : : unsigned int flags);
381 : :
382 : : extern int key_unlink(struct key *keyring,
383 : : struct key *key);
384 : :
385 : : extern struct key *keyring_alloc(const char *description, kuid_t uid, kgid_t gid,
386 : : const struct cred *cred,
387 : : key_perm_t perm,
388 : : unsigned long flags,
389 : : struct key_restriction *restrict_link,
390 : : struct key *dest);
391 : :
392 : : extern int restrict_link_reject(struct key *keyring,
393 : : const struct key_type *type,
394 : : const union key_payload *payload,
395 : : struct key *restriction_key);
396 : :
397 : : extern int keyring_clear(struct key *keyring);
398 : :
399 : : extern key_ref_t keyring_search(key_ref_t keyring,
400 : : struct key_type *type,
401 : : const char *description,
402 : : bool recurse);
403 : :
404 : : extern int keyring_add_key(struct key *keyring,
405 : : struct key *key);
406 : :
407 : : extern int keyring_restrict(key_ref_t keyring, const char *type,
408 : : const char *restriction);
409 : :
410 : : extern struct key *key_lookup(key_serial_t id);
411 : :
412 : 0 : static inline key_serial_t key_serial(const struct key *key)
413 : : {
414 [ # # ]: 0 : return key ? key->serial : 0;
415 : : }
416 : :
417 : : extern void key_set_timeout(struct key *, unsigned);
418 : :
419 : : extern key_ref_t lookup_user_key(key_serial_t id, unsigned long flags,
420 : : key_perm_t perm);
421 : : extern void key_free_user_ns(struct user_namespace *);
422 : :
423 : : /*
424 : : * The permissions required on a key that we're looking up.
425 : : */
426 : : #define KEY_NEED_VIEW 0x01 /* Require permission to view attributes */
427 : : #define KEY_NEED_READ 0x02 /* Require permission to read content */
428 : : #define KEY_NEED_WRITE 0x04 /* Require permission to update / modify */
429 : : #define KEY_NEED_SEARCH 0x08 /* Require permission to search (keyring) or find (key) */
430 : : #define KEY_NEED_LINK 0x10 /* Require permission to link */
431 : : #define KEY_NEED_SETATTR 0x20 /* Require permission to change attributes */
432 : : #define KEY_NEED_ALL 0x3f /* All the above permissions */
433 : :
434 : 2128 : static inline short key_read_state(const struct key *key)
435 : : {
436 : : /* Barrier versus mark_key_instantiated(). */
437 [ + + # # ]: 2128 : return smp_load_acquire(&key->state);
438 : : }
439 : :
440 : : /**
441 : : * key_is_positive - Determine if a key has been positively instantiated
442 : : * @key: The key to check.
443 : : *
444 : : * Return true if the specified key has been positively instantiated, false
445 : : * otherwise.
446 : : */
447 : 0 : static inline bool key_is_positive(const struct key *key)
448 : : {
449 : 0 : return key_read_state(key) == KEY_IS_POSITIVE;
450 : : }
451 : :
452 : : static inline bool key_is_negative(const struct key *key)
453 : : {
454 : : return key_read_state(key) < 0;
455 : : }
456 : :
457 : : #define dereference_key_rcu(KEY) \
458 : : (rcu_dereference((KEY)->payload.rcu_data0))
459 : :
460 : : #define dereference_key_locked(KEY) \
461 : : (rcu_dereference_protected((KEY)->payload.rcu_data0, \
462 : : rwsem_is_locked(&((struct key *)(KEY))->sem)))
463 : :
464 : : #define rcu_assign_keypointer(KEY, PAYLOAD) \
465 : : do { \
466 : : rcu_assign_pointer((KEY)->payload.rcu_data0, (PAYLOAD)); \
467 : : } while (0)
468 : :
469 : : #ifdef CONFIG_SYSCTL
470 : : extern struct ctl_table key_sysctls[];
471 : : #endif
472 : : /*
473 : : * the userspace interface
474 : : */
475 : : extern int install_thread_keyring_to_cred(struct cred *cred);
476 : : extern void key_fsuid_changed(struct cred *new_cred);
477 : : extern void key_fsgid_changed(struct cred *new_cred);
478 : : extern void key_init(void);
479 : :
480 : : #else /* CONFIG_KEYS */
481 : :
482 : : #define key_validate(k) 0
483 : : #define key_serial(k) 0
484 : : #define key_get(k) ({ NULL; })
485 : : #define key_revoke(k) do { } while(0)
486 : : #define key_invalidate(k) do { } while(0)
487 : : #define key_put(k) do { } while(0)
488 : : #define key_ref_put(k) do { } while(0)
489 : : #define make_key_ref(k, p) NULL
490 : : #define key_ref_to_ptr(k) NULL
491 : : #define is_key_possessed(k) 0
492 : : #define key_fsuid_changed(c) do { } while(0)
493 : : #define key_fsgid_changed(c) do { } while(0)
494 : : #define key_init() do { } while(0)
495 : : #define key_free_user_ns(ns) do { } while(0)
496 : : #define key_remove_domain(d) do { } while(0)
497 : :
498 : : #endif /* CONFIG_KEYS */
499 : : #endif /* __KERNEL__ */
500 : : #endif /* _LINUX_KEY_H */
|
