|
NAME | DESCRIPTION | SEE ALSO | COLOPHON |
KEYRINGS(7) Linux Programmer's Manual KEYRINGS(7)
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 add_key(2), request_key(2), and keyctl(2).
A library and some user-space utilities are provided to allow access
to the facility. See keyctl(1), keyctl(3), and keyutils(7) for more
information.
Keys
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 key_serial_t.
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 used.
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 matched.
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 request_key(2).
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 will 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.
Key types
The kernel provides several basic types of key:
"keyring"
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.
"user" 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 applications.
The payload for keys of this type is a blob of arbitrary data
of up to 32,767 bytes.
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.
"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 space.
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
implementation.
Keyrings
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:
Adding 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.
Linking
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.
Unlinking
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 collector.
Clearing
All the links may be removed from a keyring.
Searching
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.
See keyctl_clear(3), keyctl_link(3), keyctl_search(3), and
keyctl_unlink(3) for more information.
Anchoring keys
To prevent a key from being garbage collected, it must 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 space.
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 has been defined for this keyring.
Possession
The concept of possession is important to understanding the keyrings
security model. Whether a thread possesses a key is determined by
the following rules:
(1) Any key or keyring that does not grant search permission to the
caller is ignored in all the following rules.
(2) A thread possesses its session-keyring(7), process-keyring(7),
and thread-keyring(7) directly because those keyrings are
referred to by its credentials.
(3) If a keyring is possessed, then any key it links to is also
possessed.
(4) If any key a keyring links to is itself a keyring, then rule (3)
applies recursively.
(5) 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 user-keyring(7), thus making the user keyring and anything it
contains possessed by default.
Access rights
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:
user The set specifies the rights granted if the key's user ID
matches the caller's filesystem user ID.
group 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.
other The set specifies the rights granted if neither the key's user
ID nor group ID matched.
The fourth set of rights is:
possessor
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:
view The attributes of the key may be read. This includes the
type, description, and access rights (excluding the security
label).
read 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.
write 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),
search 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.
link 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 permission.
setattr
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 keyctl_get_security(3).
See keyctl_chown(3), keyctl_describe(3), keyctl_get_security(3),
keyctl_setperm(3), and selinux(8) for more information.
Searching for keys
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:
(1) 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.
(2) 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.
(3) 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 are searched.
(4) If a matching key is found that is valid, then the search
terminates and that key is returned.
(5) If a matching key is found that has an error state attached, that
error state is noted and the search continues.
(6) 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.
See request_key(2) and keyctl_search(3) for more information.
On-demand key creation
If a key cannot be found, request_key(2) will, if given a
callout_info 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 request-key(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.
See request_key(2), keyctl_assume_authority(3),
keyctl_instantiate(3), keyctl_negate(3), keyctl_reject(3),
request-key(8), and request-key.conf(5) for more information.
/proc files
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:
I The key has been instantiated.
R The key has been revoked.
D The key is dead (i.e., the key type has been
unregistered). (A key may be briefly in this state
during garbage collection.)
Q The key contributes to the user's quota.
U The key is under construction via a callback to
user space; see request-key(2).
N The key is negatively instantiated.
i 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 collected.
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:
0x01 view
Ox02 read
0x04 write
0x08 search
0x10 link
0x20 setattr
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 kernel.
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
name[: extra-info]
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 follows:
"user" and "logon"
The size in bytes of the key payload (expressed in
decimal).
"keyring"
The number of keys linked to the keyring, or the
string empty if there are no keys linked to the
keyring.
"big_key"
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 kernel memory.
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:
key The hexadecimal ID of the key being instantiated
in the requesting program.
pid The PID of the requesting program.
ci The length of the callout data with which the
requested key should be instantiated (i.e., the
length of the payload associated with the
authorization key).
/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:
uid The user ID.
usage This is a kernel-internal usage count for the kernel
structure used to record key users.
nkeys/nikeys
The total number of keys owned by the user, and the
number of those keys that have been instantiated.
qnkeys/maxkeys
The number of keys owned by the user, and the maximum
number of keys that the user may own.
qnbytes/maxbytes
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 user.
/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 3.13)
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) KEYCTL_GET_PERSISTENT operation.)
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 root.
The default value in this file is 25,000,000 (20,000 before
Linux 3.17).
/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.
Users
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 kAFS.
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 shares.
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.
keyctl(1), add_key(2), keyctl(2), request_key(2), keyctl(3),
keyutils(7), persistent-keyring(7), process-keyring(7),
session-keyring(7), thread-keyring(7), user-keyring(7),
user-session-keyring(7), pam_keyinit(8), request-key(8)
This page is part of release 4.12 of the Linux man-pages project. A
description of the project, information about reporting bugs, and the
latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.
Linux 2017-03-13 KEYRINGS(7)
Pages that refer to this page: keyctl(1), add_key(2), keyctl(2), request_key(2), find_key_by_type_and_name(3), keyctl(3), keyctl_chown(3), keyctl_clear(3), keyctl_describe(3), keyctl_get_keyring_ID(3), keyctl_get_persistent(3), keyctl_get_security(3), keyctl_instantiate(3), keyctl_invalidate(3), keyctl_join_session_keyring(3), keyctl_link(3), keyctl_read(3), keyctl_revoke(3), keyctl_search(3), keyctl_session_to_parent(3), keyctl_setperm(3), keyctl_set_reqkey_keyring(3), keyctl_set_timeout(3), keyctl_update(3), recursive_key_scan(3), proc(5), keyutils(7), persistent-keyring(7), process-keyring(7), session-keyring(7), thread-keyring(7), user-keyring(7), user_namespaces(7), user-session-keyring(7), key.dns_resolver(8), request-key(8)