Provided by: keyutils_1.6-6ubuntu1.1_amd64 
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)