About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / security / keys.txt




Custom Search

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.