# persistent-keyring - per-user persistent keyring - man(7) - [phpMan]

[_persistent-keyring_(7)](https://www.chedong.com/phpMan.php/man/persistent-keyring/7/markdown)             Miscellaneous Information Manual             [_persistent-keyring_(7)](https://www.chedong.com/phpMan.php/man/persistent-keyring/7/markdown)

## NAME
       persistent-keyring - per-user persistent keyring

## 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 __persistent.<UID>_
       where _<UID>_ is the user ID of the corresponding user.

       The persistent keyring may not be accessed directly, even by processes with  the  appropriate
       UID.   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 [**keyctl_get_persistent**(3)](https://www.chedong.com/phpMan.php/man/keyctlgetpersistent/3/markdown) function.

       If  a  persistent  keyring does not exist when it is accessed by the [**keyctl_get_persistent**(3)](https://www.chedong.com/phpMan.php/man/keyctlgetpersistent/3/markdown)
       operation, it will be automatically created.

       Each time the [**keyctl_get_persistent**(3)](https://www.chedong.com/phpMan.php/man/keyctlgetpersistent/3/markdown) operation is performed, the persistent keyring's expi‐
       ration timer is reset to the value in:

           /proc/sys/kernel/keys/persistent_keyring_expiry

       Should the timeout be reached, the persistent keyring will be removed and everything it  pins
       can  then  be garbage collected.  The keyring will then be re-created on a subsequent call to
       [**keyctl_get_persistent**(3)](https://www.chedong.com/phpMan.php/man/keyctlgetpersistent/3/markdown).

       The persistent keyring is not directly searched by [**request_key**(2)](https://www.chedong.com/phpMan.php/man/requestkey/2/markdown); it is searched only if  it
       is linked into one of the keyrings that is searched by [**request_key**(2)](https://www.chedong.com/phpMan.php/man/requestkey/2/markdown).

       The  persistent  keyring  is  independent  of  [**clone**(2)](https://www.chedong.com/phpMan.php/man/clone/2/markdown),  [**fork**(2)](https://www.chedong.com/phpMan.php/man/fork/2/markdown),  [**vfork**(2)](https://www.chedong.com/phpMan.php/man/vfork/2/markdown),  [**execve**(2)](https://www.chedong.com/phpMan.php/man/execve/2/markdown), and
       [**_exit**(2)](https://www.chedong.com/phpMan.php/man/exit/2/markdown).  It persists until its expiration timer triggers, at which point it is garbage col‐
       lected.  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
       [**user-keyring**(7)](https://www.chedong.com/phpMan.php/man/user-keyring/7/markdown) and the [**user-session-keyring**(7)](https://www.chedong.com/phpMan.php/man/user-session-keyring/7/markdown)).  The persistent keyring can thus be used to
       hold authentication tokens for processes that run without user interaction, such as  programs
       started by [**cron**(8)](https://www.chedong.com/phpMan.php/man/cron/8/markdown).

       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 corre‐
       sponding objects are automatically discarded.

### Special operations
       The _keyutils_ library provides the [**keyctl_get_persistent**(3)](https://www.chedong.com/phpMan.php/man/keyctlgetpersistent/3/markdown) function for manipulating  persis‐
       tent  keyrings.  (This function is an interface to the [**keyctl**(2)](https://www.chedong.com/phpMan.php/man/keyctl/2/markdown) **KEYCTL_GET_PERSISTENT **opera‐
       tion.)  This operation allows the calling thread to get the persistent keyring  corresponding
       to its own UID or, if the thread has the **CAP_SETUID **capability, the persistent keyring corre‐
       sponding to some other UID in the same user namespace.

## NOTES
       Each  user namespace owns a keyring called _.persistent_register_ that contains links to all of
       the persistent keys in that namespace.  (The _.persistent_register_ keyring can  be  seen  when
       reading  the  contents  of  the  _/proc/keys_  file  for  the  UID  0  in  the namespace.)  The
       [**keyctl_get_persistent**(3)](https://www.chedong.com/phpMan.php/man/keyctlgetpersistent/3/markdown) operation looks for a key with a name of the form __persistent._UID in
       that keyring, creates the key if it does not exist, and links it into the keyring.

## SEE ALSO
       [**keyctl**(1)](https://www.chedong.com/phpMan.php/man/keyctl/1/markdown), [**keyctl**(3)](https://www.chedong.com/phpMan.php/man/keyctl/3/markdown), [**keyctl_get_persistent**(3)](https://www.chedong.com/phpMan.php/man/keyctlgetpersistent/3/markdown), [**keyrings**(7)](https://www.chedong.com/phpMan.php/man/keyrings/7/markdown), [**process-keyring**(7)](https://www.chedong.com/phpMan.php/man/process-keyring/7/markdown),
       [**session-keyring**(7)](https://www.chedong.com/phpMan.php/man/session-keyring/7/markdown), [**thread-keyring**(7)](https://www.chedong.com/phpMan.php/man/thread-keyring/7/markdown), [**user-keyring**(7)](https://www.chedong.com/phpMan.php/man/user-keyring/7/markdown), [**user-session-keyring**(7)](https://www.chedong.com/phpMan.php/man/user-session-keyring/7/markdown)

Linux man-pages 6.7                          2023-10-31                        [_persistent-keyring_(7)](https://www.chedong.com/phpMan.php/man/persistent-keyring/7/markdown)