1.. SPDX-License-Identifier: GPL-2.0
2
3=============================================
4Asymmetric / 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
18Overview
19========
20
21The "asymmetric" key type is designed to be a container for the keys used in
22public-key cryptography, without imposing any particular restrictions on the
23form or mechanism of the cryptography or form of the key.
24
25The asymmetric key is given a subtype that defines what sort of data is
26associated with the key and provides operations to describe and destroy it.
27However, no requirement is made that the key data actually be stored in the
28key.
29
30A completely in-kernel key retention and operation subtype can be defined, but
31it would also be possible to provide access to cryptographic hardware (such as
32a TPM) that might be used to both retain the relevant key and perform
33operations using that key.  In such a case, the asymmetric key would then
34merely be an interface to the TPM driver.
35
36Also provided is the concept of a data parser.  Data parsers are responsible
37for extracting information from the blobs of data passed to the instantiation
38function.  The first data parser that recognises the blob gets to set the
39subtype of the key and define the operations that can be done on that key.
40
41A data parser may interpret the data blob as containing the bits representing a
42key, or it may interpret it as a reference to a key held somewhere else in the
43system (for example, a TPM).
44
45
46Key Identification
47==================
48
49If a key is added with an empty name, the instantiation data parsers are given
50the opportunity to pre-parse a key and to determine the description the key
51should be given from the content of the key.
52
53This can then be used to refer to the key, either by complete match or by
54partial match.  The key type may also use other criteria to refer to a key.
55
56The asymmetric key type's match function can then perform a wider range of
57comparisons than just the straightforward comparison of the description with
58the 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
77Looking in /proc/keys, the last 8 hex digits of the key fingerprint are
78displayed, along with the subtype::
79
80	1a39e171 I-----     1 perm 3f010000     0     0 asymmetric modsign.0: DSA 5acc2142 []
81
82
83Accessing Asymmetric Keys
84=========================
85
86For general access to asymmetric keys from within the kernel, the following
87inclusion is required::
88
89	#include <crypto/public_key.h>
90
91This gives access to functions for dealing with asymmetric / public keys.
92Three enums are defined there for representing public-key cryptography
93algorithms::
94
95	enum pkey_algo
96
97digest algorithms used by those::
98
99	enum pkey_hash_algo
100
101and key identifier representations::
102
103	enum pkey_id_type
104
105Note that the key type representation types are required because key
106identifiers from different standards aren't necessarily compatible.  For
107instance, PGP generates key identifiers by hashing the key data plus some
108PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers.
109
110The operations defined upon a key are:
111
112  1) Signature verification.
113
114Other operations are possible (such as encryption) with the same key data
115required for verification, but not currently supported, and others
116(eg. decryption and signature generation) require extra key data.
117
118
119Signature Verification
120----------------------
121
122An operation is provided to perform cryptographic signature verification, using
123an asymmetric key to provide or to provide access to the public key::
124
125	int verify_signature(const struct key *key,
126			     const struct public_key_signature *sig);
127
128The caller must have already obtained the key from some source and can then use
129it to check the signature.  The caller must have parsed the signature and
130transferred the relevant bits to the structure pointed to by sig::
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
143The algorithm used must be noted in sig->pkey_hash_algo, and all the MPIs that
144make up the actual signature must be stored in sig->mpi[] and the count of MPIs
145placed in sig->nr_mpi.
146
147In addition, the data must have been digested by the caller and the resulting
148hash must be pointed to by sig->digest and the size of the hash be placed in
149sig->digest_size.
150
151The function will return 0 upon success or -EKEYREJECTED if the signature
152doesn't match.
153
154The function may also return -ENOTSUPP if an unsupported public-key algorithm
155or public-key/hash algorithm combination is specified or the key doesn't
156support the operation; -EBADMSG or -ERANGE if some of the parameters have weird
157data; or -ENOMEM if an allocation can't be performed.  -EINVAL can be returned
158if the key argument is the wrong type or is incompletely set up.
159
160
161Asymmetric Key Subtypes
162=======================
163
164Asymmetric keys have a subtype that defines the set of operations that can be
165performed on that key and that determines what data is attached as the key
166payload.  The payload format is entirely at the whim of the subtype.
167
168The subtype is selected by the key data parser and the parser must initialise
169the data required for it.  The asymmetric key retains a reference on the
170subtype module.
171
172The subtype definition structure can be found in::
173
174	#include <keys/asymmetric-subtype.h>
175
176and looks like the following::
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);
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);
188		int (*verify_signature)(const struct key *key,
189					const struct public_key_signature *sig);
190	};
191
192Asymmetric keys point to this with their payload[asym_subtype] member.
193
194The owner and name fields should be set to the owning module and the name of
195the subtype.  Currently, the name is only used for print statements.
196
197There are a number of operations defined by the subtype:
198
199  1) describe().
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
206  2) destroy().
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
212  3) query().
213
214     Mandatory.  This is a function for querying the capabilities of a key.
215
216  4) eds_op().
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
223  5) verify_signature().
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.
228
229Instantiation Data Parsers
230==========================
231
232The asymmetric key type doesn't generally want to store or to deal with a raw
233blob of data that holds the key data.  It would have to parse it and error
234check it each time it wanted to use it.  Further, the contents of the blob may
235have various checks that can be performed on it (eg. self-signatures, validity
236dates) and may contain useful data about the key (identifiers, capabilities).
237
238Also, the blob may represent a pointer to some hardware containing the key
239rather than the key itself.
240
241Examples 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.
247 - PKCS#8 private key [RFC 5208].
248 - PKCS#5 encrypted private key [RFC 2898].
249
250During key instantiation each parser in the list is tried until one doesn't
251return -EBADMSG.
252
253The parser definition structure can be found in::
254
255	#include <keys/asymmetric-parser.h>
256
257and looks like the following::
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
266The owner and name fields should be set to the owning module and the name of
267the parser.
268
269There is currently only a single operation defined by the parser, and it is
270mandatory:
271
272  1) parse().
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
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 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
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.
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
320Functions are provided to register and unregister parsers::
321
322	int register_asymmetric_key_parser(struct asymmetric_key_parser *parser);
323	void unregister_asymmetric_key_parser(struct asymmetric_key_parser *subtype);
324
325Parsers may not have the same name.  The names are otherwise only used for
326displaying in debugging messages.
327
328
329Keyring Link Restrictions
330=========================
331
332Keyrings created from userspace using add_key can be configured to check the
333signature of the key being linked.  Keys without a valid signature are not
334allowed to link.
335
336Several restriction methods are available:
337
338  1) Restrict using the kernel builtin trusted keyring
339
340     - Option string used with KEYCTL_RESTRICT_KEYRING:
341       - "builtin_trusted"
342
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.
347
348  2) Restrict using the kernel builtin and secondary trusted keyrings
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
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.
358
359  3) Restrict using a separate key or keyring
360
361     - Option string used with KEYCTL_RESTRICT_KEYRING:
362       - "key_or_keyring:<key or keyring serial number>[:chain]"
363
364     Whenever a key link is requested, the link will only succeed if the key
365     being linked is signed by one of the designated keys.  This key may be
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
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
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
376     certificate chain to be validated::
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
398     restricting the keyring after linking the root certificate::
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
418
419In all of these cases, if the signing key is found the signature of the key to
420be linked will be verified using the signing key.  The requested key is added
421to the keyring only if the signature is successfully verified.  -ENOKEY is
422returned if the parent certificate could not be found, or -EKEYREJECTED is
423returned if the signature check fails or the key is blacklisted.  Other errors
424may be returned if the signature check could not be performed.
425