1PERSISTENT-KEYRING(7) Linux Programmer's Manual PERSISTENT-KEYRING(7)
2
6 persistent-keyring - per-user persistent keyring
7
9 The persistent keyring is a keyring used to anchor keys on behalf of a
10 user. Each UID the kernel deals with has its own persistent keyring
11 that is shared between all threads owned by that UID. The persistent
12 keyring has a name (description) of the form _persistent.<UID> where
13 <UID> is the user ID of the corresponding user.
14 The persistent keyring may not be accessed directly, even by processes
16 with the appropriate UID. Instead, it must first be linked to one of a
17 process's keyrings, before that keyring can access the persistent
18 keyring by virtue of its possessor permits. This linking is done with
19 the keyctl_get_persistent(3) function.
20 If a persistent keyring does not exist when it is accessed by the
22 keyctl_get_persistent(3) operation, it will be automatically created.
23 Each time the keyctl_get_persistent(3) operation is performed, the per‐
25 sistent key's expiration timer is reset to the value in:
26 /proc/sys/kernel/keys/persistent_keyring_expiry
28 Should the timeout be reached, the persistent keyring will be removed
30 and everything it pins can then be garbage collected. The key will
31 then be re-created on a subsequent call to keyctl_get_persistent(3).
32 The persistent keyring is not directly searched by request_key(2); it
34 is searched only if it is linked into one of the keyrings that is
35 searched by request_key(2).
36 The persistent keyring is independent of clone(2), fork(2), vfork(2),
38 execve(2), and _exit(2). It persists until its expiration timer trig‐
39 gers, at which point it is garbage collected. This allows the persis‐
40 tent keyring to carry keys beyond the life of the kernel's record of
41 the corresponding UID (the destruction of which results in the destruc‐
42 tion of the user-keyring(7) and the user-session-keyring(7)). The per‐
43 sistent keyring can thus be used to hold authentication tokens for pro‐
44 cesses that run without user interaction, such as programs started by
45 cron(8).
46 The persistent keyring is used to store UID-specific objects that them‐
48 selves have limited lifetimes (e.g., kerberos tokens). If those tokens
49 cease to be used (i.e., the persistent keyring is not accessed), then
50 the timeout of the persistent keyring ensures that the corresponding
51 objects are automatically discarded.
52 Special operations
54 The keyutils library provides the keyctl_get_persistent(3) function for
55 manipulating persistent keyrings. (This function is an interface to
56 the keyctl(2) KEYCTL_GET_PERSISTENT operation.) This operation allows
57 the calling thread to get the persistent keyring corresponding to its
58 own UID or, if the thread has the CAP_SETUID capability, the persistent
59 keyring corresponding to some other UID in the same user namespace.
60
62 Each user namespace owns a keyring called .persistent_register that
63 contains links to all of the persistent keys in that namespace. (The
64 .persistent_register keyring can be seen when reading the contents of
65 the /proc/keys file for the UID 0 in the namespace.) The
66 keyctl_get_persistent(3) operation looks for a key with a name of the
67 form _persistent.<UID> in that keyring, creates the key if it does not
68 exist, and links it into the keyring.
69
71 keyctl(1), keyctl(3), keyctl_get_persistent(3), keyrings(7),
72 process-keyring(7), session-keyring(7), thread-keyring(7),
73 user-keyring(7), user-session-keyring(7)
74
76 This page is part of release 5.12 of the Linux man-pages project. A
77 description of the project, information about reporting bugs, and the
78 latest version of this page, can be found at
79 https://www.kernel.org/doc/man-pages/.
80Linux 2020-08-13 PERSISTENT-KEYRING(7)