man > persistent-keyring(7)

persistent-keyring(7)             Miscellaneous Information Manual             persistent-keyring(7)

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

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

   Special operations
       The keyutils library provides the keyctl_get_persistent(3) function for manipulating  persis‐
       tent  keyrings.  (This function is an interface to the keyctl(2) 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) 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)