key.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386
  1. /* key.h: authentication token and access key management
  2. *
  3. * Copyright (C) 2004 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/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 <asm/atomic.h>
  21. #ifdef __KERNEL__
  22. /* key handle serial number */
  23. typedef int32_t key_serial_t;
  24. /* key handle permissions mask */
  25. typedef uint32_t key_perm_t;
  26. struct key;
  27. #ifdef CONFIG_KEYS
  28. #undef KEY_DEBUGGING
  29. #define KEY_POS_VIEW 0x01000000 /* possessor can view a key's attributes */
  30. #define KEY_POS_READ 0x02000000 /* possessor can read key payload / view keyring */
  31. #define KEY_POS_WRITE 0x04000000 /* possessor can update key payload / add link to keyring */
  32. #define KEY_POS_SEARCH 0x08000000 /* possessor can find a key in search / search a keyring */
  33. #define KEY_POS_LINK 0x10000000 /* possessor can create a link to a key/keyring */
  34. #define KEY_POS_SETATTR 0x20000000 /* possessor can set key attributes */
  35. #define KEY_POS_ALL 0x3f000000
  36. #define KEY_USR_VIEW 0x00010000 /* user permissions... */
  37. #define KEY_USR_READ 0x00020000
  38. #define KEY_USR_WRITE 0x00040000
  39. #define KEY_USR_SEARCH 0x00080000
  40. #define KEY_USR_LINK 0x00100000
  41. #define KEY_USR_SETATTR 0x00200000
  42. #define KEY_USR_ALL 0x003f0000
  43. #define KEY_GRP_VIEW 0x00000100 /* group permissions... */
  44. #define KEY_GRP_READ 0x00000200
  45. #define KEY_GRP_WRITE 0x00000400
  46. #define KEY_GRP_SEARCH 0x00000800
  47. #define KEY_GRP_LINK 0x00001000
  48. #define KEY_GRP_SETATTR 0x00002000
  49. #define KEY_GRP_ALL 0x00003f00
  50. #define KEY_OTH_VIEW 0x00000001 /* third party permissions... */
  51. #define KEY_OTH_READ 0x00000002
  52. #define KEY_OTH_WRITE 0x00000004
  53. #define KEY_OTH_SEARCH 0x00000008
  54. #define KEY_OTH_LINK 0x00000010
  55. #define KEY_OTH_SETATTR 0x00000020
  56. #define KEY_OTH_ALL 0x0000003f
  57. struct seq_file;
  58. struct user_struct;
  59. struct signal_struct;
  60. struct key_type;
  61. struct key_owner;
  62. struct keyring_list;
  63. struct keyring_name;
  64. /*****************************************************************************/
  65. /*
  66. * key reference with possession attribute handling
  67. *
  68. * NOTE! key_ref_t is a typedef'd pointer to a type that is not actually
  69. * defined. This is because we abuse the bottom bit of the reference to carry a
  70. * flag to indicate whether the calling process possesses that key in one of
  71. * its keyrings.
  72. *
  73. * the key_ref_t has been made a separate type so that the compiler can reject
  74. * attempts to dereference it without proper conversion.
  75. *
  76. * the three functions are used to assemble and disassemble references
  77. */
  78. typedef struct __key_reference_with_attributes *key_ref_t;
  79. static inline key_ref_t make_key_ref(const struct key *key,
  80. unsigned long possession)
  81. {
  82. return (key_ref_t) ((unsigned long) key | possession);
  83. }
  84. static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)
  85. {
  86. return (struct key *) ((unsigned long) key_ref & ~1UL);
  87. }
  88. static inline unsigned long is_key_possessed(const key_ref_t key_ref)
  89. {
  90. return (unsigned long) key_ref & 1UL;
  91. }
  92. /*****************************************************************************/
  93. /*
  94. * authentication token / access credential / keyring
  95. * - types of key include:
  96. * - keyrings
  97. * - disk encryption IDs
  98. * - Kerberos TGTs and tickets
  99. */
  100. struct key {
  101. atomic_t usage; /* number of references */
  102. key_serial_t serial; /* key serial number */
  103. struct rb_node serial_node;
  104. struct key_type *type; /* type of key */
  105. struct rw_semaphore sem; /* change vs change sem */
  106. struct key_user *user; /* owner of this key */
  107. void *security; /* security data for this key */
  108. time_t expiry; /* time at which key expires (or 0) */
  109. uid_t uid;
  110. gid_t gid;
  111. key_perm_t perm; /* access permissions */
  112. unsigned short quotalen; /* length added to quota */
  113. unsigned short datalen; /* payload data length
  114. * - may not match RCU dereferenced payload
  115. * - payload should contain own length
  116. */
  117. #ifdef KEY_DEBUGGING
  118. unsigned magic;
  119. #define KEY_DEBUG_MAGIC 0x18273645u
  120. #define KEY_DEBUG_MAGIC_X 0xf8e9dacbu
  121. #endif
  122. unsigned long flags; /* status flags (change with bitops) */
  123. #define KEY_FLAG_INSTANTIATED 0 /* set if key has been instantiated */
  124. #define KEY_FLAG_DEAD 1 /* set if key type has been deleted */
  125. #define KEY_FLAG_REVOKED 2 /* set if key had been revoked */
  126. #define KEY_FLAG_IN_QUOTA 3 /* set if key consumes quota */
  127. #define KEY_FLAG_USER_CONSTRUCT 4 /* set if key is being constructed in userspace */
  128. #define KEY_FLAG_NEGATIVE 5 /* set if key is negative */
  129. /* the description string
  130. * - this is used to match a key against search criteria
  131. * - this should be a printable string
  132. * - eg: for krb5 AFS, this might be "afs@REDHAT.COM"
  133. */
  134. char *description;
  135. /* type specific data
  136. * - this is used by the keyring type to index the name
  137. */
  138. union {
  139. struct list_head link;
  140. } type_data;
  141. /* key data
  142. * - this is used to hold the data actually used in cryptography or
  143. * whatever
  144. */
  145. union {
  146. unsigned long value;
  147. void *data;
  148. struct keyring_list *subscriptions;
  149. } payload;
  150. };
  151. /*****************************************************************************/
  152. /*
  153. * kernel managed key type definition
  154. */
  155. typedef int (*request_key_actor_t)(struct key *key, struct key *authkey,
  156. const char *op, void *aux);
  157. struct key_type {
  158. /* name of the type */
  159. const char *name;
  160. /* default payload length for quota precalculation (optional)
  161. * - this can be used instead of calling key_payload_reserve(), that
  162. * function only needs to be called if the real datalen is different
  163. */
  164. size_t def_datalen;
  165. /* instantiate a key of this type
  166. * - this method should call key_payload_reserve() to determine if the
  167. * user's quota will hold the payload
  168. */
  169. int (*instantiate)(struct key *key, const void *data, size_t datalen);
  170. /* update a key of this type (optional)
  171. * - this method should call key_payload_reserve() to recalculate the
  172. * quota consumption
  173. * - the key must be locked against read when modifying
  174. */
  175. int (*update)(struct key *key, const void *data, size_t datalen);
  176. /* match a key against a description */
  177. int (*match)(const struct key *key, const void *desc);
  178. /* clear some of the data from a key on revokation (optional)
  179. * - the key's semaphore will be write-locked by the caller
  180. */
  181. void (*revoke)(struct key *key);
  182. /* clear the data from a key (optional) */
  183. void (*destroy)(struct key *key);
  184. /* describe a key */
  185. void (*describe)(const struct key *key, struct seq_file *p);
  186. /* read a key's data (optional)
  187. * - permission checks will be done by the caller
  188. * - the key's semaphore will be readlocked by the caller
  189. * - should return the amount of data that could be read, no matter how
  190. * much is copied into the buffer
  191. * - shouldn't do the copy if the buffer is NULL
  192. */
  193. long (*read)(const struct key *key, char __user *buffer, size_t buflen);
  194. /* handle request_key() for this type instead of invoking
  195. * /sbin/request-key (optional)
  196. * - key is the key to instantiate
  197. * - authkey is the authority to assume when instantiating this key
  198. * - op is the operation to be done, usually "create"
  199. * - the call must not return until the instantiation process has run
  200. * its course
  201. */
  202. request_key_actor_t request_key;
  203. /* internal fields */
  204. struct list_head link; /* link in types list */
  205. };
  206. extern struct key_type key_type_keyring;
  207. extern int register_key_type(struct key_type *ktype);
  208. extern void unregister_key_type(struct key_type *ktype);
  209. extern struct key *key_alloc(struct key_type *type,
  210. const char *desc,
  211. uid_t uid, gid_t gid,
  212. struct task_struct *ctx,
  213. key_perm_t perm,
  214. unsigned long flags);
  215. #define KEY_ALLOC_IN_QUOTA 0x0000 /* add to quota, reject if would overrun */
  216. #define KEY_ALLOC_QUOTA_OVERRUN 0x0001 /* add to quota, permit even if overrun */
  217. #define KEY_ALLOC_NOT_IN_QUOTA 0x0002 /* not in quota */
  218. extern int key_payload_reserve(struct key *key, size_t datalen);
  219. extern int key_instantiate_and_link(struct key *key,
  220. const void *data,
  221. size_t datalen,
  222. struct key *keyring,
  223. struct key *instkey);
  224. extern int key_negate_and_link(struct key *key,
  225. unsigned timeout,
  226. struct key *keyring,
  227. struct key *instkey);
  228. extern void key_revoke(struct key *key);
  229. extern void key_put(struct key *key);
  230. static inline struct key *key_get(struct key *key)
  231. {
  232. if (key)
  233. atomic_inc(&key->usage);
  234. return key;
  235. }
  236. static inline void key_ref_put(key_ref_t key_ref)
  237. {
  238. key_put(key_ref_to_ptr(key_ref));
  239. }
  240. extern struct key *request_key(struct key_type *type,
  241. const char *description,
  242. const char *callout_info);
  243. extern struct key *request_key_with_auxdata(struct key_type *type,
  244. const char *description,
  245. const char *callout_info,
  246. void *aux);
  247. extern int key_validate(struct key *key);
  248. extern key_ref_t key_create_or_update(key_ref_t keyring,
  249. const char *type,
  250. const char *description,
  251. const void *payload,
  252. size_t plen,
  253. unsigned long flags);
  254. extern int key_update(key_ref_t key,
  255. const void *payload,
  256. size_t plen);
  257. extern int key_link(struct key *keyring,
  258. struct key *key);
  259. extern int key_unlink(struct key *keyring,
  260. struct key *key);
  261. extern struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
  262. struct task_struct *ctx,
  263. unsigned long flags,
  264. struct key *dest);
  265. extern int keyring_clear(struct key *keyring);
  266. extern key_ref_t keyring_search(key_ref_t keyring,
  267. struct key_type *type,
  268. const char *description);
  269. extern int keyring_add_key(struct key *keyring,
  270. struct key *key);
  271. extern struct key *key_lookup(key_serial_t id);
  272. extern void keyring_replace_payload(struct key *key, void *replacement);
  273. #define key_serial(key) ((key) ? (key)->serial : 0)
  274. /*
  275. * the userspace interface
  276. */
  277. extern struct key root_user_keyring, root_session_keyring;
  278. extern int alloc_uid_keyring(struct user_struct *user,
  279. struct task_struct *ctx);
  280. extern void switch_uid_keyring(struct user_struct *new_user);
  281. extern int copy_keys(unsigned long clone_flags, struct task_struct *tsk);
  282. extern int copy_thread_group_keys(struct task_struct *tsk);
  283. extern void exit_keys(struct task_struct *tsk);
  284. extern void exit_thread_group_keys(struct signal_struct *tg);
  285. extern int suid_keys(struct task_struct *tsk);
  286. extern int exec_keys(struct task_struct *tsk);
  287. extern void key_fsuid_changed(struct task_struct *tsk);
  288. extern void key_fsgid_changed(struct task_struct *tsk);
  289. extern void key_init(void);
  290. #define __install_session_keyring(tsk, keyring) \
  291. ({ \
  292. struct key *old_session = tsk->signal->session_keyring; \
  293. tsk->signal->session_keyring = keyring; \
  294. old_session; \
  295. })
  296. #else /* CONFIG_KEYS */
  297. #define key_validate(k) 0
  298. #define key_serial(k) 0
  299. #define key_get(k) ({ NULL; })
  300. #define key_put(k) do { } while(0)
  301. #define key_ref_put(k) do { } while(0)
  302. #define make_key_ref(k) ({ NULL; })
  303. #define key_ref_to_ptr(k) ({ NULL; })
  304. #define is_key_possessed(k) 0
  305. #define alloc_uid_keyring(u,c) 0
  306. #define switch_uid_keyring(u) do { } while(0)
  307. #define __install_session_keyring(t, k) ({ NULL; })
  308. #define copy_keys(f,t) 0
  309. #define copy_thread_group_keys(t) 0
  310. #define exit_keys(t) do { } while(0)
  311. #define exit_thread_group_keys(tg) do { } while(0)
  312. #define suid_keys(t) do { } while(0)
  313. #define exec_keys(t) do { } while(0)
  314. #define key_fsuid_changed(t) do { } while(0)
  315. #define key_fsgid_changed(t) do { } while(0)
  316. #define key_init() do { } while(0)
  317. /* Initial keyrings */
  318. extern struct key root_user_keyring;
  319. extern struct key root_session_keyring;
  320. #endif /* CONFIG_KEYS */
  321. #endif /* __KERNEL__ */
  322. #endif /* _LINUX_KEY_H */