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