About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / keys.txt


Based on kernel version 2.6.39.1. Page generated on 2011-06-03 13:47 EST.

1				 ============================
2				 KERNEL KEY RETENTION SERVICE
3				 ============================
4	
5	This service allows cryptographic keys, authentication tokens, cross-domain
6	user mappings, and similar to be cached in the kernel for the use of
7	filesystems and other kernel services.
8	
9	Keyrings are permitted; these are a special type of key that can hold links to
10	other keys. Processes each have three standard keyring subscriptions that a
11	kernel service can search for relevant keys.
12	
13	The key service can be configured on by enabling:
14	
15		"Security options"/"Enable access key retention support" (CONFIG_KEYS)
16	
17	This document has the following sections:
18	
19		- Key overview
20		- Key service overview
21		- Key access permissions
22		- SELinux support
23		- New procfs files
24		- Userspace system call interface
25		- Kernel services
26		- Notes on accessing payload contents
27		- Defining a key type
28		- Request-key callback service
29		- Garbage collection
30	
31	
32	============
33	KEY OVERVIEW
34	============
35	
36	In this context, keys represent units of cryptographic data, authentication
37	tokens, keyrings, etc.. These are represented in the kernel by struct key.
38	
39	Each key has a number of attributes:
40	
41		- A serial number.
42		- A type.
43		- A description (for matching a key in a search).
44		- Access control information.
45		- An expiry time.
46		- A payload.
47		- State.
48	
49	
50	 (*) Each key is issued a serial number of type key_serial_t that is unique for
51	     the lifetime of that key. All serial numbers are positive non-zero 32-bit
52	     integers.
53	
54	     Userspace programs can use a key's serial numbers as a way to gain access
55	     to it, subject to permission checking.
56	
57	 (*) Each key is of a defined "type". Types must be registered inside the
58	     kernel by a kernel service (such as a filesystem) before keys of that type
59	     can be added or used. Userspace programs cannot define new types directly.
60	
61	     Key types are represented in the kernel by struct key_type. This defines a
62	     number of operations that can be performed on a key of that type.
63	
64	     Should a type be removed from the system, all the keys of that type will
65	     be invalidated.
66	
67	 (*) Each key has a description. This should be a printable string. The key
68	     type provides an operation to perform a match between the description on a
69	     key and a criterion string.
70	
71	 (*) Each key has an owner user ID, a group ID and a permissions mask. These
72	     are used to control what a process may do to a key from userspace, and
73	     whether a kernel service will be able to find the key.
74	
75	 (*) Each key can be set to expire at a specific time by the key type's
76	     instantiation function. Keys can also be immortal.
77	
78	 (*) Each key can have a payload. This is a quantity of data that represent the
79	     actual "key". In the case of a keyring, this is a list of keys to which
80	     the keyring links; in the case of a user-defined key, it's an arbitrary
81	     blob of data.
82	
83	     Having a payload is not required; and the payload can, in fact, just be a
84	     value stored in the struct key itself.
85	
86	     When a key is instantiated, the key type's instantiation function is
87	     called with a blob of data, and that then creates the key's payload in
88	     some way.
89	
90	     Similarly, when userspace wants to read back the contents of the key, if
91	     permitted, another key type operation will be called to convert the key's
92	     attached payload back into a blob of data.
93	
94	 (*) Each key can be in one of a number of basic states:
95	
96	     (*) Uninstantiated. The key exists, but does not have any data attached.
97	     	 Keys being requested from userspace will be in this state.
98	
99	     (*) Instantiated. This is the normal state. The key is fully formed, and
100		 has data attached.
101	
102	     (*) Negative. This is a relatively short-lived state. The key acts as a
103		 note saying that a previous call out to userspace failed, and acts as
104		 a throttle on key lookups. A negative key can be updated to a normal
105		 state.
106	
107	     (*) Expired. Keys can have lifetimes set. If their lifetime is exceeded,
108		 they traverse to this state. An expired key can be updated back to a
109		 normal state.
110	
111	     (*) Revoked. A key is put in this state by userspace action. It can't be
112		 found or operated upon (apart from by unlinking it).
113	
114	     (*) Dead. The key's type was unregistered, and so the key is now useless.
115	
116	Keys in the last three states are subject to garbage collection.  See the
117	section on "Garbage collection".
118	
119	
120	====================
121	KEY SERVICE OVERVIEW
122	====================
123	
124	The key service provides a number of features besides keys:
125	
126	 (*) The key service defines two special key types:
127	
128	     (+) "keyring"
129	
130		 Keyrings are special keys that contain a list of other keys. Keyring
131		 lists can be modified using various system calls. Keyrings should not
132		 be given a payload when created.
133	
134	     (+) "user"
135	
136		 A key of this type has a description and a payload that are arbitrary
137		 blobs of data. These can be created, updated and read by userspace,
138		 and aren't intended for use by kernel services.
139	
140	 (*) Each process subscribes to three keyrings: a thread-specific keyring, a
141	     process-specific keyring, and a session-specific keyring.
142	
143	     The thread-specific keyring is discarded from the child when any sort of
144	     clone, fork, vfork or execve occurs. A new keyring is created only when
145	     required.
146	
147	     The process-specific keyring is replaced with an empty one in the child on
148	     clone, fork, vfork unless CLONE_THREAD is supplied, in which case it is
149	     shared. execve also discards the process's process keyring and creates a
150	     new one.
151	
152	     The session-specific keyring is persistent across clone, fork, vfork and
153	     execve, even when the latter executes a set-UID or set-GID binary. A
154	     process can, however, replace its current session keyring with a new one
155	     by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous
156	     new one, or to attempt to create or join one of a specific name.
157	
158	     The ownership of the thread keyring changes when the real UID and GID of
159	     the thread changes.
160	
161	 (*) Each user ID resident in the system holds two special keyrings: a user
162	     specific keyring and a default user session keyring. The default session
163	     keyring is initialised with a link to the user-specific keyring.
164	
165	     When a process changes its real UID, if it used to have no session key, it
166	     will be subscribed to the default session key for the new UID.
167	
168	     If a process attempts to access its session key when it doesn't have one,
169	     it will be subscribed to the default for its current UID.
170	
171	 (*) Each user has two quotas against which the keys they own are tracked. One
172	     limits the total number of keys and keyrings, the other limits the total
173	     amount of description and payload space that can be consumed.
174	
175	     The user can view information on this and other statistics through procfs
176	     files.  The root user may also alter the quota limits through sysctl files
177	     (see the section "New procfs files").
178	
179	     Process-specific and thread-specific keyrings are not counted towards a
180	     user's quota.
181	
182	     If a system call that modifies a key or keyring in some way would put the
183	     user over quota, the operation is refused and error EDQUOT is returned.
184	
185	 (*) There's a system call interface by which userspace programs can create and
186	     manipulate keys and keyrings.
187	
188	 (*) There's a kernel interface by which services can register types and search
189	     for keys.
190	
191	 (*) There's a way for the a search done from the kernel to call back to
192	     userspace to request a key that can't be found in a process's keyrings.
193	
194	 (*) An optional filesystem is available through which the key database can be
195	     viewed and manipulated.
196	
197	
198	======================
199	KEY ACCESS PERMISSIONS
200	======================
201	
202	Keys have an owner user ID, a group access ID, and a permissions mask. The mask
203	has up to eight bits each for possessor, user, group and other access. Only
204	six of each set of eight bits are defined. These permissions granted are:
205	
206	 (*) View
207	
208	     This permits a key or keyring's attributes to be viewed - including key
209	     type and description.
210	
211	 (*) Read
212	
213	     This permits a key's payload to be viewed or a keyring's list of linked
214	     keys.
215	
216	 (*) Write
217	
218	     This permits a key's payload to be instantiated or updated, or it allows a
219	     link to be added to or removed from a keyring.
220	
221	 (*) Search
222	
223	     This permits keyrings to be searched and keys to be found. Searches can
224	     only recurse into nested keyrings that have search permission set.
225	
226	 (*) Link
227	
228	     This permits a key or keyring to be linked to. To create a link from a
229	     keyring to a key, a process must have Write permission on the keyring and
230	     Link permission on the key.
231	
232	 (*) Set Attribute
233	
234	     This permits a key's UID, GID and permissions mask to be changed.
235	
236	For changing the ownership, group ID or permissions mask, being the owner of
237	the key or having the sysadmin capability is sufficient.
238	
239	
240	===============
241	SELINUX SUPPORT
242	===============
243	
244	The security class "key" has been added to SELinux so that mandatory access
245	controls can be applied to keys created within various contexts.  This support
246	is preliminary, and is likely to change quite significantly in the near future.
247	Currently, all of the basic permissions explained above are provided in SELinux
248	as well; SELinux is simply invoked after all basic permission checks have been
249	performed.
250	
251	The value of the file /proc/self/attr/keycreate influences the labeling of
252	newly-created keys.  If the contents of that file correspond to an SELinux
253	security context, then the key will be assigned that context.  Otherwise, the
254	key will be assigned the current context of the task that invoked the key
255	creation request.  Tasks must be granted explicit permission to assign a
256	particular context to newly-created keys, using the "create" permission in the
257	key security class.
258	
259	The default keyrings associated with users will be labeled with the default
260	context of the user if and only if the login programs have been instrumented to
261	properly initialize keycreate during the login process.  Otherwise, they will
262	be labeled with the context of the login program itself.
263	
264	Note, however, that the default keyrings associated with the root user are
265	labeled with the default kernel context, since they are created early in the
266	boot process, before root has a chance to log in.
267	
268	The keyrings associated with new threads are each labeled with the context of
269	their associated thread, and both session and process keyrings are handled
270	similarly.
271	
272	
273	================
274	NEW PROCFS FILES
275	================
276	
277	Two files have been added to procfs by which an administrator can find out
278	about the status of the key service:
279	
280	 (*) /proc/keys
281	
282	     This lists the keys that are currently viewable by the task reading the
283	     file, giving information about their type, description and permissions.
284	     It is not possible to view the payload of the key this way, though some
285	     information about it may be given.
286	
287	     The only keys included in the list are those that grant View permission to
288	     the reading process whether or not it possesses them.  Note that LSM
289	     security checks are still performed, and may further filter out keys that
290	     the current process is not authorised to view.
291	
292	     The contents of the file look like this:
293	
294		SERIAL   FLAGS  USAGE EXPY PERM     UID   GID   TYPE      DESCRIPTION: SUMMARY
295		00000001 I-----    39 perm 1f3f0000     0     0 keyring   _uid_ses.0: 1/4
296		00000002 I-----     2 perm 1f3f0000     0     0 keyring   _uid.0: empty
297		00000007 I-----     1 perm 1f3f0000     0     0 keyring   _pid.1: empty
298		0000018d I-----     1 perm 1f3f0000     0     0 keyring   _pid.412: empty
299		000004d2 I--Q--     1 perm 1f3f0000    32    -1 keyring   _uid.32: 1/4
300		000004d3 I--Q--     3 perm 1f3f0000    32    -1 keyring   _uid_ses.32: empty
301		00000892 I--QU-     1 perm 1f000000     0     0 user      metal:copper: 0
302		00000893 I--Q-N     1  35s 1f3f0000     0     0 user      metal:silver: 0
303		00000894 I--Q--     1  10h 003f0000     0     0 user      metal:gold: 0
304	
305	     The flags are:
306	
307		I	Instantiated
308		R	Revoked
309		D	Dead
310		Q	Contributes to user's quota
311		U	Under construction by callback to userspace
312		N	Negative key
313	
314	     This file must be enabled at kernel configuration time as it allows anyone
315	     to list the keys database.
316	
317	 (*) /proc/key-users
318	
319	     This file lists the tracking data for each user that has at least one key
320	     on the system.  Such data includes quota information and statistics:
321	
322		[root@andromeda root]# cat /proc/key-users
323		0:     46 45/45 1/100 13/10000
324		29:     2 2/2 2/100 40/10000
325		32:     2 2/2 2/100 40/10000
326		38:     2 2/2 2/100 40/10000
327	
328	     The format of each line is
329		<UID>:			User ID to which this applies
330		<usage>			Structure refcount
331		<inst>/<keys>		Total number of keys and number instantiated
332		<keys>/<max>		Key count quota
333		<bytes>/<max>		Key size quota
334	
335	
336	Four new sysctl files have been added also for the purpose of controlling the
337	quota limits on keys:
338	
339	 (*) /proc/sys/kernel/keys/root_maxkeys
340	     /proc/sys/kernel/keys/root_maxbytes
341	
342	     These files hold the maximum number of keys that root may have and the
343	     maximum total number of bytes of data that root may have stored in those
344	     keys.
345	
346	 (*) /proc/sys/kernel/keys/maxkeys
347	     /proc/sys/kernel/keys/maxbytes
348	
349	     These files hold the maximum number of keys that each non-root user may
350	     have and the maximum total number of bytes of data that each of those
351	     users may have stored in their keys.
352	
353	Root may alter these by writing each new limit as a decimal number string to
354	the appropriate file.
355	
356	
357	===============================
358	USERSPACE SYSTEM CALL INTERFACE
359	===============================
360	
361	Userspace can manipulate keys directly through three new syscalls: add_key,
362	request_key and keyctl. The latter provides a number of functions for
363	manipulating keys.
364	
365	When referring to a key directly, userspace programs should use the key's
366	serial number (a positive 32-bit integer). However, there are some special
367	values available for referring to special keys and keyrings that relate to the
368	process making the call:
369	
370		CONSTANT			VALUE	KEY REFERENCED
371		==============================	======	===========================
372		KEY_SPEC_THREAD_KEYRING		-1	thread-specific keyring
373		KEY_SPEC_PROCESS_KEYRING	-2	process-specific keyring
374		KEY_SPEC_SESSION_KEYRING	-3	session-specific keyring
375		KEY_SPEC_USER_KEYRING		-4	UID-specific keyring
376		KEY_SPEC_USER_SESSION_KEYRING	-5	UID-session keyring
377		KEY_SPEC_GROUP_KEYRING		-6	GID-specific keyring
378		KEY_SPEC_REQKEY_AUTH_KEY	-7	assumed request_key()
379							  authorisation key
380	
381	
382	The main syscalls are:
383	
384	 (*) Create a new key of given type, description and payload and add it to the
385	     nominated keyring:
386	
387		key_serial_t add_key(const char *type, const char *desc,
388				     const void *payload, size_t plen,
389				     key_serial_t keyring);
390	
391	     If a key of the same type and description as that proposed already exists
392	     in the keyring, this will try to update it with the given payload, or it
393	     will return error EEXIST if that function is not supported by the key
394	     type. The process must also have permission to write to the key to be able
395	     to update it. The new key will have all user permissions granted and no
396	     group or third party permissions.
397	
398	     Otherwise, this will attempt to create a new key of the specified type and
399	     description, and to instantiate it with the supplied payload and attach it
400	     to the keyring. In this case, an error will be generated if the process
401	     does not have permission to write to the keyring.
402	
403	     The payload is optional, and the pointer can be NULL if not required by
404	     the type. The payload is plen in size, and plen can be zero for an empty
405	     payload.
406	
407	     A new keyring can be generated by setting type "keyring", the keyring name
408	     as the description (or NULL) and setting the payload to NULL.
409	
410	     User defined keys can be created by specifying type "user". It is
411	     recommended that a user defined key's description by prefixed with a type
412	     ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting
413	     ticket.
414	
415	     Any other type must have been registered with the kernel in advance by a
416	     kernel service such as a filesystem.
417	
418	     The ID of the new or updated key is returned if successful.
419	
420	
421	 (*) Search the process's keyrings for a key, potentially calling out to
422	     userspace to create it.
423	
424		key_serial_t request_key(const char *type, const char *description,
425					 const char *callout_info,
426					 key_serial_t dest_keyring);
427	
428	     This function searches all the process's keyrings in the order thread,
429	     process, session for a matching key. This works very much like
430	     KEYCTL_SEARCH, including the optional attachment of the discovered key to
431	     a keyring.
432	
433	     If a key cannot be found, and if callout_info is not NULL, then
434	     /sbin/request-key will be invoked in an attempt to obtain a key. The
435	     callout_info string will be passed as an argument to the program.
436	
437	     See also Documentation/keys-request-key.txt.
438	
439	
440	The keyctl syscall functions are:
441	
442	 (*) Map a special key ID to a real key ID for this process:
443	
444		key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id,
445				    int create);
446	
447	     The special key specified by "id" is looked up (with the key being created
448	     if necessary) and the ID of the key or keyring thus found is returned if
449	     it exists.
450	
451	     If the key does not yet exist, the key will be created if "create" is
452	     non-zero; and the error ENOKEY will be returned if "create" is zero.
453	
454	
455	 (*) Replace the session keyring this process subscribes to with a new one:
456	
457		key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name);
458	
459	     If name is NULL, an anonymous keyring is created attached to the process
460	     as its session keyring, displacing the old session keyring.
461	
462	     If name is not NULL, if a keyring of that name exists, the process
463	     attempts to attach it as the session keyring, returning an error if that
464	     is not permitted; otherwise a new keyring of that name is created and
465	     attached as the session keyring.
466	
467	     To attach to a named keyring, the keyring must have search permission for
468	     the process's ownership.
469	
470	     The ID of the new session keyring is returned if successful.
471	
472	
473	 (*) Update the specified key:
474	
475		long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload,
476			    size_t plen);
477	
478	     This will try to update the specified key with the given payload, or it
479	     will return error EOPNOTSUPP if that function is not supported by the key
480	     type. The process must also have permission to write to the key to be able
481	     to update it.
482	
483	     The payload is of length plen, and may be absent or empty as for
484	     add_key().
485	
486	
487	 (*) Revoke a key:
488	
489		long keyctl(KEYCTL_REVOKE, key_serial_t key);
490	
491	     This makes a key unavailable for further operations. Further attempts to
492	     use the key will be met with error EKEYREVOKED, and the key will no longer
493	     be findable.
494	
495	
496	 (*) Change the ownership of a key:
497	
498		long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);
499	
500	     This function permits a key's owner and group ID to be changed. Either one
501	     of uid or gid can be set to -1 to suppress that change.
502	
503	     Only the superuser can change a key's owner to something other than the
504	     key's current owner. Similarly, only the superuser can change a key's
505	     group ID to something other than the calling process's group ID or one of
506	     its group list members.
507	
508	
509	 (*) Change the permissions mask on a key:
510	
511		long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm);
512	
513	     This function permits the owner of a key or the superuser to change the
514	     permissions mask on a key.
515	
516	     Only bits the available bits are permitted; if any other bits are set,
517	     error EINVAL will be returned.
518	
519	
520	 (*) Describe a key:
521	
522		long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer,
523			    size_t buflen);
524	
525	     This function returns a summary of the key's attributes (but not its
526	     payload data) as a string in the buffer provided.
527	
528	     Unless there's an error, it always returns the amount of data it could
529	     produce, even if that's too big for the buffer, but it won't copy more
530	     than requested to userspace. If the buffer pointer is NULL then no copy
531	     will take place.
532	
533	     A process must have view permission on the key for this function to be
534	     successful.
535	
536	     If successful, a string is placed in the buffer in the following format:
537	
538		<type>;<uid>;<gid>;<perm>;<description>
539	
540	     Where type and description are strings, uid and gid are decimal, and perm
541	     is hexadecimal. A NUL character is included at the end of the string if
542	     the buffer is sufficiently big.
543	
544	     This can be parsed with
545	
546		sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc);
547	
548	
549	 (*) Clear out a keyring:
550	
551		long keyctl(KEYCTL_CLEAR, key_serial_t keyring);
552	
553	     This function clears the list of keys attached to a keyring. The calling
554	     process must have write permission on the keyring, and it must be a
555	     keyring (or else error ENOTDIR will result).
556	
557	
558	 (*) Link a key into a keyring:
559	
560		long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);
561	
562	     This function creates a link from the keyring to the key. The process must
563	     have write permission on the keyring and must have link permission on the
564	     key.
565	
566	     Should the keyring not be a keyring, error ENOTDIR will result; and if the
567	     keyring is full, error ENFILE will result.
568	
569	     The link procedure checks the nesting of the keyrings, returning ELOOP if
570	     it appears too deep or EDEADLK if the link would introduce a cycle.
571	
572	     Any links within the keyring to keys that match the new key in terms of
573	     type and description will be discarded from the keyring as the new one is
574	     added.
575	
576	
577	 (*) Unlink a key or keyring from another keyring:
578	
579		long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key);
580	
581	     This function looks through the keyring for the first link to the
582	     specified key, and removes it if found. Subsequent links to that key are
583	     ignored. The process must have write permission on the keyring.
584	
585	     If the keyring is not a keyring, error ENOTDIR will result; and if the key
586	     is not present, error ENOENT will be the result.
587	
588	
589	 (*) Search a keyring tree for a key:
590	
591		key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring,
592				    const char *type, const char *description,
593				    key_serial_t dest_keyring);
594	
595	     This searches the keyring tree headed by the specified keyring until a key
596	     is found that matches the type and description criteria. Each keyring is
597	     checked for keys before recursion into its children occurs.
598	
599	     The process must have search permission on the top level keyring, or else
600	     error EACCES will result. Only keyrings that the process has search
601	     permission on will be recursed into, and only keys and keyrings for which
602	     a process has search permission can be matched. If the specified keyring
603	     is not a keyring, ENOTDIR will result.
604	
605	     If the search succeeds, the function will attempt to link the found key
606	     into the destination keyring if one is supplied (non-zero ID). All the
607	     constraints applicable to KEYCTL_LINK apply in this case too.
608	
609	     Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search
610	     fails. On success, the resulting key ID will be returned.
611	
612	
613	 (*) Read the payload data from a key:
614	
615		long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer,
616			    size_t buflen);
617	
618	     This function attempts to read the payload data from the specified key
619	     into the buffer. The process must have read permission on the key to
620	     succeed.
621	
622	     The returned data will be processed for presentation by the key type. For
623	     instance, a keyring will return an array of key_serial_t entries
624	     representing the IDs of all the keys to which it is subscribed. The user
625	     defined key type will return its data as is. If a key type does not
626	     implement this function, error EOPNOTSUPP will result.
627	
628	     As much of the data as can be fitted into the buffer will be copied to
629	     userspace if the buffer pointer is not NULL.
630	
631	     On a successful return, the function will always return the amount of data
632	     available rather than the amount copied.
633	
634	
635	 (*) Instantiate a partially constructed key.
636	
637		long keyctl(KEYCTL_INSTANTIATE, key_serial_t key,
638			    const void *payload, size_t plen,
639			    key_serial_t keyring);
640		long keyctl(KEYCTL_INSTANTIATE_IOV, key_serial_t key,
641			    const struct iovec *payload_iov, unsigned ioc,
642			    key_serial_t keyring);
643	
644	     If the kernel calls back to userspace to complete the instantiation of a
645	     key, userspace should use this call to supply data for the key before the
646	     invoked process returns, or else the key will be marked negative
647	     automatically.
648	
649	     The process must have write access on the key to be able to instantiate
650	     it, and the key must be uninstantiated.
651	
652	     If a keyring is specified (non-zero), the key will also be linked into
653	     that keyring, however all the constraints applying in KEYCTL_LINK apply in
654	     this case too.
655	
656	     The payload and plen arguments describe the payload data as for add_key().
657	
658	     The payload_iov and ioc arguments describe the payload data in an iovec
659	     array instead of a single buffer.
660	
661	
662	 (*) Negatively instantiate a partially constructed key.
663	
664		long keyctl(KEYCTL_NEGATE, key_serial_t key,
665			    unsigned timeout, key_serial_t keyring);
666		long keyctl(KEYCTL_REJECT, key_serial_t key,
667			    unsigned timeout, unsigned error, key_serial_t keyring);
668	
669	     If the kernel calls back to userspace to complete the instantiation of a
670	     key, userspace should use this call mark the key as negative before the
671	     invoked process returns if it is unable to fulfil the request.
672	
673	     The process must have write access on the key to be able to instantiate
674	     it, and the key must be uninstantiated.
675	
676	     If a keyring is specified (non-zero), the key will also be linked into
677	     that keyring, however all the constraints applying in KEYCTL_LINK apply in
678	     this case too.
679	
680	     If the key is rejected, future searches for it will return the specified
681	     error code until the rejected key expires.  Negating the key is the same
682	     as rejecting the key with ENOKEY as the error code.
683	
684	
685	 (*) Set the default request-key destination keyring.
686	
687		long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl);
688	
689	     This sets the default keyring to which implicitly requested keys will be
690	     attached for this thread. reqkey_defl should be one of these constants:
691	
692		CONSTANT				VALUE	NEW DEFAULT KEYRING
693		======================================	======	=======================
694		KEY_REQKEY_DEFL_NO_CHANGE		-1	No change
695		KEY_REQKEY_DEFL_DEFAULT			0	Default[1]
696		KEY_REQKEY_DEFL_THREAD_KEYRING		1	Thread keyring
697		KEY_REQKEY_DEFL_PROCESS_KEYRING		2	Process keyring
698		KEY_REQKEY_DEFL_SESSION_KEYRING		3	Session keyring
699		KEY_REQKEY_DEFL_USER_KEYRING		4	User keyring
700		KEY_REQKEY_DEFL_USER_SESSION_KEYRING	5	User session keyring
701		KEY_REQKEY_DEFL_GROUP_KEYRING		6	Group keyring
702	
703	     The old default will be returned if successful and error EINVAL will be
704	     returned if reqkey_defl is not one of the above values.
705	
706	     The default keyring can be overridden by the keyring indicated to the
707	     request_key() system call.
708	
709	     Note that this setting is inherited across fork/exec.
710	
711	     [1] The default is: the thread keyring if there is one, otherwise
712	     the process keyring if there is one, otherwise the session keyring if
713	     there is one, otherwise the user default session keyring.
714	
715	
716	 (*) Set the timeout on a key.
717	
718		long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout);
719	
720	     This sets or clears the timeout on a key. The timeout can be 0 to clear
721	     the timeout or a number of seconds to set the expiry time that far into
722	     the future.
723	
724	     The process must have attribute modification access on a key to set its
725	     timeout. Timeouts may not be set with this function on negative, revoked
726	     or expired keys.
727	
728	
729	 (*) Assume the authority granted to instantiate a key
730	
731		long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key);
732	
733	     This assumes or divests the authority required to instantiate the
734	     specified key. Authority can only be assumed if the thread has the
735	     authorisation key associated with the specified key in its keyrings
736	     somewhere.
737	
738	     Once authority is assumed, searches for keys will also search the
739	     requester's keyrings using the requester's security label, UID, GID and
740	     groups.
741	
742	     If the requested authority is unavailable, error EPERM will be returned,
743	     likewise if the authority has been revoked because the target key is
744	     already instantiated.
745	
746	     If the specified key is 0, then any assumed authority will be divested.
747	
748	     The assumed authoritative key is inherited across fork and exec.
749	
750	
751	 (*) Get the LSM security context attached to a key.
752	
753		long keyctl(KEYCTL_GET_SECURITY, key_serial_t key, char *buffer,
754			    size_t buflen)
755	
756	     This function returns a string that represents the LSM security context
757	     attached to a key in the buffer provided.
758	
759	     Unless there's an error, it always returns the amount of data it could
760	     produce, even if that's too big for the buffer, but it won't copy more
761	     than requested to userspace. If the buffer pointer is NULL then no copy
762	     will take place.
763	
764	     A NUL character is included at the end of the string if the buffer is
765	     sufficiently big.  This is included in the returned count.  If no LSM is
766	     in force then an empty string will be returned.
767	
768	     A process must have view permission on the key for this function to be
769	     successful.
770	
771	
772	 (*) Install the calling process's session keyring on its parent.
773	
774		long keyctl(KEYCTL_SESSION_TO_PARENT);
775	
776	     This functions attempts to install the calling process's session keyring
777	     on to the calling process's parent, replacing the parent's current session
778	     keyring.
779	
780	     The calling process must have the same ownership as its parent, the
781	     keyring must have the same ownership as the calling process, the calling
782	     process must have LINK permission on the keyring and the active LSM module
783	     mustn't deny permission, otherwise error EPERM will be returned.
784	
785	     Error ENOMEM will be returned if there was insufficient memory to complete
786	     the operation, otherwise 0 will be returned to indicate success.
787	
788	     The keyring will be replaced next time the parent process leaves the
789	     kernel and resumes executing userspace.
790	
791	
792	===============
793	KERNEL SERVICES
794	===============
795	
796	The kernel services for key management are fairly simple to deal with. They can
797	be broken down into two areas: keys and key types.
798	
799	Dealing with keys is fairly straightforward. Firstly, the kernel service
800	registers its type, then it searches for a key of that type. It should retain
801	the key as long as it has need of it, and then it should release it. For a
802	filesystem or device file, a search would probably be performed during the open
803	call, and the key released upon close. How to deal with conflicting keys due to
804	two different users opening the same file is left to the filesystem author to
805	solve.
806	
807	To access the key manager, the following header must be #included:
808	
809		<linux/key.h>
810	
811	Specific key types should have a header file under include/keys/ that should be
812	used to access that type.  For keys of type "user", for example, that would be:
813	
814		<keys/user-type.h>
815	
816	Note that there are two different types of pointers to keys that may be
817	encountered:
818	
819	 (*) struct key *
820	
821	     This simply points to the key structure itself. Key structures will be at
822	     least four-byte aligned.
823	
824	 (*) key_ref_t
825	
826	     This is equivalent to a struct key *, but the least significant bit is set
827	     if the caller "possesses" the key. By "possession" it is meant that the
828	     calling processes has a searchable link to the key from one of its
829	     keyrings. There are three functions for dealing with these:
830	
831		key_ref_t make_key_ref(const struct key *key,
832				       unsigned long possession);
833	
834		struct key *key_ref_to_ptr(const key_ref_t key_ref);
835	
836		unsigned long is_key_possessed(const key_ref_t key_ref);
837	
838	     The first function constructs a key reference from a key pointer and
839	     possession information (which must be 0 or 1 and not any other value).
840	
841	     The second function retrieves the key pointer from a reference and the
842	     third retrieves the possession flag.
843	
844	When accessing a key's payload contents, certain precautions must be taken to
845	prevent access vs modification races. See the section "Notes on accessing
846	payload contents" for more information.
847	
848	(*) To search for a key, call:
849	
850		struct key *request_key(const struct key_type *type,
851					const char *description,
852					const char *callout_info);
853	
854	    This is used to request a key or keyring with a description that matches
855	    the description specified according to the key type's match function. This
856	    permits approximate matching to occur. If callout_string is not NULL, then
857	    /sbin/request-key will be invoked in an attempt to obtain the key from
858	    userspace. In that case, callout_string will be passed as an argument to
859	    the program.
860	
861	    Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be
862	    returned.
863	
864	    If successful, the key will have been attached to the default keyring for
865	    implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING.
866	
867	    See also Documentation/keys-request-key.txt.
868	
869	
870	(*) To search for a key, passing auxiliary data to the upcaller, call:
871	
872		struct key *request_key_with_auxdata(const struct key_type *type,
873						     const char *description,
874						     const void *callout_info,
875						     size_t callout_len,
876						     void *aux);
877	
878	    This is identical to request_key(), except that the auxiliary data is
879	    passed to the key_type->request_key() op if it exists, and the callout_info
880	    is a blob of length callout_len, if given (the length may be 0).
881	
882	
883	(*) A key can be requested asynchronously by calling one of:
884	
885		struct key *request_key_async(const struct key_type *type,
886					      const char *description,
887					      const void *callout_info,
888					      size_t callout_len);
889	
890	    or:
891	
892		struct key *request_key_async_with_auxdata(const struct key_type *type,
893							   const char *description,
894							   const char *callout_info,
895						     	   size_t callout_len,
896						     	   void *aux);
897	
898	    which are asynchronous equivalents of request_key() and
899	    request_key_with_auxdata() respectively.
900	
901	    These two functions return with the key potentially still under
902	    construction.  To wait for construction completion, the following should be
903	    called:
904	
905		int wait_for_key_construction(struct key *key, bool intr);
906	
907	    The function will wait for the key to finish being constructed and then
908	    invokes key_validate() to return an appropriate value to indicate the state
909	    of the key (0 indicates the key is usable).
910	
911	    If intr is true, then the wait can be interrupted by a signal, in which
912	    case error ERESTARTSYS will be returned.
913	
914	
915	(*) When it is no longer required, the key should be released using:
916	
917		void key_put(struct key *key);
918	
919	    Or:
920	
921		void key_ref_put(key_ref_t key_ref);
922	
923	    These can be called from interrupt context. If CONFIG_KEYS is not set then
924	    the argument will not be parsed.
925	
926	
927	(*) Extra references can be made to a key by calling the following function:
928	
929		struct key *key_get(struct key *key);
930	
931	    These need to be disposed of by calling key_put() when they've been
932	    finished with. The key pointer passed in will be returned. If the pointer
933	    is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and
934	    no increment will take place.
935	
936	
937	(*) A key's serial number can be obtained by calling:
938	
939		key_serial_t key_serial(struct key *key);
940	
941	    If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the
942	    latter case without parsing the argument).
943	
944	
945	(*) If a keyring was found in the search, this can be further searched by:
946	
947		key_ref_t keyring_search(key_ref_t keyring_ref,
948					 const struct key_type *type,
949					 const char *description)
950	
951	    This searches the keyring tree specified for a matching key. Error ENOKEY
952	    is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful,
953	    the returned key will need to be released.
954	
955	    The possession attribute from the keyring reference is used to control
956	    access through the permissions mask and is propagated to the returned key
957	    reference pointer if successful.
958	
959	
960	(*) To check the validity of a key, this function can be called:
961	
962		int validate_key(struct key *key);
963	
964	    This checks that the key in question hasn't expired or and hasn't been
965	    revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will
966	    be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be
967	    returned (in the latter case without parsing the argument).
968	
969	
970	(*) To register a key type, the following function should be called:
971	
972		int register_key_type(struct key_type *type);
973	
974	    This will return error EEXIST if a type of the same name is already
975	    present.
976	
977	
978	(*) To unregister a key type, call:
979	
980		void unregister_key_type(struct key_type *type);
981	
982	
983	Under some circumstances, it may be desirable to deal with a bundle of keys.
984	The facility provides access to the keyring type for managing such a bundle:
985	
986		struct key_type key_type_keyring;
987	
988	This can be used with a function such as request_key() to find a specific
989	keyring in a process's keyrings.  A keyring thus found can then be searched
990	with keyring_search().  Note that it is not possible to use request_key() to
991	search a specific keyring, so using keyrings in this way is of limited utility.
992	
993	
994	===================================
995	NOTES ON ACCESSING PAYLOAD CONTENTS
996	===================================
997	
998	The simplest payload is just a number in key->payload.value. In this case,
999	there's no need to indulge in RCU or locking when accessing the payload.
1000	
1001	More complex payload contents must be allocated and a pointer to them set in
1002	key->payload.data. One of the following ways must be selected to access the
1003	data:
1004	
1005	 (1) Unmodifiable key type.
1006	
1007	     If the key type does not have a modify method, then the key's payload can
1008	     be accessed without any form of locking, provided that it's known to be
1009	     instantiated (uninstantiated keys cannot be "found").
1010	
1011	 (2) The key's semaphore.
1012	
1013	     The semaphore could be used to govern access to the payload and to control
1014	     the payload pointer. It must be write-locked for modifications and would
1015	     have to be read-locked for general access. The disadvantage of doing this
1016	     is that the accessor may be required to sleep.
1017	
1018	 (3) RCU.
1019	
1020	     RCU must be used when the semaphore isn't already held; if the semaphore
1021	     is held then the contents can't change under you unexpectedly as the
1022	     semaphore must still be used to serialise modifications to the key. The
1023	     key management code takes care of this for the key type.
1024	
1025	     However, this means using:
1026	
1027		rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock()
1028	
1029	     to read the pointer, and:
1030	
1031		rcu_dereference() ... rcu_assign_pointer() ... call_rcu()
1032	
1033	     to set the pointer and dispose of the old contents after a grace period.
1034	     Note that only the key type should ever modify a key's payload.
1035	
1036	     Furthermore, an RCU controlled payload must hold a struct rcu_head for the
1037	     use of call_rcu() and, if the payload is of variable size, the length of
1038	     the payload. key->datalen cannot be relied upon to be consistent with the
1039	     payload just dereferenced if the key's semaphore is not held.
1040	
1041	
1042	===================
1043	DEFINING A KEY TYPE
1044	===================
1045	
1046	A kernel service may want to define its own key type. For instance, an AFS
1047	filesystem might want to define a Kerberos 5 ticket key type. To do this, it
1048	author fills in a key_type struct and registers it with the system.
1049	
1050	Source files that implement key types should include the following header file:
1051	
1052		<linux/key-type.h>
1053	
1054	The structure has a number of fields, some of which are mandatory:
1055	
1056	 (*) const char *name
1057	
1058	     The name of the key type. This is used to translate a key type name
1059	     supplied by userspace into a pointer to the structure.
1060	
1061	
1062	 (*) size_t def_datalen
1063	
1064	     This is optional - it supplies the default payload data length as
1065	     contributed to the quota. If the key type's payload is always or almost
1066	     always the same size, then this is a more efficient way to do things.
1067	
1068	     The data length (and quota) on a particular key can always be changed
1069	     during instantiation or update by calling:
1070	
1071		int key_payload_reserve(struct key *key, size_t datalen);
1072	
1073	     With the revised data length. Error EDQUOT will be returned if this is not
1074	     viable.
1075	
1076	
1077	 (*) int (*vet_description)(const char *description);
1078	
1079	     This optional method is called to vet a key description.  If the key type
1080	     doesn't approve of the key description, it may return an error, otherwise
1081	     it should return 0.
1082	
1083	
1084	 (*) int (*instantiate)(struct key *key, const void *data, size_t datalen);
1085	
1086	     This method is called to attach a payload to a key during construction.
1087	     The payload attached need not bear any relation to the data passed to this
1088	     function.
1089	
1090	     If the amount of data attached to the key differs from the size in
1091	     keytype->def_datalen, then key_payload_reserve() should be called.
1092	
1093	     This method does not have to lock the key in order to attach a payload.
1094	     The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
1095	     anything else from gaining access to the key.
1096	
1097	     It is safe to sleep in this method.
1098	
1099	
1100	 (*) int (*update)(struct key *key, const void *data, size_t datalen);
1101	
1102	     If this type of key can be updated, then this method should be provided.
1103	     It is called to update a key's payload from the blob of data provided.
1104	
1105	     key_payload_reserve() should be called if the data length might change
1106	     before any changes are actually made. Note that if this succeeds, the type
1107	     is committed to changing the key because it's already been altered, so all
1108	     memory allocation must be done first.
1109	
1110	     The key will have its semaphore write-locked before this method is called,
1111	     but this only deters other writers; any changes to the key's payload must
1112	     be made under RCU conditions, and call_rcu() must be used to dispose of
1113	     the old payload.
1114	
1115	     key_payload_reserve() should be called before the changes are made, but
1116	     after all allocations and other potentially failing function calls are
1117	     made.
1118	
1119	     It is safe to sleep in this method.
1120	
1121	
1122	 (*) int (*match)(const struct key *key, const void *desc);
1123	
1124	     This method is called to match a key against a description. It should
1125	     return non-zero if the two match, zero if they don't.
1126	
1127	     This method should not need to lock the key in any way. The type and
1128	     description can be considered invariant, and the payload should not be
1129	     accessed (the key may not yet be instantiated).
1130	
1131	     It is not safe to sleep in this method; the caller may hold spinlocks.
1132	
1133	
1134	 (*) void (*revoke)(struct key *key);
1135	
1136	     This method is optional.  It is called to discard part of the payload
1137	     data upon a key being revoked.  The caller will have the key semaphore
1138	     write-locked.
1139	
1140	     It is safe to sleep in this method, though care should be taken to avoid
1141	     a deadlock against the key semaphore.
1142	
1143	
1144	 (*) void (*destroy)(struct key *key);
1145	
1146	     This method is optional. It is called to discard the payload data on a key
1147	     when it is being destroyed.
1148	
1149	     This method does not need to lock the key to access the payload; it can
1150	     consider the key as being inaccessible at this time. Note that the key's
1151	     type may have been changed before this function is called.
1152	
1153	     It is not safe to sleep in this method; the caller may hold spinlocks.
1154	
1155	
1156	 (*) void (*describe)(const struct key *key, struct seq_file *p);
1157	
1158	     This method is optional. It is called during /proc/keys reading to
1159	     summarise a key's description and payload in text form.
1160	
1161	     This method will be called with the RCU read lock held. rcu_dereference()
1162	     should be used to read the payload pointer if the payload is to be
1163	     accessed. key->datalen cannot be trusted to stay consistent with the
1164	     contents of the payload.
1165	
1166	     The description will not change, though the key's state may.
1167	
1168	     It is not safe to sleep in this method; the RCU read lock is held by the
1169	     caller.
1170	
1171	
1172	 (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen);
1173	
1174	     This method is optional. It is called by KEYCTL_READ to translate the
1175	     key's payload into something a blob of data for userspace to deal with.
1176	     Ideally, the blob should be in the same format as that passed in to the
1177	     instantiate and update methods.
1178	
1179	     If successful, the blob size that could be produced should be returned
1180	     rather than the size copied.
1181	
1182	     This method will be called with the key's semaphore read-locked. This will
1183	     prevent the key's payload changing. It is not necessary to use RCU locking
1184	     when accessing the key's payload. It is safe to sleep in this method, such
1185	     as might happen when the userspace buffer is accessed.
1186	
1187	
1188	 (*) int (*request_key)(struct key_construction *cons, const char *op,
1189				void *aux);
1190	
1191	     This method is optional.  If provided, request_key() and friends will
1192	     invoke this function rather than upcalling to /sbin/request-key to operate
1193	     upon a key of this type.
1194	
1195	     The aux parameter is as passed to request_key_async_with_auxdata() and
1196	     similar or is NULL otherwise.  Also passed are the construction record for
1197	     the key to be operated upon and the operation type (currently only
1198	     "create").
1199	
1200	     This method is permitted to return before the upcall is complete, but the
1201	     following function must be called under all circumstances to complete the
1202	     instantiation process, whether or not it succeeds, whether or not there's
1203	     an error:
1204	
1205		void complete_request_key(struct key_construction *cons, int error);
1206	
1207	     The error parameter should be 0 on success, -ve on error.  The
1208	     construction record is destroyed by this action and the authorisation key
1209	     will be revoked.  If an error is indicated, the key under construction
1210	     will be negatively instantiated if it wasn't already instantiated.
1211	
1212	     If this method returns an error, that error will be returned to the
1213	     caller of request_key*().  complete_request_key() must be called prior to
1214	     returning.
1215	
1216	     The key under construction and the authorisation key can be found in the
1217	     key_construction struct pointed to by cons:
1218	
1219	     (*) struct key *key;
1220	
1221	     	 The key under construction.
1222	
1223	     (*) struct key *authkey;
1224	
1225	     	 The authorisation key.
1226	
1227	
1228	============================
1229	REQUEST-KEY CALLBACK SERVICE
1230	============================
1231	
1232	To create a new key, the kernel will attempt to execute the following command
1233	line:
1234	
1235		/sbin/request-key create <key> <uid> <gid> \
1236			<threadring> <processring> <sessionring> <callout_info>
1237	
1238	<key> is the key being constructed, and the three keyrings are the process
1239	keyrings from the process that caused the search to be issued. These are
1240	included for two reasons:
1241	
1242	  (1) There may be an authentication token in one of the keyrings that is
1243	      required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
1244	
1245	  (2) The new key should probably be cached in one of these rings.
1246	
1247	This program should set it UID and GID to those specified before attempting to
1248	access any more keys. It may then look around for a user specific process to
1249	hand the request off to (perhaps a path held in placed in another key by, for
1250	example, the KDE desktop manager).
1251	
1252	The program (or whatever it calls) should finish construction of the key by
1253	calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to
1254	cache the key in one of the keyrings (probably the session ring) before
1255	returning.  Alternatively, the key can be marked as negative with KEYCTL_NEGATE
1256	or KEYCTL_REJECT; this also permits the key to be cached in one of the
1257	keyrings.
1258	
1259	If it returns with the key remaining in the unconstructed state, the key will
1260	be marked as being negative, it will be added to the session keyring, and an
1261	error will be returned to the key requestor.
1262	
1263	Supplementary information may be provided from whoever or whatever invoked this
1264	service. This will be passed as the <callout_info> parameter. If no such
1265	information was made available, then "-" will be passed as this parameter
1266	instead.
1267	
1268	
1269	Similarly, the kernel may attempt to update an expired or a soon to expire key
1270	by executing:
1271	
1272		/sbin/request-key update <key> <uid> <gid> \
1273			<threadring> <processring> <sessionring>
1274	
1275	In this case, the program isn't required to actually attach the key to a ring;
1276	the rings are provided for reference.
1277	
1278	
1279	==================
1280	GARBAGE COLLECTION
1281	==================
1282	
1283	Dead keys (for which the type has been removed) will be automatically unlinked
1284	from those keyrings that point to them and deleted as soon as possible by a
1285	background garbage collector.
1286	
1287	Similarly, revoked and expired keys will be garbage collected, but only after a
1288	certain amount of time has passed.  This time is set as a number of seconds in:
1289	
1290		/proc/sys/kernel/keys/gc_delay
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog