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) function.

       If a persistent keyring does not exist when it is accessed by the keyctl_get_persistent(3) operation,  it
       will be automatically created.

       Each  time the keyctl_get_persistent(3) operation is performed, the persistent keyring's expiration 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).

       The  persistent  keyring  is not directly searched by request_key(2); it is searched only if it is linked
       into one of the keyrings that is searched by request_key(2).

       The persistent keyring is independent of  clone(2),  fork(2),  vfork(2),  execve(2),  and  _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 user-keyring(7) and the 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 cron(8).

       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.

   Special operations
       The keyutils library provides the keyctl_get_persistent(3) function for manipulating persistent keyrings.
       (This  function is an interface to the keyctl(2) 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
       CAP_SETUID capability, the persistent keyring corresponding 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) 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), keyctl(3), keyctl_get_persistent(3), keyrings(7), process-keyring(7), session-keyring(7),
       thread-keyring(7), user-keyring(7), user-session-keyring(7)

Linux man-pages 6.7                                2023-10-31                              persistent-keyring(7)