^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Asymmetric / Public-key Cryptography Key Type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) =============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) .. Contents:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) - Overview.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) - Key identification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) - Accessing asymmetric keys.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) - Signature verification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) - Asymmetric key subtypes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) - Instantiation data parsers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) - Keyring link restrictions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) The "asymmetric" key type is designed to be a container for the keys used in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) public-key cryptography, without imposing any particular restrictions on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) form or mechanism of the cryptography or form of the key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) The asymmetric key is given a subtype that defines what sort of data is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) associated with the key and provides operations to describe and destroy it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) However, no requirement is made that the key data actually be stored in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) A completely in-kernel key retention and operation subtype can be defined, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) it would also be possible to provide access to cryptographic hardware (such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) a TPM) that might be used to both retain the relevant key and perform
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) operations using that key. In such a case, the asymmetric key would then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) merely be an interface to the TPM driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Also provided is the concept of a data parser. Data parsers are responsible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) for extracting information from the blobs of data passed to the instantiation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) function. The first data parser that recognises the blob gets to set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) subtype of the key and define the operations that can be done on that key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) A data parser may interpret the data blob as containing the bits representing a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) key, or it may interpret it as a reference to a key held somewhere else in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) system (for example, a TPM).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Key Identification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) If a key is added with an empty name, the instantiation data parsers are given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) the opportunity to pre-parse a key and to determine the description the key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) should be given from the content of the key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) This can then be used to refer to the key, either by complete match or by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) partial match. The key type may also use other criteria to refer to a key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) The asymmetric key type's match function can then perform a wider range of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) comparisons than just the straightforward comparison of the description with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) the criterion string:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 1) If the criterion string is of the form "id:<hexdigits>" then the match
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) function will examine a key's fingerprint to see if the hex digits given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) after the "id:" match the tail. For instance::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) keyctl search @s asymmetric id:5acc2142
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) will match a key with fingerprint::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) 1A00 2040 7601 7889 DE11 882C 3823 04AD 5ACC 2142
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) 2) If the criterion string is of the form "<subtype>:<hexdigits>" then the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) match will match the ID as in (1), but with the added restriction that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) only keys of the specified subtype (e.g. tpm) will be matched. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) instance::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) keyctl search @s asymmetric tpm:5acc2142
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) Looking in /proc/keys, the last 8 hex digits of the key fingerprint are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) displayed, along with the subtype::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) 1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 []
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) Accessing Asymmetric Keys
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) For general access to asymmetric keys from within the kernel, the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) inclusion is required::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) #include <crypto/public_key.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) This gives access to functions for dealing with asymmetric / public keys.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) Three enums are defined there for representing public-key cryptography
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) algorithms::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) enum pkey_algo
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) digest algorithms used by those::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) enum pkey_hash_algo
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) and key identifier representations::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) enum pkey_id_type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) Note that the key type representation types are required because key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) identifiers from different standards aren't necessarily compatible. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) instance, PGP generates key identifiers by hashing the key data plus some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) The operations defined upon a key are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) 1) Signature verification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) Other operations are possible (such as encryption) with the same key data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) required for verification, but not currently supported, and others
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) (eg. decryption and signature generation) require extra key data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) Signature Verification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) An operation is provided to perform cryptographic signature verification, using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) an asymmetric key to provide or to provide access to the public key::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) int verify_signature(const struct key *key,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) const struct public_key_signature *sig);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) The caller must have already obtained the key from some source and can then use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) it to check the signature. The caller must have parsed the signature and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) transferred the relevant bits to the structure pointed to by sig::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) struct public_key_signature {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) u8 *digest;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) u8 digest_size;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) enum pkey_hash_algo pkey_hash_algo : 8;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) u8 nr_mpi;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) MPI mpi[2];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) The algorithm used must be noted in sig->pkey_hash_algo, and all the MPIs that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) make up the actual signature must be stored in sig->mpi[] and the count of MPIs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) placed in sig->nr_mpi.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) In addition, the data must have been digested by the caller and the resulting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) hash must be pointed to by sig->digest and the size of the hash be placed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) sig->digest_size.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) The function will return 0 upon success or -EKEYREJECTED if the signature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) doesn't match.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) The function may also return -ENOTSUPP if an unsupported public-key algorithm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) or public-key/hash algorithm combination is specified or the key doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) support the operation; -EBADMSG or -ERANGE if some of the parameters have weird
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) data; or -ENOMEM if an allocation can't be performed. -EINVAL can be returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) if the key argument is the wrong type or is incompletely set up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) Asymmetric Key Subtypes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) Asymmetric keys have a subtype that defines the set of operations that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) performed on that key and that determines what data is attached as the key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) payload. The payload format is entirely at the whim of the subtype.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) The subtype is selected by the key data parser and the parser must initialise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) the data required for it. The asymmetric key retains a reference on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) subtype module.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) The subtype definition structure can be found in::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) #include <keys/asymmetric-subtype.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) and looks like the following::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) struct asymmetric_key_subtype {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) struct module *owner;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) const char *name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) void (*describe)(const struct key *key, struct seq_file *m);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) void (*destroy)(void *payload);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) int (*query)(const struct kernel_pkey_params *params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) struct kernel_pkey_query *info);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) int (*eds_op)(struct kernel_pkey_params *params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) const void *in, void *out);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) int (*verify_signature)(const struct key *key,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) const struct public_key_signature *sig);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) Asymmetric keys point to this with their payload[asym_subtype] member.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) The owner and name fields should be set to the owning module and the name of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) the subtype. Currently, the name is only used for print statements.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) There are a number of operations defined by the subtype:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) 1) describe().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) Mandatory. This allows the subtype to display something in /proc/keys
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) against the key. For instance the name of the public key algorithm type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) could be displayed. The key type will display the tail of the key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) identity string after this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) 2) destroy().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) Mandatory. This should free the memory associated with the key. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) asymmetric key will look after freeing the fingerprint and releasing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) reference on the subtype module.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) 3) query().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) Mandatory. This is a function for querying the capabilities of a key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) 4) eds_op().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) Optional. This is the entry point for the encryption, decryption and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) signature creation operations (which are distinguished by the operation ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) in the parameter struct). The subtype may do anything it likes to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) implement an operation, including offloading to hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) 5) verify_signature().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) Optional. This is the entry point for signature verification. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) subtype may do anything it likes to implement an operation, including
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) offloading to hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) Instantiation Data Parsers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) The asymmetric key type doesn't generally want to store or to deal with a raw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) blob of data that holds the key data. It would have to parse it and error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) check it each time it wanted to use it. Further, the contents of the blob may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) have various checks that can be performed on it (eg. self-signatures, validity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) dates) and may contain useful data about the key (identifiers, capabilities).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) Also, the blob may represent a pointer to some hardware containing the key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) rather than the key itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) Examples of blob formats for which parsers could be implemented include:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) - OpenPGP packet stream [RFC 4880].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) - X.509 ASN.1 stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) - Pointer to TPM key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) - Pointer to UEFI key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) - PKCS#8 private key [RFC 5208].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) - PKCS#5 encrypted private key [RFC 2898].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) During key instantiation each parser in the list is tried until one doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) return -EBADMSG.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) The parser definition structure can be found in::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) #include <keys/asymmetric-parser.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) and looks like the following::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) struct asymmetric_key_parser {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) struct module *owner;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) const char *name;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) int (*parse)(struct key_preparsed_payload *prep);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) The owner and name fields should be set to the owning module and the name of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) the parser.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) There is currently only a single operation defined by the parser, and it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) mandatory:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) 1) parse().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) This is called to preparse the key from the key creation and update paths.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) In particular, it is called during the key creation _before_ a key is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) allocated, and as such, is permitted to provide the key's description in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) the case that the caller declines to do so.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) The caller passes a pointer to the following struct with all of the fields
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) cleared, except for data, datalen and quotalen [see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) Documentation/security/keys/core.rst]::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) struct key_preparsed_payload {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) char *description;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) void *payload[4];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) const void *data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) size_t datalen;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) size_t quotalen;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) The instantiation data is in a blob pointed to by data and is datalen in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) size. The parse() function is not permitted to change these two values at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) all, and shouldn't change any of the other values _unless_ they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) recognise the blob format and will not return -EBADMSG to indicate it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) not theirs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) If the parser is happy with the blob, it should propose a description for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) the key and attach it to ->description, ->payload[asym_subtype] should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) set to point to the subtype to be used, ->payload[asym_crypto] should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) set to point to the initialised data for that subtype,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) ->payload[asym_key_ids] should point to one or more hex fingerprints and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) quotalen should be updated to indicate how much quota this key should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) account for.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) When clearing up, the data attached to ->payload[asym_key_ids] and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) ->description will be kfree()'d and the data attached to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) ->payload[asm_crypto] will be passed to the subtype's ->destroy() method
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) to be disposed of. A module reference for the subtype pointed to by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) ->payload[asym_subtype] will be put.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) If the data format is not recognised, -EBADMSG should be returned. If it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) is recognised, but the key cannot for some reason be set up, some other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) negative error code should be returned. On success, 0 should be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) The key's fingerprint string may be partially matched upon. For a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) public-key algorithm such as RSA and DSA this will likely be a printable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) hex version of the key's fingerprint.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) Functions are provided to register and unregister parsers::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) int register_asymmetric_key_parser(struct asymmetric_key_parser *parser);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) void unregister_asymmetric_key_parser(struct asymmetric_key_parser *subtype);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) Parsers may not have the same name. The names are otherwise only used for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) displaying in debugging messages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) Keyring Link Restrictions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) Keyrings created from userspace using add_key can be configured to check the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) signature of the key being linked. Keys without a valid signature are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) allowed to link.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) Several restriction methods are available:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) 1) Restrict using the kernel builtin trusted keyring
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) - Option string used with KEYCTL_RESTRICT_KEYRING:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) - "builtin_trusted"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) The kernel builtin trusted keyring will be searched for the signing key.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) If the builtin trusted keyring is not configured, all links will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) rejected. The ca_keys kernel parameter also affects which keys are used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) for signature verification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) 2) Restrict using the kernel builtin and secondary trusted keyrings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) - Option string used with KEYCTL_RESTRICT_KEYRING:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) - "builtin_and_secondary_trusted"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) The kernel builtin and secondary trusted keyrings will be searched for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) signing key. If the secondary trusted keyring is not configured, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) restriction will behave like the "builtin_trusted" option. The ca_keys
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) kernel parameter also affects which keys are used for signature
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) verification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) 3) Restrict using a separate key or keyring
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) - Option string used with KEYCTL_RESTRICT_KEYRING:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) - "key_or_keyring:<key or keyring serial number>[:chain]"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) Whenever a key link is requested, the link will only succeed if the key
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) being linked is signed by one of the designated keys. This key may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) specified directly by providing a serial number for one asymmetric key, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) a group of keys may be searched for the signing key by providing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) serial number for a keyring.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) When the "chain" option is provided at the end of the string, the keys
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) within the destination keyring will also be searched for signing keys.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) This allows for verification of certificate chains by adding each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) certificate in order (starting closest to the root) to a keyring. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) instance, one keyring can be populated with links to a set of root
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) certificates, with a separate, restricted keyring set up for each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) certificate chain to be validated::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) # Create and populate a keyring for root certificates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) root_id=`keyctl add keyring root-certs "" @s`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) keyctl padd asymmetric "" $root_id < root1.cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) keyctl padd asymmetric "" $root_id < root2.cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) # Create and restrict a keyring for the certificate chain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) chain_id=`keyctl add keyring chain "" @s`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) keyctl restrict_keyring $chain_id asymmetric key_or_keyring:$root_id:chain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) # Attempt to add each certificate in the chain, starting with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) # certificate closest to the root.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) keyctl padd asymmetric "" $chain_id < intermediateA.cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) keyctl padd asymmetric "" $chain_id < intermediateB.cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) keyctl padd asymmetric "" $chain_id < end-entity.cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) If the final end-entity certificate is successfully added to the "chain"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) keyring, we can be certain that it has a valid signing chain going back to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) one of the root certificates.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) A single keyring can be used to verify a chain of signatures by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) restricting the keyring after linking the root certificate::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) # Create a keyring for the certificate chain and add the root
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) chain2_id=`keyctl add keyring chain2 "" @s`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) keyctl padd asymmetric "" $chain2_id < root1.cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) # Restrict the keyring that already has root1.cert linked. The cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) # will remain linked by the keyring.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) keyctl restrict_keyring $chain2_id asymmetric key_or_keyring:0:chain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) # Attempt to add each certificate in the chain, starting with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) # certificate closest to the root.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) keyctl padd asymmetric "" $chain2_id < intermediateA.cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) keyctl padd asymmetric "" $chain2_id < intermediateB.cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) keyctl padd asymmetric "" $chain2_id < end-entity.cert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) If the final end-entity certificate is successfully added to the "chain2"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) keyring, we can be certain that there is a valid signing chain going back
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) to the root certificate that was added before the keyring was restricted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) In all of these cases, if the signing key is found the signature of the key to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) be linked will be verified using the signing key. The requested key is added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) to the keyring only if the signature is successfully verified. -ENOKEY is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) returned if the parent certificate could not be found, or -EKEYREJECTED is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) returned if the signature check fails or the key is blacklisted. Other errors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) may be returned if the signature check could not be performed.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags