About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / crypto / asymmetric-keys.txt




Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:54 EST.

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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.