Documentation/crypto/asymmetric-keys.txt

   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.