1 |
3 |
xianfeng |
============================
|
2 |
|
|
KERNEL KEY RETENTION SERVICE
|
3 |
|
|
============================
|
4 |
|
|
|
5 |
|
|
This service allows cryptographic keys, authentication tokens, cross-domain
|
6 |
|
|
user mappings, and similar to be cached in the kernel for the use of
|
7 |
|
|
filesystems and other kernel services.
|
8 |
|
|
|
9 |
|
|
Keyrings are permitted; these are a special type of key that can hold links to
|
10 |
|
|
other keys. Processes each have three standard keyring subscriptions that a
|
11 |
|
|
kernel service can search for relevant keys.
|
12 |
|
|
|
13 |
|
|
The key service can be configured on by enabling:
|
14 |
|
|
|
15 |
|
|
"Security options"/"Enable access key retention support" (CONFIG_KEYS)
|
16 |
|
|
|
17 |
|
|
This document has the following sections:
|
18 |
|
|
|
19 |
|
|
- Key overview
|
20 |
|
|
- Key service overview
|
21 |
|
|
- Key access permissions
|
22 |
|
|
- SELinux support
|
23 |
|
|
- New procfs files
|
24 |
|
|
- Userspace system call interface
|
25 |
|
|
- Kernel services
|
26 |
|
|
- Notes on accessing payload contents
|
27 |
|
|
- Defining a key type
|
28 |
|
|
- Request-key callback service
|
29 |
|
|
- Key access filesystem
|
30 |
|
|
|
31 |
|
|
|
32 |
|
|
============
|
33 |
|
|
KEY OVERVIEW
|
34 |
|
|
============
|
35 |
|
|
|
36 |
|
|
In this context, keys represent units of cryptographic data, authentication
|
37 |
|
|
tokens, keyrings, etc.. These are represented in the kernel by struct key.
|
38 |
|
|
|
39 |
|
|
Each key has a number of attributes:
|
40 |
|
|
|
41 |
|
|
- A serial number.
|
42 |
|
|
- A type.
|
43 |
|
|
- A description (for matching a key in a search).
|
44 |
|
|
- Access control information.
|
45 |
|
|
- An expiry time.
|
46 |
|
|
- A payload.
|
47 |
|
|
- State.
|
48 |
|
|
|
49 |
|
|
|
50 |
|
|
(*) Each key is issued a serial number of type key_serial_t that is unique for
|
51 |
|
|
the lifetime of that key. All serial numbers are positive non-zero 32-bit
|
52 |
|
|
integers.
|
53 |
|
|
|
54 |
|
|
Userspace programs can use a key's serial numbers as a way to gain access
|
55 |
|
|
to it, subject to permission checking.
|
56 |
|
|
|
57 |
|
|
(*) Each key is of a defined "type". Types must be registered inside the
|
58 |
|
|
kernel by a kernel service (such as a filesystem) before keys of that type
|
59 |
|
|
can be added or used. Userspace programs cannot define new types directly.
|
60 |
|
|
|
61 |
|
|
Key types are represented in the kernel by struct key_type. This defines a
|
62 |
|
|
number of operations that can be performed on a key of that type.
|
63 |
|
|
|
64 |
|
|
Should a type be removed from the system, all the keys of that type will
|
65 |
|
|
be invalidated.
|
66 |
|
|
|
67 |
|
|
(*) Each key has a description. This should be a printable string. The key
|
68 |
|
|
type provides an operation to perform a match between the description on a
|
69 |
|
|
key and a criterion string.
|
70 |
|
|
|
71 |
|
|
(*) Each key has an owner user ID, a group ID and a permissions mask. These
|
72 |
|
|
are used to control what a process may do to a key from userspace, and
|
73 |
|
|
whether a kernel service will be able to find the key.
|
74 |
|
|
|
75 |
|
|
(*) Each key can be set to expire at a specific time by the key type's
|
76 |
|
|
instantiation function. Keys can also be immortal.
|
77 |
|
|
|
78 |
|
|
(*) Each key can have a payload. This is a quantity of data that represent the
|
79 |
|
|
actual "key". In the case of a keyring, this is a list of keys to which
|
80 |
|
|
the keyring links; in the case of a user-defined key, it's an arbitrary
|
81 |
|
|
blob of data.
|
82 |
|
|
|
83 |
|
|
Having a payload is not required; and the payload can, in fact, just be a
|
84 |
|
|
value stored in the struct key itself.
|
85 |
|
|
|
86 |
|
|
When a key is instantiated, the key type's instantiation function is
|
87 |
|
|
called with a blob of data, and that then creates the key's payload in
|
88 |
|
|
some way.
|
89 |
|
|
|
90 |
|
|
Similarly, when userspace wants to read back the contents of the key, if
|
91 |
|
|
permitted, another key type operation will be called to convert the key's
|
92 |
|
|
attached payload back into a blob of data.
|
93 |
|
|
|
94 |
|
|
(*) Each key can be in one of a number of basic states:
|
95 |
|
|
|
96 |
|
|
(*) Uninstantiated. The key exists, but does not have any data attached.
|
97 |
|
|
Keys being requested from userspace will be in this state.
|
98 |
|
|
|
99 |
|
|
(*) Instantiated. This is the normal state. The key is fully formed, and
|
100 |
|
|
has data attached.
|
101 |
|
|
|
102 |
|
|
(*) Negative. This is a relatively short-lived state. The key acts as a
|
103 |
|
|
note saying that a previous call out to userspace failed, and acts as
|
104 |
|
|
a throttle on key lookups. A negative key can be updated to a normal
|
105 |
|
|
state.
|
106 |
|
|
|
107 |
|
|
(*) Expired. Keys can have lifetimes set. If their lifetime is exceeded,
|
108 |
|
|
they traverse to this state. An expired key can be updated back to a
|
109 |
|
|
normal state.
|
110 |
|
|
|
111 |
|
|
(*) Revoked. A key is put in this state by userspace action. It can't be
|
112 |
|
|
found or operated upon (apart from by unlinking it).
|
113 |
|
|
|
114 |
|
|
(*) Dead. The key's type was unregistered, and so the key is now useless.
|
115 |
|
|
|
116 |
|
|
|
117 |
|
|
====================
|
118 |
|
|
KEY SERVICE OVERVIEW
|
119 |
|
|
====================
|
120 |
|
|
|
121 |
|
|
The key service provides a number of features besides keys:
|
122 |
|
|
|
123 |
|
|
(*) The key service defines two special key types:
|
124 |
|
|
|
125 |
|
|
(+) "keyring"
|
126 |
|
|
|
127 |
|
|
Keyrings are special keys that contain a list of other keys. Keyring
|
128 |
|
|
lists can be modified using various system calls. Keyrings should not
|
129 |
|
|
be given a payload when created.
|
130 |
|
|
|
131 |
|
|
(+) "user"
|
132 |
|
|
|
133 |
|
|
A key of this type has a description and a payload that are arbitrary
|
134 |
|
|
blobs of data. These can be created, updated and read by userspace,
|
135 |
|
|
and aren't intended for use by kernel services.
|
136 |
|
|
|
137 |
|
|
(*) Each process subscribes to three keyrings: a thread-specific keyring, a
|
138 |
|
|
process-specific keyring, and a session-specific keyring.
|
139 |
|
|
|
140 |
|
|
The thread-specific keyring is discarded from the child when any sort of
|
141 |
|
|
clone, fork, vfork or execve occurs. A new keyring is created only when
|
142 |
|
|
required.
|
143 |
|
|
|
144 |
|
|
The process-specific keyring is replaced with an empty one in the child on
|
145 |
|
|
clone, fork, vfork unless CLONE_THREAD is supplied, in which case it is
|
146 |
|
|
shared. execve also discards the process's process keyring and creates a
|
147 |
|
|
new one.
|
148 |
|
|
|
149 |
|
|
The session-specific keyring is persistent across clone, fork, vfork and
|
150 |
|
|
execve, even when the latter executes a set-UID or set-GID binary. A
|
151 |
|
|
process can, however, replace its current session keyring with a new one
|
152 |
|
|
by using PR_JOIN_SESSION_KEYRING. It is permitted to request an anonymous
|
153 |
|
|
new one, or to attempt to create or join one of a specific name.
|
154 |
|
|
|
155 |
|
|
The ownership of the thread keyring changes when the real UID and GID of
|
156 |
|
|
the thread changes.
|
157 |
|
|
|
158 |
|
|
(*) Each user ID resident in the system holds two special keyrings: a user
|
159 |
|
|
specific keyring and a default user session keyring. The default session
|
160 |
|
|
keyring is initialised with a link to the user-specific keyring.
|
161 |
|
|
|
162 |
|
|
When a process changes its real UID, if it used to have no session key, it
|
163 |
|
|
will be subscribed to the default session key for the new UID.
|
164 |
|
|
|
165 |
|
|
If a process attempts to access its session key when it doesn't have one,
|
166 |
|
|
it will be subscribed to the default for its current UID.
|
167 |
|
|
|
168 |
|
|
(*) Each user has two quotas against which the keys they own are tracked. One
|
169 |
|
|
limits the total number of keys and keyrings, the other limits the total
|
170 |
|
|
amount of description and payload space that can be consumed.
|
171 |
|
|
|
172 |
|
|
The user can view information on this and other statistics through procfs
|
173 |
|
|
files.
|
174 |
|
|
|
175 |
|
|
Process-specific and thread-specific keyrings are not counted towards a
|
176 |
|
|
user's quota.
|
177 |
|
|
|
178 |
|
|
If a system call that modifies a key or keyring in some way would put the
|
179 |
|
|
user over quota, the operation is refused and error EDQUOT is returned.
|
180 |
|
|
|
181 |
|
|
(*) There's a system call interface by which userspace programs can create and
|
182 |
|
|
manipulate keys and keyrings.
|
183 |
|
|
|
184 |
|
|
(*) There's a kernel interface by which services can register types and search
|
185 |
|
|
for keys.
|
186 |
|
|
|
187 |
|
|
(*) There's a way for the a search done from the kernel to call back to
|
188 |
|
|
userspace to request a key that can't be found in a process's keyrings.
|
189 |
|
|
|
190 |
|
|
(*) An optional filesystem is available through which the key database can be
|
191 |
|
|
viewed and manipulated.
|
192 |
|
|
|
193 |
|
|
|
194 |
|
|
======================
|
195 |
|
|
KEY ACCESS PERMISSIONS
|
196 |
|
|
======================
|
197 |
|
|
|
198 |
|
|
Keys have an owner user ID, a group access ID, and a permissions mask. The mask
|
199 |
|
|
has up to eight bits each for possessor, user, group and other access. Only
|
200 |
|
|
six of each set of eight bits are defined. These permissions granted are:
|
201 |
|
|
|
202 |
|
|
(*) View
|
203 |
|
|
|
204 |
|
|
This permits a key or keyring's attributes to be viewed - including key
|
205 |
|
|
type and description.
|
206 |
|
|
|
207 |
|
|
(*) Read
|
208 |
|
|
|
209 |
|
|
This permits a key's payload to be viewed or a keyring's list of linked
|
210 |
|
|
keys.
|
211 |
|
|
|
212 |
|
|
(*) Write
|
213 |
|
|
|
214 |
|
|
This permits a key's payload to be instantiated or updated, or it allows a
|
215 |
|
|
link to be added to or removed from a keyring.
|
216 |
|
|
|
217 |
|
|
(*) Search
|
218 |
|
|
|
219 |
|
|
This permits keyrings to be searched and keys to be found. Searches can
|
220 |
|
|
only recurse into nested keyrings that have search permission set.
|
221 |
|
|
|
222 |
|
|
(*) Link
|
223 |
|
|
|
224 |
|
|
This permits a key or keyring to be linked to. To create a link from a
|
225 |
|
|
keyring to a key, a process must have Write permission on the keyring and
|
226 |
|
|
Link permission on the key.
|
227 |
|
|
|
228 |
|
|
(*) Set Attribute
|
229 |
|
|
|
230 |
|
|
This permits a key's UID, GID and permissions mask to be changed.
|
231 |
|
|
|
232 |
|
|
For changing the ownership, group ID or permissions mask, being the owner of
|
233 |
|
|
the key or having the sysadmin capability is sufficient.
|
234 |
|
|
|
235 |
|
|
|
236 |
|
|
===============
|
237 |
|
|
SELINUX SUPPORT
|
238 |
|
|
===============
|
239 |
|
|
|
240 |
|
|
The security class "key" has been added to SELinux so that mandatory access
|
241 |
|
|
controls can be applied to keys created within various contexts. This support
|
242 |
|
|
is preliminary, and is likely to change quite significantly in the near future.
|
243 |
|
|
Currently, all of the basic permissions explained above are provided in SELinux
|
244 |
|
|
as well; SELinux is simply invoked after all basic permission checks have been
|
245 |
|
|
performed.
|
246 |
|
|
|
247 |
|
|
The value of the file /proc/self/attr/keycreate influences the labeling of
|
248 |
|
|
newly-created keys. If the contents of that file correspond to an SELinux
|
249 |
|
|
security context, then the key will be assigned that context. Otherwise, the
|
250 |
|
|
key will be assigned the current context of the task that invoked the key
|
251 |
|
|
creation request. Tasks must be granted explicit permission to assign a
|
252 |
|
|
particular context to newly-created keys, using the "create" permission in the
|
253 |
|
|
key security class.
|
254 |
|
|
|
255 |
|
|
The default keyrings associated with users will be labeled with the default
|
256 |
|
|
context of the user if and only if the login programs have been instrumented to
|
257 |
|
|
properly initialize keycreate during the login process. Otherwise, they will
|
258 |
|
|
be labeled with the context of the login program itself.
|
259 |
|
|
|
260 |
|
|
Note, however, that the default keyrings associated with the root user are
|
261 |
|
|
labeled with the default kernel context, since they are created early in the
|
262 |
|
|
boot process, before root has a chance to log in.
|
263 |
|
|
|
264 |
|
|
The keyrings associated with new threads are each labeled with the context of
|
265 |
|
|
their associated thread, and both session and process keyrings are handled
|
266 |
|
|
similarly.
|
267 |
|
|
|
268 |
|
|
|
269 |
|
|
================
|
270 |
|
|
NEW PROCFS FILES
|
271 |
|
|
================
|
272 |
|
|
|
273 |
|
|
Two files have been added to procfs by which an administrator can find out
|
274 |
|
|
about the status of the key service:
|
275 |
|
|
|
276 |
|
|
(*) /proc/keys
|
277 |
|
|
|
278 |
|
|
This lists the keys that are currently viewable by the task reading the
|
279 |
|
|
file, giving information about their type, description and permissions.
|
280 |
|
|
It is not possible to view the payload of the key this way, though some
|
281 |
|
|
information about it may be given.
|
282 |
|
|
|
283 |
|
|
The only keys included in the list are those that grant View permission to
|
284 |
|
|
the reading process whether or not it possesses them. Note that LSM
|
285 |
|
|
security checks are still performed, and may further filter out keys that
|
286 |
|
|
the current process is not authorised to view.
|
287 |
|
|
|
288 |
|
|
The contents of the file look like this:
|
289 |
|
|
|
290 |
|
|
SERIAL FLAGS USAGE EXPY PERM UID GID TYPE DESCRIPTION: SUMMARY
|
291 |
|
|
00000001 I----- 39 perm 1f3f0000 0 0 keyring _uid_ses.0: 1/4
|
292 |
|
|
00000002 I----- 2 perm 1f3f0000 0 0 keyring _uid.0: empty
|
293 |
|
|
00000007 I----- 1 perm 1f3f0000 0 0 keyring _pid.1: empty
|
294 |
|
|
0000018d I----- 1 perm 1f3f0000 0 0 keyring _pid.412: empty
|
295 |
|
|
000004d2 I--Q-- 1 perm 1f3f0000 32 -1 keyring _uid.32: 1/4
|
296 |
|
|
000004d3 I--Q-- 3 perm 1f3f0000 32 -1 keyring _uid_ses.32: empty
|
297 |
|
|
00000892 I--QU- 1 perm 1f000000 0 0 user metal:copper: 0
|
298 |
|
|
00000893 I--Q-N 1 35s 1f3f0000 0 0 user metal:silver: 0
|
299 |
|
|
00000894 I--Q-- 1 10h 003f0000 0 0 user metal:gold: 0
|
300 |
|
|
|
301 |
|
|
The flags are:
|
302 |
|
|
|
303 |
|
|
I Instantiated
|
304 |
|
|
R Revoked
|
305 |
|
|
D Dead
|
306 |
|
|
Q Contributes to user's quota
|
307 |
|
|
U Under construction by callback to userspace
|
308 |
|
|
N Negative key
|
309 |
|
|
|
310 |
|
|
This file must be enabled at kernel configuration time as it allows anyone
|
311 |
|
|
to list the keys database.
|
312 |
|
|
|
313 |
|
|
(*) /proc/key-users
|
314 |
|
|
|
315 |
|
|
This file lists the tracking data for each user that has at least one key
|
316 |
|
|
on the system. Such data includes quota information and statistics:
|
317 |
|
|
|
318 |
|
|
[root@andromeda root]# cat /proc/key-users
|
319 |
|
|
0: 46 45/45 1/100 13/10000
|
320 |
|
|
29: 2 2/2 2/100 40/10000
|
321 |
|
|
32: 2 2/2 2/100 40/10000
|
322 |
|
|
38: 2 2/2 2/100 40/10000
|
323 |
|
|
|
324 |
|
|
The format of each line is
|
325 |
|
|
: User ID to which this applies
|
326 |
|
|
Structure refcount
|
327 |
|
|
/ Total number of keys and number instantiated
|
328 |
|
|
/ Key count quota
|
329 |
|
|
/ Key size quota
|
330 |
|
|
|
331 |
|
|
|
332 |
|
|
===============================
|
333 |
|
|
USERSPACE SYSTEM CALL INTERFACE
|
334 |
|
|
===============================
|
335 |
|
|
|
336 |
|
|
Userspace can manipulate keys directly through three new syscalls: add_key,
|
337 |
|
|
request_key and keyctl. The latter provides a number of functions for
|
338 |
|
|
manipulating keys.
|
339 |
|
|
|
340 |
|
|
When referring to a key directly, userspace programs should use the key's
|
341 |
|
|
serial number (a positive 32-bit integer). However, there are some special
|
342 |
|
|
values available for referring to special keys and keyrings that relate to the
|
343 |
|
|
process making the call:
|
344 |
|
|
|
345 |
|
|
CONSTANT VALUE KEY REFERENCED
|
346 |
|
|
============================== ====== ===========================
|
347 |
|
|
KEY_SPEC_THREAD_KEYRING -1 thread-specific keyring
|
348 |
|
|
KEY_SPEC_PROCESS_KEYRING -2 process-specific keyring
|
349 |
|
|
KEY_SPEC_SESSION_KEYRING -3 session-specific keyring
|
350 |
|
|
KEY_SPEC_USER_KEYRING -4 UID-specific keyring
|
351 |
|
|
KEY_SPEC_USER_SESSION_KEYRING -5 UID-session keyring
|
352 |
|
|
KEY_SPEC_GROUP_KEYRING -6 GID-specific keyring
|
353 |
|
|
KEY_SPEC_REQKEY_AUTH_KEY -7 assumed request_key()
|
354 |
|
|
authorisation key
|
355 |
|
|
|
356 |
|
|
|
357 |
|
|
The main syscalls are:
|
358 |
|
|
|
359 |
|
|
(*) Create a new key of given type, description and payload and add it to the
|
360 |
|
|
nominated keyring:
|
361 |
|
|
|
362 |
|
|
key_serial_t add_key(const char *type, const char *desc,
|
363 |
|
|
const void *payload, size_t plen,
|
364 |
|
|
key_serial_t keyring);
|
365 |
|
|
|
366 |
|
|
If a key of the same type and description as that proposed already exists
|
367 |
|
|
in the keyring, this will try to update it with the given payload, or it
|
368 |
|
|
will return error EEXIST if that function is not supported by the key
|
369 |
|
|
type. The process must also have permission to write to the key to be able
|
370 |
|
|
to update it. The new key will have all user permissions granted and no
|
371 |
|
|
group or third party permissions.
|
372 |
|
|
|
373 |
|
|
Otherwise, this will attempt to create a new key of the specified type and
|
374 |
|
|
description, and to instantiate it with the supplied payload and attach it
|
375 |
|
|
to the keyring. In this case, an error will be generated if the process
|
376 |
|
|
does not have permission to write to the keyring.
|
377 |
|
|
|
378 |
|
|
The payload is optional, and the pointer can be NULL if not required by
|
379 |
|
|
the type. The payload is plen in size, and plen can be zero for an empty
|
380 |
|
|
payload.
|
381 |
|
|
|
382 |
|
|
A new keyring can be generated by setting type "keyring", the keyring name
|
383 |
|
|
as the description (or NULL) and setting the payload to NULL.
|
384 |
|
|
|
385 |
|
|
User defined keys can be created by specifying type "user". It is
|
386 |
|
|
recommended that a user defined key's description by prefixed with a type
|
387 |
|
|
ID and a colon, such as "krb5tgt:" for a Kerberos 5 ticket granting
|
388 |
|
|
ticket.
|
389 |
|
|
|
390 |
|
|
Any other type must have been registered with the kernel in advance by a
|
391 |
|
|
kernel service such as a filesystem.
|
392 |
|
|
|
393 |
|
|
The ID of the new or updated key is returned if successful.
|
394 |
|
|
|
395 |
|
|
|
396 |
|
|
(*) Search the process's keyrings for a key, potentially calling out to
|
397 |
|
|
userspace to create it.
|
398 |
|
|
|
399 |
|
|
key_serial_t request_key(const char *type, const char *description,
|
400 |
|
|
const char *callout_info,
|
401 |
|
|
key_serial_t dest_keyring);
|
402 |
|
|
|
403 |
|
|
This function searches all the process's keyrings in the order thread,
|
404 |
|
|
process, session for a matching key. This works very much like
|
405 |
|
|
KEYCTL_SEARCH, including the optional attachment of the discovered key to
|
406 |
|
|
a keyring.
|
407 |
|
|
|
408 |
|
|
If a key cannot be found, and if callout_info is not NULL, then
|
409 |
|
|
/sbin/request-key will be invoked in an attempt to obtain a key. The
|
410 |
|
|
callout_info string will be passed as an argument to the program.
|
411 |
|
|
|
412 |
|
|
See also Documentation/keys-request-key.txt.
|
413 |
|
|
|
414 |
|
|
|
415 |
|
|
The keyctl syscall functions are:
|
416 |
|
|
|
417 |
|
|
(*) Map a special key ID to a real key ID for this process:
|
418 |
|
|
|
419 |
|
|
key_serial_t keyctl(KEYCTL_GET_KEYRING_ID, key_serial_t id,
|
420 |
|
|
int create);
|
421 |
|
|
|
422 |
|
|
The special key specified by "id" is looked up (with the key being created
|
423 |
|
|
if necessary) and the ID of the key or keyring thus found is returned if
|
424 |
|
|
it exists.
|
425 |
|
|
|
426 |
|
|
If the key does not yet exist, the key will be created if "create" is
|
427 |
|
|
non-zero; and the error ENOKEY will be returned if "create" is zero.
|
428 |
|
|
|
429 |
|
|
|
430 |
|
|
(*) Replace the session keyring this process subscribes to with a new one:
|
431 |
|
|
|
432 |
|
|
key_serial_t keyctl(KEYCTL_JOIN_SESSION_KEYRING, const char *name);
|
433 |
|
|
|
434 |
|
|
If name is NULL, an anonymous keyring is created attached to the process
|
435 |
|
|
as its session keyring, displacing the old session keyring.
|
436 |
|
|
|
437 |
|
|
If name is not NULL, if a keyring of that name exists, the process
|
438 |
|
|
attempts to attach it as the session keyring, returning an error if that
|
439 |
|
|
is not permitted; otherwise a new keyring of that name is created and
|
440 |
|
|
attached as the session keyring.
|
441 |
|
|
|
442 |
|
|
To attach to a named keyring, the keyring must have search permission for
|
443 |
|
|
the process's ownership.
|
444 |
|
|
|
445 |
|
|
The ID of the new session keyring is returned if successful.
|
446 |
|
|
|
447 |
|
|
|
448 |
|
|
(*) Update the specified key:
|
449 |
|
|
|
450 |
|
|
long keyctl(KEYCTL_UPDATE, key_serial_t key, const void *payload,
|
451 |
|
|
size_t plen);
|
452 |
|
|
|
453 |
|
|
This will try to update the specified key with the given payload, or it
|
454 |
|
|
will return error EOPNOTSUPP if that function is not supported by the key
|
455 |
|
|
type. The process must also have permission to write to the key to be able
|
456 |
|
|
to update it.
|
457 |
|
|
|
458 |
|
|
The payload is of length plen, and may be absent or empty as for
|
459 |
|
|
add_key().
|
460 |
|
|
|
461 |
|
|
|
462 |
|
|
(*) Revoke a key:
|
463 |
|
|
|
464 |
|
|
long keyctl(KEYCTL_REVOKE, key_serial_t key);
|
465 |
|
|
|
466 |
|
|
This makes a key unavailable for further operations. Further attempts to
|
467 |
|
|
use the key will be met with error EKEYREVOKED, and the key will no longer
|
468 |
|
|
be findable.
|
469 |
|
|
|
470 |
|
|
|
471 |
|
|
(*) Change the ownership of a key:
|
472 |
|
|
|
473 |
|
|
long keyctl(KEYCTL_CHOWN, key_serial_t key, uid_t uid, gid_t gid);
|
474 |
|
|
|
475 |
|
|
This function permits a key's owner and group ID to be changed. Either one
|
476 |
|
|
of uid or gid can be set to -1 to suppress that change.
|
477 |
|
|
|
478 |
|
|
Only the superuser can change a key's owner to something other than the
|
479 |
|
|
key's current owner. Similarly, only the superuser can change a key's
|
480 |
|
|
group ID to something other than the calling process's group ID or one of
|
481 |
|
|
its group list members.
|
482 |
|
|
|
483 |
|
|
|
484 |
|
|
(*) Change the permissions mask on a key:
|
485 |
|
|
|
486 |
|
|
long keyctl(KEYCTL_SETPERM, key_serial_t key, key_perm_t perm);
|
487 |
|
|
|
488 |
|
|
This function permits the owner of a key or the superuser to change the
|
489 |
|
|
permissions mask on a key.
|
490 |
|
|
|
491 |
|
|
Only bits the available bits are permitted; if any other bits are set,
|
492 |
|
|
error EINVAL will be returned.
|
493 |
|
|
|
494 |
|
|
|
495 |
|
|
(*) Describe a key:
|
496 |
|
|
|
497 |
|
|
long keyctl(KEYCTL_DESCRIBE, key_serial_t key, char *buffer,
|
498 |
|
|
size_t buflen);
|
499 |
|
|
|
500 |
|
|
This function returns a summary of the key's attributes (but not its
|
501 |
|
|
payload data) as a string in the buffer provided.
|
502 |
|
|
|
503 |
|
|
Unless there's an error, it always returns the amount of data it could
|
504 |
|
|
produce, even if that's too big for the buffer, but it won't copy more
|
505 |
|
|
than requested to userspace. If the buffer pointer is NULL then no copy
|
506 |
|
|
will take place.
|
507 |
|
|
|
508 |
|
|
A process must have view permission on the key for this function to be
|
509 |
|
|
successful.
|
510 |
|
|
|
511 |
|
|
If successful, a string is placed in the buffer in the following format:
|
512 |
|
|
|
513 |
|
|
;;;;
|
514 |
|
|
|
515 |
|
|
Where type and description are strings, uid and gid are decimal, and perm
|
516 |
|
|
is hexadecimal. A NUL character is included at the end of the string if
|
517 |
|
|
the buffer is sufficiently big.
|
518 |
|
|
|
519 |
|
|
This can be parsed with
|
520 |
|
|
|
521 |
|
|
sscanf(buffer, "%[^;];%d;%d;%o;%s", type, &uid, &gid, &mode, desc);
|
522 |
|
|
|
523 |
|
|
|
524 |
|
|
(*) Clear out a keyring:
|
525 |
|
|
|
526 |
|
|
long keyctl(KEYCTL_CLEAR, key_serial_t keyring);
|
527 |
|
|
|
528 |
|
|
This function clears the list of keys attached to a keyring. The calling
|
529 |
|
|
process must have write permission on the keyring, and it must be a
|
530 |
|
|
keyring (or else error ENOTDIR will result).
|
531 |
|
|
|
532 |
|
|
|
533 |
|
|
(*) Link a key into a keyring:
|
534 |
|
|
|
535 |
|
|
long keyctl(KEYCTL_LINK, key_serial_t keyring, key_serial_t key);
|
536 |
|
|
|
537 |
|
|
This function creates a link from the keyring to the key. The process must
|
538 |
|
|
have write permission on the keyring and must have link permission on the
|
539 |
|
|
key.
|
540 |
|
|
|
541 |
|
|
Should the keyring not be a keyring, error ENOTDIR will result; and if the
|
542 |
|
|
keyring is full, error ENFILE will result.
|
543 |
|
|
|
544 |
|
|
The link procedure checks the nesting of the keyrings, returning ELOOP if
|
545 |
|
|
it appears too deep or EDEADLK if the link would introduce a cycle.
|
546 |
|
|
|
547 |
|
|
Any links within the keyring to keys that match the new key in terms of
|
548 |
|
|
type and description will be discarded from the keyring as the new one is
|
549 |
|
|
added.
|
550 |
|
|
|
551 |
|
|
|
552 |
|
|
(*) Unlink a key or keyring from another keyring:
|
553 |
|
|
|
554 |
|
|
long keyctl(KEYCTL_UNLINK, key_serial_t keyring, key_serial_t key);
|
555 |
|
|
|
556 |
|
|
This function looks through the keyring for the first link to the
|
557 |
|
|
specified key, and removes it if found. Subsequent links to that key are
|
558 |
|
|
ignored. The process must have write permission on the keyring.
|
559 |
|
|
|
560 |
|
|
If the keyring is not a keyring, error ENOTDIR will result; and if the key
|
561 |
|
|
is not present, error ENOENT will be the result.
|
562 |
|
|
|
563 |
|
|
|
564 |
|
|
(*) Search a keyring tree for a key:
|
565 |
|
|
|
566 |
|
|
key_serial_t keyctl(KEYCTL_SEARCH, key_serial_t keyring,
|
567 |
|
|
const char *type, const char *description,
|
568 |
|
|
key_serial_t dest_keyring);
|
569 |
|
|
|
570 |
|
|
This searches the keyring tree headed by the specified keyring until a key
|
571 |
|
|
is found that matches the type and description criteria. Each keyring is
|
572 |
|
|
checked for keys before recursion into its children occurs.
|
573 |
|
|
|
574 |
|
|
The process must have search permission on the top level keyring, or else
|
575 |
|
|
error EACCES will result. Only keyrings that the process has search
|
576 |
|
|
permission on will be recursed into, and only keys and keyrings for which
|
577 |
|
|
a process has search permission can be matched. If the specified keyring
|
578 |
|
|
is not a keyring, ENOTDIR will result.
|
579 |
|
|
|
580 |
|
|
If the search succeeds, the function will attempt to link the found key
|
581 |
|
|
into the destination keyring if one is supplied (non-zero ID). All the
|
582 |
|
|
constraints applicable to KEYCTL_LINK apply in this case too.
|
583 |
|
|
|
584 |
|
|
Error ENOKEY, EKEYREVOKED or EKEYEXPIRED will be returned if the search
|
585 |
|
|
fails. On success, the resulting key ID will be returned.
|
586 |
|
|
|
587 |
|
|
|
588 |
|
|
(*) Read the payload data from a key:
|
589 |
|
|
|
590 |
|
|
long keyctl(KEYCTL_READ, key_serial_t keyring, char *buffer,
|
591 |
|
|
size_t buflen);
|
592 |
|
|
|
593 |
|
|
This function attempts to read the payload data from the specified key
|
594 |
|
|
into the buffer. The process must have read permission on the key to
|
595 |
|
|
succeed.
|
596 |
|
|
|
597 |
|
|
The returned data will be processed for presentation by the key type. For
|
598 |
|
|
instance, a keyring will return an array of key_serial_t entries
|
599 |
|
|
representing the IDs of all the keys to which it is subscribed. The user
|
600 |
|
|
defined key type will return its data as is. If a key type does not
|
601 |
|
|
implement this function, error EOPNOTSUPP will result.
|
602 |
|
|
|
603 |
|
|
As much of the data as can be fitted into the buffer will be copied to
|
604 |
|
|
userspace if the buffer pointer is not NULL.
|
605 |
|
|
|
606 |
|
|
On a successful return, the function will always return the amount of data
|
607 |
|
|
available rather than the amount copied.
|
608 |
|
|
|
609 |
|
|
|
610 |
|
|
(*) Instantiate a partially constructed key.
|
611 |
|
|
|
612 |
|
|
long keyctl(KEYCTL_INSTANTIATE, key_serial_t key,
|
613 |
|
|
const void *payload, size_t plen,
|
614 |
|
|
key_serial_t keyring);
|
615 |
|
|
|
616 |
|
|
If the kernel calls back to userspace to complete the instantiation of a
|
617 |
|
|
key, userspace should use this call to supply data for the key before the
|
618 |
|
|
invoked process returns, or else the key will be marked negative
|
619 |
|
|
automatically.
|
620 |
|
|
|
621 |
|
|
The process must have write access on the key to be able to instantiate
|
622 |
|
|
it, and the key must be uninstantiated.
|
623 |
|
|
|
624 |
|
|
If a keyring is specified (non-zero), the key will also be linked into
|
625 |
|
|
that keyring, however all the constraints applying in KEYCTL_LINK apply in
|
626 |
|
|
this case too.
|
627 |
|
|
|
628 |
|
|
The payload and plen arguments describe the payload data as for add_key().
|
629 |
|
|
|
630 |
|
|
|
631 |
|
|
(*) Negatively instantiate a partially constructed key.
|
632 |
|
|
|
633 |
|
|
long keyctl(KEYCTL_NEGATE, key_serial_t key,
|
634 |
|
|
unsigned timeout, key_serial_t keyring);
|
635 |
|
|
|
636 |
|
|
If the kernel calls back to userspace to complete the instantiation of a
|
637 |
|
|
key, userspace should use this call mark the key as negative before the
|
638 |
|
|
invoked process returns if it is unable to fulfil the request.
|
639 |
|
|
|
640 |
|
|
The process must have write access on the key to be able to instantiate
|
641 |
|
|
it, and the key must be uninstantiated.
|
642 |
|
|
|
643 |
|
|
If a keyring is specified (non-zero), the key will also be linked into
|
644 |
|
|
that keyring, however all the constraints applying in KEYCTL_LINK apply in
|
645 |
|
|
this case too.
|
646 |
|
|
|
647 |
|
|
|
648 |
|
|
(*) Set the default request-key destination keyring.
|
649 |
|
|
|
650 |
|
|
long keyctl(KEYCTL_SET_REQKEY_KEYRING, int reqkey_defl);
|
651 |
|
|
|
652 |
|
|
This sets the default keyring to which implicitly requested keys will be
|
653 |
|
|
attached for this thread. reqkey_defl should be one of these constants:
|
654 |
|
|
|
655 |
|
|
CONSTANT VALUE NEW DEFAULT KEYRING
|
656 |
|
|
====================================== ====== =======================
|
657 |
|
|
KEY_REQKEY_DEFL_NO_CHANGE -1 No change
|
658 |
|
|
KEY_REQKEY_DEFL_DEFAULT 0 Default[1]
|
659 |
|
|
KEY_REQKEY_DEFL_THREAD_KEYRING 1 Thread keyring
|
660 |
|
|
KEY_REQKEY_DEFL_PROCESS_KEYRING 2 Process keyring
|
661 |
|
|
KEY_REQKEY_DEFL_SESSION_KEYRING 3 Session keyring
|
662 |
|
|
KEY_REQKEY_DEFL_USER_KEYRING 4 User keyring
|
663 |
|
|
KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5 User session keyring
|
664 |
|
|
KEY_REQKEY_DEFL_GROUP_KEYRING 6 Group keyring
|
665 |
|
|
|
666 |
|
|
The old default will be returned if successful and error EINVAL will be
|
667 |
|
|
returned if reqkey_defl is not one of the above values.
|
668 |
|
|
|
669 |
|
|
The default keyring can be overridden by the keyring indicated to the
|
670 |
|
|
request_key() system call.
|
671 |
|
|
|
672 |
|
|
Note that this setting is inherited across fork/exec.
|
673 |
|
|
|
674 |
|
|
[1] The default is: the thread keyring if there is one, otherwise
|
675 |
|
|
the process keyring if there is one, otherwise the session keyring if
|
676 |
|
|
there is one, otherwise the user default session keyring.
|
677 |
|
|
|
678 |
|
|
|
679 |
|
|
(*) Set the timeout on a key.
|
680 |
|
|
|
681 |
|
|
long keyctl(KEYCTL_SET_TIMEOUT, key_serial_t key, unsigned timeout);
|
682 |
|
|
|
683 |
|
|
This sets or clears the timeout on a key. The timeout can be 0 to clear
|
684 |
|
|
the timeout or a number of seconds to set the expiry time that far into
|
685 |
|
|
the future.
|
686 |
|
|
|
687 |
|
|
The process must have attribute modification access on a key to set its
|
688 |
|
|
timeout. Timeouts may not be set with this function on negative, revoked
|
689 |
|
|
or expired keys.
|
690 |
|
|
|
691 |
|
|
|
692 |
|
|
(*) Assume the authority granted to instantiate a key
|
693 |
|
|
|
694 |
|
|
long keyctl(KEYCTL_ASSUME_AUTHORITY, key_serial_t key);
|
695 |
|
|
|
696 |
|
|
This assumes or divests the authority required to instantiate the
|
697 |
|
|
specified key. Authority can only be assumed if the thread has the
|
698 |
|
|
authorisation key associated with the specified key in its keyrings
|
699 |
|
|
somewhere.
|
700 |
|
|
|
701 |
|
|
Once authority is assumed, searches for keys will also search the
|
702 |
|
|
requester's keyrings using the requester's security label, UID, GID and
|
703 |
|
|
groups.
|
704 |
|
|
|
705 |
|
|
If the requested authority is unavailable, error EPERM will be returned,
|
706 |
|
|
likewise if the authority has been revoked because the target key is
|
707 |
|
|
already instantiated.
|
708 |
|
|
|
709 |
|
|
If the specified key is 0, then any assumed authority will be divested.
|
710 |
|
|
|
711 |
|
|
The assumed authoritative key is inherited across fork and exec.
|
712 |
|
|
|
713 |
|
|
|
714 |
|
|
===============
|
715 |
|
|
KERNEL SERVICES
|
716 |
|
|
===============
|
717 |
|
|
|
718 |
|
|
The kernel services for key management are fairly simple to deal with. They can
|
719 |
|
|
be broken down into two areas: keys and key types.
|
720 |
|
|
|
721 |
|
|
Dealing with keys is fairly straightforward. Firstly, the kernel service
|
722 |
|
|
registers its type, then it searches for a key of that type. It should retain
|
723 |
|
|
the key as long as it has need of it, and then it should release it. For a
|
724 |
|
|
filesystem or device file, a search would probably be performed during the open
|
725 |
|
|
call, and the key released upon close. How to deal with conflicting keys due to
|
726 |
|
|
two different users opening the same file is left to the filesystem author to
|
727 |
|
|
solve.
|
728 |
|
|
|
729 |
|
|
To access the key manager, the following header must be #included:
|
730 |
|
|
|
731 |
|
|
|
732 |
|
|
|
733 |
|
|
Specific key types should have a header file under include/keys/ that should be
|
734 |
|
|
used to access that type. For keys of type "user", for example, that would be:
|
735 |
|
|
|
736 |
|
|
|
737 |
|
|
|
738 |
|
|
Note that there are two different types of pointers to keys that may be
|
739 |
|
|
encountered:
|
740 |
|
|
|
741 |
|
|
(*) struct key *
|
742 |
|
|
|
743 |
|
|
This simply points to the key structure itself. Key structures will be at
|
744 |
|
|
least four-byte aligned.
|
745 |
|
|
|
746 |
|
|
(*) key_ref_t
|
747 |
|
|
|
748 |
|
|
This is equivalent to a struct key *, but the least significant bit is set
|
749 |
|
|
if the caller "possesses" the key. By "possession" it is meant that the
|
750 |
|
|
calling processes has a searchable link to the key from one of its
|
751 |
|
|
keyrings. There are three functions for dealing with these:
|
752 |
|
|
|
753 |
|
|
key_ref_t make_key_ref(const struct key *key,
|
754 |
|
|
unsigned long possession);
|
755 |
|
|
|
756 |
|
|
struct key *key_ref_to_ptr(const key_ref_t key_ref);
|
757 |
|
|
|
758 |
|
|
unsigned long is_key_possessed(const key_ref_t key_ref);
|
759 |
|
|
|
760 |
|
|
The first function constructs a key reference from a key pointer and
|
761 |
|
|
possession information (which must be 0 or 1 and not any other value).
|
762 |
|
|
|
763 |
|
|
The second function retrieves the key pointer from a reference and the
|
764 |
|
|
third retrieves the possession flag.
|
765 |
|
|
|
766 |
|
|
When accessing a key's payload contents, certain precautions must be taken to
|
767 |
|
|
prevent access vs modification races. See the section "Notes on accessing
|
768 |
|
|
payload contents" for more information.
|
769 |
|
|
|
770 |
|
|
(*) To search for a key, call:
|
771 |
|
|
|
772 |
|
|
struct key *request_key(const struct key_type *type,
|
773 |
|
|
const char *description,
|
774 |
|
|
const char *callout_string);
|
775 |
|
|
|
776 |
|
|
This is used to request a key or keyring with a description that matches
|
777 |
|
|
the description specified according to the key type's match function. This
|
778 |
|
|
permits approximate matching to occur. If callout_string is not NULL, then
|
779 |
|
|
/sbin/request-key will be invoked in an attempt to obtain the key from
|
780 |
|
|
userspace. In that case, callout_string will be passed as an argument to
|
781 |
|
|
the program.
|
782 |
|
|
|
783 |
|
|
Should the function fail error ENOKEY, EKEYEXPIRED or EKEYREVOKED will be
|
784 |
|
|
returned.
|
785 |
|
|
|
786 |
|
|
If successful, the key will have been attached to the default keyring for
|
787 |
|
|
implicitly obtained request-key keys, as set by KEYCTL_SET_REQKEY_KEYRING.
|
788 |
|
|
|
789 |
|
|
See also Documentation/keys-request-key.txt.
|
790 |
|
|
|
791 |
|
|
|
792 |
|
|
(*) To search for a key, passing auxiliary data to the upcaller, call:
|
793 |
|
|
|
794 |
|
|
struct key *request_key_with_auxdata(const struct key_type *type,
|
795 |
|
|
const char *description,
|
796 |
|
|
const char *callout_string,
|
797 |
|
|
void *aux);
|
798 |
|
|
|
799 |
|
|
This is identical to request_key(), except that the auxiliary data is
|
800 |
|
|
passed to the key_type->request_key() op if it exists.
|
801 |
|
|
|
802 |
|
|
|
803 |
|
|
(*) A key can be requested asynchronously by calling one of:
|
804 |
|
|
|
805 |
|
|
struct key *request_key_async(const struct key_type *type,
|
806 |
|
|
const char *description,
|
807 |
|
|
const char *callout_string);
|
808 |
|
|
|
809 |
|
|
or:
|
810 |
|
|
|
811 |
|
|
struct key *request_key_async_with_auxdata(const struct key_type *type,
|
812 |
|
|
const char *description,
|
813 |
|
|
const char *callout_string,
|
814 |
|
|
void *aux);
|
815 |
|
|
|
816 |
|
|
which are asynchronous equivalents of request_key() and
|
817 |
|
|
request_key_with_auxdata() respectively.
|
818 |
|
|
|
819 |
|
|
These two functions return with the key potentially still under
|
820 |
|
|
construction. To wait for contruction completion, the following should be
|
821 |
|
|
called:
|
822 |
|
|
|
823 |
|
|
int wait_for_key_construction(struct key *key, bool intr);
|
824 |
|
|
|
825 |
|
|
The function will wait for the key to finish being constructed and then
|
826 |
|
|
invokes key_validate() to return an appropriate value to indicate the state
|
827 |
|
|
of the key (0 indicates the key is usable).
|
828 |
|
|
|
829 |
|
|
If intr is true, then the wait can be interrupted by a signal, in which
|
830 |
|
|
case error ERESTARTSYS will be returned.
|
831 |
|
|
|
832 |
|
|
|
833 |
|
|
(*) When it is no longer required, the key should be released using:
|
834 |
|
|
|
835 |
|
|
void key_put(struct key *key);
|
836 |
|
|
|
837 |
|
|
Or:
|
838 |
|
|
|
839 |
|
|
void key_ref_put(key_ref_t key_ref);
|
840 |
|
|
|
841 |
|
|
These can be called from interrupt context. If CONFIG_KEYS is not set then
|
842 |
|
|
the argument will not be parsed.
|
843 |
|
|
|
844 |
|
|
|
845 |
|
|
(*) Extra references can be made to a key by calling the following function:
|
846 |
|
|
|
847 |
|
|
struct key *key_get(struct key *key);
|
848 |
|
|
|
849 |
|
|
These need to be disposed of by calling key_put() when they've been
|
850 |
|
|
finished with. The key pointer passed in will be returned. If the pointer
|
851 |
|
|
is NULL or CONFIG_KEYS is not set then the key will not be dereferenced and
|
852 |
|
|
no increment will take place.
|
853 |
|
|
|
854 |
|
|
|
855 |
|
|
(*) A key's serial number can be obtained by calling:
|
856 |
|
|
|
857 |
|
|
key_serial_t key_serial(struct key *key);
|
858 |
|
|
|
859 |
|
|
If key is NULL or if CONFIG_KEYS is not set then 0 will be returned (in the
|
860 |
|
|
latter case without parsing the argument).
|
861 |
|
|
|
862 |
|
|
|
863 |
|
|
(*) If a keyring was found in the search, this can be further searched by:
|
864 |
|
|
|
865 |
|
|
key_ref_t keyring_search(key_ref_t keyring_ref,
|
866 |
|
|
const struct key_type *type,
|
867 |
|
|
const char *description)
|
868 |
|
|
|
869 |
|
|
This searches the keyring tree specified for a matching key. Error ENOKEY
|
870 |
|
|
is returned upon failure (use IS_ERR/PTR_ERR to determine). If successful,
|
871 |
|
|
the returned key will need to be released.
|
872 |
|
|
|
873 |
|
|
The possession attribute from the keyring reference is used to control
|
874 |
|
|
access through the permissions mask and is propagated to the returned key
|
875 |
|
|
reference pointer if successful.
|
876 |
|
|
|
877 |
|
|
|
878 |
|
|
(*) To check the validity of a key, this function can be called:
|
879 |
|
|
|
880 |
|
|
int validate_key(struct key *key);
|
881 |
|
|
|
882 |
|
|
This checks that the key in question hasn't expired or and hasn't been
|
883 |
|
|
revoked. Should the key be invalid, error EKEYEXPIRED or EKEYREVOKED will
|
884 |
|
|
be returned. If the key is NULL or if CONFIG_KEYS is not set then 0 will be
|
885 |
|
|
returned (in the latter case without parsing the argument).
|
886 |
|
|
|
887 |
|
|
|
888 |
|
|
(*) To register a key type, the following function should be called:
|
889 |
|
|
|
890 |
|
|
int register_key_type(struct key_type *type);
|
891 |
|
|
|
892 |
|
|
This will return error EEXIST if a type of the same name is already
|
893 |
|
|
present.
|
894 |
|
|
|
895 |
|
|
|
896 |
|
|
(*) To unregister a key type, call:
|
897 |
|
|
|
898 |
|
|
void unregister_key_type(struct key_type *type);
|
899 |
|
|
|
900 |
|
|
|
901 |
|
|
Under some circumstances, it may be desirable to deal with a bundle of keys.
|
902 |
|
|
The facility provides access to the keyring type for managing such a bundle:
|
903 |
|
|
|
904 |
|
|
struct key_type key_type_keyring;
|
905 |
|
|
|
906 |
|
|
This can be used with a function such as request_key() to find a specific
|
907 |
|
|
keyring in a process's keyrings. A keyring thus found can then be searched
|
908 |
|
|
with keyring_search(). Note that it is not possible to use request_key() to
|
909 |
|
|
search a specific keyring, so using keyrings in this way is of limited utility.
|
910 |
|
|
|
911 |
|
|
|
912 |
|
|
===================================
|
913 |
|
|
NOTES ON ACCESSING PAYLOAD CONTENTS
|
914 |
|
|
===================================
|
915 |
|
|
|
916 |
|
|
The simplest payload is just a number in key->payload.value. In this case,
|
917 |
|
|
there's no need to indulge in RCU or locking when accessing the payload.
|
918 |
|
|
|
919 |
|
|
More complex payload contents must be allocated and a pointer to them set in
|
920 |
|
|
key->payload.data. One of the following ways must be selected to access the
|
921 |
|
|
data:
|
922 |
|
|
|
923 |
|
|
(1) Unmodifiable key type.
|
924 |
|
|
|
925 |
|
|
If the key type does not have a modify method, then the key's payload can
|
926 |
|
|
be accessed without any form of locking, provided that it's known to be
|
927 |
|
|
instantiated (uninstantiated keys cannot be "found").
|
928 |
|
|
|
929 |
|
|
(2) The key's semaphore.
|
930 |
|
|
|
931 |
|
|
The semaphore could be used to govern access to the payload and to control
|
932 |
|
|
the payload pointer. It must be write-locked for modifications and would
|
933 |
|
|
have to be read-locked for general access. The disadvantage of doing this
|
934 |
|
|
is that the accessor may be required to sleep.
|
935 |
|
|
|
936 |
|
|
(3) RCU.
|
937 |
|
|
|
938 |
|
|
RCU must be used when the semaphore isn't already held; if the semaphore
|
939 |
|
|
is held then the contents can't change under you unexpectedly as the
|
940 |
|
|
semaphore must still be used to serialise modifications to the key. The
|
941 |
|
|
key management code takes care of this for the key type.
|
942 |
|
|
|
943 |
|
|
However, this means using:
|
944 |
|
|
|
945 |
|
|
rcu_read_lock() ... rcu_dereference() ... rcu_read_unlock()
|
946 |
|
|
|
947 |
|
|
to read the pointer, and:
|
948 |
|
|
|
949 |
|
|
rcu_dereference() ... rcu_assign_pointer() ... call_rcu()
|
950 |
|
|
|
951 |
|
|
to set the pointer and dispose of the old contents after a grace period.
|
952 |
|
|
Note that only the key type should ever modify a key's payload.
|
953 |
|
|
|
954 |
|
|
Furthermore, an RCU controlled payload must hold a struct rcu_head for the
|
955 |
|
|
use of call_rcu() and, if the payload is of variable size, the length of
|
956 |
|
|
the payload. key->datalen cannot be relied upon to be consistent with the
|
957 |
|
|
payload just dereferenced if the key's semaphore is not held.
|
958 |
|
|
|
959 |
|
|
|
960 |
|
|
===================
|
961 |
|
|
DEFINING A KEY TYPE
|
962 |
|
|
===================
|
963 |
|
|
|
964 |
|
|
A kernel service may want to define its own key type. For instance, an AFS
|
965 |
|
|
filesystem might want to define a Kerberos 5 ticket key type. To do this, it
|
966 |
|
|
author fills in a key_type struct and registers it with the system.
|
967 |
|
|
|
968 |
|
|
Source files that implement key types should include the following header file:
|
969 |
|
|
|
970 |
|
|
|
971 |
|
|
|
972 |
|
|
The structure has a number of fields, some of which are mandatory:
|
973 |
|
|
|
974 |
|
|
(*) const char *name
|
975 |
|
|
|
976 |
|
|
The name of the key type. This is used to translate a key type name
|
977 |
|
|
supplied by userspace into a pointer to the structure.
|
978 |
|
|
|
979 |
|
|
|
980 |
|
|
(*) size_t def_datalen
|
981 |
|
|
|
982 |
|
|
This is optional - it supplies the default payload data length as
|
983 |
|
|
contributed to the quota. If the key type's payload is always or almost
|
984 |
|
|
always the same size, then this is a more efficient way to do things.
|
985 |
|
|
|
986 |
|
|
The data length (and quota) on a particular key can always be changed
|
987 |
|
|
during instantiation or update by calling:
|
988 |
|
|
|
989 |
|
|
int key_payload_reserve(struct key *key, size_t datalen);
|
990 |
|
|
|
991 |
|
|
With the revised data length. Error EDQUOT will be returned if this is not
|
992 |
|
|
viable.
|
993 |
|
|
|
994 |
|
|
|
995 |
|
|
(*) int (*instantiate)(struct key *key, const void *data, size_t datalen);
|
996 |
|
|
|
997 |
|
|
This method is called to attach a payload to a key during construction.
|
998 |
|
|
The payload attached need not bear any relation to the data passed to this
|
999 |
|
|
function.
|
1000 |
|
|
|
1001 |
|
|
If the amount of data attached to the key differs from the size in
|
1002 |
|
|
keytype->def_datalen, then key_payload_reserve() should be called.
|
1003 |
|
|
|
1004 |
|
|
This method does not have to lock the key in order to attach a payload.
|
1005 |
|
|
The fact that KEY_FLAG_INSTANTIATED is not set in key->flags prevents
|
1006 |
|
|
anything else from gaining access to the key.
|
1007 |
|
|
|
1008 |
|
|
It is safe to sleep in this method.
|
1009 |
|
|
|
1010 |
|
|
|
1011 |
|
|
(*) int (*update)(struct key *key, const void *data, size_t datalen);
|
1012 |
|
|
|
1013 |
|
|
If this type of key can be updated, then this method should be provided.
|
1014 |
|
|
It is called to update a key's payload from the blob of data provided.
|
1015 |
|
|
|
1016 |
|
|
key_payload_reserve() should be called if the data length might change
|
1017 |
|
|
before any changes are actually made. Note that if this succeeds, the type
|
1018 |
|
|
is committed to changing the key because it's already been altered, so all
|
1019 |
|
|
memory allocation must be done first.
|
1020 |
|
|
|
1021 |
|
|
The key will have its semaphore write-locked before this method is called,
|
1022 |
|
|
but this only deters other writers; any changes to the key's payload must
|
1023 |
|
|
be made under RCU conditions, and call_rcu() must be used to dispose of
|
1024 |
|
|
the old payload.
|
1025 |
|
|
|
1026 |
|
|
key_payload_reserve() should be called before the changes are made, but
|
1027 |
|
|
after all allocations and other potentially failing function calls are
|
1028 |
|
|
made.
|
1029 |
|
|
|
1030 |
|
|
It is safe to sleep in this method.
|
1031 |
|
|
|
1032 |
|
|
|
1033 |
|
|
(*) int (*match)(const struct key *key, const void *desc);
|
1034 |
|
|
|
1035 |
|
|
This method is called to match a key against a description. It should
|
1036 |
|
|
return non-zero if the two match, zero if they don't.
|
1037 |
|
|
|
1038 |
|
|
This method should not need to lock the key in any way. The type and
|
1039 |
|
|
description can be considered invariant, and the payload should not be
|
1040 |
|
|
accessed (the key may not yet be instantiated).
|
1041 |
|
|
|
1042 |
|
|
It is not safe to sleep in this method; the caller may hold spinlocks.
|
1043 |
|
|
|
1044 |
|
|
|
1045 |
|
|
(*) void (*revoke)(struct key *key);
|
1046 |
|
|
|
1047 |
|
|
This method is optional. It is called to discard part of the payload
|
1048 |
|
|
data upon a key being revoked. The caller will have the key semaphore
|
1049 |
|
|
write-locked.
|
1050 |
|
|
|
1051 |
|
|
It is safe to sleep in this method, though care should be taken to avoid
|
1052 |
|
|
a deadlock against the key semaphore.
|
1053 |
|
|
|
1054 |
|
|
|
1055 |
|
|
(*) void (*destroy)(struct key *key);
|
1056 |
|
|
|
1057 |
|
|
This method is optional. It is called to discard the payload data on a key
|
1058 |
|
|
when it is being destroyed.
|
1059 |
|
|
|
1060 |
|
|
This method does not need to lock the key to access the payload; it can
|
1061 |
|
|
consider the key as being inaccessible at this time. Note that the key's
|
1062 |
|
|
type may have been changed before this function is called.
|
1063 |
|
|
|
1064 |
|
|
It is not safe to sleep in this method; the caller may hold spinlocks.
|
1065 |
|
|
|
1066 |
|
|
|
1067 |
|
|
(*) void (*describe)(const struct key *key, struct seq_file *p);
|
1068 |
|
|
|
1069 |
|
|
This method is optional. It is called during /proc/keys reading to
|
1070 |
|
|
summarise a key's description and payload in text form.
|
1071 |
|
|
|
1072 |
|
|
This method will be called with the RCU read lock held. rcu_dereference()
|
1073 |
|
|
should be used to read the payload pointer if the payload is to be
|
1074 |
|
|
accessed. key->datalen cannot be trusted to stay consistent with the
|
1075 |
|
|
contents of the payload.
|
1076 |
|
|
|
1077 |
|
|
The description will not change, though the key's state may.
|
1078 |
|
|
|
1079 |
|
|
It is not safe to sleep in this method; the RCU read lock is held by the
|
1080 |
|
|
caller.
|
1081 |
|
|
|
1082 |
|
|
|
1083 |
|
|
(*) long (*read)(const struct key *key, char __user *buffer, size_t buflen);
|
1084 |
|
|
|
1085 |
|
|
This method is optional. It is called by KEYCTL_READ to translate the
|
1086 |
|
|
key's payload into something a blob of data for userspace to deal with.
|
1087 |
|
|
Ideally, the blob should be in the same format as that passed in to the
|
1088 |
|
|
instantiate and update methods.
|
1089 |
|
|
|
1090 |
|
|
If successful, the blob size that could be produced should be returned
|
1091 |
|
|
rather than the size copied.
|
1092 |
|
|
|
1093 |
|
|
This method will be called with the key's semaphore read-locked. This will
|
1094 |
|
|
prevent the key's payload changing. It is not necessary to use RCU locking
|
1095 |
|
|
when accessing the key's payload. It is safe to sleep in this method, such
|
1096 |
|
|
as might happen when the userspace buffer is accessed.
|
1097 |
|
|
|
1098 |
|
|
|
1099 |
|
|
(*) int (*request_key)(struct key_construction *cons, const char *op,
|
1100 |
|
|
void *aux);
|
1101 |
|
|
|
1102 |
|
|
This method is optional. If provided, request_key() and friends will
|
1103 |
|
|
invoke this function rather than upcalling to /sbin/request-key to operate
|
1104 |
|
|
upon a key of this type.
|
1105 |
|
|
|
1106 |
|
|
The aux parameter is as passed to request_key_async_with_auxdata() and
|
1107 |
|
|
similar or is NULL otherwise. Also passed are the construction record for
|
1108 |
|
|
the key to be operated upon and the operation type (currently only
|
1109 |
|
|
"create").
|
1110 |
|
|
|
1111 |
|
|
This method is permitted to return before the upcall is complete, but the
|
1112 |
|
|
following function must be called under all circumstances to complete the
|
1113 |
|
|
instantiation process, whether or not it succeeds, whether or not there's
|
1114 |
|
|
an error:
|
1115 |
|
|
|
1116 |
|
|
void complete_request_key(struct key_construction *cons, int error);
|
1117 |
|
|
|
1118 |
|
|
The error parameter should be 0 on success, -ve on error. The
|
1119 |
|
|
construction record is destroyed by this action and the authorisation key
|
1120 |
|
|
will be revoked. If an error is indicated, the key under construction
|
1121 |
|
|
will be negatively instantiated if it wasn't already instantiated.
|
1122 |
|
|
|
1123 |
|
|
If this method returns an error, that error will be returned to the
|
1124 |
|
|
caller of request_key*(). complete_request_key() must be called prior to
|
1125 |
|
|
returning.
|
1126 |
|
|
|
1127 |
|
|
The key under construction and the authorisation key can be found in the
|
1128 |
|
|
key_construction struct pointed to by cons:
|
1129 |
|
|
|
1130 |
|
|
(*) struct key *key;
|
1131 |
|
|
|
1132 |
|
|
The key under construction.
|
1133 |
|
|
|
1134 |
|
|
(*) struct key *authkey;
|
1135 |
|
|
|
1136 |
|
|
The authorisation key.
|
1137 |
|
|
|
1138 |
|
|
|
1139 |
|
|
============================
|
1140 |
|
|
REQUEST-KEY CALLBACK SERVICE
|
1141 |
|
|
============================
|
1142 |
|
|
|
1143 |
|
|
To create a new key, the kernel will attempt to execute the following command
|
1144 |
|
|
line:
|
1145 |
|
|
|
1146 |
|
|
/sbin/request-key create \
|
1147 |
|
|
|
1148 |
|
|
|
1149 |
|
|
is the key being constructed, and the three keyrings are the process
|
1150 |
|
|
keyrings from the process that caused the search to be issued. These are
|
1151 |
|
|
included for two reasons:
|
1152 |
|
|
|
1153 |
|
|
(1) There may be an authentication token in one of the keyrings that is
|
1154 |
|
|
required to obtain the key, eg: a Kerberos Ticket-Granting Ticket.
|
1155 |
|
|
|
1156 |
|
|
(2) The new key should probably be cached in one of these rings.
|
1157 |
|
|
|
1158 |
|
|
This program should set it UID and GID to those specified before attempting to
|
1159 |
|
|
access any more keys. It may then look around for a user specific process to
|
1160 |
|
|
hand the request off to (perhaps a path held in placed in another key by, for
|
1161 |
|
|
example, the KDE desktop manager).
|
1162 |
|
|
|
1163 |
|
|
The program (or whatever it calls) should finish construction of the key by
|
1164 |
|
|
calling KEYCTL_INSTANTIATE, which also permits it to cache the key in one of
|
1165 |
|
|
the keyrings (probably the session ring) before returning. Alternatively, the
|
1166 |
|
|
key can be marked as negative with KEYCTL_NEGATE; this also permits the key to
|
1167 |
|
|
be cached in one of the keyrings.
|
1168 |
|
|
|
1169 |
|
|
If it returns with the key remaining in the unconstructed state, the key will
|
1170 |
|
|
be marked as being negative, it will be added to the session keyring, and an
|
1171 |
|
|
error will be returned to the key requestor.
|
1172 |
|
|
|
1173 |
|
|
Supplementary information may be provided from whoever or whatever invoked this
|
1174 |
|
|
service. This will be passed as the parameter. If no such
|
1175 |
|
|
information was made available, then "-" will be passed as this parameter
|
1176 |
|
|
instead.
|
1177 |
|
|
|
1178 |
|
|
|
1179 |
|
|
Similarly, the kernel may attempt to update an expired or a soon to expire key
|
1180 |
|
|
by executing:
|
1181 |
|
|
|
1182 |
|
|
/sbin/request-key update \
|
1183 |
|
|
|
1184 |
|
|
|
1185 |
|
|
In this case, the program isn't required to actually attach the key to a ring;
|
1186 |
|
|
the rings are provided for reference.
|