blob: 1b70e35a71e378808454a60429c478c20200fe48 [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 *
12 * See Documentation/keys.txt for information on keys/keyrings.
13 */
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>
Linus Torvalds1da177e2005-04-16 15:20:36 -070023#include <asm/atomic.h>
24
25#ifdef __KERNEL__
26
27/* key handle serial number */
28typedef int32_t key_serial_t;
29
30/* key handle permissions mask */
31typedef uint32_t key_perm_t;
32
33struct key;
34
35#ifdef CONFIG_KEYS
36
37#undef KEY_DEBUGGING
38
David Howells664cceb2005-09-28 17:03:15 +010039#define KEY_POS_VIEW 0x01000000 /* possessor can view a key's attributes */
40#define KEY_POS_READ 0x02000000 /* possessor can read key payload / view keyring */
41#define KEY_POS_WRITE 0x04000000 /* possessor can update key payload / add link to keyring */
42#define KEY_POS_SEARCH 0x08000000 /* possessor can find a key in search / search a keyring */
43#define KEY_POS_LINK 0x10000000 /* possessor can create a link to a key/keyring */
David Howells29db9192005-10-30 15:02:44 -080044#define KEY_POS_SETATTR 0x20000000 /* possessor can set key attributes */
45#define KEY_POS_ALL 0x3f000000
David Howells664cceb2005-09-28 17:03:15 +010046
47#define KEY_USR_VIEW 0x00010000 /* user permissions... */
48#define KEY_USR_READ 0x00020000
49#define KEY_USR_WRITE 0x00040000
50#define KEY_USR_SEARCH 0x00080000
51#define KEY_USR_LINK 0x00100000
David Howells29db9192005-10-30 15:02:44 -080052#define KEY_USR_SETATTR 0x00200000
53#define KEY_USR_ALL 0x003f0000
Linus Torvalds1da177e2005-04-16 15:20:36 -070054
55#define KEY_GRP_VIEW 0x00000100 /* group permissions... */
56#define KEY_GRP_READ 0x00000200
57#define KEY_GRP_WRITE 0x00000400
58#define KEY_GRP_SEARCH 0x00000800
59#define KEY_GRP_LINK 0x00001000
David Howells29db9192005-10-30 15:02:44 -080060#define KEY_GRP_SETATTR 0x00002000
61#define KEY_GRP_ALL 0x00003f00
Linus Torvalds1da177e2005-04-16 15:20:36 -070062
63#define KEY_OTH_VIEW 0x00000001 /* third party permissions... */
64#define KEY_OTH_READ 0x00000002
65#define KEY_OTH_WRITE 0x00000004
66#define KEY_OTH_SEARCH 0x00000008
67#define KEY_OTH_LINK 0x00000010
David Howells29db9192005-10-30 15:02:44 -080068#define KEY_OTH_SETATTR 0x00000020
69#define KEY_OTH_ALL 0x0000003f
Linus Torvalds1da177e2005-04-16 15:20:36 -070070
Arun Raghavan6b79ccb2008-04-29 01:01:28 -070071#define KEY_PERM_UNDEF 0xffffffff
72
Linus Torvalds1da177e2005-04-16 15:20:36 -070073struct seq_file;
74struct user_struct;
75struct signal_struct;
76
77struct key_type;
78struct key_owner;
79struct keyring_list;
80struct keyring_name;
81
82/*****************************************************************************/
83/*
David Howells664cceb2005-09-28 17:03:15 +010084 * key reference with possession attribute handling
85 *
86 * NOTE! key_ref_t is a typedef'd pointer to a type that is not actually
87 * defined. This is because we abuse the bottom bit of the reference to carry a
88 * flag to indicate whether the calling process possesses that key in one of
89 * its keyrings.
90 *
91 * the key_ref_t has been made a separate type so that the compiler can reject
92 * attempts to dereference it without proper conversion.
93 *
94 * the three functions are used to assemble and disassemble references
95 */
96typedef struct __key_reference_with_attributes *key_ref_t;
97
98static inline key_ref_t make_key_ref(const struct key *key,
99 unsigned long possession)
100{
101 return (key_ref_t) ((unsigned long) key | possession);
102}
103
104static inline struct key *key_ref_to_ptr(const key_ref_t key_ref)
105{
106 return (struct key *) ((unsigned long) key_ref & ~1UL);
107}
108
109static inline unsigned long is_key_possessed(const key_ref_t key_ref)
110{
111 return (unsigned long) key_ref & 1UL;
112}
113
114/*****************************************************************************/
115/*
Linus Torvalds1da177e2005-04-16 15:20:36 -0700116 * authentication token / access credential / keyring
117 * - types of key include:
118 * - keyrings
119 * - disk encryption IDs
120 * - Kerberos TGTs and tickets
121 */
122struct key {
123 atomic_t usage; /* number of references */
124 key_serial_t serial; /* key serial number */
125 struct rb_node serial_node;
126 struct key_type *type; /* type of key */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700127 struct rw_semaphore sem; /* change vs change sem */
128 struct key_user *user; /* owner of this key */
David Howells29db9192005-10-30 15:02:44 -0800129 void *security; /* security data for this key */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700130 time_t expiry; /* time at which key expires (or 0) */
131 uid_t uid;
132 gid_t gid;
133 key_perm_t perm; /* access permissions */
134 unsigned short quotalen; /* length added to quota */
David Howells76d8aea2005-06-23 22:00:49 -0700135 unsigned short datalen; /* payload data length
136 * - may not match RCU dereferenced payload
137 * - payload should contain own length
138 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700139
140#ifdef KEY_DEBUGGING
141 unsigned magic;
142#define KEY_DEBUG_MAGIC 0x18273645u
143#define KEY_DEBUG_MAGIC_X 0xf8e9dacbu
144#endif
145
David Howells76d8aea2005-06-23 22:00:49 -0700146 unsigned long flags; /* status flags (change with bitops) */
147#define KEY_FLAG_INSTANTIATED 0 /* set if key has been instantiated */
148#define KEY_FLAG_DEAD 1 /* set if key type has been deleted */
149#define KEY_FLAG_REVOKED 2 /* set if key had been revoked */
150#define KEY_FLAG_IN_QUOTA 3 /* set if key consumes quota */
151#define KEY_FLAG_USER_CONSTRUCT 4 /* set if key is being constructed in userspace */
152#define KEY_FLAG_NEGATIVE 5 /* set if key is negative */
153
Linus Torvalds1da177e2005-04-16 15:20:36 -0700154 /* the description string
155 * - this is used to match a key against search criteria
156 * - this should be a printable string
157 * - eg: for krb5 AFS, this might be "afs@REDHAT.COM"
158 */
159 char *description;
160
161 /* type specific data
162 * - this is used by the keyring type to index the name
163 */
164 union {
165 struct list_head link;
David Howells73182262007-04-26 15:46:23 -0700166 unsigned long x[2];
167 void *p[2];
Linus Torvalds1da177e2005-04-16 15:20:36 -0700168 } type_data;
169
170 /* key data
171 * - this is used to hold the data actually used in cryptography or
172 * whatever
173 */
174 union {
175 unsigned long value;
176 void *data;
177 struct keyring_list *subscriptions;
178 } payload;
179};
180
Linus Torvalds1da177e2005-04-16 15:20:36 -0700181extern struct key *key_alloc(struct key_type *type,
182 const char *desc,
Michael LeMayd7200242006-06-22 14:47:17 -0700183 uid_t uid, gid_t gid,
184 struct task_struct *ctx,
David Howells7e047ef2006-06-26 00:24:50 -0700185 key_perm_t perm,
186 unsigned long flags);
187
188
189#define KEY_ALLOC_IN_QUOTA 0x0000 /* add to quota, reject if would overrun */
190#define KEY_ALLOC_QUOTA_OVERRUN 0x0001 /* add to quota, permit even if overrun */
191#define KEY_ALLOC_NOT_IN_QUOTA 0x0002 /* not in quota */
192
Linus Torvalds1da177e2005-04-16 15:20:36 -0700193extern void key_revoke(struct key *key);
194extern void key_put(struct key *key);
195
196static inline struct key *key_get(struct key *key)
197{
198 if (key)
199 atomic_inc(&key->usage);
200 return key;
201}
202
David Howells664cceb2005-09-28 17:03:15 +0100203static inline void key_ref_put(key_ref_t key_ref)
204{
205 key_put(key_ref_to_ptr(key_ref));
206}
207
Linus Torvalds1da177e2005-04-16 15:20:36 -0700208extern struct key *request_key(struct key_type *type,
209 const char *description,
210 const char *callout_info);
211
David Howells4e54f082006-06-29 02:24:28 -0700212extern struct key *request_key_with_auxdata(struct key_type *type,
213 const char *description,
David Howells4a38e122008-04-29 01:01:24 -0700214 const void *callout_info,
215 size_t callout_len,
David Howells4e54f082006-06-29 02:24:28 -0700216 void *aux);
217
David Howells76181c12007-10-16 23:29:46 -0700218extern struct key *request_key_async(struct key_type *type,
219 const char *description,
David Howells4a38e122008-04-29 01:01:24 -0700220 const void *callout_info,
221 size_t callout_len);
David Howells76181c12007-10-16 23:29:46 -0700222
223extern struct key *request_key_async_with_auxdata(struct key_type *type,
224 const char *description,
David Howells4a38e122008-04-29 01:01:24 -0700225 const void *callout_info,
226 size_t callout_len,
David Howells76181c12007-10-16 23:29:46 -0700227 void *aux);
228
229extern int wait_for_key_construction(struct key *key, bool intr);
230
Linus Torvalds1da177e2005-04-16 15:20:36 -0700231extern int key_validate(struct key *key);
232
David Howells664cceb2005-09-28 17:03:15 +0100233extern key_ref_t key_create_or_update(key_ref_t keyring,
234 const char *type,
235 const char *description,
236 const void *payload,
237 size_t plen,
Arun Raghavan6b79ccb2008-04-29 01:01:28 -0700238 key_perm_t perm,
David Howells7e047ef2006-06-26 00:24:50 -0700239 unsigned long flags);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700240
David Howells664cceb2005-09-28 17:03:15 +0100241extern int key_update(key_ref_t key,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700242 const void *payload,
243 size_t plen);
244
245extern int key_link(struct key *keyring,
246 struct key *key);
247
248extern int key_unlink(struct key *keyring,
249 struct key *key);
250
251extern struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
Michael LeMayd7200242006-06-22 14:47:17 -0700252 struct task_struct *ctx,
David Howells7e047ef2006-06-26 00:24:50 -0700253 unsigned long flags,
Michael LeMayd7200242006-06-22 14:47:17 -0700254 struct key *dest);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700255
256extern int keyring_clear(struct key *keyring);
257
David Howells664cceb2005-09-28 17:03:15 +0100258extern key_ref_t keyring_search(key_ref_t keyring,
259 struct key_type *type,
260 const char *description);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700261
Linus Torvalds1da177e2005-04-16 15:20:36 -0700262extern int keyring_add_key(struct key *keyring,
263 struct key *key);
264
265extern struct key *key_lookup(key_serial_t id);
266
David Howells7249db22008-04-29 01:01:34 -0700267static inline key_serial_t key_serial(struct key *key)
268{
269 return key ? key->serial : 0;
270}
Linus Torvalds1da177e2005-04-16 15:20:36 -0700271
David Howells0b77f5b2008-04-29 01:01:32 -0700272#ifdef CONFIG_SYSCTL
273extern ctl_table key_sysctls[];
274#endif
275
Linus Torvalds1da177e2005-04-16 15:20:36 -0700276/*
277 * the userspace interface
278 */
Linus Torvalds1da177e2005-04-16 15:20:36 -0700279extern void switch_uid_keyring(struct user_struct *new_user);
280extern int copy_keys(unsigned long clone_flags, struct task_struct *tsk);
281extern int copy_thread_group_keys(struct task_struct *tsk);
282extern void exit_keys(struct task_struct *tsk);
283extern void exit_thread_group_keys(struct signal_struct *tg);
284extern int suid_keys(struct task_struct *tsk);
285extern int exec_keys(struct task_struct *tsk);
286extern void key_fsuid_changed(struct task_struct *tsk);
287extern void key_fsgid_changed(struct task_struct *tsk);
288extern void key_init(void);
289
David Howells7888e7f2005-06-23 22:00:51 -0700290#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
Linus Torvalds1da177e2005-04-16 15:20:36 -0700297#else /* CONFIG_KEYS */
298
299#define key_validate(k) 0
300#define key_serial(k) 0
David Howells7888e7f2005-06-23 22:00:51 -0700301#define key_get(k) ({ NULL; })
Adrian Bunk0dab9cf2008-10-12 07:10:50 +0300302#define key_revoke(k) do { } while(0)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700303#define key_put(k) do { } while(0)
David Howells664cceb2005-09-28 17:03:15 +0100304#define key_ref_put(k) do { } while(0)
Sebastian Siewior5b7741b2008-01-08 15:32:47 -0800305#define make_key_ref(k, p) ({ NULL; })
David Howells664cceb2005-09-28 17:03:15 +0100306#define key_ref_to_ptr(k) ({ NULL; })
307#define is_key_possessed(k) 0
Linus Torvalds1da177e2005-04-16 15:20:36 -0700308#define switch_uid_keyring(u) do { } while(0)
David Howells7888e7f2005-06-23 22:00:51 -0700309#define __install_session_keyring(t, k) ({ NULL; })
Linus Torvalds1da177e2005-04-16 15:20:36 -0700310#define copy_keys(f,t) 0
311#define copy_thread_group_keys(t) 0
312#define exit_keys(t) do { } while(0)
313#define exit_thread_group_keys(tg) do { } while(0)
314#define suid_keys(t) do { } while(0)
315#define exec_keys(t) do { } while(0)
316#define key_fsuid_changed(t) do { } while(0)
317#define key_fsgid_changed(t) do { } while(0)
318#define key_init() do { } while(0)
319
Linus Torvalds1da177e2005-04-16 15:20:36 -0700320#endif /* CONFIG_KEYS */
321#endif /* __KERNEL__ */
322#endif /* _LINUX_KEY_H */