2 .\" Copyright (C) 2014 Red Hat, Inc. All Rights Reserved.
3 .\" Written by David Howells (dhowells@redhat.com)
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 License
8 .\" as published by the Free Software Foundation; either version
9 .\" 2 of the License, or (at your option) any later version.
12 .TH "PERSISTENT-KEYRING" 7 2016-11-01 Linux "Linux Programmer's Manual"
14 persistent-keyring \- per-user persistent keyring
16 The persistent keyring is a keyring used to anchor keys on behalf of a user.
17 Each UID the kernel deals with has its own persistent keyring that
18 is shared between all threads owned by that UID.
19 The persistent keyring has a name (description) of the form
23 is the user ID of the corresponding user.
25 The persistent keyring may not be accessed directly,
26 even by processes with the appropriate UID.
27 .\" FIXME The meaning of the preceding sentence isn't clear. What is meant?
28 Instead, it must first be linked to one of a process's keyrings,
29 before that keyring can access the persistent keyring
30 by virtue of its possessor permits.
31 This linking is done with the
32 .BR keyctl_get_persistent (3)
35 If a persistent keyring does not exist when it is accessed by the
36 .BR keyctl_get_persistent (3)
37 operation, it will be automatically created.
40 .BR keyctl_get_persistent (3)
41 operation is performed,
42 the persistent key's expiration timer is reset to the value in:
44 /proc/sys/kernel/keys/persistent_keyring_expiry
46 Should the timeout be reached,
47 the persistent keyring will be removed and
48 everything it pins can then be garbage collected.
49 The key will then be re-created on a subsequent call to
50 .BR keyctl_get_persistent (3).
52 The persistent keyring is not directly searched by
54 it is searched only if it is linked into one of the keyrings
58 The persistent keyring is independent of
65 It persists until its expiration timer triggers,
66 at which point it is garbage collected.
67 This allows the persistent keyring to carry keys beyond the life of
68 the kernel's record of the corresponding UID
69 (the destruction of which results in the destruction of the
72 .BR user-session-keyring (7)).
73 The persistent keyring can thus be used to
74 hold authentication tokens for processes that run without user interaction,
75 such as programs started by
78 The persistent keyring is used to store UID-specific objects that
79 themselves have limited lifetimes (e.g., kerberos tokens).
80 If those tokens cease to be used
81 (i.e., the persistent keyring is not accessed),
82 then the timeout of the persistent keyring ensures that
83 the corresponding objects are automatically discarded.
85 .SS Special operations
89 .BR keyctl_get_persistent (3)
90 function for manipulating persistent keyrings.
91 (This function is an interface to the
93 .B KEYCTL_GET_PERSISTENT
95 This operation allows the calling thread to get the persistent keyring
96 corresponding to its own UID or, if the thread has the
98 capability, the persistent keyring corresponding to some other UID
99 in the same user namespace.
101 Each user namespace owns a keyring called
102 .IR .persistent_register
103 that contains links to all of the persistent keys in that namespace.
105 .IR .persistent_register
106 keyring can be seen when reading the contents of the
108 file for the UID 0 in the namespace.)
110 .BR keyctl_get_persistent (3)
111 operation looks for a key with a name of the form
112 .IR _persistent.<UID>
114 creates the key if it does not exist, and links it into the keyring.
120 .BR keyctl_get_persistent (3),
122 .BR process\-keyring (7),
123 .BR session\-keyring (7),
124 .BR thread\-keyring (7),
125 .BR user\-keyring (7),
126 .BR user\-session\-keyring (7)