1KEYRINGS(7) Linux Programmer's Manual KEYRINGS(7)
2
6 keyrings - in-kernel key management and retention facility
7
9 The Linux key-management facility is primarily a way for various kernel
10 components to retain or cache security data, authentication keys, en‐
11 cryption keys, and other data in the kernel.
12 System call interfaces are provided so that user-space programs can
14 manage those objects and also use the facility for their own purposes;
15 see add_key(2), request_key(2), and keyctl(2).
16 A library and some user-space utilities are provided to allow access to
18 the facility. See keyctl(1), keyctl(3), and keyutils(7) for more in‐
19 formation.
20 Keys
22 A key has the following attributes:
23 Serial number (ID)
25 This is a unique integer handle by which a key is referred to in
26 system calls. The serial number is sometimes synonymously re‐
27 ferred as the key ID. Programmatically, key serial numbers are
28 represented using the type key_serial_t.
29 Type A key's type defines what sort of data can be held in the key,
31 how the proposed content of the key will be parsed, and how the
32 payload will be used.
33 There are a number of general-purpose types available, plus some
35 specialist types defined by specific kernel components.
36 Description (name)
38 The key description is a printable string that is used as the
39 search term for the key (in conjunction with the key type) as
40 well as a display name. During searches, the description may be
41 partially matched or exactly matched.
42 Payload (data)
44 The payload is the actual content of a key. This is usually set
45 when a key is created, but it is possible for the kernel to up‐
46 call to user space to finish the instantiation of a key if that
47 key wasn't already known to the kernel when it was requested.
48 For further details, see request_key(2).
49 A key's payload can be read and updated if the key type supports
51 it and if suitable permission is granted to the caller.
52 Access rights
54 Much as files do, each key has an owning user ID, an owning
55 group ID, and a security label. Each key also has a set of per‐
56 missions, though there are more than for a normal UNIX file, and
57 there is an additional category—possessor—beyond the usual user,
58 group, and other (see Possession, below).
59 Note that keys are quota controlled, since they require unswap‐
61 pable kernel memory. The owning user ID specifies whose quota
62 is to be debited.
63 Expiration time
65 Each key can have an expiration time set. When that time is
66 reached, the key is marked as being expired and accesses to it
67 fail with the error EKEYEXPIRED. If not deleted, updated, or
68 replaced, then, after a set amount of time, an expired key is
69 automatically removed (garbage collected) along with all links
70 to it, and attempts to access the key fail with the error
71 ENOKEY.
72 Reference count
74 Each key has a reference count. Keys are referenced by
75 keyrings, by currently active users, and by a process's creden‐
76 tials. When the reference count reaches zero, the key is sched‐
77 uled for garbage collection.
78 Key types
80 The kernel provides several basic types of key:
81 "keyring"
83 Keyrings are special keys which store a set of links to other
84 keys (including other keyrings), analogous to a directory hold‐
85 ing links to files. The main purpose of a keyring is to prevent
86 other keys from being garbage collected because nothing refers
87 to them.
88 Keyrings with descriptions (names) that begin with a period
90 ('.') are reserved to the implementation.
91 "user" This is a general-purpose key type. The key is kept entirely
93 within kernel memory. The payload may be read and updated by
94 user-space applications.
95 The payload for keys of this type is a blob of arbitrary data of
97 up to 32,767 bytes.
98 The description may be any valid string, though it is preferred
100 that it start with a colon-delimited prefix representing the
101 service to which the key is of interest (for instance
102 "afs:mykey").
103 "logon" (since Linux 3.3)
105 This key type is essentially the same as "user", but it does not
106 provide reading (i.e., the keyctl(2) KEYCTL_READ operation),
107 meaning that the key payload is never visible from user space.
108 This is suitable for storing username-password pairs that should
109 not be readable from user space.
110 The description of a "logon" key must start with a non-empty
112 colon-delimited prefix whose purpose is to identify the service
113 to which the key belongs. (Note that this differs from keys of
114 the "user" type, where the inclusion of a prefix is recommended
115 but is not enforced.)
116 "big_key" (since Linux 3.13)
118 This key type is similar to the "user" key type, but it may hold
119 a payload of up to 1 MiB in size. This key type is useful for
120 purposes such as holding Kerberos ticket caches.
121 The payload data may be stored in a tmpfs filesystem, rather
123 than in kernel memory, if the data size exceeds the overhead of
124 storing the data in the filesystem. (Storing the data in a
125 filesystem requires filesystem structures to be allocated in the
126 kernel. The size of these structures determines the size
127 threshold above which the tmpfs storage method is used.) Since
128 Linux 4.8, the payload data is encrypted when stored in tmpfs,
129 thereby preventing it from being written unencrypted into swap
130 space.
131 There are more specialized key types available also, but they aren't
133 discussed here because they aren't intended for normal user-space use.
134 Key type names that begin with a period ('.') are reserved to the im‐
136 plementation.
137 Keyrings
139 As previously mentioned, keyrings are a special type of key that con‐
140 tain links to other keys (which may include other keyrings). Keys may
141 be linked to by multiple keyrings. Keyrings may be considered as anal‐
142 ogous to UNIX directories where each directory contains a set of hard
143 links to files.
144 Various operations (system calls) may be applied only to keyrings:
146 Adding A key may be added to a keyring by system calls that create
148 keys. This prevents the new key from being immediately deleted
149 when the system call releases its last reference to the key.
150 Linking
152 A link may be added to a keyring pointing to a key that is al‐
153 ready known, provided this does not create a self-referential
154 cycle.
155 Unlinking
157 A link may be removed from a keyring. When the last link to a
158 key is removed, that key will be scheduled for deletion by the
159 garbage collector.
160 Clearing
162 All the links may be removed from a keyring.
163 Searching
165 A keyring may be considered the root of a tree or subtree in
166 which keyrings form the branches and non-keyrings the leaves.
167 This tree may be searched for a key matching a particular type
168 and description.
169 See keyctl_clear(3), keyctl_link(3), keyctl_search(3), and keyctl_un‐
171 link(3) for more information.
172 Anchoring keys
174 To prevent a key from being garbage collected, it must be anchored to
175 keep its reference count elevated when it is not in active use by the
176 kernel.
177 Keyrings are used to anchor other keys: each link is a reference on a
179 key. Note that keyrings themselves are just keys and are also subject
180 to the same anchoring requirement to prevent them being garbage col‐
181 lected.
182 The kernel makes available a number of anchor keyrings. Note that some
184 of these keyrings will be created only when first accessed.
185 Process keyrings
187 Process credentials themselves reference keyrings with specific
188 semantics. These keyrings are pinned as long as the set of cre‐
189 dentials exists, which is usually as long as the process exists.
190 There are three keyrings with different inheritance/sharing
192 rules: the session-keyring(7) (inherited and shared by all child
193 processes), the process-keyring(7) (shared by all threads in a
194 process) and the thread-keyring(7) (specific to a particular
195 thread).
196 As an alternative to using the actual keyring IDs, in calls to
198 add_key(2), keyctl(2), and request_key(2), the special keyring
199 values KEY_SPEC_SESSION_KEYRING, KEY_SPEC_PROCESS_KEYRING, and
200 KEY_SPEC_THREAD_KEYRING can be used to refer to the caller's own
201 instances of these keyrings.
202 User keyrings
204 Each UID known to the kernel has a record that contains two
205 keyrings: the user-keyring(7) and the user-session-keyring(7).
206 These exist for as long as the UID record in the kernel exists.
207 As an alternative to using the actual keyring IDs, in calls to
209 add_key(2), keyctl(2), and request_key(2), the special keyring
210 values KEY_SPEC_USER_KEYRING and KEY_SPEC_USER_SESSION_KEYRING
211 can be used to refer to the caller's own instances of these
212 keyrings.
213 A link to the user keyring is placed in a new session keyring by
215 pam_keyinit(8) when a new login session is initiated.
216 Persistent keyrings
218 There is a persistent-keyring(7) available to each UID known to
219 the system. It may persist beyond the life of the UID record
220 previously mentioned, but has an expiration time set such that
221 it is automatically cleaned up after a set time. The persistent
222 keyring permits, for example, cron(8) scripts to use credentials
223 that are left in the persistent keyring after the user logs out.
224 Note that the expiration time of the persistent keyring is reset
226 every time the persistent key is requested.
227 Special keyrings
229 There are special keyrings owned by the kernel that can anchor
230 keys for special purposes. An example of this is the system
231 keyring used for holding encryption keys for module signature
232 verification.
233 These special keyrings are usually closed to direct alteration
235 by user space.
236 An originally planned "group keyring", for storing keys associated with
238 each GID known to the kernel, is not so far implemented, is unlikely to
239 be implemented. Nevertheless, the constant KEY_SPEC_GROUP_KEYRING has
240 been defined for this keyring.
241 Possession
243 The concept of possession is important to understanding the keyrings
244 security model. Whether a thread possesses a key is determined by the
245 following rules:
246 (1) Any key or keyring that does not grant search permission to the
248 caller is ignored in all the following rules.
249 (2) A thread possesses its session-keyring(7), process-keyring(7), and
251 thread-keyring(7) directly because those keyrings are referred to
252 by its credentials.
253 (3) If a keyring is possessed, then any key it links to is also pos‐
255 sessed.
256 (4) If any key a keyring links to is itself a keyring, then rule (3)
258 applies recursively.
259 (5) If a process is upcalled from the kernel to instantiate a key (see
261 request_key(2)), then it also possesses the requester's keyrings as
262 in rule (1) as if it were the requester.
263 Note that possession is not a fundamental property of a key, but must
265 rather be calculated each time the key is needed.
266 Possession is designed to allow set-user-ID programs run from, say a
268 user's shell to access the user's keys. Granting permissions to the
269 key possessor while denying them to the key owner and group allows the
270 prevention of access to keys on the basis of UID and GID matches.
271 When it creates the session keyring, pam_keyinit(8) adds a link to the
273 user-keyring(7), thus making the user keyring and anything it contains
274 possessed by default.
275 Access rights
277 Each key has the following security-related attributes:
278 * The owning user ID
280 * The ID of a group that is permitted to access the key
282 * A security label
284 * A permissions mask
286 The permissions mask contains four sets of rights. The first three
288 sets are mutually exclusive. One and only one will be in force for a
289 particular access check. In order of descending priority, these three
290 sets are:
291 user The set specifies the rights granted if the key's user ID
293 matches the caller's filesystem user ID.
294 group The set specifies the rights granted if the user ID didn't match
296 and the key's group ID matches the caller's filesystem GID or
297 one of the caller's supplementary group IDs.
298 other The set specifies the rights granted if neither the key's user
300 ID nor group ID matched.
301 The fourth set of rights is:
303 possessor
305 The set specifies the rights granted if a key is determined to
306 be possessed by the caller.
307 The complete set of rights for a key is the union of whichever of the
309 first three sets is applicable plus the fourth set if the key is pos‐
310 sessed.
311 The set of rights that may be granted in each of the four masks is as
313 follows:
314 view The attributes of the key may be read. This includes the type,
316 description, and access rights (excluding the security label).
317 read For a key: the payload of the key may be read. For a keyring:
319 the list of serial numbers (keys) to which the keyring has links
320 may be read.
321 write The payload of the key may be updated and the key may be re‐
323 voked. For a keyring, links may be added to or removed from the
324 keyring, and the keyring may be cleared completely (all links
325 are removed),
326 search For a key (or a keyring): the key may be found by a search. For
328 a keyring: keys and keyrings that are linked to by the keyring
329 may be searched.
330 link Links may be created from keyrings to the key. The initial link
332 to a key that is established when the key is created doesn't re‐
333 quire this permission.
334 setattr
336 The ownership details and security label of the key may be
337 changed, the key's expiration time may be set, and the key may
338 be revoked.
339 In addition to access rights, any active Linux Security Module (LSM)
341 may prevent access to a key if its policy so dictates. A key may be
342 given a security label or other attribute by the LSM; this label is re‐
343 trievable via keyctl_get_security(3).
344 See keyctl_chown(3), keyctl_describe(3), keyctl_get_security(3),
346 keyctl_setperm(3), and selinux(8) for more information.
347 Searching for keys
349 One of the key features of the Linux key-management facility is the
350 ability to find a key that a process is retaining. The request_key(2)
351 system call is the primary point of access for user-space applications
352 to find a key. (Internally, the kernel has something similar available
353 for use by internal components that make use of keys.)
354 The search algorithm works as follows:
356 (1) The process keyrings are searched in the following order: the
358 thread thread-keyring(7) if it exists, the process-keyring(7) if it
359 exists, and then either the session-keyring(7) if it exists or the
360 user-session-keyring(7) if that exists.
361 (2) If the caller was a process that was invoked by the request_key(2)
363 upcall mechanism, then the keyrings of the original caller of re‐
364 quest_key(2) will be searched as well.
365 (3) The search of a keyring tree is in breadth-first order: each
367 keyring is searched first for a match, then the keyrings referred
368 to by that keyring are searched.
369 (4) If a matching key is found that is valid, then the search termi‐
371 nates and that key is returned.
372 (5) If a matching key is found that has an error state attached, that
374 error state is noted and the search continues.
375 (6) If no valid matching key is found, then the first noted error state
377 is returned; otherwise, an ENOKEY error is returned.
378 It is also possible to search a specific keyring, in which case only
380 steps (3) to (6) apply.
381 See request_key(2) and keyctl_search(3) for more information.
383 On-demand key creation
385 If a key cannot be found, request_key(2) will, if given a callout_info
386 argument, create a new key and then upcall to user space to instantiate
387 the key. This allows keys to be created on an as-needed basis.
388 Typically, this will involve the kernel creating a new process that ex‐
390 ecutes the request-key(8) program, which will then execute the appro‐
391 priate handler based on its configuration.
392 The handler is passed a special authorization key that allows it and
394 only it to instantiate the new key. This is also used to permit
395 searches performed by the handler program to also search the re‐
396 quester's keyrings.
397 See request_key(2), keyctl_assume_authority(3), keyctl_instantiate(3),
399 keyctl_negate(3), keyctl_reject(3), request-key(8), and re‐
400 quest-key.conf(5) for more information.
401 /proc files
403 The kernel provides various /proc files that expose information about
404 keys or define limits on key usage.
405 /proc/keys (since Linux 2.6.10)
407 This file exposes a list of the keys for which the reading
408 thread has view permission, providing various information about
409 each key. The thread need not possess the key for it to be vis‐
410 ible in this file.
411 The only keys included in the list are those that grant view
413 permission to the reading process (regardless of whether or not
414 it possesses them). LSM security checks are still performed,
415 and may filter out further keys that the process is not autho‐
416 rized to view.
417 An example of the data that one might see in this file (with the
419 columns numbered for easy reference below) is the following:
420 (1) (2) (3)(4) (5) (6) (7) (8) (9)
422 009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
423 1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
424 25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
425 28576bd8 I--Q--- 3 perm 3f010000 1000 1000 keyring _krb: 1
426 2c546d21 I--Q--- 190 perm 3f030000 1000 1000 keyring _ses: 2
427 30a4e0be I------ 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1
428 32100fab I--Q--- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2
429 32a387ea I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
430 3ce56aea I--Q--- 5 perm 3f030000 1000 1000 keyring _ses: 1
431 The fields shown in each line of this file are as follows:
433 ID (1) The ID (serial number) of the key, expressed in hexadeci‐
435 mal.
436 Flags (2)
438 A set of flags describing the state of the key:
439 I The key has been instantiated.
441 R The key has been revoked.
443 D The key is dead (i.e., the key type has been unregis‐
445 tered). (A key may be briefly in this state during
446 garbage collection.)
447 Q The key contributes to the user's quota.
449 U The key is under construction via a callback to user
451 space; see request-key(2).
452 N The key is negatively instantiated.
454 i The key has been invalidated.
456 Usage (3)
458 This is a count of the number of kernel credential struc‐
459 tures that are pinning the key (approximately: the number
460 of threads and open file references that refer to this
461 key).
462 Timeout (4)
464 The amount of time until the key will expire, expressed
465 in human-readable form (weeks, days, hours, minutes, and
466 seconds). The string perm here means that the key is
467 permanent (no timeout). The string expd means that the
468 key has already expired, but has not yet been garbage
469 collected.
470 Permissions (5)
472 The key permissions, expressed as four hexadecimal bytes
473 containing, from left to right, the possessor, user,
474 group, and other permissions. Within each byte, the per‐
475 mission bits are as follows:
476 0x01 view
478 Ox02 read
479 0x04 write
480 0x08 search
481 0x10 link
482 0x20 setattr
483 UID (6)
485 The user ID of the key owner.
486 GID (7)
488 The group ID of the key. The value -1 here means that
489 the key has no group ID; this can occur in certain cir‐
490 cumstances for keys created by the kernel.
491 Type (8)
493 The key type (user, keyring, etc.)
494 Description (9)
496 The key description (name). This field contains descrip‐
497 tive information about the key. For most key types, it
498 has the form
499 name[: extra-info]
501 The name subfield is the key's description (name). The
503 optional extra-info field provides some further informa‐
504 tion about the key. The information that appears here
505 depends on the key type, as follows:
506 "user" and "logon"
508 The size in bytes of the key payload (expressed in
509 decimal).
510 "keyring"
512 The number of keys linked to the keyring, or the
513 string empty if there are no keys linked to the
514 keyring.
515 "big_key"
517 The payload size in bytes, followed either by the
518 string [file], if the key payload exceeds the
519 threshold that means that the payload is stored in
520 a (swappable) tmpfs(5) filesystem, or otherwise
521 the string [buff], indicating that the key is
522 small enough to reside in kernel memory.
523 For the ".request_key_auth" key type (authorization key;
525 see request_key(2)), the description field has the form
526 shown in the following example:
527 key:c9a9b19 pid:28880 ci:10
529 The three subfields are as follows:
531 key The hexadecimal ID of the key being instantiated
533 in the requesting program.
534 pid The PID of the requesting program.
536 ci The length of the callout data with which the re‐
538 quested key should be instantiated (i.e., the
539 length of the payload associated with the autho‐
540 rization key).
541 /proc/key-users (since Linux 2.6.10)
543 This file lists various information for each user ID that has at
544 least one key on the system. An example of the data that one
545 might see in this file is the following:
546 0: 10 9/9 2/1000000 22/25000000
548 42: 9 9/9 8/200 106/20000
549 1000: 11 11/11 10/200 271/20000
550 The fields shown in each line are as follows:
552 uid The user ID.
554 usage This is a kernel-internal usage count for the kernel
556 structure used to record key users.
557 nkeys/nikeys
559 The total number of keys owned by the user, and the num‐
560 ber of those keys that have been instantiated.
561 qnkeys/maxkeys
563 The number of keys owned by the user, and the maximum
564 number of keys that the user may own.
565 qnbytes/maxbytes
567 The number of bytes consumed in payloads of the keys
568 owned by this user, and the upper limit on the number of
569 bytes in key payloads for that user.
570 /proc/sys/kernel/keys/gc_delay (since Linux 2.6.32)
572 The value in this file specifies the interval, in seconds, after
573 which revoked and expired keys will be garbage collected. The
574 purpose of having such an interval is so that there is a window
575 of time where user space can see an error (respectively EKEYRE‐
576 VOKED and EKEYEXPIRED) that indicates what happened to the key.
577 The default value in this file is 300 (i.e., 5 minutes).
579 /proc/sys/kernel/keys/persistent_keyring_expiry (since Linux 3.13)
581 This file defines an interval, in seconds, to which the persis‐
582 tent keyring's expiration timer is reset each time the keyring
583 is accessed (via keyctl_get_persistent(3) or the keyctl(2)
584 KEYCTL_GET_PERSISTENT operation.)
585 The default value in this file is 259200 (i.e., 3 days).
587 The following files (which are writable by privileged processes) are
589 used to enforce quotas on the number of keys and number of bytes of
590 data that can be stored in key payloads:
591 /proc/sys/kernel/keys/maxbytes (since Linux 2.6.26)
593 This is the maximum number of bytes of data that a nonroot user
594 can hold in the payloads of the keys owned by the user.
595 The default value in this file is 20,000.
597 /proc/sys/kernel/keys/maxkeys (since Linux 2.6.26)
599 This is the maximum number of keys that a nonroot user may own.
600 The default value in this file is 200.
602 /proc/sys/kernel/keys/root_maxbytes (since Linux 2.6.26)
604 This is the maximum number of bytes of data that the root user
605 (UID 0 in the root user namespace) can hold in the payloads of
606 the keys owned by root.
607 The default value in this file is 25,000,000 (20,000 before
609 Linux 3.17).
610 /proc/sys/kernel/keys/root_maxkeys (since Linux 2.6.26)
612 This is the maximum number of keys that the root user (UID 0 in
613 the root user namespace) may own.
614 The default value in this file is 1,000,000 (200 before Linux
616 3.17).
617 With respect to keyrings, note that each link in a keyring consumes 4
619 bytes of the keyring payload.
620 Users
622 The Linux key-management facility has a number of users and usages, but
623 is not limited to those that already exist.
624 In-kernel users of this facility include:
626 Network filesystems - DNS
628 The kernel uses the upcall mechanism provided by the keys to up‐
629 call to user space to do DNS lookups and then to cache the re‐
630 sults.
631 AF_RXRPC and kAFS - Authentication
633 The AF_RXRPC network protocol and the in-kernel AFS filesystem
634 use keys to store the ticket needed to do secured or encrypted
635 traffic. These are then looked up by network operations on
636 AF_RXRPC and filesystem operations on kAFS.
637 NFS - User ID mapping
639 The NFS filesystem uses keys to store mappings of foreign user
640 IDs to local user IDs.
641 CIFS - Password
643 The CIFS filesystem uses keys to store passwords for accessing
644 remote shares.
645 Module verification
647 The kernel build process can be made to cryptographically sign
648 modules. That signature is then checked when a module is
649 loaded.
650 User-space users of this facility include:
652 Kerberos key storage
654 The MIT Kerberos 5 facility (libkrb5) can use keys to store au‐
655 thentication tokens which can be made to be automatically
656 cleaned up a set time after the user last uses them, but until
657 then permits them to hang around after the user has logged out
658 so that cron(8) scripts can use them.
659
661 keyctl(1), add_key(2), keyctl(2), request_key(2), keyctl(3),
662 keyutils(7), persistent-keyring(7), process-keyring(7),
663 session-keyring(7), thread-keyring(7), user-keyring(7),
664 user-session-keyring(7), pam_keyinit(8), request-key(8)
665 The kernel source files Documentation/crypto/asymmetric-keys.txt and
667 under Documentation/security/keys (or, before Linux 4.13, in the file
668 Documentation/security/keys.txt).
669
671 This page is part of release 5.12 of the Linux man-pages project. A
672 description of the project, information about reporting bugs, and the
673 latest version of this page, can be found at
674 https://www.kernel.org/doc/man-pages/.
675Linux 2021-03-22 KEYRINGS(7)