GNU Linux-libre 4.19.264-gnu1
[releases.git] / Documentation / crypto / asymmetric-keys.txt
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.
13   - Keyring link restrictions.
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
80         1a39e171 I-----     1 perm 3f010000     0     0 asymmetric modsign.0: DSA 5acc2142 []
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
190 Asymmetric keys point to this with their payload[asym_subtype] member.
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
269      Documentation/security/keys/core.rst].
270
271         struct key_preparsed_payload {
272                 char            *description;
273                 void            *payload[4];
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
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.
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.
315
316
317 =========================
318 KEYRING LINK RESTRICTIONS
319 =========================
320
321 Keyrings created from userspace using add_key can be configured to check the
322 signature of the key being linked.  Keys without a valid signature are not
323 allowed to link.
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
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.
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
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.
347
348  (3) Restrict using a separate key or keyring
349
350      - Option string used with KEYCTL_RESTRICT_KEYRING:
351        - "key_or_keyring:<key or keyring serial number>[:chain]"
352
353      Whenever a key link is requested, the link will only succeed if the key
354      being linked is signed by one of the designated keys.  This key may be
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
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
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
407
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.