1 .. SPDX-License-Identifier: GPL-2.0
2
3 =============================================
4 Asymmetric / Public-key Cryptography Key Type
5 =============================================
6
7 .. Contents:
8
9 - Overview.
10 - Key identification.
11 - Accessing asymmetric keys.
12 - Signature verification.
13 - Asymmetric key subtypes.
14 - Instantiation data parsers.
15 - Keyring link restrictions.
16
17
18 Overview
19 ========
20
21 The "asymmetric" key type is designed to be a
22 public-key cryptography, without imposing any
23 form or mechanism of the cryptography or form
24
25 The asymmetric key is given a subtype that def
26 associated with the key and provides operation
27 However, no requirement is made that the key d
28 key.
29
30 A completely in-kernel key retention and opera
31 it would also be possible to provide access to
32 a TPM) that might be used to both retain the r
33 operations using that key. In such a case, th
34 merely be an interface to the TPM driver.
35
36 Also provided is the concept of a data parser.
37 for extracting information from the blobs of d
38 function. The first data parser that recognis
39 subtype of the key and define the operations t
40
41 A data parser may interpret the data blob as c
42 key, or it may interpret it as a reference to
43 system (for example, a TPM).
44
45
46 Key Identification
47 ==================
48
49 If a key is added with an empty name, the inst
50 the opportunity to pre-parse a key and to dete
51 should be given from the content of the key.
52
53 This can then be used to refer to the key, eit
54 partial match. The key type may also use othe
55
56 The asymmetric key type's match function can t
57 comparisons than just the straightforward comp
58 the criterion string:
59
60 1) If the criterion string is of the form "i
61 function will examine a key's fingerprint
62 after the "id:" match the tail. For inst
63
64 keyctl search @s asymmetric id:5acc214
65
66 will match a key with fingerprint::
67
68 1A00 2040 7601 7889 DE11 882C 3823 04
69
70 2) If the criterion string is of the form "<
71 match will match the ID as in (1), but wi
72 only keys of the specified subtype (e.g.
73 instance::
74
75 keyctl search @s asymmetric tpm:5acc21
76
77 Looking in /proc/keys, the last 8 hex digits o
78 displayed, along with the subtype::
79
80 1a39e171 I----- 1 perm 3f010000
81
82
83 Accessing Asymmetric Keys
84 =========================
85
86 For general access to asymmetric keys from wit
87 inclusion is required::
88
89 #include <crypto/public_key.h>
90
91 This gives access to functions for dealing wit
92 Three enums are defined there for representing
93 algorithms::
94
95 enum pkey_algo
96
97 digest algorithms used by those::
98
99 enum pkey_hash_algo
100
101 and key identifier representations::
102
103 enum pkey_id_type
104
105 Note that the key type representation types ar
106 identifiers from different standards aren't ne
107 instance, PGP generates key identifiers by has
108 PGP-specific metadata, whereas X.509 has arbit
109
110 The operations defined upon a key are:
111
112 1) Signature verification.
113
114 Other operations are possible (such as encrypt
115 required for verification, but not currently s
116 (eg. decryption and signature generation) requ
117
118
119 Signature Verification
120 ----------------------
121
122 An operation is provided to perform cryptograp
123 an asymmetric key to provide or to provide acc
124
125 int verify_signature(const struct key
126 const struct publ
127
128 The caller must have already obtained the key
129 it to check the signature. The caller must ha
130 transferred the relevant bits to the structure
131
132 struct public_key_signature {
133 u8 *digest;
134 u8 digest_size;
135 enum pkey_hash_algo pkey_hash_
136 u8 nr_mpi;
137 union {
138 MPI mpi[2];
139 ...
140 };
141 };
142
143 The algorithm used must be noted in sig->pkey_
144 make up the actual signature must be stored in
145 placed in sig->nr_mpi.
146
147 In addition, the data must have been digested
148 hash must be pointed to by sig->digest and the
149 sig->digest_size.
150
151 The function will return 0 upon success or -EK
152 doesn't match.
153
154 The function may also return -ENOTSUPP if an u
155 or public-key/hash algorithm combination is sp
156 support the operation; -EBADMSG or -ERANGE if
157 data; or -ENOMEM if an allocation can't be per
158 if the key argument is the wrong type or is in
159
160
161 Asymmetric Key Subtypes
162 =======================
163
164 Asymmetric keys have a subtype that defines th
165 performed on that key and that determines what
166 payload. The payload format is entirely at th
167
168 The subtype is selected by the key data parser
169 the data required for it. The asymmetric key
170 subtype module.
171
172 The subtype definition structure can be found
173
174 #include <keys/asymmetric-subtype.h>
175
176 and looks like the following::
177
178 struct asymmetric_key_subtype {
179 struct module *owner
180 const char *name;
181
182 void (*describe)(const struct
183 void (*destroy)(void *payload)
184 int (*query)(const struct kern
185 struct kernel_pke
186 int (*eds_op)(struct kernel_pk
187 const void *in,
188 int (*verify_signature)(const
189 const
190 };
191
192 Asymmetric keys point to this with their paylo
193
194 The owner and name fields should be set to the
195 the subtype. Currently, the name is only used
196
197 There are a number of operations defined by th
198
199 1) describe().
200
201 Mandatory. This allows the subtype to di
202 against the key. For instance the name o
203 could be displayed. The key type will di
204 identity string after this.
205
206 2) destroy().
207
208 Mandatory. This should free the memory a
209 asymmetric key will look after freeing th
210 reference on the subtype module.
211
212 3) query().
213
214 Mandatory. This is a function for queryi
215
216 4) eds_op().
217
218 Optional. This is the entry point for th
219 signature creation operations (which are
220 in the parameter struct). The subtype ma
221 implement an operation, including offload
222
223 5) verify_signature().
224
225 Optional. This is the entry point for si
226 subtype may do anything it likes to imple
227 offloading to hardware.
228
229 Instantiation Data Parsers
230 ==========================
231
232 The asymmetric key type doesn't generally want
233 blob of data that holds the key data. It woul
234 check it each time it wanted to use it. Furth
235 have various checks that can be performed on i
236 dates) and may contain useful data about the k
237
238 Also, the blob may represent a pointer to some
239 rather than the key itself.
240
241 Examples of blob formats for which parsers cou
242
243 - OpenPGP packet stream [RFC 4880].
244 - X.509 ASN.1 stream.
245 - Pointer to TPM key.
246 - Pointer to UEFI key.
247 - PKCS#8 private key [RFC 5208].
248 - PKCS#5 encrypted private key [RFC 2898].
249
250 During key instantiation each parser in the li
251 return -EBADMSG.
252
253 The parser definition structure can be found i
254
255 #include <keys/asymmetric-parser.h>
256
257 and looks like the following::
258
259 struct asymmetric_key_parser {
260 struct module *owner;
261 const char *name;
262
263 int (*parse)(struct key_prepar
264 };
265
266 The owner and name fields should be set to the
267 the parser.
268
269 There is currently only a single operation def
270 mandatory:
271
272 1) parse().
273
274 This is called to preparse the key from t
275 In particular, it is called during the ke
276 allocated, and as such, is permitted to p
277 the case that the caller declines to do s
278
279 The caller passes a pointer to the follow
280 cleared, except for data, datalen and quo
281 Documentation/security/keys/core.rst]::
282
283 struct key_preparsed_payload {
284 char *description;
285 void *payload[4];
286 const void *data;
287 size_t datalen;
288 size_t quotalen;
289 };
290
291 The instantiation data is in a blob point
292 size. The parse() function is not permit
293 all, and shouldn't change any of the othe
294 recognise the blob format and will not re
295 not theirs.
296
297 If the parser is happy with the blob, it
298 the key and attach it to ->description, -
299 set to point to the subtype to be used, -
300 set to point to the initialised data for
301 ->payload[asym_key_ids] should point to o
302 quotalen should be updated to indicate ho
303 account for.
304
305 When clearing up, the data attached to ->
306 ->description will be kfree()'d and the d
307 ->payload[asm_crypto] will be passed to t
308 to be disposed of. A module reference fo
309 ->payload[asym_subtype] will be put.
310
311
312 If the data format is not recognised, -EB
313 is recognised, but the key cannot for som
314 negative error code should be returned.
315
316 The key's fingerprint string may be parti
317 public-key algorithm such as RSA and DSA
318 hex version of the key's fingerprint.
319
320 Functions are provided to register and unregis
321
322 int register_asymmetric_key_parser(str
323 void unregister_asymmetric_key_parser(
324
325 Parsers may not have the same name. The names
326 displaying in debugging messages.
327
328
329 Keyring Link Restrictions
330 =========================
331
332 Keyrings created from userspace using add_key
333 signature of the key being linked. Keys witho
334 allowed to link.
335
336 Several restriction methods are available:
337
338 1) Restrict using the kernel builtin trusted
339
340 - Option string used with KEYCTL_RESTRICT
341 - "builtin_trusted"
342
343 The kernel builtin trusted keyring will b
344 If the builtin trusted keyring is not con
345 rejected. The ca_keys kernel parameter a
346 for signature verification.
347
348 2) Restrict using the kernel builtin and sec
349
350 - Option string used with KEYCTL_RESTRICT
351 - "builtin_and_secondary_trusted"
352
353 The kernel builtin and secondary trusted
354 signing key. If the secondary trusted ke
355 restriction will behave like the "builtin
356 kernel parameter also affects which keys
357 verification.
358
359 3) Restrict using a separate key or keyring
360
361 - Option string used with KEYCTL_RESTRICT
362 - "key_or_keyring:<key or keyring seria
363
364 Whenever a key link is requested, the lin
365 being linked is signed by one of the desi
366 specified directly by providing a serial
367 a group of keys may be searched for the s
368 serial number for a keyring.
369
370 When the "chain" option is provided at th
371 within the destination keyring will also
372 This allows for verification of certifica
373 certificate in order (starting closest to
374 instance, one keyring can be populated wi
375 certificates, with a separate, restricted
376 certificate chain to be validated::
377
378 # Create and populate a keyring for ro
379 root_id=`keyctl add keyring root-certs
380 keyctl padd asymmetric "" $root_id < r
381 keyctl padd asymmetric "" $root_id < r
382
383 # Create and restrict a keyring for th
384 chain_id=`keyctl add keyring chain ""
385 keyctl restrict_keyring $chain_id asym
386
387 # Attempt to add each certificate in t
388 # certificate closest to the root.
389 keyctl padd asymmetric "" $chain_id <
390 keyctl padd asymmetric "" $chain_id <
391 keyctl padd asymmetric "" $chain_id <
392
393 If the final end-entity certificate is su
394 keyring, we can be certain that it has a
395 one of the root certificates.
396
397 A single keyring can be used to verify a
398 restricting the keyring after linking the
399
400 # Create a keyring for the certificate
401 chain2_id=`keyctl add keyring chain2 "
402 keyctl padd asymmetric "" $chain2_id <
403
404 # Restrict the keyring that already ha
405 # will remain linked by the keyring.
406 keyctl restrict_keyring $chain2_id asy
407
408 # Attempt to add each certificate in t
409 # certificate closest to the root.
410 keyctl padd asymmetric "" $chain2_id <
411 keyctl padd asymmetric "" $chain2_id <
412 keyctl padd asymmetric "" $chain2_id <
413
414 If the final end-entity certificate is su
415 keyring, we can be certain that there is
416 to the root certificate that was added be
417
418
419 In all of these cases, if the signing key is f
420 be linked will be verified using the signing k
421 to the keyring only if the signature is succes
422 returned if the parent certificate could not b
423 returned if the signature check fails or the k
424 may be returned if the signature check could n
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.