1PERSISTENT-KEYRING(7)      Linux Programmer's Manual     PERSISTENT-KEYRING(7)
2
3
4

NAME

6       persistent-keyring - per-user persistent keyring
7

DESCRIPTION

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
15       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
21       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
24       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
27           /proc/sys/kernel/keys/persistent_keyring_expiry
28
29       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
33       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
37       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
47       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
53   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

NOTES

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

SEE ALSO

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

COLOPHON

76       This page is part of release 5.13 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/.
80
81
82
83Linux                             2020-08-13             PERSISTENT-KEYRING(7)
Impressum