blob: 2393b1c040b695d69d3a2f700300d3b4cec296c5 [file] [log] [blame]
David Howells76181c12007-10-16 23:29:46 -07001/* Authentication token and access key management
Linus Torvalds1da177e2005-04-16 15:20:36 -07002 *
David Howells76181c12007-10-16 23:29:46 -07003 * Copyright (C) 2004, 2007 Red Hat, Inc. All Rights Reserved.
Linus Torvalds1da177e2005-04-16 15:20:36 -07004 * 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 *
Randy Dunlapd410fa42011-05-19 15:59:38 -070012 * See Documentation/security/keys.txt for information on keys/keyrings.
Linus Torvalds1da177e2005-04-16 15:20:36 -070013 */
14
15#ifndef _LINUX_KEY_H
16#define _LINUX_KEY_H
17
18#include <linux/types.h>
19#include <linux/list.h>
20#include <linux/rbtree.h>
David Howells76d8aea2005-06-23 22:00:49 -070021#include <linux/rcupdate.h>
David Howells0b77f5b2008-04-29 01:01:32 -070022#include <linux/sysctl.h>
Pekka Enbergaa844422009-03-24 10:54:46 +020023#include <linux/rwsem.h>
Arun Sharma600634972011-07-26 16:09:06 -070024#include <linux/atomic.h>
Linus Torvalds1da177e2005-04-16 15:20:36 -070025
26#ifdef __KERNEL__
Eric W. Biederman9a56c2d2012-02-08 07:53:04 -080027#include <linux/uidgid.h>
Linus Torvalds1da177e2005-04-16 15:20:36 -070028
29/* key handle serial number */
30typedef int32_t key_serial_t;
31
32/* key handle permissions mask */
33typedef uint32_t key_perm_t;
34
35struct key;
36
37#ifdef CONFIG_KEYS
38
39#undef KEY_DEBUGGING
40
David Howells664cceb2005-09-28 17:03:15 +010041#define KEY_POS_VIEW 0x01000000 /* possessor can view a key's attributes */
42#define KEY_POS_READ 0x02000000 /* possessor can read key payload / view keyring */
43#define KEY_POS_WRITE 0x04000000 /* possessor can update key payload / add link to keyring */
44#define KEY_POS_SEARCH 0x08000000 /* possessor can find a key in search / search a keyring */
45#define KEY_POS_LINK 0x10000000 /* possessor can create a link to a key/keyring */
David Howells29db9192005-10-30 15:02:44 -080046#define KEY_POS_SETATTR 0x20000000 /* possessor can set key attributes */
47#define KEY_POS_ALL 0x3f000000
David Howells664cceb2005-09-28 17:03:15 +010048
49#define KEY_USR_VIEW 0x00010000 /* user permissions... */
50#define KEY_USR_READ 0x00020000
51#define KEY_USR_WRITE 0x00040000
52#define KEY_USR_SEARCH 0x00080000
53#define KEY_USR_LINK 0x00100000
David Howells29db9192005-10-30 15:02:44 -080054#define KEY_USR_SETATTR 0x00200000
55#define KEY_USR_ALL 0x003f0000
Linus Torvalds1da177e2005-04-16 15:20:36 -070056
57#define KEY_GRP_VIEW 0x00000100 /* group permissions... */
58#define KEY_GRP_READ 0x00000200
59#define KEY_GRP_WRITE 0x00000400
60#define KEY_GRP_SEARCH 0x00000800
61#define KEY_GRP_LINK 0x00001000
David Howells29db9192005-10-30 15:02:44 -080062#define KEY_GRP_SETATTR 0x00002000
63#define KEY_GRP_ALL 0x00003f00
Linus Torvalds1da177e2005-04-16 15:20:36 -070064
65#define KEY_OTH_VIEW 0x00000001 /* third party permissions... */
66#define KEY_OTH_READ 0x00000002
67#define KEY_OTH_WRITE 0x00000004
68#define KEY_OTH_SEARCH 0x00000008
69#define KEY_OTH_LINK 0x00000010
David Howells29db9192005-10-30 15:02:44 -080070#define KEY_OTH_SETATTR 0x00000020
71#define KEY_OTH_ALL 0x0000003f
Linus Torvalds1da177e2005-04-16 15:20:36 -070072
Arun Raghavan6b79ccb2008-04-29 01:01:28 -070073#define KEY_PERM_UNDEF 0xffffffff
74
Linus Torvalds1da177e2005-04-16 15:20:36 -070075struct seq_file;
76struct user_struct;
77struct signal_struct;
David Howellsd84f4f92008-11-14 10:39:23 +110078struct cred;
Linus Torvalds1da177e2005-04-16 15:20:36 -070079
80struct key_type;
81struct key_owner;
82struct keyring_list;
83struct keyring_name;
84
85/*****************************************************************************/
86/*
David Howells664cceb2005-09-28 17:03:15 +010087 * key reference with possession attribute handling
88 *
89 * NOTE! key_ref_t is a typedef'd pointer to a type that is not actually
90 * defined. This is because we abuse the bottom bit of the reference to carry a
91 * flag to indicate whether the calling process possesses that key in one of
92 * its keyrings.
93 *
94 * the key_ref_t has been made a separate type so that the compiler can reject
95 * attempts to dereference it without proper conversion.
96 *
97 * the three functions are used to assemble and disassemble references
98 */
99typedef struct __key_reference_with_attributes *key_ref_t;
100
101static inline key_ref_t make_key_ref(const struct key *key,
102 unsigned long possession)
103{
104 return (key_ref_t) ((unsigned long) key | possession);
105}
106
107static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)
108{
109 return (struct key *) ((unsigned long) key_ref & ~1UL);
110}
111
112static inline unsigned long is_key_possessed(const key_ref_t key_ref)
113{
114 return (unsigned long) key_ref & 1UL;
115}
116
117/*****************************************************************************/
118/*
Linus Torvalds1da177e2005-04-16 15:20:36 -0700119 * authentication token / access credential / keyring
120 * - types of key include:
121 * - keyrings
122 * - disk encryption IDs
123 * - Kerberos TGTs and tickets
124 */
125struct key {
126 atomic_t usage; /* number of references */
127 key_serial_t serial; /* key serial number */
David Howells65d87fe2012-05-11 10:56:56 +0100128 union {
129 struct list_head graveyard_link;
130 struct rb_node serial_node;
131 };
Linus Torvalds1da177e2005-04-16 15:20:36 -0700132 struct key_type *type; /* type of key */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700133 struct rw_semaphore sem; /* change vs change sem */
134 struct key_user *user; /* owner of this key */
David Howells29db9192005-10-30 15:02:44 -0800135 void *security; /* security data for this key */
David Howells5d135442009-09-02 09:14:00 +0100136 union {
137 time_t expiry; /* time at which key expires (or 0) */
138 time_t revoked_at; /* time at which key was revoked */
139 };
David Howells31d5a792012-05-11 10:56:56 +0100140 time_t last_used_at; /* last time used for LRU keyring discard */
Eric W. Biederman9a56c2d2012-02-08 07:53:04 -0800141 kuid_t uid;
142 kgid_t gid;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700143 key_perm_t perm; /* access permissions */
144 unsigned short quotalen; /* length added to quota */
David Howells76d8aea2005-06-23 22:00:49 -0700145 unsigned short datalen; /* payload data length
146 * - may not match RCU dereferenced payload
147 * - payload should contain own length
148 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700149
150#ifdef KEY_DEBUGGING
151 unsigned magic;
152#define KEY_DEBUG_MAGIC 0x18273645u
153#define KEY_DEBUG_MAGIC_X 0xf8e9dacbu
154#endif
155
David Howells76d8aea2005-06-23 22:00:49 -0700156 unsigned long flags; /* status flags (change with bitops) */
157#define KEY_FLAG_INSTANTIATED 0 /* set if key has been instantiated */
158#define KEY_FLAG_DEAD 1 /* set if key type has been deleted */
159#define KEY_FLAG_REVOKED 2 /* set if key had been revoked */
160#define KEY_FLAG_IN_QUOTA 3 /* set if key consumes quota */
161#define KEY_FLAG_USER_CONSTRUCT 4 /* set if key is being constructed in userspace */
162#define KEY_FLAG_NEGATIVE 5 /* set if key is negative */
David Howells700920e2012-01-18 15:31:45 +0000163#define KEY_FLAG_ROOT_CAN_CLEAR 6 /* set if key can be cleared by root without permission */
David Howellsfd758152012-05-11 10:56:56 +0100164#define KEY_FLAG_INVALIDATED 7 /* set if key has been invalidated */
David Howells76d8aea2005-06-23 22:00:49 -0700165
Linus Torvalds1da177e2005-04-16 15:20:36 -0700166 /* the description string
167 * - this is used to match a key against search criteria
168 * - this should be a printable string
169 * - eg: for krb5 AFS, this might be "afs@REDHAT.COM"
170 */
171 char *description;
172
173 /* type specific data
174 * - this is used by the keyring type to index the name
175 */
176 union {
177 struct list_head link;
David Howells73182262007-04-26 15:46:23 -0700178 unsigned long x[2];
179 void *p[2];
David Howellsfdd1b942011-03-07 15:06:09 +0000180 int reject_error;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700181 } type_data;
182
183 /* key data
184 * - this is used to hold the data actually used in cryptography or
185 * whatever
186 */
187 union {
188 unsigned long value;
Arnd Bergmanne63ba742010-02-26 18:01:20 +0100189 void __rcu *rcudata;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700190 void *data;
Arnd Bergmanne63ba742010-02-26 18:01:20 +0100191 struct keyring_list __rcu *subscriptions;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700192 } payload;
193};
194
Linus Torvalds1da177e2005-04-16 15:20:36 -0700195extern struct key *key_alloc(struct key_type *type,
196 const char *desc,
Eric W. Biederman9a56c2d2012-02-08 07:53:04 -0800197 kuid_t uid, kgid_t gid,
David Howellsd84f4f92008-11-14 10:39:23 +1100198 const struct cred *cred,
David Howells7e047ef2006-06-26 00:24:50 -0700199 key_perm_t perm,
200 unsigned long flags);
201
202
203#define KEY_ALLOC_IN_QUOTA 0x0000 /* add to quota, reject if would overrun */
204#define KEY_ALLOC_QUOTA_OVERRUN 0x0001 /* add to quota, permit even if overrun */
205#define KEY_ALLOC_NOT_IN_QUOTA 0x0002 /* not in quota */
206
Linus Torvalds1da177e2005-04-16 15:20:36 -0700207extern void key_revoke(struct key *key);
David Howellsfd758152012-05-11 10:56:56 +0100208extern void key_invalidate(struct key *key);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700209extern void key_put(struct key *key);
210
211static inline struct key *key_get(struct key *key)
212{
213 if (key)
214 atomic_inc(&key->usage);
215 return key;
216}
217
David Howells664cceb2005-09-28 17:03:15 +0100218static inline void key_ref_put(key_ref_t key_ref)
219{
220 key_put(key_ref_to_ptr(key_ref));
221}
222
Linus Torvalds1da177e2005-04-16 15:20:36 -0700223extern struct key *request_key(struct key_type *type,
224 const char *description,
225 const char *callout_info);
226
David Howells4e54f082006-06-29 02:24:28 -0700227extern struct key *request_key_with_auxdata(struct key_type *type,
228 const char *description,
David Howells4a38e122008-04-29 01:01:24 -0700229 const void *callout_info,
230 size_t callout_len,
David Howells4e54f082006-06-29 02:24:28 -0700231 void *aux);
232
David Howells76181c12007-10-16 23:29:46 -0700233extern struct key *request_key_async(struct key_type *type,
234 const char *description,
David Howells4a38e122008-04-29 01:01:24 -0700235 const void *callout_info,
236 size_t callout_len);
David Howells76181c12007-10-16 23:29:46 -0700237
238extern struct key *request_key_async_with_auxdata(struct key_type *type,
239 const char *description,
David Howells4a38e122008-04-29 01:01:24 -0700240 const void *callout_info,
241 size_t callout_len,
David Howells76181c12007-10-16 23:29:46 -0700242 void *aux);
243
244extern int wait_for_key_construction(struct key *key, bool intr);
245
David Howellsb404aef2012-05-15 14:11:11 +0100246extern int key_validate(const struct key *key);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700247
David Howells664cceb2005-09-28 17:03:15 +0100248extern 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,
Arun Raghavan6b79ccb2008-04-29 01:01:28 -0700253 key_perm_t perm,
David Howells7e047ef2006-06-26 00:24:50 -0700254 unsigned long flags);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700255
David Howells664cceb2005-09-28 17:03:15 +0100256extern int key_update(key_ref_t key,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700257 const void *payload,
258 size_t plen);
259
260extern int key_link(struct key *keyring,
261 struct key *key);
262
263extern int key_unlink(struct key *keyring,
264 struct key *key);
265
Eric W. Biederman9a56c2d2012-02-08 07:53:04 -0800266extern struct key *keyring_alloc(const char *description, kuid_t uid, kgid_t gid,
David Howellsd84f4f92008-11-14 10:39:23 +1100267 const struct cred *cred,
David Howells7e047ef2006-06-26 00:24:50 -0700268 unsigned long flags,
Michael LeMayd7200242006-06-22 14:47:17 -0700269 struct key *dest);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700270
271extern int keyring_clear(struct key *keyring);
272
David Howells664cceb2005-09-28 17:03:15 +0100273extern key_ref_t keyring_search(key_ref_t keyring,
274 struct key_type *type,
275 const char *description);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700276
Linus Torvalds1da177e2005-04-16 15:20:36 -0700277extern int keyring_add_key(struct key *keyring,
278 struct key *key);
279
280extern struct key *key_lookup(key_serial_t id);
281
David Howells456a8162012-01-18 10:04:29 +0000282static inline key_serial_t key_serial(const struct key *key)
David Howells7249db22008-04-29 01:01:34 -0700283{
284 return key ? key->serial : 0;
285}
Linus Torvalds1da177e2005-04-16 15:20:36 -0700286
Bryan Schumaker59e6b9c2012-02-24 14:14:50 -0500287extern void key_set_timeout(struct key *, unsigned);
288
David Howells78b72802011-03-11 17:57:23 +0000289/**
290 * key_is_instantiated - Determine if a key has been positively instantiated
291 * @key: The key to check.
292 *
293 * Return true if the specified key has been positively instantiated, false
294 * otherwise.
295 */
296static inline bool key_is_instantiated(const struct key *key)
297{
298 return test_bit(KEY_FLAG_INSTANTIATED, &key->flags) &&
299 !test_bit(KEY_FLAG_NEGATIVE, &key->flags);
300}
301
David Howells633e8042011-03-07 15:05:51 +0000302#define rcu_dereference_key(KEY) \
303 (rcu_dereference_protected((KEY)->payload.rcudata, \
304 rwsem_is_locked(&((struct key *)(KEY))->sem)))
305
Mimi Zoharee0b31a2012-01-17 20:39:51 +0000306#define rcu_assign_keypointer(KEY, PAYLOAD) \
Paul E. McKenneye5c1f442012-05-16 16:31:38 -0700307do { \
308 rcu_assign_pointer((KEY)->payload.rcudata, (PAYLOAD)); \
309} while (0)
Mimi Zoharee0b31a2012-01-17 20:39:51 +0000310
David Howells0b77f5b2008-04-29 01:01:32 -0700311#ifdef CONFIG_SYSCTL
312extern ctl_table key_sysctls[];
313#endif
Linus Torvalds1da177e2005-04-16 15:20:36 -0700314/*
315 * the userspace interface
316 */
David Howellsd84f4f92008-11-14 10:39:23 +1100317extern int install_thread_keyring_to_cred(struct cred *cred);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700318extern void key_fsuid_changed(struct task_struct *tsk);
319extern void key_fsgid_changed(struct task_struct *tsk);
320extern void key_init(void);
321
322#else /* CONFIG_KEYS */
323
324#define key_validate(k) 0
325#define key_serial(k) 0
David Howells7888e7f2005-06-23 22:00:51 -0700326#define key_get(k) ({ NULL; })
Adrian Bunk0dab9cf2008-10-12 07:10:50 +0300327#define key_revoke(k) do { } while(0)
David Howellsfd758152012-05-11 10:56:56 +0100328#define key_invalidate(k) do { } while(0)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700329#define key_put(k) do { } while(0)
David Howells664cceb2005-09-28 17:03:15 +0100330#define key_ref_put(k) do { } while(0)
David Howells8bbf49762008-11-14 10:39:14 +1100331#define make_key_ref(k, p) NULL
332#define key_ref_to_ptr(k) NULL
David Howells664cceb2005-09-28 17:03:15 +0100333#define is_key_possessed(k) 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700334#define key_fsuid_changed(t) do { } while(0)
335#define key_fsgid_changed(t) do { } while(0)
336#define key_init() do { } while(0)
337
Linus Torvalds1da177e2005-04-16 15:20:36 -0700338#endif /* CONFIG_KEYS */
339#endif /* __KERNEL__ */
340#endif /* _LINUX_KEY_H */