About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / security / keys.txt




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22: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 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	 (*) Compute a Diffie-Hellman shared secret or public key
827	
828	       long keyctl(KEYCTL_DH_COMPUTE, struct keyctl_dh_params *params,
829			   char *buffer, size_t buflen,
830			   void *reserved);
831	
832	     The params struct contains serial numbers for three keys:
833	
834		 - The prime, p, known to both parties
835		 - The local private key
836		 - The base integer, which is either a shared generator or the
837		   remote public key
838	
839	     The value computed is:
840	
841		result = base ^ private (mod prime)
842	
843	     If the base is the shared generator, the result is the local
844	     public key.  If the base is the remote public key, the result is
845	     the shared secret.
846	
847	     The reserved argument must be set to NULL.
848	
849	     The buffer length must be at least the length of the prime, or zero.
850	
851	     If the buffer length is nonzero, the length of the result is
852	     returned when it is successfully calculated and copied in to the
853	     buffer. When the buffer length is zero, the minimum required
854	     buffer length is returned.
855	
856	     This function will return error EOPNOTSUPP if the key type is not
857	     supported, error ENOKEY if the key could not be found, or error
858	     EACCES if the key is not readable by the caller.
859	
860	===============
861	KERNEL SERVICES
862	===============
863	
864	The kernel services for key management are fairly simple to deal with. They can
865	be broken down into two areas: keys and key types.
866	
867	Dealing with keys is fairly straightforward. Firstly, the kernel service
868	registers its type, then it searches for a key of that type. It should retain
869	the key as long as it has need of it, and then it should release it. For a
870	filesystem or device file, a search would probably be performed during the open
871	call, and the key released upon close. How to deal with conflicting keys due to
872	two different users opening the same file is left to the filesystem author to
873	solve.
874	
875	To access the key manager, the following header must be #included:
876	
877		<linux/key.h>
878	
879	Specific key types should have a header file under include/keys/ that should be
880	used to access that type.  For keys of type "user", for example, that would be:
881	
882		<keys/user-type.h>
883	
884	Note that there are two different types of pointers to keys that may be
885	encountered:
886	
887	 (*) struct key *
888	
889	     This simply points to the key structure itself. Key structures will be at
890	     least four-byte aligned.
891	
892	 (*) key_ref_t
893	
894	     This is equivalent to a struct key *, but the least significant bit is set
895	     if the caller "possesses" the key. By "possession" it is meant that the
896	     calling processes has a searchable link to the key from one of its
897	     keyrings. There are three functions for dealing with these:
898	
899		key_ref_t make_key_ref(const struct key *key, bool possession);
900	
901		struct key *key_ref_to_ptr(const key_ref_t key_ref);
902	
903		bool is_key_possessed(const key_ref_t key_ref);
904	
905	     The first function constructs a key reference from a key pointer and
906	     possession information (which must be true or false).
907	
908	     The second function retrieves the key pointer from a reference and the
909	     third retrieves the possession flag.
910	
911	When accessing a key's payload contents, certain precautions must be taken to
912	prevent access vs modification races. See the section "Notes on accessing
913	payload contents" for more information.
914	
915	(*) To search for a key, call:
916	
917		struct key *request_key(const struct key_type *type,
918					const char *description,
919					const char *callout_info);
920	
921	    This is used to request a key or keyring with a description that matches
922	    the description specified according to the key type's match_preparse()
923	    method. This permits approximate matching to occur. If callout_string is
924	    not NULL, then /sbin/request-key will be invoked in an attempt to obtain
925	    the key from userspace. In that case, callout_string will be passed as an
926	    argument to the program.
927	
928	    Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be
929	    returned.
930	
931	    If successful, the key will have been attached to the default keyring for
932	    implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING.
933	
934	    See also Documentation/security/keys-request-key.txt.
935	
936	
937	(*) To search for a key, passing auxiliary data to the upcaller, call:
938	
939		struct key *request_key_with_auxdata(const struct key_type *type,
940						     const char *description,
941						     const void *callout_info,
942						     size_t callout_len,
943						     void *aux);
944	
945	    This is identical to request_key(), except that the auxiliary data is
946	    passed to the key_type->request_key() op if it exists, and the callout_info
947	    is a blob of length callout_len, if given (the length may be 0).
948	
949	
950	(*) A key can be requested asynchronously by calling one of:
951	
952		struct key *request_key_async(const struct key_type *type,
953					      const char *description,
954					      const void *callout_info,
955					      size_t callout_len);
956	
957	    or:
958	
959		struct key *request_key_async_with_auxdata(const struct key_type *type,
960							   const char *description,
961							   const char *callout_info,
962						     	   size_t callout_len,
963						     	   void *aux);
964	
965	    which are asynchronous equivalents of request_key() and
966	    request_key_with_auxdata() respectively.
967	
968	    These two functions return with the key potentially still under
969	    construction.  To wait for construction completion, the following should be
970	    called:
971	
972		int wait_for_key_construction(struct key *key, bool intr);
973	
974	    The function will wait for the key to finish being constructed and then
975	    invokes key_validate() to return an appropriate value to indicate the state
976	    of the key (0 indicates the key is usable).
977	
978	    If intr is true, then the wait can be interrupted by a signal, in which
979	    case error ERESTARTSYS will be returned.
980	
981	
982	(*) When it is no longer required, the key should be released using:
983	
984		void key_put(struct key *key);
985	
986	    Or:
987	
988		void key_ref_put(key_ref_t key_ref);
989	
990	    These can be called from interrupt context. If CONFIG_KEYS is not set then
991	    the argument will not be parsed.
992	
993	
994	(*) Extra references can be made to a key by calling one of the following
995	    functions:
996	
997		struct key *__key_get(struct key *key);
998		struct key *key_get(struct key *key);
999	
1000	    Keys so references will need to be disposed of by calling key_put() when
1001	    they've been finished with.  The key pointer passed in will be returned.
1002	
1003	    In the case of key_get(), if the pointer is NULL or CONFIG_KEYS is not set
1004	    then the key will not be dereferenced and no increment will take place.
1005	
1006	
1007	(*) A key's serial number can be obtained by calling:
1008	
1009		key_serial_t key_serial(struct key *key);
1010	
1011	    If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the
1012	    latter case without parsing the argument).
1013	
1014	
1015	(*) If a keyring was found in the search, this can be further searched by:
1016	
1017		key_ref_t keyring_search(key_ref_t keyring_ref,
1018					 const struct key_type *type,
1019					 const char *description)
1020	
1021	    This searches the keyring tree specified for a matching key. Error ENOKEY
1022	    is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful,
1023	    the returned key will need to be released.
1024	
1025	    The possession attribute from the keyring reference is used to control
1026	    access through the permissions mask and is propagated to the returned key
1027	    reference pointer if successful.
1028	
1029	
1030	(*) A keyring can be created by:
1031	
1032		struct key *keyring_alloc(const char *description, uid_t uid, gid_t gid,
1033					  const struct cred *cred,
1034					  key_perm_t perm,
1035					  int (*restrict_link)(struct key *,
1036							       const struct key_type *,
1037							       unsigned long,
1038							       const union key_payload *),
1039					  unsigned long flags,
1040					  struct key *dest);
1041	
1042	    This creates a keyring with the given attributes and returns it.  If dest
1043	    is not NULL, the new keyring will be linked into the keyring to which it
1044	    points.  No permission checks are made upon the destination keyring.
1045	
1046	    Error EDQUOT can be returned if the keyring would overload the quota (pass
1047	    KEY_ALLOC_NOT_IN_QUOTA in flags if the keyring shouldn't be accounted
1048	    towards the user's quota).  Error ENOMEM can also be returned.
1049	
1050	    If restrict_link not NULL, it should point to a function that will be
1051	    called each time an attempt is made to link a key into the new keyring.
1052	    This function is called to check whether a key may be added into the keying
1053	    or not.  Callers of key_create_or_update() within the kernel can pass
1054	    KEY_ALLOC_BYPASS_RESTRICTION to suppress the check.  An example of using
1055	    this is to manage rings of cryptographic keys that are set up when the
1056	    kernel boots where userspace is also permitted to add keys - provided they
1057	    can be verified by a key the kernel already has.
1058	
1059	    When called, the restriction function will be passed the keyring being
1060	    added to, the key flags value and the type and payload of the key being
1061	    added.  Note that when a new key is being created, this is called between
1062	    payload preparsing and actual key creation.  The function should return 0
1063	    to allow the link or an error to reject it.
1064	
1065	    A convenience function, restrict_link_reject, exists to always return
1066	    -EPERM to in this case.
1067	
1068	
1069	(*) To check the validity of a key, this function can be called:
1070	
1071		int validate_key(struct key *key);
1072	
1073	    This checks that the key in question hasn't expired or and hasn't been
1074	    revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will
1075	    be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be
1076	    returned (in the latter case without parsing the argument).
1077	
1078	
1079	(*) To register a key type, the following function should be called:
1080	
1081		int register_key_type(struct key_type *type);
1082	
1083	    This will return error EEXIST if a type of the same name is already
1084	    present.
1085	
1086	
1087	(*) To unregister a key type, call:
1088	
1089		void unregister_key_type(struct key_type *type);
1090	
1091	
1092	Under some circumstances, it may be desirable to deal with a bundle of keys.
1093	The facility provides access to the keyring type for managing such a bundle:
1094	
1095		struct key_type key_type_keyring;
1096	
1097	This can be used with a function such as request_key() to find a specific
1098	keyring in a process's keyrings.  A keyring thus found can then be searched
1099	with keyring_search().  Note that it is not possible to use request_key() to
1100	search a specific keyring, so using keyrings in this way is of limited utility.
1101	
1102	
1103	===================================
1104	NOTES ON ACCESSING PAYLOAD CONTENTS
1105	===================================
1106	
1107	The simplest payload is just data stored in key->payload directly.  In this
1108	case, there's no need to indulge in RCU or locking when accessing the payload.
1109	
1110	More complex payload contents must be allocated and pointers to them set in the
1111	key->payload.data[] array.  One of the following ways must be selected to
1112	access the data:
1113	
1114	 (1) Unmodifiable key type.
1115	
1116	     If the key type does not have a modify method, then the key's payload can
1117	     be accessed without any form of locking, provided that it's known to be
1118	     instantiated (uninstantiated keys cannot be "found").
1119	
1120	 (2) The key's semaphore.
1121	
1122	     The semaphore could be used to govern access to the payload and to control
1123	     the payload pointer. It must be write-locked for modifications and would
1124	     have to be read-locked for general access. The disadvantage of doing this
1125	     is that the accessor may be required to sleep.
1126	
1127	 (3) RCU.
1128	
1129	     RCU must be used when the semaphore isn't already held; if the semaphore
1130	     is held then the contents can't change under you unexpectedly as the
1131	     semaphore must still be used to serialise modifications to the key. The
1132	     key management code takes care of this for the key type.
1133	
1134	     However, this means using:
1135	
1136		rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock()
1137	
1138	     to read the pointer, and:
1139	
1140		rcu_dereference() ... rcu_assign_pointer() ... call_rcu()
1141	
1142	     to set the pointer and dispose of the old contents after a grace period.
1143	     Note that only the key type should ever modify a key's payload.
1144	
1145	     Furthermore, an RCU controlled payload must hold a struct rcu_head for the
1146	     use of call_rcu() and, if the payload is of variable size, the length of
1147	     the payload. key->datalen cannot be relied upon to be consistent with the
1148	     payload just dereferenced if the key's semaphore is not held.
1149	
1150	     Note that key->payload.data[0] has a shadow that is marked for __rcu
1151	     usage.  This is called key->payload.rcu_data0.  The following accessors
1152	     wrap the RCU calls to this element:
1153	
1154		rcu_assign_keypointer(struct key *key, void *data);
1155		void *rcu_dereference_key(struct key *key);
1156	
1157	
1158	===================
1159	DEFINING A KEY TYPE
1160	===================
1161	
1162	A kernel service may want to define its own key type. For instance, an AFS
1163	filesystem might want to define a Kerberos 5 ticket key type. To do this, it
1164	author fills in a key_type struct and registers it with the system.
1165	
1166	Source files that implement key types should include the following header file:
1167	
1168		<linux/key-type.h>
1169	
1170	The structure has a number of fields, some of which are mandatory:
1171	
1172	 (*) const char *name
1173	
1174	     The name of the key type. This is used to translate a key type name
1175	     supplied by userspace into a pointer to the structure.
1176	
1177	
1178	 (*) size_t def_datalen
1179	
1180	     This is optional - it supplies the default payload data length as
1181	     contributed to the quota. If the key type's payload is always or almost
1182	     always the same size, then this is a more efficient way to do things.
1183	
1184	     The data length (and quota) on a particular key can always be changed
1185	     during instantiation or update by calling:
1186	
1187		int key_payload_reserve(struct key *key, size_t datalen);
1188	
1189	     With the revised data length. Error EDQUOT will be returned if this is not
1190	     viable.
1191	
1192	
1193	 (*) int (*vet_description)(const char *description);
1194	
1195	     This optional method is called to vet a key description.  If the key type
1196	     doesn't approve of the key description, it may return an error, otherwise
1197	     it should return 0.
1198	
1199	
1200	 (*) int (*preparse)(struct key_preparsed_payload *prep);
1201	
1202	     This optional method permits the key type to attempt to parse payload
1203	     before a key is created (add key) or the key semaphore is taken (update or
1204	     instantiate key).  The structure pointed to by prep looks like:
1205	
1206		struct key_preparsed_payload {
1207			char		*description;
1208			union key_payload payload;
1209			const void	*data;
1210			size_t		datalen;
1211			size_t		quotalen;
1212			time_t		expiry;
1213		};
1214	
1215	     Before calling the method, the caller will fill in data and datalen with
1216	     the payload blob parameters; quotalen will be filled in with the default
1217	     quota size from the key type; expiry will be set to TIME_T_MAX and the
1218	     rest will be cleared.
1219	
1220	     If a description can be proposed from the payload contents, that should be
1221	     attached as a string to the description field.  This will be used for the
1222	     key description if the caller of add_key() passes NULL or "".
1223	
1224	     The method can attach anything it likes to payload.  This is merely passed
1225	     along to the instantiate() or update() operations.  If set, the expiry
1226	     time will be applied to the key if it is instantiated from this data.
1227	
1228	     The method should return 0 if successful or a negative error code
1229	     otherwise.
1230	
1231	
1232	 (*) void (*free_preparse)(struct key_preparsed_payload *prep);
1233	
1234	     This method is only required if the preparse() method is provided,
1235	     otherwise it is unused.  It cleans up anything attached to the description
1236	     and payload fields of the key_preparsed_payload struct as filled in by the
1237	     preparse() method.  It will always be called after preparse() returns
1238	     successfully, even if instantiate() or update() succeed.
1239	
1240	
1241	 (*) int (*instantiate)(struct key *key, struct key_preparsed_payload *prep);
1242	
1243	     This method is called to attach a payload to a key during construction.
1244	     The payload attached need not bear any relation to the data passed to this
1245	     function.
1246	
1247	     The prep->data and prep->datalen fields will define the original payload
1248	     blob.  If preparse() was supplied then other fields may be filled in also.
1249	
1250	     If the amount of data attached to the key differs from the size in
1251	     keytype->def_datalen, then key_payload_reserve() should be called.
1252	
1253	     This method does not have to lock the key in order to attach a payload.
1254	     The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
1255	     anything else from gaining access to the key.
1256	
1257	     It is safe to sleep in this method.
1258	
1259	     generic_key_instantiate() is provided to simply copy the data from
1260	     prep->payload.data[] to key->payload.data[], with RCU-safe assignment on
1261	     the first element.  It will then clear prep->payload.data[] so that the
1262	     free_preparse method doesn't release the data.
1263	
1264	
1265	 (*) int (*update)(struct key *key, const void *data, size_t datalen);
1266	
1267	     If this type of key can be updated, then this method should be provided.
1268	     It is called to update a key's payload from the blob of data provided.
1269	
1270	     The prep->data and prep->datalen fields will define the original payload
1271	     blob.  If preparse() was supplied then other fields may be filled in also.
1272	
1273	     key_payload_reserve() should be called if the data length might change
1274	     before any changes are actually made. Note that if this succeeds, the type
1275	     is committed to changing the key because it's already been altered, so all
1276	     memory allocation must be done first.
1277	
1278	     The key will have its semaphore write-locked before this method is called,
1279	     but this only deters other writers; any changes to the key's payload must
1280	     be made under RCU conditions, and call_rcu() must be used to dispose of
1281	     the old payload.
1282	
1283	     key_payload_reserve() should be called before the changes are made, but
1284	     after all allocations and other potentially failing function calls are
1285	     made.
1286	
1287	     It is safe to sleep in this method.
1288	
1289	
1290	 (*) int (*match_preparse)(struct key_match_data *match_data);
1291	
1292	     This method is optional.  It is called when a key search is about to be
1293	     performed.  It is given the following structure:
1294	
1295		struct key_match_data {
1296			bool (*cmp)(const struct key *key,
1297				    const struct key_match_data *match_data);
1298			const void	*raw_data;
1299			void		*preparsed;
1300			unsigned	lookup_type;
1301		};
1302	
1303	     On entry, raw_data will be pointing to the criteria to be used in matching
1304	     a key by the caller and should not be modified.  (*cmp)() will be pointing
1305	     to the default matcher function (which does an exact description match
1306	     against raw_data) and lookup_type will be set to indicate a direct lookup.
1307	
1308	     The following lookup_type values are available:
1309	
1310	      [*] KEYRING_SEARCH_LOOKUP_DIRECT - A direct lookup hashes the type and
1311	      	  description to narrow down the search to a small number of keys.
1312	
1313	      [*] KEYRING_SEARCH_LOOKUP_ITERATE - An iterative lookup walks all the
1314	      	  keys in the keyring until one is matched.  This must be used for any
1315	      	  search that's not doing a simple direct match on the key description.
1316	
1317	     The method may set cmp to point to a function of its choice that does some
1318	     other form of match, may set lookup_type to KEYRING_SEARCH_LOOKUP_ITERATE
1319	     and may attach something to the preparsed pointer for use by (*cmp)().
1320	     (*cmp)() should return true if a key matches and false otherwise.
1321	
1322	     If preparsed is set, it may be necessary to use the match_free() method to
1323	     clean it up.
1324	
1325	     The method should return 0 if successful or a negative error code
1326	     otherwise.
1327	
1328	     It is permitted to sleep in this method, but (*cmp)() may not sleep as
1329	     locks will be held over it.
1330	
1331	     If match_preparse() is not provided, keys of this type will be matched
1332	     exactly by their description.
1333	
1334	
1335	 (*) void (*match_free)(struct key_match_data *match_data);
1336	
1337	     This method is optional.  If given, it called to clean up
1338	     match_data->preparsed after a successful call to match_preparse().
1339	
1340	
1341	 (*) void (*revoke)(struct key *key);
1342	
1343	     This method is optional.  It is called to discard part of the payload
1344	     data upon a key being revoked.  The caller will have the key semaphore
1345	     write-locked.
1346	
1347	     It is safe to sleep in this method, though care should be taken to avoid
1348	     a deadlock against the key semaphore.
1349	
1350	
1351	 (*) void (*destroy)(struct key *key);
1352	
1353	     This method is optional. It is called to discard the payload data on a key
1354	     when it is being destroyed.
1355	
1356	     This method does not need to lock the key to access the payload; it can
1357	     consider the key as being inaccessible at this time. Note that the key's
1358	     type may have been changed before this function is called.
1359	
1360	     It is not safe to sleep in this method; the caller may hold spinlocks.
1361	
1362	
1363	 (*) void (*describe)(const struct key *key, struct seq_file *p);
1364	
1365	     This method is optional. It is called during /proc/keys reading to
1366	     summarise a key's description and payload in text form.
1367	
1368	     This method will be called with the RCU read lock held. rcu_dereference()
1369	     should be used to read the payload pointer if the payload is to be
1370	     accessed. key->datalen cannot be trusted to stay consistent with the
1371	     contents of the payload.
1372	
1373	     The description will not change, though the key's state may.
1374	
1375	     It is not safe to sleep in this method; the RCU read lock is held by the
1376	     caller.
1377	
1378	
1379	 (*) long (*read)(const struct key *key, char __user *buffer, size_t buflen);
1380	
1381	     This method is optional. It is called by KEYCTL_READ to translate the
1382	     key's payload into something a blob of data for userspace to deal with.
1383	     Ideally, the blob should be in the same format as that passed in to the
1384	     instantiate and update methods.
1385	
1386	     If successful, the blob size that could be produced should be returned
1387	     rather than the size copied.
1388	
1389	     This method will be called with the key's semaphore read-locked. This will
1390	     prevent the key's payload changing. It is not necessary to use RCU locking
1391	     when accessing the key's payload. It is safe to sleep in this method, such
1392	     as might happen when the userspace buffer is accessed.
1393	
1394	
1395	 (*) int (*request_key)(struct key_construction *cons, const char *op,
1396				void *aux);
1397	
1398	     This method is optional.  If provided, request_key() and friends will
1399	     invoke this function rather than upcalling to /sbin/request-key to operate
1400	     upon a key of this type.
1401	
1402	     The aux parameter is as passed to request_key_async_with_auxdata() and
1403	     similar or is NULL otherwise.  Also passed are the construction record for
1404	     the key to be operated upon and the operation type (currently only
1405	     "create").
1406	
1407	     This method is permitted to return before the upcall is complete, but the
1408	     following function must be called under all circumstances to complete the
1409	     instantiation process, whether or not it succeeds, whether or not there's
1410	     an error:
1411	
1412		void complete_request_key(struct key_construction *cons, int error);
1413	
1414	     The error parameter should be 0 on success, -ve on error.  The
1415	     construction record is destroyed by this action and the authorisation key
1416	     will be revoked.  If an error is indicated, the key under construction
1417	     will be negatively instantiated if it wasn't already instantiated.
1418	
1419	     If this method returns an error, that error will be returned to the
1420	     caller of request_key*().  complete_request_key() must be called prior to
1421	     returning.
1422	
1423	     The key under construction and the authorisation key can be found in the
1424	     key_construction struct pointed to by cons:
1425	
1426	     (*) struct key *key;
1427	
1428	     	 The key under construction.
1429	
1430	     (*) struct key *authkey;
1431	
1432	     	 The authorisation key.
1433	
1434	
1435	============================
1436	REQUEST-KEY CALLBACK SERVICE
1437	============================
1438	
1439	To create a new key, the kernel will attempt to execute the following command
1440	line:
1441	
1442		/sbin/request-key create <key> <uid> <gid> \
1443			<threadring> <processring> <sessionring> <callout_info>
1444	
1445	<key> is the key being constructed, and the three keyrings are the process
1446	keyrings from the process that caused the search to be issued. These are
1447	included for two reasons:
1448	
1449	  (1) There may be an authentication token in one of the keyrings that is
1450	      required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
1451	
1452	  (2) The new key should probably be cached in one of these rings.
1453	
1454	This program should set it UID and GID to those specified before attempting to
1455	access any more keys. It may then look around for a user specific process to
1456	hand the request off to (perhaps a path held in placed in another key by, for
1457	example, the KDE desktop manager).
1458	
1459	The program (or whatever it calls) should finish construction of the key by
1460	calling KEYCTL_INSTANTIATE or KEYCTL_INSTANTIATE_IOV, which also permits it to
1461	cache the key in one of the keyrings (probably the session ring) before
1462	returning.  Alternatively, the key can be marked as negative with KEYCTL_NEGATE
1463	or KEYCTL_REJECT; this also permits the key to be cached in one of the
1464	keyrings.
1465	
1466	If it returns with the key remaining in the unconstructed state, the key will
1467	be marked as being negative, it will be added to the session keyring, and an
1468	error will be returned to the key requestor.
1469	
1470	Supplementary information may be provided from whoever or whatever invoked this
1471	service. This will be passed as the <callout_info> parameter. If no such
1472	information was made available, then "-" will be passed as this parameter
1473	instead.
1474	
1475	
1476	Similarly, the kernel may attempt to update an expired or a soon to expire key
1477	by executing:
1478	
1479		/sbin/request-key update <key> <uid> <gid> \
1480			<threadring> <processring> <sessionring>
1481	
1482	In this case, the program isn't required to actually attach the key to a ring;
1483	the rings are provided for reference.
1484	
1485	
1486	==================
1487	GARBAGE COLLECTION
1488	==================
1489	
1490	Dead keys (for which the type has been removed) will be automatically unlinked
1491	from those keyrings that point to them and deleted as soon as possible by a
1492	background garbage collector.
1493	
1494	Similarly, revoked and expired keys will be garbage collected, but only after a
1495	certain amount of time has passed.  This time is set as a number of seconds in:
1496	
1497		/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.