key.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386
  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. #ifndef _LINUX_KEY_H
  15. #define _LINUX_KEY_H
  16. #include <linux/types.h>
  17. #include <linux/list.h>
  18. #include <linux/rbtree.h>
  19. #include <linux/rcupdate.h>
  20. #include <linux/sysctl.h>
  21. #include <linux/rwsem.h>
  22. #include <linux/atomic.h>
  23. #include <linux/assoc_array.h>
  24. #ifdef __KERNEL__
  25. #include <linux/uidgid.h>
  26. /* key handle serial number */
  27. typedef int32_t key_serial_t;
  28. /* key handle permissions mask */
  29. typedef uint32_t key_perm_t;
  30. struct key;
  31. #ifdef CONFIG_KEYS
  32. #undef KEY_DEBUGGING
  33. #define KEY_POS_VIEW 0x01000000 /* possessor can view a key's attributes */
  34. #define KEY_POS_READ 0x02000000 /* possessor can read key payload / view keyring */
  35. #define KEY_POS_WRITE 0x04000000 /* possessor can update key payload / add link to keyring */
  36. #define KEY_POS_SEARCH 0x08000000 /* possessor can find a key in search / search a keyring */
  37. #define KEY_POS_LINK 0x10000000 /* possessor can create a link to a key/keyring */
  38. #define KEY_POS_SETATTR 0x20000000 /* possessor can set key attributes */
  39. #define KEY_POS_ALL 0x3f000000
  40. #define KEY_USR_VIEW 0x00010000 /* user permissions... */
  41. #define KEY_USR_READ 0x00020000
  42. #define KEY_USR_WRITE 0x00040000
  43. #define KEY_USR_SEARCH 0x00080000
  44. #define KEY_USR_LINK 0x00100000
  45. #define KEY_USR_SETATTR 0x00200000
  46. #define KEY_USR_ALL 0x003f0000
  47. #define KEY_GRP_VIEW 0x00000100 /* group permissions... */
  48. #define KEY_GRP_READ 0x00000200
  49. #define KEY_GRP_WRITE 0x00000400
  50. #define KEY_GRP_SEARCH 0x00000800
  51. #define KEY_GRP_LINK 0x00001000
  52. #define KEY_GRP_SETATTR 0x00002000
  53. #define KEY_GRP_ALL 0x00003f00
  54. #define KEY_OTH_VIEW 0x00000001 /* third party permissions... */
  55. #define KEY_OTH_READ 0x00000002
  56. #define KEY_OTH_WRITE 0x00000004
  57. #define KEY_OTH_SEARCH 0x00000008
  58. #define KEY_OTH_LINK 0x00000010
  59. #define KEY_OTH_SETATTR 0x00000020
  60. #define KEY_OTH_ALL 0x0000003f
  61. #define KEY_PERM_UNDEF 0xffffffff
  62. struct seq_file;
  63. struct user_struct;
  64. struct signal_struct;
  65. struct cred;
  66. struct key_type;
  67. struct key_owner;
  68. struct keyring_list;
  69. struct keyring_name;
  70. struct keyring_index_key {
  71. struct key_type *type;
  72. const char *description;
  73. size_t desc_len;
  74. };
  75. union key_payload {
  76. void __rcu *rcu_data0;
  77. void *data[4];
  78. };
  79. /*****************************************************************************/
  80. /*
  81. * key reference with possession attribute handling
  82. *
  83. * NOTE! key_ref_t is a typedef'd pointer to a type that is not actually
  84. * defined. This is because we abuse the bottom bit of the reference to carry a
  85. * flag to indicate whether the calling process possesses that key in one of
  86. * its keyrings.
  87. *
  88. * the key_ref_t has been made a separate type so that the compiler can reject
  89. * attempts to dereference it without proper conversion.
  90. *
  91. * the three functions are used to assemble and disassemble references
  92. */
  93. typedef struct __key_reference_with_attributes *key_ref_t;
  94. static inline key_ref_t make_key_ref(const struct key *key,
  95. bool possession)
  96. {
  97. return (key_ref_t) ((unsigned long) key | possession);
  98. }
  99. static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)
  100. {
  101. return (struct key *) ((unsigned long) key_ref & ~1UL);
  102. }
  103. static inline bool is_key_possessed(const key_ref_t key_ref)
  104. {
  105. return (unsigned long) key_ref & 1UL;
  106. }
  107. enum key_state {
  108. KEY_IS_UNINSTANTIATED,
  109. KEY_IS_POSITIVE, /* Positively instantiated */
  110. };
  111. /*****************************************************************************/
  112. /*
  113. * authentication token / access credential / keyring
  114. * - types of key include:
  115. * - keyrings
  116. * - disk encryption IDs
  117. * - Kerberos TGTs and tickets
  118. */
  119. struct key {
  120. atomic_t usage; /* number of references */
  121. key_serial_t serial; /* key serial number */
  122. union {
  123. struct list_head graveyard_link;
  124. struct rb_node serial_node;
  125. };
  126. struct rw_semaphore sem; /* change vs change sem */
  127. struct key_user *user; /* owner of this key */
  128. void *security; /* security data for this key */
  129. union {
  130. time_t expiry; /* time at which key expires (or 0) */
  131. time_t revoked_at; /* time at which key was revoked */
  132. };
  133. time_t last_used_at; /* last time used for LRU keyring discard */
  134. kuid_t uid;
  135. kgid_t gid;
  136. key_perm_t perm; /* access permissions */
  137. unsigned short quotalen; /* length added to quota */
  138. unsigned short datalen; /* payload data length
  139. * - may not match RCU dereferenced payload
  140. * - payload should contain own length
  141. */
  142. short state; /* Key state (+) or rejection error (-) */
  143. #ifdef KEY_DEBUGGING
  144. unsigned magic;
  145. #define KEY_DEBUG_MAGIC 0x18273645u
  146. #define KEY_DEBUG_MAGIC_X 0xf8e9dacbu
  147. #endif
  148. unsigned long flags; /* status flags (change with bitops) */
  149. #define KEY_FLAG_DEAD 0 /* set if key type has been deleted */
  150. #define KEY_FLAG_REVOKED 1 /* set if key had been revoked */
  151. #define KEY_FLAG_IN_QUOTA 2 /* set if key consumes quota */
  152. #define KEY_FLAG_USER_CONSTRUCT 3 /* set if key is being constructed in userspace */
  153. #define KEY_FLAG_ROOT_CAN_CLEAR 4 /* set if key can be cleared by root without permission */
  154. #define KEY_FLAG_INVALIDATED 5 /* set if key has been invalidated */
  155. #define KEY_FLAG_TRUSTED 6 /* set if key is trusted */
  156. #define KEY_FLAG_TRUSTED_ONLY 7 /* set if keyring only accepts links to trusted keys */
  157. #define KEY_FLAG_BUILTIN 8 /* set if key is builtin */
  158. #define KEY_FLAG_ROOT_CAN_INVAL 9 /* set if key can be invalidated by root without permission */
  159. #define KEY_FLAG_UID_KEYRING 10 /* set if key is a user or user session keyring */
  160. /* the key type and key description string
  161. * - the desc is used to match a key against search criteria
  162. * - it should be a printable string
  163. * - eg: for krb5 AFS, this might be "afs@REDHAT.COM"
  164. */
  165. union {
  166. struct keyring_index_key index_key;
  167. struct {
  168. struct key_type *type; /* type of key */
  169. char *description;
  170. };
  171. };
  172. /* key data
  173. * - this is used to hold the data actually used in cryptography or
  174. * whatever
  175. */
  176. union {
  177. union key_payload payload;
  178. struct {
  179. /* Keyring bits */
  180. struct list_head name_link;
  181. struct assoc_array keys;
  182. };
  183. };
  184. };
  185. extern struct key *key_alloc(struct key_type *type,
  186. const char *desc,
  187. kuid_t uid, kgid_t gid,
  188. const struct cred *cred,
  189. key_perm_t perm,
  190. unsigned long flags);
  191. #define KEY_ALLOC_IN_QUOTA 0x0000 /* add to quota, reject if would overrun */
  192. #define KEY_ALLOC_QUOTA_OVERRUN 0x0001 /* add to quota, permit even if overrun */
  193. #define KEY_ALLOC_NOT_IN_QUOTA 0x0002 /* not in quota */
  194. #define KEY_ALLOC_TRUSTED 0x0004 /* Key should be flagged as trusted */
  195. #define KEY_ALLOC_UID_KEYRING 0x0010 /* allocating a user or user session keyring */
  196. extern void key_revoke(struct key *key);
  197. extern void key_invalidate(struct key *key);
  198. extern void key_put(struct key *key);
  199. static inline struct key *__key_get(struct key *key)
  200. {
  201. atomic_inc(&key->usage);
  202. return key;
  203. }
  204. static inline struct key *key_get(struct key *key)
  205. {
  206. return key ? __key_get(key) : key;
  207. }
  208. static inline void key_ref_put(key_ref_t key_ref)
  209. {
  210. key_put(key_ref_to_ptr(key_ref));
  211. }
  212. extern struct key *request_key(struct key_type *type,
  213. const char *description,
  214. const char *callout_info);
  215. extern struct key *request_key_with_auxdata(struct key_type *type,
  216. const char *description,
  217. const void *callout_info,
  218. size_t callout_len,
  219. void *aux);
  220. extern struct key *request_key_async(struct key_type *type,
  221. const char *description,
  222. const void *callout_info,
  223. size_t callout_len);
  224. extern struct key *request_key_async_with_auxdata(struct key_type *type,
  225. const char *description,
  226. const void *callout_info,
  227. size_t callout_len,
  228. void *aux);
  229. extern int wait_for_key_construction(struct key *key, bool intr);
  230. extern int key_validate(const struct key *key);
  231. extern key_ref_t key_create_or_update(key_ref_t keyring,
  232. const char *type,
  233. const char *description,
  234. const void *payload,
  235. size_t plen,
  236. key_perm_t perm,
  237. unsigned long flags);
  238. extern int key_update(key_ref_t key,
  239. const void *payload,
  240. size_t plen);
  241. extern int key_link(struct key *keyring,
  242. struct key *key);
  243. extern int key_unlink(struct key *keyring,
  244. struct key *key);
  245. extern struct key *keyring_alloc(const char *description, kuid_t uid, kgid_t gid,
  246. const struct cred *cred,
  247. key_perm_t perm,
  248. unsigned long flags,
  249. struct key *dest);
  250. extern int keyring_clear(struct key *keyring);
  251. extern key_ref_t keyring_search(key_ref_t keyring,
  252. struct key_type *type,
  253. const char *description);
  254. extern int keyring_add_key(struct key *keyring,
  255. struct key *key);
  256. extern struct key *key_lookup(key_serial_t id);
  257. static inline key_serial_t key_serial(const struct key *key)
  258. {
  259. return key ? key->serial : 0;
  260. }
  261. extern void key_set_timeout(struct key *, unsigned);
  262. /*
  263. * The permissions required on a key that we're looking up.
  264. */
  265. #define KEY_NEED_VIEW 0x01 /* Require permission to view attributes */
  266. #define KEY_NEED_READ 0x02 /* Require permission to read content */
  267. #define KEY_NEED_WRITE 0x04 /* Require permission to update / modify */
  268. #define KEY_NEED_SEARCH 0x08 /* Require permission to search (keyring) or find (key) */
  269. #define KEY_NEED_LINK 0x10 /* Require permission to link */
  270. #define KEY_NEED_SETATTR 0x20 /* Require permission to change attributes */
  271. #define KEY_NEED_ALL 0x3f /* All the above permissions */
  272. static inline short key_read_state(const struct key *key)
  273. {
  274. /* Barrier versus mark_key_instantiated(). */
  275. return smp_load_acquire(&key->state);
  276. }
  277. /**
  278. * key_is_positive - Determine if a key has been positively instantiated
  279. * @key: The key to check.
  280. *
  281. * Return true if the specified key has been positively instantiated, false
  282. * otherwise.
  283. */
  284. static inline bool key_is_positive(const struct key *key)
  285. {
  286. return key_read_state(key) == KEY_IS_POSITIVE;
  287. }
  288. static inline bool key_is_negative(const struct key *key)
  289. {
  290. return key_read_state(key) < 0;
  291. }
  292. #define rcu_dereference_key(KEY) \
  293. (rcu_dereference_protected((KEY)->payload.rcu_data0, \
  294. rwsem_is_locked(&((struct key *)(KEY))->sem)))
  295. #define rcu_assign_keypointer(KEY, PAYLOAD) \
  296. do { \
  297. rcu_assign_pointer((KEY)->payload.rcu_data0, (PAYLOAD)); \
  298. } while (0)
  299. #ifdef CONFIG_SYSCTL
  300. extern struct ctl_table key_sysctls[];
  301. #endif
  302. /*
  303. * the userspace interface
  304. */
  305. extern int install_thread_keyring_to_cred(struct cred *cred);
  306. extern void key_fsuid_changed(struct task_struct *tsk);
  307. extern void key_fsgid_changed(struct task_struct *tsk);
  308. extern void key_init(void);
  309. #else /* CONFIG_KEYS */
  310. #define key_validate(k) 0
  311. #define key_serial(k) 0
  312. #define key_get(k) ({ NULL; })
  313. #define key_revoke(k) do { } while(0)
  314. #define key_invalidate(k) do { } while(0)
  315. #define key_put(k) do { } while(0)
  316. #define key_ref_put(k) do { } while(0)
  317. #define make_key_ref(k, p) NULL
  318. #define key_ref_to_ptr(k) NULL
  319. #define is_key_possessed(k) 0
  320. #define key_fsuid_changed(t) do { } while(0)
  321. #define key_fsgid_changed(t) do { } while(0)
  322. #define key_init() do { } while(0)
  323. #endif /* CONFIG_KEYS */
  324. #endif /* __KERNEL__ */
  325. #endif /* _LINUX_KEY_H */