man7/user-session-keyring.7

   1 .\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
   2 .\" Written by David Howells (dhowells@redhat.com)
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH USER-SESSION-KEYRING 7 2020-08-13 "Linux man-pages (unreleased)"
   7 .SH NAME
   8 user-session-keyring \- per-user default session keyring
   9 .SH DESCRIPTION
  10 The user session keyring is a keyring used to anchor keys on behalf of a user.
  11 Each UID the kernel deals with has its own user session keyring that
  12 is shared by all processes with that UID.
  13 The user session keyring has a name (description) of the form
  14 .I _uid_ses.<UID>
  15 where
  16 .I <UID>
  17 is the user ID of the corresponding user.
  18 .PP
  19 The user session keyring is associated with the record that
  20 the kernel maintains for the UID.
  21 It comes into existence upon the first attempt to access either the
  22 user session keyring, the
  23 .BR user\-keyring (7),
  24 or the
  25 .BR session\-keyring (7).
  26 .\" Davis Howells: the user and user-session keyrings are managed as a pair.
  27 The keyring remains pinned in existence so long as there are processes
  28 running with that real UID or files opened by those processes remain open.
  29 (The keyring can also be pinned indefinitely by linking it
  30 into another keyring.)
  31 .PP
  32 The user session keyring is created on demand when a thread requests it
  33 or when a thread asks for its
  34 .BR session\-keyring (7)
  35 and that keyring doesn't exist.
  36 In the latter case, a user session keyring will be created and,
  37 if the session keyring wasn't to be created,
  38 the user session keyring will be set as the process's actual session keyring.
  39 .PP
  40 The user session keyring is searched by
  41 .BR request_key (2)
  42 if the actual session keyring does not exist and is ignored otherwise.
  43 .PP
  44 A special serial number value,
  45 .BR KEY_SPEC_USER_SESSION_KEYRING ,
  46 is defined
  47 that can be used in lieu of the actual serial number of
  48 the calling process's user session keyring.
  49 .PP
  50 From the
  51 .BR keyctl (1)
  52 utility, '\fB@us\fP' can be used instead of a numeric key ID in
  53 much the same way.
  54 .PP
  55 User session keyrings are independent of
  56 .BR clone (2),
  57 .BR fork (2),
  58 .BR vfork (2),
  59 .BR execve (2),
  60 and
  61 .BR _exit (2)
  62 excepting that the keyring is destroyed when the UID record is destroyed
  63 when the last process pinning it exits.
  64 .PP
  65 If a user session keyring does not exist when it is accessed,
  66 it will be created.
  67 .PP
  68 Rather than relying on the user session keyring,
  69 it is strongly recommended\(emespecially if the process
  70 is running as root\(emthat a
  71 .BR session\-keyring (7)
  72 be set explicitly, for example by
  73 .BR pam_keyinit (8).
  74 .SH NOTES
  75 The user session keyring was added to support situations where
  76 a process doesn't have a session keyring,
  77 perhaps because it was created via a pathway that didn't involve PAM
  78 (e.g., perhaps it was a daemon started by
  79 .BR inetd (8)).
  80 In such a scenario, the user session keyring acts as a substitute for the
  81 .BR session\-keyring (7).
  82 .SH SEE ALSO
  83 .ad l
  84 .nh
  85 .BR keyctl (1),
  86 .BR keyctl (3),
  87 .BR keyrings (7),
  88 .BR persistent\-keyring (7),
  89 .BR process\-keyring (7),
  90 .BR session\-keyring (7),
  91 .BR thread\-keyring (7),
  92 .BR user\-keyring (7)