Lines Matching +full:key +full:-
1 .. SPDX-License-Identifier: GPL-2.0
4 Asymmetric / Public-key Cryptography Key Type
9 - Overview.
10 - Key identification.
11 - Accessing asymmetric keys.
12 - Signature verification.
13 - Asymmetric key subtypes.
14 - Instantiation data parsers.
15 - Keyring link restrictions.
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.
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.
30 A completely in-kernel key retention and operation subtype can be defined, but
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
39 subtype of the key and define the operations that can be done on that key.
42 key, or it may interpret it as a reference to a key held somewhere else in the
46 Key Identification
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.
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.
56 The asymmetric key type's match function can then perform a wider range of
61 function will examine a key's fingerprint to see if the hex digits given
66 will match a key with fingerprint::
77 Looking in /proc/keys, the last 8 hex digits of the key fingerprint are
80 1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 []
92 Three enums are defined there for representing public-key cryptography
101 and key identifier representations::
105 Note that the key type representation types are required because key
107 instance, PGP generates key identifiers by hashing the key data plus some
108 PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers.
110 The operations defined upon a key are:
114 Other operations are possible (such as encryption) with the same key data
116 (eg. decryption and signature generation) require extra key data.
120 ----------------------
123 an asymmetric key to provide or to provide access to the public key::
125 int verify_signature(const struct key *key,
128 The caller must have already obtained the key from some source and can then use
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.
148 hash must be pointed to by sig->digest and the size of the hash be placed in
149 sig->digest_size.
151 The function will return 0 upon success or -EKEYREJECTED if the signature
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.
161 Asymmetric Key Subtypes
165 performed on that key and that determines what data is attached as the key
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
174 #include <keys/asymmetric-subtype.h>
182 void (*describe)(const struct key *key, struct seq_file *m);
188 int (*verify_signature)(const struct key *key,
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
208 Mandatory. This should free the memory associated with the key. The
209 asymmetric key will look after freeing the fingerprint and releasing the
214 Mandatory. This is a function for querying the capabilities of a key.
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
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).
238 Also, the blob may represent a pointer to some hardware containing the key
239 rather than the key itself.
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].
250 During key instantiation each parser in the list is tried until one doesn't
251 return -EBADMSG.
255 #include <keys/asymmetric-parser.h>
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
294 recognise the blob format and will not return -EBADMSG to indicate it is
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
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
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
309 ->payload[asym_subtype] will be put.
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
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.
333 signature of the key being linked. Keys without a valid signature are not
340 - Option string used with KEYCTL_RESTRICT_KEYRING:
341 - "builtin_trusted"
343 The kernel builtin trusted keyring will be searched for the signing key.
350 - Option string used with KEYCTL_RESTRICT_KEYRING:
351 - "builtin_and_secondary_trusted"
354 signing key. If the secondary trusted keyring is not configured, this
359 3) Restrict using a separate key or keyring
361 - Option string used with KEYCTL_RESTRICT_KEYRING:
362 - "key_or_keyring:<key or keyring serial number>[:chain]"
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
379 root_id=`keyctl add keyring root-certs "" @s`
391 keyctl padd asymmetric "" $chain_id < end-entity.cert
393 If the final end-entity certificate is successfully added to the "chain"
412 keyctl padd asymmetric "" $chain2_id < end-entity.cert
414 If the final end-entity certificate is successfully added to the "chain2"
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