2 /* Authentication token and access key management
27 /* key handle serial number */
30 /* key handle permissions mask */
33 struct key;
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 */
75  * The permissions required on a key that we're looking up.
82 	KEY_NEED_SEARCH,	/* Require permission to search (keyring) or find (key) */
85 	KEY_NEED_UNLINK,	/* Require permission to unlink key */
109 	/* [!] If this structure is altered, the union in struct key must change too! */
135  * key reference with possession attribute handling
139  * flag to indicate whether the calling process possesses that key in one of
149 static inline key_ref_t make_key_ref(const struct key *key,  in make_key_ref()  argument
152 	return (key_ref_t) ((unsigned long) key | possession);  in make_key_ref()
155 static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)  in key_ref_to_ptr()
157 	return (struct key *) ((unsigned long) key_ref & ~1UL);  in key_ref_to_ptr()
165 typedef int (*key_restrict_link_func_t)(struct key *dest_keyring,
168 					struct key *restriction_key);
172 	struct key *key;  member
184  * - types of key include:
189 struct key {  struct
191 	key_serial_t		serial;		/* key serial number */  argument
197 	struct watch_list	*watchers;	/* Entities watching this key for changes */  argument
200 	struct key_user		*user;		/* owner of this key */  argument
201 	void			*security;	/* security data for this key */  argument
203 		time64_t	expiry;		/* time at which key expires (or 0) */  argument
204 		time64_t	revoked_at;	/* time at which key was revoked */
215 	short			state;		/* Key state (+) or rejection error (-) */
223 #define KEY_FLAG_DEAD		0	/* set if key type has been deleted */  argument
224 #define KEY_FLAG_REVOKED	1	/* set if key had been revoked */
225 #define KEY_FLAG_IN_QUOTA	2	/* set if key consumes quota */
226 #define KEY_FLAG_USER_CONSTRUCT	3	/* set if key is being constructed in userspace */
227 #define KEY_FLAG_ROOT_CAN_CLEAR	4	/* set if key can be cleared by root without permission */
228 #define KEY_FLAG_INVALIDATED	5	/* set if key has been invalidated */
229 #define KEY_FLAG_BUILTIN	6	/* set if key is built in to the kernel */
230 #define KEY_FLAG_ROOT_CAN_INVAL	7	/* set if key can be invalidated by root without permission */
231 #define KEY_FLAG_KEEP		8	/* set if key should not be removed */
232 #define KEY_FLAG_UID_KEYRING	9	/* set if key is a user or user session keyring */
234 	/* the key type and key description string
235 	 * - the desc is used to match a key against search criteria
244 			struct key_type	*type;		/* type of key */  argument
250 	/* key data
263 	/* This is set on a keyring to restrict the addition of a link to a key  argument
277 extern struct key *key_alloc(struct key_type *type,
289 #define KEY_ALLOC_BUILT_IN		0x0004	/* Key is built into kernel */
293 extern void key_revoke(struct key *key);
294 extern void key_invalidate(struct key *key);
295 extern void key_put(struct key *key);
299 static inline struct key *__key_get(struct key *key)  in __key_get()  argument
301 	refcount_inc(&key->usage);  in __key_get()
302 	return key;  in __key_get()
305 static inline struct key *key_get(struct key *key)  in key_get()  argument
307 	return key ? __key_get(key) : key;  in key_get()
315 extern struct key *request_key_tag(struct key_type *type,
320 extern struct key *request_key_rcu(struct key_type *type,
324 extern struct key *request_key_with_auxdata(struct key_type *type,
332  * request_key - Request a key and wait for construction
333  * @type: Type of key.
334  * @description: The searchable description of the key.
339 static inline struct key *request_key(struct key_type *type,  in request_key()
348  * request_key_net - Request a key for a net namespace and wait for construction
349  * @type: Type of key.
350  * @description: The searchable description of the key.
351  * @net: The network namespace that is the key's domain of operation.
354  * As for request_key() except that it does not add the returned key to a
366  * request_key_net_rcu - Request a key for a net namespace under RCU conditions
367  * @type: Type of key.
368  * @description: The searchable description of the key.
369  * @net: The network namespace that is the key's domain of operation.
378 extern int wait_for_key_construction(struct key *key, bool intr);
380 extern int key_validate(const struct key *key);
390 extern int key_update(key_ref_t key,
394 extern int key_link(struct key *keyring,
395 		    struct key *key);
397 extern int key_move(struct key *key,
398 		    struct key *from_keyring,
399 		    struct key *to_keyring,
402 extern int key_unlink(struct key *keyring,
403 		      struct key *key);
405 extern struct key *keyring_alloc(const char *description, kuid_t uid, kgid_t gid,
410 				 struct key *dest);
412 extern int restrict_link_reject(struct key *keyring,
415 				struct key *restriction_key);
417 extern int keyring_clear(struct key *keyring);
424 extern int keyring_add_key(struct key *keyring,
425 			   struct key *key);
430 extern struct key *key_lookup(key_serial_t id);
432 static inline key_serial_t key_serial(const struct key *key)  in key_serial()  argument
434 	return key ? key->serial : 0;  in key_serial()
437 extern void key_set_timeout(struct key *, unsigned);
443 static inline short key_read_state(const struct key *key)  in key_read_state()  argument
446 	return smp_load_acquire(&key->state);  in key_read_state()
450  * key_is_positive - Determine if a key has been positively instantiated
451  * @key: The key to check.
453  * Return true if the specified key has been positively instantiated, false
456 static inline bool key_is_positive(const struct key *key)  in key_is_positive()  argument
458 	return key_read_state(key) == KEY_IS_POSITIVE;  in key_is_positive()
461 static inline bool key_is_negative(const struct key *key)  in key_is_negative()  argument
463 	return key_read_state(key) < 0;  in key_is_negative()
466 #define dereference_key_rcu(KEY)					\  argument
467 	(rcu_dereference((KEY)->payload.rcu_data0))
469 #define dereference_key_locked(KEY)					\  argument
470 	(rcu_dereference_protected((KEY)->payload.rcu_data0,		\
471 				   rwsem_is_locked(&((struct key *)(KEY))->sem)))
473 #define rcu_assign_keypointer(KEY, PAYLOAD)				\  argument
475 	rcu_assign_pointer((KEY)->payload.rcu_data0, (PAYLOAD));	\