1 ===================
2 Key Request Service
3 ===================
4
5 The key request service is part of the key ret
6 Documentation/security/keys/core.rst). This d
7 the requesting algorithm works.
8
9 The process starts by either the kernel reques
10 ``request_key*()``::
11
12 struct key *request_key(const struct k
13 const char *de
14 const char *ca
15
16 or::
17
18 struct key *request_key_tag(const stru
19 const char
20 const stru
21 const char
22
23 or::
24
25 struct key *request_key_with_auxdata(c
26 c
27 c
28 c
29 s
30 v
31
32 or::
33
34 struct key *request_key_rcu(const stru
35 const char
36 const stru
37
38 Or by userspace invoking the request_key syste
39
40 key_serial_t request_key(const char *t
41 const char *d
42 const char *c
43 key_serial_t
44
45 The main difference between the access points
46 does not need to link the key to a keyring to
47 destroyed. The kernel interface returns a poi
48 it's up to the caller to destroy the key.
49
50 The request_key_tag() call is like the in-kern
51 also takes a domain tag that allows keys to be
52 killed off as a group.
53
54 The request_key_with_auxdata() calls is like t
55 that they permit auxiliary data to be passed t
56 NULL). This is only useful for those key type
57 mechanism rather than using /sbin/request-key.
58
59 The request_key_rcu() call is like the request
60 doesn't check for keys that are under construc
61 construct missing keys.
62
63 The userspace interface links the key to a key
64 to prevent the key from going away, and return
65 the caller.
66
67
68 The following example assumes that the key typ
69 own upcall mechanisms. If they do, then those
70 forking and execution of /sbin/request-key.
71
72
73 The Process
74 ===========
75
76 A request proceeds in the following manner:
77
78 1) Process A calls request_key() [the usersp
79 interface].
80
81 2) request_key() searches the process's subs
82 a suitable key there. If there is, it re
83 and callout_info is not set, an error is
84 proceeds to the next step.
85
86 3) request_key() sees that A doesn't have th
87 two things:
88
89 a) An uninstantiated key U of requested
90
91 b) An authorisation key V that refers to
92 is the context in which key U should
93 from which associated key requests ma
94
95 4) request_key() then forks and executes /sb
96 keyring that contains a link to auth key
97
98 5) /sbin/request-key assumes the authority a
99
100 6) /sbin/request-key execs an appropriate pr
101 instantiation.
102
103 7) The program may want to access another ke
104 Kerberos TGT key). It just requests the
105 search notes that the session keyring has
106
107 This will permit it to then search the ke
108 UID, GID, groups and security info of pro
109 and come up with key W.
110
111 8) The program then does what it must to get
112 instantiate key U, using key W as a refer
113 Kerberos server using the TGT) and then i
114
115 9) Upon instantiating key U, auth key V is a
116 may not be used again.
117
118 10) The program then exits 0 and request_key
119 U to the caller.
120
121 This also extends further. If key W (step 7 a
122 be created uninstantiated, another auth key (X
123 3) and another copy of /sbin/request-key spawn
124 context specified by auth key X will still be
125 V.
126
127 This is because process A's keyrings can't sim
128 /sbin/request-key at the appropriate places be
129 of them, and (b) it requires the same UID/GID/
130
131
132 Negative Instantiation And Rejection
133 ====================================
134
135 Rather than instantiating a key, it is possibl
136 authorisation key to negatively instantiate a
137 This is a short duration placeholder that caus
138 the key while it exists to fail with error ENO
139 error if rejected.
140
141 This is provided to prevent excessive repeated
142 processes for a key that will never be obtaina
143
144 Should the /sbin/request-key process exit anyt
145 signal, the key under construction will be aut
146 instantiated for a short amount of time.
147
148
149 The Search Algorithm
150 ====================
151
152 A search of any particular keyring proceeds in
153
154 1) When the key management code searches for
155 firstly calls key_permission(SEARCH) on t
156 if this denies permission, it doesn't sea
157
158 2) It considers all the non-keyring keys wit
159 matches the criteria specified, calls key
160 if the key is allowed to be found. If it
161 not, the search continues, and the error
162 priority than the one currently set.
163
164 3) It then considers all the keyring-type ke
165 searching. It calls key_permission(SEARC
166 grants permission, it recurses, executing
167 keyring.
168
169 The process stops immediately a valid key is f
170 use it. Any error from a previous match attem
171 returned.
172
173 When request_key() is invoked, if CONFIG_KEYS_
174 one-key cache is first checked for a match.
175
176 When search_process_keyrings() is invoked, it
177 until one succeeds:
178
179 1) If extant, the process's thread keyring i
180
181 2) If extant, the process's process keyring
182
183 3) The process's session keyring is searched
184
185 4) If the process has assumed the authority
186 authorisation key then:
187
188 a) If extant, the calling process's thre
189
190 b) If extant, the calling process's proc
191
192 c) The calling process's session keyring
193
194 The moment one succeeds, all pending errors ar
195 returned. If CONFIG_KEYS_REQUEST_CACHE=y, the
196 per-task cache, displacing the previous key.
197 just prior to resumption of userspace.
198
199 Only if all these fail does the whole thing fa
200 error. Note that several errors may have come
201
202 The error priority is::
203
204 EKEYREVOKED > EKEYEXPIRED > ENOKEY
205
206 EACCES/EPERM are only returned on a direct sea
207 the basal keyring does not grant Search permis
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.