{ "mode": "man", "parameter": "asymmetric-key", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/asymmetric-key/7/json", "generated": "2026-06-17T13:37:48Z", "sections": { "NAME": { "content": "asymmetric - Kernel key type for holding asymmetric keys\n", "subsections": [] }, "OVERVIEW": { "content": "A kernel key of asymmetric type acts as a handle to an asymmetric key as used for public-key\ncryptography. The key material itself may be held inside the kernel or it may be held in\nhardware with operations being offloaded. This prevents direct user access to the crypto‐\ngraphic material.\n\nKeys may be any asymmetric type (RSA, ECDSA, ...) and may have both private and public compo‐\nnents present or just the public component.\n\nAsymmetric keys can be made use of by both the kernel and userspace. The kernel can make use\nof them for module signature verification and kexec image verification for example.\nUserspace is provided with a set of keyctl(KEYCTLPKEY*) calls for querying and using the\nkey. These are wrapped by libkeyutils as functions named keyctlpkey*().\n\nAn asymmetric-type key can be loaded by the keyctl utility using a command line like:\n\nopenssl x509 -in key.x509 -outform DER |\nkeyctl padd asymmetric foo @s\n", "subsections": [] }, "DESCRIPTION": { "content": "The asymmetric-type key can be viewed as a container that comprises of a number of compo‐\nnents:\n\nParsers\nThe asymmetric key parsers attempt to identify the content of the payload blob and ex‐\ntract useful data from it with which to instantiate the key. The parser is only used\nwhen adding, instantiating or updating a key and isn't thereafter associated with the\nkey.\n\nAvailable parsers include ones that can deal with DER-encoded X.509, DER-encoded\nPKCS#8 and DER-encoded TPM-wrapped blobs.\n\nPublic and private keys\nThese are the cryptographic components of the key pair. The public half should always\nbe available, but the private half might not be. What operations are available can be\nqueried, as can the size of the key. The key material may or may not actually reside\nin the kernel.\n\nIdentifiers\nIn addition to the normal key description (which can be generated by the parser), a\nnumber of supplementary identifiers may be available that can be searched for. These\nmay be obtained, for example, by hashing the public key material or from the subjec‐\ntKeyIdentifier in an X.509 certificate.\n\nIdentifier-based searches are selected by passing as the description to\nkeyctlsearch() a string constructed of hex characters prefixed with either \"id:\" or\n\"ex:\". The \"id:\" prefix indicates that a partial tail match is permissible whereas\n\"ex:\" requires an exact match on the full string. The hex characters indicate the\ndata to match.\n\nSubtype\nThis is the driver inside the kernel that accesses the key material and performs oper‐\nations on it. It might be entirely software-based or it may offload the operations to\na hardware key store, such as a TPM.\n\nNote that expiry times from the payload are ignored as these patches may be used during boot\nbefore the system clock is set.\n", "subsections": [] }, "PARSERS": { "content": "The asymmetric key parsers can handle keys in a number of forms:\n\nX.509 DER-encoded X.509 certificates can be accepted. Two identifiers are constructed: one\nfrom from the certificate issuer and serial number and the other from the subjectKeyI‐\ndentifier, if present. If left blank, the key description will be filled in from the\nsubject field plus either the subjectKeyIdentifier or the serialNumber. Only the pub‐\nlic key is filled in and only the encrypt and verify operations are supported.\n\nThe signature on the X.509 certificate may be checked by the keyring it is being added\nto and it may also be rejected if the key is blacklisted.\n\nPKCS#8 Unencrypted DER-encoded PKCS#8 key data containers can be accepted. Currently no\nidentifiers are constructed. The private key and the public key are loaded from the\nPKCS#8 blobs. Encrypted PKCS#8 is not currently supported.\n", "subsections": [ { "name": "TPM-Wrapped keys", "content": "DER-encoded TPM-wrapped TSS key blobs can be accepted. Currently no identifiers are\nconstructed. The public key is extracted from the blob but the private key is ex‐\npected to be resident in the TPM. Encryption and signature verification is done in\nsoftware, but decryption and signing are offloaded to the TPM so as not to expose the\nprivate key.\n\nThis parser only supports TPM-1.2 wrappings and enc=pkcs1 encoding type. It also uses\na hard-coded null SRK password; password-protected SRKs are not yet supported.\n" } ] }, "USERSPACE API": { "content": "In addition to the standard keyutils library functions, such as keyctlupdate(), there are\nfive calls specific to the asymmetric key type (though they are open to being used by other\nkey types also):\n\nkeyctlpkeyquery()\nkeyctlpkeyencrypt()\nkeyctlpkeydecrypt()\nkeyctlpkeysign()\nkeyctlpkeyverify()\n\nThe query function can be used to retrieve information about an asymmetric key, such as the\nkey size, the amount of space required by buffers for the other operations and which opera‐\ntions are actually supported.\n\nThe other operations form two pairs: encrypt/decrypt and create/verify signature. Not all of\nthese operations will necessarily be available; typically, encrypt and verify only require\nthe public key to be available whereas decrypt and sign require the private key as well.\n\nAll of these operations take an information string parameter that supplies additional infor‐\nmation such as encoding type/form and the password(s) needed to unlock/unwrap the key. This\ntakes the form of a comma-separated list of \"key[=value]\" pairs, the exact set of which de‐\npends on the subtype driver used by a particular key.\n\nAvailable parameters include:\n\nenc=\nThe encoding type for use in an encrypted blob or a signature. An example might be\n\"enc=pkcs1\".\n\nhash=\nThe name of the hash algorithm that was used to digest the data to be signed. Note\nthat this is only used to construct any encoding that is used in a signature. The\ndata to be signed or verified must have been parsed by the caller and the hash passed\nto keyctlpkeysign() or keyctlpkeyverify() beforehand. An example might be\n\"hash=sha256\".\n\nNote that not all parameters are used by all subtypes.\n", "subsections": [] }, "RESTRICTED KEYRINGS": { "content": "An additional keyutils function, keyctlrestrictkeyring(), can be used to gate a keyring so\nthat a new key can only be added to the affected keyring if (a) it's an asymmetric key, (b)\nit's validly signed by a key in some appropriate keyring and (c) it's not blacklisted.\n\nkeyctlrestrictkeyring(keyring, \"asymmetric\",\n\"keyorkeyring:[:chain]\");\n\nWhere is the ID of a key or a ring of keys that act as the authority to permit\na new key to be added to the keyring. The chain flag indicates that keys that have been\nadded to the keyring may also be used to verify new keys. Authorising keys must themselves\nbe asymmetric-type keys that can be used to do a signature verification on the key being\nadded.\n\nNote that there are various system keyrings visible to the root user that may permit addi‐\ntional keys to be added. These are typically gated by keys that already exist, preventing\nunauthorised keys from being used for such things as module verification.\n", "subsections": [] }, "BLACKLISTING": { "content": "When the attempt is made to add a key to the kernel, a hash of the public key is checked\nagainst the blacklist. This is a system keyring named .blacklist and contains keys of type\nblacklist. If the blacklist contains a key whose description matches the hash of the new\nkey, that new key will be rejected with error EKEYREJECTED.\n\nThe blacklist keyring may be loaded from multiple sources, including a list compiled into the\nkernel and the UEFI dbx variable. Further hashes may also be blacklisted by the administra‐\ntor. Note that blacklisting is not retroactive, so an asymmetric key that is already on the\nsystem cannot be blacklisted by adding a matching blacklist entry later.\n", "subsections": [] }, "VERSIONS": { "content": "The asymmetric key type first appeared in v3.7 of the Linux kernel, the restriction function\nin v4.11 and the public key operations in v4.20.\n", "subsections": [] }, "SEE ALSO": { "content": "keyctl(1), addkey(2), keyctl(3), keyctlpkeyencrypt(3), keyctlpkeyquery(3),\nkeyctlpkeysign(3), keyrings(7), keyutils(7)\n\n\n\nLinux 8 Nov 2018 ASYMMETRIC-KEY(7)", "subsections": [] } }, "summary": "asymmetric - Kernel key type for holding asymmetric keys", "flags": [], "examples": [], "see_also": [ { "name": "keyctl", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/keyctl/1/json" }, { "name": "addkey", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/addkey/2/json" }, { "name": "keyctl", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/keyctl/3/json" }, { "name": "keyctlpkeyencrypt", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/keyctlpkeyencrypt/3/json" }, { "name": "keyctlpkeyquery", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/keyctlpkeyquery/3/json" }, { "name": "keyctlpkeysign", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/keyctlpkeysign/3/json" }, { "name": "keyrings", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/keyrings/7/json" }, { "name": "keyutils", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/keyutils/7/json" }, { "name": "ASYMMETRIC-KEY", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/ASYMMETRIC-KEY/7/json" } ] }