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