Provided by: keyutils_1.6-6_amd64 bug

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.

SEE ALSO

       keyctl(1), add_key(2), keyctl(3), keyctl_pkey_encrypt(3), keyctl_pkey_query(3),
       keyctl_pkey_sign(3), keyrings(7), keyutils(7)