MAN page from Fedora 30 keyutils-libs-1.6-2.fc30.i686.rpm


Section: Asymmetric Kernel Key Type (7)
Updated: 8 Nov 2018


asymmetric - Kernel key type for holding asymmetric keys 


A kernel key ofasymmetrictype acts as a handle to an asymmetric key as used for public-keycryptography. The key material itself may be held inside the kernel or it maybe held in hardware with operations being offloaded. This prevents directuser access to the cryptographic material.

Keys may be any asymmetric type (RSA, ECDSA, ...) and may have both private andpublic components present or just the public component.

Asymmetric keys can be made use of by both the kernel and userspace. Thekernel can make use of them for module signature verification and kexec imageverification for example. Userspace is provided with a set ofkeyctl(KEYCTL_PKEY_*)calls for querying and using the key. These are wrapped bylibkeyutilsas functions namedkeyctl_pkey_*().

An asymmetric-type key can be loaded by the keyctl utility using a commandline like:

openssl x509 -in key.x509 -outform DER |keyctl padd asymmetric foo @s 


The asymmetric-type key can be viewed as a container that comprises of anumber of components:

The asymmetric key parsers attempt to identify the content of the payload bloband extract useful data from it with which to instantiate the key. The parseris only used when adding, instantiating or updating a key and isn't thereafterassociated with the key.
Available parsers include ones that can deal withDER-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 halfshould always be available, but the private half might not be. Whatoperations are available can be queried, as can the size of the key. The keymaterial may or may not actually reside in the kernel.
In addition to the normal key description (which can be generated by theparser), a number of supplementary identifiers may be available that can besearched for. These may be obtained, for example, by hashing the public keymaterial or from the subjectKeyIdentifier in an X.509 certificate.
Identifier-based searches are selected by passing as the description tokeyctl_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 indicatethe data to match.
This is the driver inside the kernel that accesses the key material andperforms operations on it. It might be entirely software-based or it mayoffload the operations to a hardware key store, such as aTPM.

Note that expiry times from the payload are ignored as these patches may beused during boot before the system clock is set. 


The asymmetric key parsers can handle keys in a number of forms:

DER-encoded X.509 certificates can be accepted. Two identifiers areconstructed: one from from the certificate issuer and serial number and theother from the subjectKeyIdentifier, if present. If left blank, the keydescription will be filled in from the subject field plus either thesubjectKeyIdentifier or the serialNumber. Only the public key is filled inand only the encrypt and verify operations are supported.
The signature on the X.509 certificate may be checked by the keyring it isbeing added to and it may also be rejected if the key is blacklisted.
Unencrypted DER-encoded PKCS#8 key data containers can be accepted. Currentlyno identifiers are constructed. The private key and the public key are loadedfrom 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 noidentifiers are constructed. The public key is extracted from the blob butthe private key is expected to be resident in the TPM. Encryption andsignature verification is done in software, but decryption and signing areoffloaded to the TPM so as not to expose the private key.
This parser only supports TPM-1.2 wrappings and enc=pkcs1 encoding type. Italso uses a hard-coded null SRK password; password-protected SRKs are not yetsupported.


In addition to the standard keyutils library functions, such askeyctl_update(),there are five calls specific to the asymmetric key type (though they are opento being used by other key types also):


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 otheroperations and which operations are actually supported.

The other operations form two pairs: encrypt/decrypt and create/verifysignature. Not all of these operations will necessarily be available;typically, encrypt and verify only require the public key to be availablewhereas decrypt and sign require the private key as well.

All of these operations take an information string parameter that suppliesadditional information such as encoding type/form and the password(s) needed tounlock/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 usedby a particular key.

Available parameters include:

The encoding type for use in an encrypted blob or a signature. An examplemight be "enc=pkcs1".
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 asignature. The data to be signed or verified must have been parsed by thecaller and the hash passed to keyctl_pkey_sign() orkeyctl_pkey_verify() beforehand. An example might be "hash=sha256".

Note that not all parameters are used by all subtypes. 


An additional keyutils function,keyctl_restrict_keyring(),can be used to gate a keyring so that a new key can only be added to theaffected keyring if (a) it's an asymmetric key, (b) it's validly signed by akey in some appropriate keyring and (c) it's not blacklisted.

 keyctl_restrict_keyring(keyring, "asymmetric",

Where <signing-key> is the ID of a key or a ring of keys that act as theauthority to permit a new key to be added to the keyring. The chain flagindicates that keys that have been added to the keyring may also be used toverify new keys. Authorising keys must themselves be asymmetric-type keys thatcan 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 maypermit additional keys to be added. These are typically gated by keys thatalready exist, preventing unauthorised keys from being used for such things asmodule verification. 


When the attempt is made to add a key to the kernel, a hash of the public keyis checked against theblacklist.This is a system keyring named.blacklistand contains keys of typeblacklist.If the blacklist contains a key whose description matches the hash of the newkey, that new key will be rejected with errorEKEYREJECTED.

The blacklist keyring may be loaded from multiple sources, including a listcompiled into the kernel and the UEFIdbxvariable. Further hashes may also be blacklisted by the administrator. Notethat blacklisting is not retroactive, so an asymmetric key that is already onthe system cannot be blacklisted by adding a matching blacklist entry later. 


Theasymmetrickey type first appeared in v3.7 of the Linux kernel, therestrictionfunction in v4.11 and thepublic key operationsin v4.20. 






This document was created byman2html,using the manual pages.