keyrings - in-kernel key management and retention facility
The Linux key-management facility is primarily a way for various kernel
components to retain or cache security data, authentication keys, encryption
keys, and other data in the kernel.
System call interfaces are provided so that user-space programs can manage those
objects and also use the facility for their own purposes; see
(2), and keyctl
A library and some user-space utilities are provided to allow access to the
facility. See keyctl
(3), and keyutils
A key has the following attributes:
- Serial number (ID)
- This is a unique integer handle by which a key is referred to in system
calls. The serial number is sometimes synonymously referred as the key ID.
Programmatically, key serial numbers are represented using the type
- A key's type defines what sort of data can be held in the key, how the
proposed content of the key will be parsed, and how the payload will be
- There are a number of general-purpose types available, plus some
specialist types defined by specific kernel components.
- Description (name)
- The key description is a printable string that is used as the search term
for the key (in conjunction with the key type) as well as a display name.
During searches, the description may be partially matched or exactly
- Payload (data)
- The payload is the actual content of a key. This is usually set when a key
is created, but it is possible for the kernel to upcall to user space to
finish the instantiation of a key if that key wasn't already known to the
kernel when it was requested. For further details, see
- A key's payload can be read and updated if the key type supports it and if
suitable permission is granted to the caller.
- Access rights
- Much as files do, each key has an owning user ID, an owning group ID, and
a security label. Each key also has a set of permissions, though there are
more than for a normal UNIX file, and there is an additional
category—possessor—beyond the usual user, group, and other
(see Possession, below).
- Note that keys are quota controlled, since they require unswappable kernel
memory. The owning user ID specifies whose quota is to be debited.
- Expiration time
- Each key can have an expiration time set. When that time is reached, the
key is marked as being expired and accesses to it fail with the error
EKEYEXPIRED. If not deleted, updated, or replaced, then, after a
set amount of time, an expired key is automatically removed (garbage
collected) along with all links to it, and attempts to access the key fail
with the error ENOKEY.
- Reference count
- Each key has a reference count. Keys are referenced by keyrings, by
currently active users, and by a process's credentials. When the reference
count reaches zero, the key is scheduled for garbage collection.
The kernel provides several basic types of key:
- Keyrings are special keys which store a set of links to other keys
(including other keyrings), analogous to a directory holding links to
files. The main purpose of a keyring is to prevent other keys from being
garbage collected because nothing refers to them.
- Keyrings with descriptions (names) that begin with a period ('.') are
reserved to the implementation.
- This is a general-purpose key type. The key is kept entirely within kernel
memory. The payload may be read and updated by user-space
- The payload for keys of this type is a blob of arbitrary data of up to
- The description may be any valid string, though it is preferred that it
start with a colon-delimited prefix representing the service to which the
key is of interest (for instance "afs:mykey").
- "logon" (since Linux 3.3)
- This key type is essentially the same as "user", but it
does not provide reading (i.e., the keyctl(2) KEYCTL_READ
operation), meaning that the key payload is never visible from user space.
This is suitable for storing username-password pairs that should not be
readable from user space.
- The description of a "logon" key must start with a
non-empty colon-delimited prefix whose purpose is to identify the service
to which the key belongs. (Note that this differs from keys of the
"user" type, where the inclusion of a prefix is
recommended but is not enforced.)
- "big_key" (since Linux 3.13)
- This key type is similar to the "user" key type, but it
may hold a payload of up to 1 MiB in size. This key type is useful
for purposes such as holding Kerberos ticket caches.
- The payload data may be stored in a tmpfs filesystem, rather than in
kernel memory, if the data size exceeds the overhead of storing the data
in the filesystem. (Storing the data in a filesystem requires filesystem
structures to be allocated in the kernel. The size of these structures
determines the size threshold above which the tmpfs storage method is
used.) Since Linux 4.8, the payload data is encrypted when stored in
tmpfs, thereby preventing it from being written unencrypted into swap
There are more specialized key types available also, but they aren't discussed
here because they aren't intended for normal user-space use.
Key type names that begin with a period ('.') are reserved to the
As previously mentioned, keyrings are a special type of key that contain links
to other keys (which may include other keyrings). Keys may be linked to by
multiple keyrings. Keyrings may be considered as analogous to UNIX directories
where each directory contains a set of hard links to files.
Various operations (system calls) may be applied only to keyrings:
- A key may be added to a keyring by system calls that create keys. This
prevents the new key from being immediately deleted when the system call
releases its last reference to the key.
- A link may be added to a keyring pointing to a key that is already known,
provided this does not create a self-referential cycle.
- A link may be removed from a keyring. When the last link to a key is
removed, that key will be scheduled for deletion by the garbage
- All the links may be removed from a keyring.
- A keyring may be considered the root of a tree or subtree in which
keyrings form the branches and non-keyrings the leaves. This tree may be
searched for a key matching a particular type and description.
(3) for more information.
To prevent a key from being garbage collected, it must be anchored to keep its
reference count elevated when it is not in active use by the kernel.
Keyrings are used to anchor other keys: each link is a reference on a key. Note
that keyrings themselves are just keys and are also subject to the same
anchoring requirement to prevent them being garbage collected.
The kernel makes available a number of anchor keyrings. Note that some of these
keyrings will be created only when first accessed.
- Process keyrings
- Process credentials themselves reference keyrings with specific semantics.
These keyrings are pinned as long as the set of credentials exists, which
is usually as long as the process exists.
- There are three keyrings with different inheritance/sharing rules: the
session-keyring(7) (inherited and shared by all child processes),
the process-keyring(7) (shared by all threads in a process) and the
thread-keyring(7) (specific to a particular thread).
- As an alternative to using the actual keyring IDs, in calls to
add_key(2), keyctl(2), and request_key(2), the
special keyring values KEY_SPEC_SESSION_KEYRING,
KEY_SPEC_PROCESS_KEYRING, and KEY_SPEC_THREAD_KEYRING can be
used to refer to the caller's own instances of these keyrings.
- User keyrings
- Each UID known to the kernel has a record that contains two keyrings: the
user-keyring(7) and the user-session-keyring(7). These exist
for as long as the UID record in the kernel exists.
- As an alternative to using the actual keyring IDs, in calls to
add_key(2), keyctl(2), and request_key(2), the
special keyring values KEY_SPEC_USER_KEYRING and
KEY_SPEC_USER_SESSION_KEYRING can be used to refer to the caller's
own instances of these keyrings.
- A link to the user keyring is placed in a new session keyring by
pam_keyinit(8) when a new login session is initiated.
- Persistent keyrings
- There is a persistent-keyring(7) available to each UID known to the
system. It may persist beyond the life of the UID record previously
mentioned, but has an expiration time set such that it is automatically
cleaned up after a set time. The persistent keyring permits, for example,
cron(8) scripts to use credentials that are left in the persistent
keyring after the user logs out.
- Note that the expiration time of the persistent keyring is reset every
time the persistent key is requested.
- Special keyrings
- There are special keyrings owned by the kernel that can anchor keys for
special purposes. An example of this is the system keyring used for
holding encryption keys for module signature verification.
- These special keyrings are usually closed to direct alteration by user
An originally planned "group keyring", for storing keys associated
with each GID known to the kernel, is not so far implemented, is unlikely to
be implemented. Nevertheless, the constant KEY_SPEC_GROUP_KEYRING
been defined for this keyring.
The concept of possession is important to understanding the keyrings security
model. Whether a thread possesses a key is determined by the following rules:
- Any key or keyring that does not grant search permission to the
caller is ignored in all the following rules.
- A thread possesses its session-keyring(7),
process-keyring(7), and thread-keyring(7) directly because
those keyrings are referred to by its credentials.
- If a keyring is possessed, then any key it links to is also
- If any key a keyring links to is itself a keyring, then rule (3) applies
- If a process is upcalled from the kernel to instantiate a key (see
request_key(2)), then it also possesses the requester's keyrings as
in rule (1) as if it were the requester.
Note that possession is not a fundamental property of a key, but must rather be
calculated each time the key is needed.
Possession is designed to allow set-user-ID programs run from, say a user's
shell to access the user's keys. Granting permissions to the key possessor
while denying them to the key owner and group allows the prevention of access
to keys on the basis of UID and GID matches.
When it creates the session keyring, pam_keyinit
(8) adds a link to the
(7), thus making the user keyring and anything it contains
possessed by default.
Each key has the following security-related attributes:
- The owning user ID
- The ID of a group that is permitted to access the key
- A security label
- A permissions mask
The permissions mask contains four sets of rights. The first three sets are
mutually exclusive. One and only one will be in force for a particular access
check. In order of descending priority, these three sets are:
- The set specifies the rights granted if the key's user ID matches the
caller's filesystem user ID.
- The set specifies the rights granted if the user ID didn't match and the
key's group ID matches the caller's filesystem GID or one of the caller's
supplementary group IDs.
- The set specifies the rights granted if neither the key's user ID nor
group ID matched.
The fourth set of rights is:
- The set specifies the rights granted if a key is determined to be
possessed by the caller.
The complete set of rights for a key is the union of whichever of the first
three sets is applicable plus the fourth set if the key is possessed.
The set of rights that may be granted in each of the four masks is as follows:
- The attributes of the key may be read. This includes the type,
description, and access rights (excluding the security label).
- For a key: the payload of the key may be read. For a keyring: the list of
serial numbers (keys) to which the keyring has links may be read.
- The payload of the key may be updated and the key may be revoked. For a
keyring, links may be added to or removed from the keyring, and the
keyring may be cleared completely (all links are removed),
- For a key (or a keyring): the key may be found by a search. For a keyring:
keys and keyrings that are linked to by the keyring may be searched.
- Links may be created from keyrings to the key. The initial link to a key
that is established when the key is created doesn't require this
- The ownership details and security label of the key may be changed, the
key's expiration time may be set, and the key may be revoked.
In addition to access rights, any active Linux Security Module (LSM) may prevent
access to a key if its policy so dictates. A key may be given a security label
or other attribute by the LSM; this label is retrievable via
(3), and selinux
for more information.
One of the key features of the Linux key-management facility is the ability to
find a key that a process is retaining. The request_key
(2) system call
is the primary point of access for user-space applications to find a key.
(Internally, the kernel has something similar available for use by internal
components that make use of keys.)
The search algorithm works as follows:
- The process keyrings are searched in the following order: the thread
thread-keyring(7) if it exists, the process-keyring(7) if it
exists, and then either the session-keyring(7) if it exists or the
user-session-keyring(7) if that exists.
- If the caller was a process that was invoked by the request_key(2)
upcall mechanism, then the keyrings of the original caller of
request_key(2) will be searched as well.
- The search of a keyring tree is in breadth-first order: each keyring is
searched first for a match, then the keyrings referred to by that keyring
- If a matching key is found that is valid, then the search terminates and
that key is returned.
- If a matching key is found that has an error state attached, that error
state is noted and the search continues.
- If no valid matching key is found, then the first noted error state is
returned; otherwise, an ENOKEY error is returned.
It is also possible to search a specific keyring, in which case only steps (3)
to (6) apply.
(2) and keyctl_search
(3) for more information.
If a key cannot be found, request_key
(2) will, if given a
argument, create a new key and then upcall to user space
to instantiate the key. This allows keys to be created on an as-needed basis.
Typically, this will involve the kernel creating a new process that executes the
(8) program, which will then execute the appropriate handler
based on its configuration.
The handler is passed a special authorization key that allows it and only it to
instantiate the new key. This is also used to permit searches performed by the
handler program to also search the requester's keyrings.
(8), and request-key.conf
for more information.
The kernel provides various /proc
files that expose information about
keys or define limits on key usage.
- /proc/keys (since Linux 2.6.10)
- This file exposes a list of the keys for which the reading thread has
view permission, providing various information about each key. The
thread need not possess the key for it to be visible in this file.
- The only keys included in the list are those that grant view
permission to the reading process (regardless of whether or not it
possesses them). LSM security checks are still performed, and may filter
out further keys that the process is not authorized to view.
- An example of the data that one might see in this file (with the columns
numbered for easy reference below) is the following:
(1) (2) (3)(4) (5) (6) (7) (8) (9)
009a2028 I--Q--- 1 perm 3f010000 1000 1000 user krb_ccache:primary: 12
1806c4ba I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
25d3a08f I--Q--- 1 perm 1f3f0000 1000 65534 keyring _uid_ses.1000: 1
28576bd8 I--Q--- 3 perm 3f010000 1000 1000 keyring _krb: 1
2c546d21 I--Q--- 190 perm 3f030000 1000 1000 keyring _ses: 2
30a4e0be I------ 4 2d 1f030000 1000 65534 keyring _persistent.1000: 1
32100fab I--Q--- 4 perm 1f3f0000 1000 65534 keyring _uid.1000: 2
32a387ea I--Q--- 1 perm 3f010000 1000 1000 keyring _pid: 2
3ce56aea I--Q--- 5 perm 3f030000 1000 1000 keyring _ses: 1
- The fields shown in each line of this file are as follows:
- ID (1)
- The ID (serial number) of the key, expressed in hexadecimal.
- Flags (2)
- A set of flags describing the state of the key:
- The key has been instantiated.
- The key has been revoked.
- The key is dead (i.e., the key type has been unregistered). (A key may be
briefly in this state during garbage collection.)
- The key contributes to the user's quota.
- The key is under construction via a callback to user space; see
- The key is negatively instantiated.
- The key has been invalidated.
- Usage (3)
- This is a count of the number of kernel credential structures that are
pinning the key (approximately: the number of threads and open file
references that refer to this key).
- Timeout (4)
- The amount of time until the key will expire, expressed in human-readable
form (weeks, days, hours, minutes, and seconds). The string perm
here means that the key is permanent (no timeout). The string expd
means that the key has already expired, but has not yet been garbage
- Permissions (5)
- The key permissions, expressed as four hexadecimal bytes containing, from
left to right, the possessor, user, group, and other permissions. Within
each byte, the permission bits are as follows:
- UID (6)
- The user ID of the key owner.
- GID (7)
- The group ID of the key. The value -1 here means that the key has no group
ID; this can occur in certain circumstances for keys created by the
- Type (8)
- The key type (user, keyring, etc.)
- Description (9)
- The key description (name). This field contains descriptive information
about the key. For most key types, it has the form
- The name subfield is the key's description (name). The optional
extra-info field provides some further information about the key.
The information that appears here depends on the key type, as
- "user" and "logon"
- The size in bytes of the key payload (expressed in decimal).
- The number of keys linked to the keyring, or the string empty if
there are no keys linked to the keyring.
- The payload size in bytes, followed either by the string [file], if
the key payload exceeds the threshold that means that the payload is
stored in a (swappable) tmpfs(5) filesystem, or otherwise the
string [buff], indicating that the key is small enough to reside in
- For the ".request_key_auth" key type (authorization key;
see request_key(2)), the description field has the form shown in
the following example:
key:c9a9b19 pid:28880 ci:10
- The three subfields are as follows:
- The hexadecimal ID of the key being instantiated in the requesting
- The PID of the requesting program.
- The length of the callout data with which the requested key should be
instantiated (i.e., the length of the payload associated with the
- /proc/key-users (since Linux 2.6.10)
- This file lists various information for each user ID that has at least one
key on the system. An example of the data that one might see in this file
is the following:
0: 10 9/9 2/1000000 22/25000000
42: 9 9/9 8/200 106/20000
1000: 11 11/11 10/200 271/20000
- The fields shown in each line are as follows:
- The user ID.
- This is a kernel-internal usage count for the kernel structure used to
record key users.
- The total number of keys owned by the user, and the number of those keys
that have been instantiated.
- The number of keys owned by the user, and the maximum number of keys that
the user may own.
- The number of bytes consumed in payloads of the keys owned by this user,
and the upper limit on the number of bytes in key payloads for that
- /proc/sys/kernel/keys/gc_delay (since Linux 2.6.32)
- The value in this file specifies the interval, in seconds, after which
revoked and expired keys will be garbage collected. The purpose of having
such an interval is so that there is a window of time where user space can
see an error (respectively EKEYREVOKED and EKEYEXPIRED) that
indicates what happened to the key.
- The default value in this file is 300 (i.e., 5 minutes).
- /proc/sys/kernel/keys/persistent_keyring_expiry (since Linux
- This file defines an interval, in seconds, to which the persistent
keyring's expiration timer is reset each time the keyring is accessed (via
keyctl_get_persistent(3) or the keyctl(2)
- The default value in this file is 259200 (i.e., 3 days).
The following files (which are writable by privileged processes) are used to
enforce quotas on the number of keys and number of bytes of data that can be
stored in key payloads:
- /proc/sys/kernel/keys/maxbytes (since Linux 2.6.26)
- This is the maximum number of bytes of data that a nonroot user can hold
in the payloads of the keys owned by the user.
- The default value in this file is 20,000.
- /proc/sys/kernel/keys/maxkeys (since Linux 2.6.26)
- This is the maximum number of keys that a nonroot user may own.
- The default value in this file is 200.
- /proc/sys/kernel/keys/root_maxbytes (since Linux 2.6.26)
- This is the maximum number of bytes of data that the root user (UID 0 in
the root user namespace) can hold in the payloads of the keys owned by
- The default value in this file is 25,000,000 (20,000 before Linux
- /proc/sys/kernel/keys/root_maxkeys (since Linux 2.6.26)
- This is the maximum number of keys that the root user (UID 0 in the root
user namespace) may own.
- The default value in this file is 1,000,000 (200 before Linux 3.17).
With respect to keyrings, note that each link in a keyring consumes 4 bytes of
the keyring payload.
The Linux key-management facility has a number of users and usages, but is not
limited to those that already exist.
In-kernel users of this facility include:
- Network filesystems - DNS
- The kernel uses the upcall mechanism provided by the keys to upcall to
user space to do DNS lookups and then to cache the results.
- AF_RXRPC and kAFS - Authentication
- The AF_RXRPC network protocol and the in-kernel AFS filesystem use keys to
store the ticket needed to do secured or encrypted traffic. These are then
looked up by network operations on AF_RXRPC and filesystem operations on
- NFS - User ID mapping
- The NFS filesystem uses keys to store mappings of foreign user IDs to
local user IDs.
- CIFS - Password
- The CIFS filesystem uses keys to store passwords for accessing remote
- Module verification
- The kernel build process can be made to cryptographically sign modules.
That signature is then checked when a module is loaded.
User-space users of this facility include:
- Kerberos key storage
- The MIT Kerberos 5 facility (libkrb5) can use keys to store authentication
tokens which can be made to be automatically cleaned up a set time after
the user last uses them, but until then permits them to hang around after
the user has logged out so that cron(8) scripts can use them.
The kernel source files Documentation/crypto/asymmetric-keys.txt
(or, before Linux 4.13, in the file