| 1 |
.\" Copyright 2014, Red Hat, Inc. |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: GPL-2.0-or-later |
| 5 |
.\" |
| 6 |
.TH persistent-keyring 7 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
persistent-keyring \- per-user persistent keyring |
| 9 |
.SH DESCRIPTION |
| 10 |
The persistent keyring is a keyring used to anchor keys on behalf of a user. |
| 11 |
Each UID the kernel deals with has its own persistent keyring that |
| 12 |
is shared between all threads owned by that UID. |
| 13 |
The persistent keyring has a name (description) of the form |
| 14 |
.I _persistent.<UID> |
| 15 |
where |
| 16 |
.I <UID> |
| 17 |
is the user ID of the corresponding user. |
| 18 |
.P |
| 19 |
The persistent keyring may not be accessed directly, |
| 20 |
even by processes with the appropriate UID. |
| 21 |
.\" FIXME The meaning of the preceding sentence isn't clear. What is meant? |
| 22 |
Instead, it must first be linked to one of a process's keyrings, |
| 23 |
before that keyring can access the persistent keyring |
| 24 |
by virtue of its possessor permits. |
| 25 |
This linking is done with the |
| 26 |
.BR keyctl_get_persistent (3) |
| 27 |
function. |
| 28 |
.P |
| 29 |
If a persistent keyring does not exist when it is accessed by the |
| 30 |
.BR keyctl_get_persistent (3) |
| 31 |
operation, it will be automatically created. |
| 32 |
.P |
| 33 |
Each time the |
| 34 |
.BR keyctl_get_persistent (3) |
| 35 |
operation is performed, |
| 36 |
the persistent keyring's expiration timer is reset to the value in: |
| 37 |
.P |
| 38 |
.in +4n |
| 39 |
.EX |
| 40 |
/proc/sys/kernel/keys/persistent_keyring_expiry |
| 41 |
.EE |
| 42 |
.in |
| 43 |
.P |
| 44 |
Should the timeout be reached, |
| 45 |
the persistent keyring will be removed and |
| 46 |
everything it pins can then be garbage collected. |
| 47 |
The keyring will then be re-created on a subsequent call to |
| 48 |
.BR keyctl_get_persistent (3). |
| 49 |
.P |
| 50 |
The persistent keyring is not directly searched by |
| 51 |
.BR request_key (2); |
| 52 |
it is searched only if it is linked into one of the keyrings |
| 53 |
that is searched by |
| 54 |
.BR request_key (2). |
| 55 |
.P |
| 56 |
The persistent keyring is independent of |
| 57 |
.BR clone (2), |
| 58 |
.BR fork (2), |
| 59 |
.BR vfork (2), |
| 60 |
.BR execve (2), |
| 61 |
and |
| 62 |
.BR _exit (2). |
| 63 |
It persists until its expiration timer triggers, |
| 64 |
at which point it is garbage collected. |
| 65 |
This allows the persistent keyring to carry keys beyond the life of |
| 66 |
the kernel's record of the corresponding UID |
| 67 |
(the destruction of which results in the destruction of the |
| 68 |
.BR user\-keyring (7) |
| 69 |
and the |
| 70 |
.BR user\-session\-keyring (7)). |
| 71 |
The persistent keyring can thus be used to |
| 72 |
hold authentication tokens for processes that run without user interaction, |
| 73 |
such as programs started by |
| 74 |
.BR cron (8). |
| 75 |
.P |
| 76 |
The persistent keyring is used to store UID-specific objects that |
| 77 |
themselves have limited lifetimes (e.g., kerberos tokens). |
| 78 |
If those tokens cease to be used |
| 79 |
(i.e., the persistent keyring is not accessed), |
| 80 |
then the timeout of the persistent keyring ensures that |
| 81 |
the corresponding objects are automatically discarded. |
| 82 |
.\" |
| 83 |
.SS Special operations |
| 84 |
The |
| 85 |
.I keyutils |
| 86 |
library provides the |
| 87 |
.BR keyctl_get_persistent (3) |
| 88 |
function for manipulating persistent keyrings. |
| 89 |
(This function is an interface to the |
| 90 |
.BR keyctl (2) |
| 91 |
.B KEYCTL_GET_PERSISTENT |
| 92 |
operation.) |
| 93 |
This operation allows the calling thread to get the persistent keyring |
| 94 |
corresponding to its own UID or, if the thread has the |
| 95 |
.B CAP_SETUID |
| 96 |
capability, the persistent keyring corresponding to some other UID |
| 97 |
in the same user namespace. |
| 98 |
.SH NOTES |
| 99 |
Each user namespace owns a keyring called |
| 100 |
.I .persistent_register |
| 101 |
that contains links to all of the persistent keys in that namespace. |
| 102 |
(The |
| 103 |
.I .persistent_register |
| 104 |
keyring can be seen when reading the contents of the |
| 105 |
.I /proc/keys |
| 106 |
file for the UID 0 in the namespace.) |
| 107 |
The |
| 108 |
.BR keyctl_get_persistent (3) |
| 109 |
operation looks for a key with a name of the form |
| 110 |
.IR _persistent. UID |
| 111 |
in that keyring, |
| 112 |
creates the key if it does not exist, and links it into the keyring. |
| 113 |
.SH SEE ALSO |
| 114 |
.ad l |
| 115 |
.nh |
| 116 |
.BR keyctl (1), |
| 117 |
.BR keyctl (3), |
| 118 |
.BR keyctl_get_persistent (3), |
| 119 |
.BR keyrings (7), |
| 120 |
.BR process\-keyring (7), |
| 121 |
.BR session\-keyring (7), |
| 122 |
.BR thread\-keyring (7), |
| 123 |
.BR user\-keyring (7), |
| 124 |
.BR user\-session\-keyring (7) |