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,
11 encryption 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
19 information.
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
27 referred as the key ID. Programmatically, key serial numbers
28 are 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
46 upcall to user space to finish the instantiation of a key if
47 that key wasn't already known to the kernel when it was
48 requested. 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