Merge branch 'upstream-davem' of master.kernel.org:/pub/scm/linux/kernel/git/jgarzik...
[linux-2.6] / include / linux / key.h
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/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>
21 #include <linux/rcupdate.h>
22 #include <linux/sysctl.h>
23 #include <asm/atomic.h>
24
25 #ifdef __KERNEL__
26
27 /* key handle serial number */
28 typedef int32_t key_serial_t;
29
30 /* key handle permissions mask */
31 typedef uint32_t key_perm_t;
32
33 struct key;
34
35 #ifdef CONFIG_KEYS
36
37 #undef KEY_DEBUGGING
38
39 #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 */
44 #define KEY_POS_SETATTR 0x20000000      /* possessor can set key attributes */
45 #define KEY_POS_ALL     0x3f000000
46
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
52 #define KEY_USR_SETATTR 0x00200000
53 #define KEY_USR_ALL     0x003f0000
54
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
60 #define KEY_GRP_SETATTR 0x00002000
61 #define KEY_GRP_ALL     0x00003f00
62
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
68 #define KEY_OTH_SETATTR 0x00000020
69 #define KEY_OTH_ALL     0x0000003f
70
71 #define KEY_PERM_UNDEF  0xffffffff
72
73 struct seq_file;
74 struct user_struct;
75 struct signal_struct;
76
77 struct key_type;
78 struct key_owner;
79 struct keyring_list;
80 struct keyring_name;
81
82 /*****************************************************************************/
83 /*
84  * 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  */
96 typedef struct __key_reference_with_attributes *key_ref_t;
97
98 static 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
104 static 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
109 static inline unsigned long is_key_possessed(const key_ref_t key_ref)
110 {
111         return (unsigned long) key_ref & 1UL;
112 }
113
114 /*****************************************************************************/
115 /*
116  * authentication token / access credential / keyring
117  * - types of key include:
118  *   - keyrings
119  *   - disk encryption IDs
120  *   - Kerberos TGTs and tickets
121  */
122 struct 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 */
127         struct rw_semaphore     sem;            /* change vs change sem */
128         struct key_user         *user;          /* owner of this key */
129         void                    *security;      /* security data for this key */
130         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 */
135         unsigned short          datalen;        /* payload data length
136                                                  * - may not match RCU dereferenced payload
137                                                  * - payload should contain own length
138                                                  */
139
140 #ifdef KEY_DEBUGGING
141         unsigned                magic;
142 #define KEY_DEBUG_MAGIC         0x18273645u
143 #define KEY_DEBUG_MAGIC_X       0xf8e9dacbu
144 #endif
145
146         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
154         /* 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;
166                 unsigned long           x[2];
167                 void                    *p[2];
168         } 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
181 extern struct key *key_alloc(struct key_type *type,
182                              const char *desc,
183                              uid_t uid, gid_t gid,
184                              struct task_struct *ctx,
185                              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
193 extern void key_revoke(struct key *key);
194 extern void key_put(struct key *key);
195
196 static inline struct key *key_get(struct key *key)
197 {
198         if (key)
199                 atomic_inc(&key->usage);
200         return key;
201 }
202
203 static inline void key_ref_put(key_ref_t key_ref)
204 {
205         key_put(key_ref_to_ptr(key_ref));
206 }
207
208 extern struct key *request_key(struct key_type *type,
209                                const char *description,
210                                const char *callout_info);
211
212 extern struct key *request_key_with_auxdata(struct key_type *type,
213                                             const char *description,
214                                             const void *callout_info,
215                                             size_t callout_len,
216                                             void *aux);
217
218 extern struct key *request_key_async(struct key_type *type,
219                                      const char *description,
220                                      const void *callout_info,
221                                      size_t callout_len);
222
223 extern struct key *request_key_async_with_auxdata(struct key_type *type,
224                                                   const char *description,
225                                                   const void *callout_info,
226                                                   size_t callout_len,
227                                                   void *aux);
228
229 extern int wait_for_key_construction(struct key *key, bool intr);
230
231 extern int key_validate(struct key *key);
232
233 extern 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,
238                                       key_perm_t perm,
239                                       unsigned long flags);
240
241 extern int key_update(key_ref_t key,
242                       const void *payload,
243                       size_t plen);
244
245 extern int key_link(struct key *keyring,
246                     struct key *key);
247
248 extern int key_unlink(struct key *keyring,
249                       struct key *key);
250
251 extern struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
252                                  struct task_struct *ctx,
253                                  unsigned long flags,
254                                  struct key *dest);
255
256 extern int keyring_clear(struct key *keyring);
257
258 extern key_ref_t keyring_search(key_ref_t keyring,
259                                 struct key_type *type,
260                                 const char *description);
261
262 extern int keyring_add_key(struct key *keyring,
263                            struct key *key);
264
265 extern struct key *key_lookup(key_serial_t id);
266
267 static inline key_serial_t key_serial(struct key *key)
268 {
269         return key ? key->serial : 0;
270 }
271
272 #ifdef CONFIG_SYSCTL
273 extern ctl_table key_sysctls[];
274 #endif
275
276 /*
277  * the userspace interface
278  */
279 extern void switch_uid_keyring(struct user_struct *new_user);
280 extern int copy_keys(unsigned long clone_flags, struct task_struct *tsk);
281 extern int copy_thread_group_keys(struct task_struct *tsk);
282 extern void exit_keys(struct task_struct *tsk);
283 extern void exit_thread_group_keys(struct signal_struct *tg);
284 extern int suid_keys(struct task_struct *tsk);
285 extern int exec_keys(struct task_struct *tsk);
286 extern void key_fsuid_changed(struct task_struct *tsk);
287 extern void key_fsgid_changed(struct task_struct *tsk);
288 extern void key_init(void);
289
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
297 #else /* CONFIG_KEYS */
298
299 #define key_validate(k)                 0
300 #define key_serial(k)                   0
301 #define key_get(k)                      ({ NULL; })
302 #define key_put(k)                      do { } while(0)
303 #define key_ref_put(k)                  do { } while(0)
304 #define make_key_ref(k, p)                      ({ NULL; })
305 #define key_ref_to_ptr(k)               ({ NULL; })
306 #define is_key_possessed(k)             0
307 #define switch_uid_keyring(u)           do { } while(0)
308 #define __install_session_keyring(t, k) ({ NULL; })
309 #define copy_keys(f,t)                  0
310 #define copy_thread_group_keys(t)       0
311 #define exit_keys(t)                    do { } while(0)
312 #define exit_thread_group_keys(tg)      do { } while(0)
313 #define suid_keys(t)                    do { } while(0)
314 #define exec_keys(t)                    do { } while(0)
315 #define key_fsuid_changed(t)            do { } while(0)
316 #define key_fsgid_changed(t)            do { } while(0)
317 #define key_init()                      do { } while(0)
318
319 #endif /* CONFIG_KEYS */
320 #endif /* __KERNEL__ */
321 #endif /* _LINUX_KEY_H */