Documentation/crypto/asymmetric-keys.rst

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.
22 public-key cryptography, without imposing any particular restrictions on the
30 A completely in-kernel key retention and operation subtype can be defined, but
50 the opportunity to pre-parse a key and to determine the description the key
80 	1a39e171 I-----     1 perm 3f010000     0     0 asymmetric modsign.0: DSA 5acc2142 []
92 Three enums are defined there for representing public-key cryptography
108 PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers.
120 ----------------------
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
174 	#include <keys/asymmetric-subtype.h>
235 have various checks that can be performed on it (eg. self-signatures, validity
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].
251 return -EBADMSG.
255 	#include <keys/asymmetric-parser.h>
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
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
317      public-key algorithm such as RSA and DSA this will likely be a printable
340      - Option string used with KEYCTL_RESTRICT_KEYRING:
341        - "builtin_trusted"
350      - Option string used with KEYCTL_RESTRICT_KEYRING:
351        - "builtin_and_secondary_trusted"
361      - Option string used with KEYCTL_RESTRICT_KEYRING:
362        - "key_or_keyring:<key or keyring serial number>[:chain]"
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"
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