man7/persistent-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 persistent-keyring 7 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 persistent-keyring \- per-user persistent keyring
   9 .SH DESCRIPTION
  10 The persistent keyring is a keyring used to anchor keys on behalf of a user.
  11 Each UID the kernel deals with has its own persistent keyring that
  12 is shared between all threads owned by that UID.
  13 The persistent keyring has a name (description) of the form
  14 .I _persistent.<UID>
  15 where
  16 .I <UID>
  17 is the user ID of the corresponding user.
  18 .P
  19 The persistent keyring may not be accessed directly,
  20 even by processes with the appropriate UID.
  21 .\" FIXME The meaning of the preceding sentence isn't clear. What is meant?
  22 Instead, it must first be linked to one of a process's keyrings,
  23 before that keyring can access the persistent keyring
  24 by virtue of its possessor permits.
  25 This linking is done with the
  26 .BR keyctl_get_persistent (3)
  27 function.
  28 .P
  29 If a persistent keyring does not exist when it is accessed by the
  30 .BR keyctl_get_persistent (3)
  31 operation, it will be automatically created.
  32 .P
  33 Each time the
  34 .BR keyctl_get_persistent (3)
  35 operation is performed,
  36 the persistent keyring's expiration timer is reset to the value in:
  37 .P
  38 .in +4n
  39 .EX
  40 /proc/sys/kernel/keys/persistent_keyring_expiry
  41 .EE
  42 .in
  43 .P
  44 Should the timeout be reached,
  45 the persistent keyring will be removed and
  46 everything it pins can then be garbage collected.
  47 The keyring will then be re-created on a subsequent call to
  48 .BR keyctl_get_persistent (3).
  49 .P
  50 The persistent keyring is not directly searched by
  51 .BR request_key (2);
  52 it is searched only if it is linked into one of the keyrings
  53 that is searched by
  54 .BR request_key (2).
  55 .P
  56 The persistent keyring is independent of
  57 .BR clone (2),
  58 .BR fork (2),
  59 .BR vfork (2),
  60 .BR execve (2),
  61 and
  62 .BR _exit (2).
  63 It persists until its expiration timer triggers,
  64 at which point it is garbage collected.
  65 This allows the persistent keyring to carry keys beyond the life of
  66 the kernel's record of the corresponding UID
  67 (the destruction of which results in the destruction of the
  68 .BR user\-keyring (7)
  69 and the
  70 .BR user\-session\-keyring (7)).
  71 The persistent keyring can thus be used to
  72 hold authentication tokens for processes that run without user interaction,
  73 such as programs started by
  74 .BR cron (8).
  75 .P
  76 The persistent keyring is used to store UID-specific objects that
  77 themselves have limited lifetimes (e.g., kerberos tokens).
  78 If those tokens cease to be used
  79 (i.e., the persistent keyring is not accessed),
  80 then the timeout of the persistent keyring ensures that
  81 the corresponding objects are automatically discarded.
  82 .\"
  83 .SS Special operations
  84 The
  85 .I keyutils
  86 library provides the
  87 .BR keyctl_get_persistent (3)
  88 function for manipulating persistent keyrings.
  89 (This function is an interface to the
  90 .BR keyctl (2)
  91 .B KEYCTL_GET_PERSISTENT
  92 operation.)
  93 This operation allows the calling thread to get the persistent keyring
  94 corresponding to its own UID or, if the thread has the
  95 .B CAP_SETUID
  96 capability, the persistent keyring corresponding to some other UID
  97 in the same user namespace.
  98 .SH NOTES
  99 Each user namespace owns a keyring called
 100 .I .persistent_register
 101 that contains links to all of the persistent keys in that namespace.
 102 (The
 103 .I .persistent_register
 104 keyring can be seen when reading the contents of the
 105 .I /proc/keys
 106 file for the UID 0 in the namespace.)
 107 The
 108 .BR keyctl_get_persistent (3)
 109 operation looks for a key with a name of the form
 110 .IR _persistent. UID
 111 in that keyring,
 112 creates the key if it does not exist, and links it into the keyring.
 113 .SH SEE ALSO
 114 .ad l
 115 .nh
 116 .BR keyctl (1),
 117 .BR keyctl (3),
 118 .BR keyctl_get_persistent (3),
 119 .BR keyrings (7),
 120 .BR process\-keyring (7),
 121 .BR session\-keyring (7),
 122 .BR thread\-keyring (7),
 123 .BR user\-keyring (7),
 124 .BR user\-session\-keyring (7)