| .\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved. |
| .\" Written by David Howells (dhowells@redhat.com) |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA) |
| .\" This program is free software; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License |
| .\" as published by the Free Software Foundation; either version |
| .\" 2 of the License, or (at your option) any later version. |
| .\" %%%LICENSE_END |
| .\" |
| .TH PERSISTENT-KEYRING 7 2020-08-13 Linux "Linux Programmer's Manual" |
| .SH NAME |
| persistent-keyring \- per-user persistent keyring |
| .SH DESCRIPTION |
| The persistent keyring is a keyring used to anchor keys on behalf of a user. |
| Each UID the kernel deals with has its own persistent keyring that |
| is shared between all threads owned by that UID. |
| The persistent keyring has a name (description) of the form |
| .I _persistent.<UID> |
| where |
| .I <UID> |
| is the user ID of the corresponding user. |
| .PP |
| The persistent keyring may not be accessed directly, |
| even by processes with the appropriate UID. |
| .\" FIXME The meaning of the preceding sentence isn't clear. What is meant? |
| Instead, it must first be linked to one of a process's keyrings, |
| before that keyring can access the persistent keyring |
| by virtue of its possessor permits. |
| This linking is done with the |
| .BR keyctl_get_persistent (3) |
| function. |
| .PP |
| If a persistent keyring does not exist when it is accessed by the |
| .BR keyctl_get_persistent (3) |
| operation, it will be automatically created. |
| .PP |
| Each time the |
| .BR keyctl_get_persistent (3) |
| operation is performed, |
| the persistent key's expiration timer is reset to the value in: |
| .PP |
| /proc/sys/kernel/keys/persistent_keyring_expiry |
| .PP |
| Should the timeout be reached, |
| the persistent keyring will be removed and |
| everything it pins can then be garbage collected. |
| The key will then be re-created on a subsequent call to |
| .BR keyctl_get_persistent (3). |
| .PP |
| The persistent keyring is not directly searched by |
| .BR request_key (2); |
| it is searched only if it is linked into one of the keyrings |
| that is searched by |
| .BR request_key (2). |
| .PP |
| The persistent keyring is independent of |
| .BR clone (2), |
| .BR fork (2), |
| .BR vfork (2), |
| .BR execve (2), |
| and |
| .BR _exit (2). |
| It persists until its expiration timer triggers, |
| at which point it is garbage collected. |
| This allows the persistent keyring to carry keys beyond the life of |
| the kernel's record of the corresponding UID |
| (the destruction of which results in the destruction of the |
| .BR user\-keyring (7) |
| and the |
| .BR user\-session\-keyring (7)). |
| The persistent keyring can thus be used to |
| hold authentication tokens for processes that run without user interaction, |
| such as programs started by |
| .BR cron (8). |
| .PP |
| The persistent keyring is used to store UID-specific objects that |
| themselves have limited lifetimes (e.g., kerberos tokens). |
| If those tokens cease to be used |
| (i.e., the persistent keyring is not accessed), |
| then the timeout of the persistent keyring ensures that |
| the corresponding objects are automatically discarded. |
| .\" |
| .SS Special operations |
| The |
| .I keyutils |
| library provides the |
| .BR keyctl_get_persistent (3) |
| function for manipulating persistent keyrings. |
| (This function is an interface to the |
| .BR keyctl (2) |
| .B KEYCTL_GET_PERSISTENT |
| operation.) |
| This operation allows the calling thread to get the persistent keyring |
| corresponding to its own UID or, if the thread has the |
| .BR CAP_SETUID |
| capability, the persistent keyring corresponding to some other UID |
| in the same user namespace. |
| .SH NOTES |
| Each user namespace owns a keyring called |
| .IR .persistent_register |
| that contains links to all of the persistent keys in that namespace. |
| (The |
| .IR .persistent_register |
| keyring can be seen when reading the contents of the |
| .IR /proc/keys |
| file for the UID 0 in the namespace.) |
| The |
| .BR keyctl_get_persistent (3) |
| operation looks for a key with a name of the form |
| .IR _persistent.<UID> |
| in that keyring, |
| creates the key if it does not exist, and links it into the keyring. |
| .SH SEE ALSO |
| .ad l |
| .nh |
| .BR keyctl (1), |
| .BR keyctl (3), |
| .BR keyctl_get_persistent (3), |
| .BR keyrings (7), |
| .BR process\-keyring (7), |
| .BR session\-keyring (7), |
| .BR thread\-keyring (7), |
| .BR user\-keyring (7), |
| .BR user\-session\-keyring (7) |