GENWiki

USER-KEYRING(7) Linux Programmer's Manual USER-KEYRING(7)

NAME

     user-keyring - per-user keyring

DESCRIPTION

     The  user keyring is a keyring used to anchor keys on behalf of a user.
     Each UID the kernel deals with has its own user keyring that is  shared
     by  all processes with that UID.  The user keyring has a name (descrip-
     tion) of the form _uid.<UID> where <UID> is the user ID of  the  corre-
     sponding user.

     The  user  keyring  is associated with the record that the kernel main-
     tains for the UID.  It comes into existence upon the first  attempt  to
     access  either  the  user  keyring, the user-session-keyring(7), or the
     session-keyring(7).  The keyring remains pinned in existence so long as
     there are processes running with that real UID or files opened by those
     processes remain open.  (The keyring can also be pinned indefinitely by
     linking it into another keyring.)

     Typically,  the  user  keyring is created by pam_keyinit(8) when a user
     logs in.

     The user keyring is not searched by default  by  request_key(2).   When
     pam_keyinit(8)  creates  a session keyring, it adds to it a link to the
     user keyring so that the user keyring will be searched when the session
     keyring is.

     A  special  serial number value, KEY_SPEC_USER_KEYRING, is defined that
     can be used in  lieu  of  the  actual  serial  number  of  the  calling
     process's user keyring.

     From  the  keyctl(1) utility, '@u' can be used instead of a numeric key
     ID in much the same way.

     User  keyrings  are  independent  of   clone(2),   fork(2),   vfork(2),
     execve(2),  and  _exit(2)  excepting that the keyring is destroyed when
     the UID record is destroyed when the last process pinning it exits.

     If it is necessary for a key associated with a user to exist beyond the
     UID  record  being garbage collected--for example, for use by a cron(8)
     script--then the persistent-keyring(7) should be used instead.

     If a user keyring does not exist when it is accessed, it will  be  cre-
     ated.