key.h 16 KB

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