man7/persistent-keyring.7

   1 .\"
   2 .\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
   3 .\" Written by David Howells (dhowells@redhat.com)
   4 .\"
   5 .\" This program is free software; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public Licence
   7 .\" as published by the Free Software Foundation; either version
   8 .\" 2 of the Licence, or (at your option) any later version.
   9 .\"
  10 .TH "PERSISTENT-KEYRING" 7 2016-11-01 Linux "Linux Programmer's Manual"
  11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  12 .SH NAME
  13 persistent-keyring \- per-user persistent keyring
  14 .SH DESCRIPTION
  15 The
  16 .B persistent keyring
  17 is a keyring used to anchor keys on behalf of a user.  Each UID the kernel
  18 deals with has its own persistent keyring that is shared between all threads
  19 owned by that UID.
  20 .P
  21 The persistent keyring is created on demand when a thread requests it.  The
  22 keyring's expiration timer is reset every time it is accessed to the value in:
  23 .IP
  24 /proc/sys/kernel/keys/persistent_keyring_expiry
  25 .P
  26 The persistent keyring is not searched by \fBrequest_key\fP() unless it is
  27 referred to by a keyring that is.
  28 .P
  29 The persistent keyring may not be accessed directly, even by processes with
  30 the appropriate UID.  Instead it must be linked to one of a process's keyrings
  31 first before that keyring can access it by virtue of its possessor permits.
  32 This is done with \fBkeyctl_get_persistent\fP().
  33 .P
  34 Persistent keyrings are independent of clone(), fork(), vfork(), execve() and
  35 exit().  They persist until their expiration timers trigger - at which point
  36 they are garbage collected.  This allows them to carry keys beyond the life of
  37 the kernel's record of the corresponding UID (the destruction of which results
  38 in the destruction of the user and user session keyrings).
  39 .P
  40 If a persistent keyring does not exist when it is accessed, it will be
  41 created.
  42 .SH SPECIAL OPERATIONS
  43 The keyutils library provides a special operation for manipulating persistent
  44 keyrings:
  45 .IP \fBkeyctl_get_persistent\fP()
  46 This operation allows the caller to get the persistent keyring corresponding
  47 to their own UID or, if they have \fBCAP_SETUID\fR, the persistent keyring
  48 corresponding to some other UID in the same user namespace.
  49 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  50 .SH SEE ALSO
  51 .ad l
  52 .nh
  53 .BR keyctl (1),
  54 .BR keyctl (3),
  55 .BR keyctl_get_persistent (3),
  56 .BR keyrings (7),
  57 .BR process\-keyring (7),
  58 .BR session\-keyring (7),
  59 .BR thread\-keyring (7),
  60 .BR user\-keyring (7),
  61 .BR user\-session\-keyring (7)