man7/user-session-keyring.7

   1 .\"
   2 .\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
   3 .\" Written by David Howells (dhowells@redhat.com)
   4 .\"
   5 .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
   6 .\" This program is free software; you can redistribute it and/or
   7 .\" modify it under the terms of the GNU General Public Licence
   8 .\" as published by the Free Software Foundation; either version
   9 .\" 2 of the Licence, or (at your option) any later version.
  10 .\" %%%LICENSE_END
  11 .\"
  12 .TH "USER-SESSION-KEYRING" 7 2016-11-01 Linux "Linux Programmer's Manual"
  13 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  14 .SH NAME
  15 user-session-keyring \- per-user default session keyring
  16 .SH DESCRIPTION
  17 The
  18 .B user session keyring
  19 is a keyring used to anchor keys on behalf of a user.
  20 Each UID the kernel
  21 deals with has its own user session keyring.
  22 This keyring is associated with
  23 the record that the kernel maintains for the UID and, once created, is retained
  24 as long as that record persists.
  25 It is shared amongst all processes of that
  26 UID.
  27 .P
  28 The user session keyring is created on demand when a thread requests it
  29 or when a thread asks for its \fBsession keyring\fP and that doesn't exist.
  30 In the latter case,
  31 a user session keyring will be created and, if the session keyring
  32 wasn't to be created, the user session keyring will be set as the process's
  33 actual session keyring.
  34 .P
  35 The user session keyring is searched by \fBrequest_key\fP() if the actual
  36 session keyring does not exist and is ignored otherwise.
  37 .P
  38 A special serial number value, \fBKEY_SPEC_USER_SESSION_KEYRING\fP, is defined
  39 that can be used in lieu of the calling process's user session keyring's actual
  40 serial number.
  41 .P
  42 From the keyctl utility, '\fB@us\fP' can be used instead of a numeric key ID in
  43 much the same way.
  44 .P
  45 User session keyrings are independent of clone(), fork(), vfork(), execve() and
  46 exit() excepting that the keyring is destroyed when the UID record is destroyed
  47 when the last process pinning it exits.
  48 .P
  49 If a user session keyring does not exist when it is accessed, it will be
  50 created.
  51 .P
  52 It is strongly recommended that a \fBsession keyring\fP be set explicitly, for
  53 example by \fBpam_keyinit\fP, rather than relying on the user session keyring -
  54 particularly if a process is running as root.
  55 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  56 .SH SEE ALSO
  57 .ad l
  58 .nh
  59 .BR keyctl (1),
  60 .BR keyctl (3),
  61 .BR keyrings (7),
  62 .BR persistent\-keyring (7),
  63 .BR process\-keyring (7),
  64 .BR session\-keyring (7),
  65 .BR thread\-keyring (7),
  66 .BR user\-keyring (7)