# asymmetric-key

## NAME



           asymmetric - Kernel key type for holding asymmetric keys
    


## OVERVIEW



           A kernel key of **asymmetric** type acts as a handle to an asymmetric
           key as used for public-key cryptography.  The key material itself
           may be held inside the kernel or it may be held in hardware with
           operations being offloaded.  This prevents direct user access to
           the cryptographic material.
    
           Keys may be any asymmetric type (RSA, ECDSA, ...) and may have
           both private and public components present or just the public
           component.
    
           Asymmetric keys can be made use of by both the kernel and
           userspace.  The kernel can make use of them for module signature
           verification and kexec image verification for example.  Userspace
           is provided with a set of **keyctl**(**KEYCTL_PKEY_***) calls for querying
           and using the key.  These are wrapped by **libkeyutils** as functions
           named **keyctl_pkey_*()**.
    
           An asymmetric-type key can be loaded by the keyctl utility using a
           command line like:
    
               openssl x509 -in key.x509 -outform DER |
               keyctl padd asymmetric foo @s
    


## DESCRIPTION



           The asymmetric-type key can be viewed as a container that
           comprises of a number of components:
    
           Parsers
                  The asymmetric key parsers attempt to identify the content
                  of the payload blob and extract useful data from it with
                  which to instantiate the key.  The parser is only used when
                  adding, instantiating or updating a key and isn't
                  thereafter associated with the key.
    
                  Available parsers include ones that can deal with DER-
                  encoded **X.509** , DER-encoded **PKCS#8** and DER-encoded **TPM** -
                  wrapped blobs.
    
           Public and private keys
                  These are the cryptographic components of the key pair.
                  The public half should always be available, but the private
                  half might not be.  What operations are available can be
                  queried, as can the size of the key.  The key material may
                  or may not actually reside in the kernel.
    
           Identifiers
                  In addition to the normal key description (which can be
                  generated by the parser), a number of supplementary
                  identifiers may be available that can be searched for.
                  These may be obtained, for example, by hashing the public
                  key material or from the subjectKeyIdentifier in an X.509
                  certificate.
    
                  Identifier-based searches are selected by passing as the
                  description to **keyctl_search**() a string constructed of hex
                  characters prefixed with either "id:" or "ex:".  The "id:"
                  prefix indicates that a partial tail match is permissible
                  whereas "ex:" requires an exact match on the full string.
                  The hex characters indicate the data to match.
    
           Subtype
                  This is the driver inside the kernel that accesses the key
                  material and performs operations on it.  It might be
                  entirely software-based or it may offload the operations to
                  a hardware key store, such as a **TPM**.
    
           Note that expiry times from the payload are ignored as these
           patches may be used during boot before the system clock is set.
    


## PARSERS



           The asymmetric key parsers can handle keys in a number of forms:
    
           **X.509** DER-encoded X.509 certificates can be accepted.  Two
                  identifiers are constructed: one from from the certificate
                  issuer and serial number and the other from the
                  subjectKeyIdentifier, if present.  If left blank, the key
                  description will be filled in from the subject field plus
                  either the subjectKeyIdentifier or the serialNumber.  Only
                  the public key is filled in and only the encrypt and verify
                  operations are supported.
    
                  The signature on the X.509 certificate may be checked by
                  the keyring it is being added to and it may also be
                  rejected if the key is blacklisted.
    
           **PKCS#8** Unencrypted DER-encoded PKCS#8 key data containers can be
                  accepted.  Currently no identifiers are constructed.  The
                  private key and the public key are loaded from the PKCS#8
                  blobs.  Encrypted PKCS#8 is not currently supported.
    
           **TPM-Wrapped keys**
                  DER-encoded TPM-wrapped TSS key blobs can be accepted.
                  Currently no identifiers are constructed.  The public key
                  is extracted from the blob but the private key is expected
                  to be resident in the TPM.  Encryption and signature
                  verification is done in software, but decryption and
                  signing are offloaded to the TPM so as not to expose the
                  private key.
    
                  This parser only supports TPM-1.2 wrappings and enc=pkcs1
                  encoding type.  It also uses a hard-coded null SRK
                  password; password-protected SRKs are not yet supported.
    


## USERSPACE API



           In addition to the standard keyutils library functions, such as
           _keyctl_update_(), there are five calls specific to the asymmetric
           key type (though they are open to being used by other key types
           also):
    
                  _keyctl_pkey_query_()
                  _keyctl_pkey_encrypt_()
                  _keyctl_pkey_decrypt_()
                  _keyctl_pkey_sign_()
                  _keyctl_pkey_verify_()
    
           The query function can be used to retrieve information about an
           asymmetric key, such as the key size, the amount of space required
           by buffers for the other operations and which operations are
           actually supported.
    
           The other operations form two pairs: encrypt/decrypt and
           create/verify signature.  Not all of these operations will
           necessarily be available; typically, encrypt and verify only
           require the public key to be available whereas decrypt and sign
           require the private key as well.
    
           All of these operations take an information string parameter that
           supplies additional information such as encoding type/form and the
           password(s) needed to unlock/unwrap the key.  This takes the form
           of a comma-separated list of "key[=value]" pairs, the exact set of
           which depends on the subtype driver used by a particular key.
    
           Available parameters include:
    
           enc=<type>
                  The encoding type for use in an encrypted blob or a
                  signature.  An example might be "enc=pkcs1".
    
           hash=<name>
                  The name of the hash algorithm that was used to digest the
                  data to be signed.  Note that this is only used to
                  construct any encoding that is used in a signature.  The
                  data to be signed or verified must have been parsed by the
                  caller and the hash passed to _keyctl_pkey_sign_() or
                  _keyctl_pkey_verify_() beforehand.  An example might be
                  "hash=sha256".
    
           Note that not all parameters are used by all subtypes.
    


## RESTRICTED KEYRINGS



           An additional keyutils function, _keyctl_restrict_keyring_(), can be
           used to gate a keyring so that a new key can only be added to the
           affected keyring if (a) it's an asymmetric key, (b) it's validly
           signed by a key in some appropriate keyring and (c) it's not
           blacklisted.
    
                keyctl_restrict_keyring(keyring, "asymmetric",
                                        "key_or_keyring:<signing-key>[:chain]");
    
           Where _< signing-key>_ is the ID of a key or a ring of keys that act
           as the authority to permit a new key to be added to the keyring.
           The _chain_ flag indicates that keys that have been added to the
           keyring may also be used to verify new keys.  Authorising keys
           must themselves be asymmetric-type keys that can be used to do a
           signature verification on the key being added.
    
           Note that there are various system keyrings visible to the root
           user that may permit additional keys to be added.  These are
           typically gated by keys that already exist, preventing
           unauthorised keys from being used for such things as module
           verification.
    


## BLACKLISTING



           When the attempt is made to add a key to the kernel, a hash of the
           public key is checked against the **blacklist.** This is a system
           keyring named **.blacklist** and contains keys of type **blacklist**.  If
           the blacklist contains a key whose description matches the hash of
           the new key, that new key will be rejected with error
           **EKEYREJECTED**.
    
           The blacklist keyring may be loaded from multiple sources,
           including a list compiled into the kernel and the UEFI **dbx**
           variable.  Further hashes may also be blacklisted by the
           administrator.  Note that blacklisting is not retroactive, so an
           asymmetric key that is already on the system cannot be blacklisted
           by adding a matching blacklist entry later.
    


## VERSIONS



           The **asymmetric** key type first appeared in v3.7 of the Linux
           kernel, the **restriction** function in v4.11 and the **public key**
           **operations** in v4.20.
    


* * *