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 */
115 	/* [!] If this structure is altered, the union in struct key must change too! */
141  * key reference with possession attribute handling
145  * flag to indicate whether the calling process possesses that key in one of
155 static inline key_ref_t make_key_ref(const struct key *key,  in make_key_ref()  argument
158 	return (key_ref_t) ((unsigned long) key | possession);  in make_key_ref()
161 static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)  in key_ref_to_ptr()
163 	return (struct key *) ((unsigned long) key_ref & ~1UL);  in key_ref_to_ptr()
171 typedef int (*key_restrict_link_func_t)(struct key *dest_keyring,
174 					struct key *restriction_key);
178 	struct key *key;  member
190  * - types of key include:
195 struct key {  struct
197 	key_serial_t		serial;		/* key serial number */  argument
203 	struct watch_list	*watchers;	/* Entities watching this key for changes */  argument
206 	struct key_user		*user;		/* owner of this key */  argument
207 	void			*security;	/* security data for this key */  argument
209 		time64_t	expiry;		/* time at which key expires (or 0) */  argument
210 		time64_t	revoked_at;	/* time at which key was revoked */
221 	short			state;		/* Key state (+) or rejection error (-) */
229 #define KEY_FLAG_DEAD		0	/* set if key type has been deleted */  argument
230 #define KEY_FLAG_REVOKED	1	/* set if key had been revoked */
231 #define KEY_FLAG_IN_QUOTA	2	/* set if key consumes quota */
232 #define KEY_FLAG_USER_CONSTRUCT	3	/* set if key is being constructed in userspace */
233 #define KEY_FLAG_ROOT_CAN_CLEAR	4	/* set if key can be cleared by root without permission */
234 #define KEY_FLAG_INVALIDATED	5	/* set if key has been invalidated */
235 #define KEY_FLAG_BUILTIN	6	/* set if key is built in to the kernel */
236 #define KEY_FLAG_ROOT_CAN_INVAL	7	/* set if key can be invalidated by root without permission */
237 #define KEY_FLAG_KEEP		8	/* set if key should not be removed */
238 #define KEY_FLAG_UID_KEYRING	9	/* set if key is a user or user session keyring */
240 	/* the key type and key description string
241 	 * - the desc is used to match a key against search criteria
250 			struct key_type	*type;		/* type of key */  argument
256 	/* key data
269 	/* This is set on a keyring to restrict the addition of a link to a key  argument
283 extern struct key *key_alloc(struct key_type *type,
295 #define KEY_ALLOC_BUILT_IN		0x0004	/* Key is built into kernel */
298 #define KEY_ALLOC_SET_KEEP		0x0020	/* Set the KEEP flag on the key/keyring */
300 extern void key_revoke(struct key *key);
301 extern void key_invalidate(struct key *key);
302 extern void key_put(struct key *key);
306 static inline struct key *__key_get(struct key *key)  in __key_get()  argument
308 	refcount_inc(&key->usage);  in __key_get()
309 	return key;  in __key_get()
312 static inline struct key *key_get(struct key *key)  in key_get()  argument
314 	return key ? __key_get(key) : key;  in key_get()
322 extern struct key *request_key_tag(struct key_type *type,
327 extern struct key *request_key_rcu(struct key_type *type,
331 extern struct key *request_key_with_auxdata(struct key_type *type,
339  * request_key - Request a key and wait for construction
340  * @type: Type of key.
341  * @description: The searchable description of the key.
346 static inline struct key *request_key(struct key_type *type,  in request_key()
355  * request_key_net - Request a key for a net namespace and wait for construction
356  * @type: Type of key.
357  * @description: The searchable description of the key.
358  * @net: The network namespace that is the key's domain of operation.
361  * As for request_key() except that it does not add the returned key to a
373  * request_key_net_rcu - Request a key for a net namespace under RCU conditions
374  * @type: Type of key.
375  * @description: The searchable description of the key.
376  * @net: The network namespace that is the key's domain of operation.
385 extern int wait_for_key_construction(struct key *key, bool intr);
387 extern int key_validate(const struct key *key);
397 extern int key_update(key_ref_t key,
401 extern int key_link(struct key *keyring,
402 		    struct key *key);
404 extern int key_move(struct key *key,
405 		    struct key *from_keyring,
406 		    struct key *to_keyring,
409 extern int key_unlink(struct key *keyring,
410 		      struct key *key);
412 extern struct key *keyring_alloc(const char *description, kuid_t uid, kgid_t gid,
417 				 struct key *dest);
419 extern int restrict_link_reject(struct key *keyring,
422 				struct key *restriction_key);
424 extern int keyring_clear(struct key *keyring);
431 extern int keyring_add_key(struct key *keyring,
432 			   struct key *key);
437 extern struct key *key_lookup(key_serial_t id);
439 static inline key_serial_t key_serial(const struct key *key)  in key_serial()  argument
441 	return key ? key->serial : 0;  in key_serial()
444 extern void key_set_timeout(struct key *, unsigned);
450 static inline short key_read_state(const struct key *key)  in key_read_state()  argument
453 	return smp_load_acquire(&key->state);  in key_read_state()
457  * key_is_positive - Determine if a key has been positively instantiated
458  * @key: The key to check.
460  * Return true if the specified key has been positively instantiated, false
463 static inline bool key_is_positive(const struct key *key)  in key_is_positive()  argument
465 	return key_read_state(key) == KEY_IS_POSITIVE;  in key_is_positive()
468 static inline bool key_is_negative(const struct key *key)  in key_is_negative()  argument
470 	return key_read_state(key) < 0;  in key_is_negative()
473 #define dereference_key_rcu(KEY)					\  argument
474 	(rcu_dereference((KEY)->payload.rcu_data0))
476 #define dereference_key_locked(KEY)					\  argument
477 	(rcu_dereference_protected((KEY)->payload.rcu_data0,		\
478 				   rwsem_is_locked(&((struct key *)(KEY))->sem)))
480 #define rcu_assign_keypointer(KEY, PAYLOAD)				\  argument
482 	rcu_assign_pointer((KEY)->payload.rcu_data0, (PAYLOAD));	\