{ "mode": "info", "parameter": "asymmetric-key", "section": "", "url": "https://www.chedong.com/phpMan.php/info/asymmetric-key/json", "generated": "2026-07-05T01:20:14Z", "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\nas used for public-key cryptography. The key material itself may be\nheld inside the kernel or it may be held in hardware with operations\nbeing offloaded. This prevents direct user access to the cryptographic\nmaterial.\n\nKeys may be any asymmetric type (RSA, ECDSA, ...) and may have both\nprivate and public components present or just the public component.\n\nAsymmetric keys can be made use of by both the kernel and userspace.\nThe kernel can make use of them for module signature verification and\nkexec image verification for example. Userspace is provided with a set\nof keyctl(KEYCTLPKEY*) calls for querying and using the key. These\nare wrapped by libkeyutils as functions named keyctlpkey*().\n\nAn asymmetric-type key can be loaded by the keyctl utility using a com-\nmand 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\na number of components:\n\nParsers\nThe asymmetric key parsers attempt to identify the content of\nthe payload blob and extract useful data from it with which to\ninstantiate the key. The parser is only used when adding, in-\nstantiating or updating a key and isn't thereafter associated\nwith the key.\n\nAvailable parsers include ones that can deal with DER-encoded\nX.509, DER-encoded PKCS#8 and DER-encoded TPM-wrapped blobs.\n\nPublic and private keys\nThese are the cryptographic components of the key pair. The\npublic half should always be available, but the private half\nmight not be. What operations are available can be queried, as\ncan the size of the key. The key material may or may not actu-\nally reside in the kernel.\n\nIdentifiers\nIn addition to the normal key description (which can be gener-\nated by the parser), a number of supplementary identifiers may\nbe available that can be searched for. These may be obtained,\nfor example, by hashing the public key material or from the sub-\njectKeyIdentifier in an X.509 certificate.\n\nIdentifier-based searches are selected by passing as the de-\nscription to keyctlsearch() a string constructed of hex charac-\nters prefixed with either \"id:\" or \"ex:\". The \"id:\" prefix in-\ndicates that a partial tail match is permissible whereas \"ex:\"\nrequires an exact match on the full string. The hex characters\nindicate the data to match.\n\nSubtype\nThis is the driver inside the kernel that accesses the key mate-\nrial and performs operations on it. It might be entirely soft-\nware-based or it may offload the operations to a hardware key\nstore, such as a TPM.\n\nNote that expiry times from the payload are ignored as these patches\nmay be used during boot before 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\nare constructed: one from from the certificate issuer and serial\nnumber and the other from the subjectKeyIdentifier, if present.\nIf left blank, the key description will be filled in from the\nsubject field plus either the subjectKeyIdentifier or the seri-\nalNumber. Only the public key is filled in and only the encrypt\nand verify operations are supported.\n\nThe signature on the X.509 certificate may be checked by the\nkeyring it is being added to and it may also be rejected if the\nkey is blacklisted.\n\nPKCS#8 Unencrypted DER-encoded PKCS#8 key data containers can be ac-\ncepted. Currently no identifiers are constructed. The private\nkey and the public key are loaded from the PKCS#8 blobs. En-\ncrypted PKCS#8 is not currently supported.\n\nTPM-Wrapped keys\nDER-encoded TPM-wrapped TSS key blobs can be accepted. Cur-\nrently no identifiers are constructed. The public key is ex-\ntracted from the blob but the private key is expected to be res-\nident in the TPM. Encryption and signature verification is done\nin software, but decryption and signing are offloaded to the TPM\nso as not to expose the private key.\n\nThis parser only supports TPM-1.2 wrappings and enc=pkcs1 encod-\ning type. It also uses a hard-coded null SRK password; pass-\nword-protected SRKs are not yet supported.\n", "subsections": [] }, "USERSPACE API": { "content": "In addition to the standard keyutils library functions, such as\nkeyctlupdate(), there are five calls specific to the asymmetric key\ntype (though they are open to being used by other key types also):\n\nkeyctlpkeyquery()\nkeyctlpkeyencrypt()\nkeyctlpkeydecrypt()\nkeyctlpkeysign()\nkeyctlpkeyverify()\n\nThe query function can be used to retrieve information about an asym-\nmetric key, such as the key size, the amount of space required by buf-\nfers for the other operations and which operations are actually sup-\nported.\n\nThe other operations form two pairs: encrypt/decrypt and create/verify\nsignature. Not all of these operations will necessarily be available;\ntypically, encrypt and verify only require the public key to be avail-\nable whereas decrypt and sign require the private key as well.\n\nAll of these operations take an information string parameter that sup-\nplies additional information such as encoding type/form and the pass-\nword(s) needed to unlock/unwrap the key. This takes the form of a\ncomma-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.\nAn example might be \"enc=pkcs1\".\n\nhash=\nThe name of the hash algorithm that was used to digest the data\nto be signed. Note that this is only used to construct any en-\ncoding that is used in a signature. The data to be signed or\nverified must have been parsed by the caller and the hash passed\nto keyctlpkeysign() or keyctlpkeyverify() beforehand. An\nexample might be \"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\nto gate a keyring so that a new key can only be added to the affected\nkeyring if (a) it's an asymmetric key, (b) it's validly signed by a key\nin 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\nthe authority to permit a new key to be added to the keyring. The\nchain flag indicates that keys that have been added to the keyring may\nalso be used to verify new keys. Authorising keys must themselves be\nasymmetric-type keys that can be used to do a signature verification on\nthe key being added.\n\nNote that there are various system keyrings visible to the root user\nthat may permit additional keys to be added. These are typically gated\nby keys that already exist, preventing unauthorised keys from being\nused 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 pub-\nlic key is checked against the blacklist. This is a system keyring\nnamed .blacklist and contains keys of type blacklist. If the blacklist\ncontains a key whose description matches the hash of the new key, that\nnew key will be rejected with error EKEYREJECTED.\n\nThe blacklist keyring may be loaded from multiple sources, including a\nlist compiled into the kernel and the UEFI dbx variable. Further\nhashes may also be blacklisted by the administrator. Note that black-\nlisting is not retroactive, so an asymmetric key that is already on the\nsystem cannot be blacklisted by adding a matching blacklist entry\nlater.\n", "subsections": [] }, "VERSIONS": { "content": "The asymmetric key type first appeared in v3.7 of the Linux kernel, the\nrestriction function in v4.11 and the public key operations in v4.20.\n", "subsections": [] }, "SEE ALSO": { "content": "keyctl(1), addkey(2), keyctl(3), keyctlpkeyencrypt(3),\nkeyctlpkeyquery(3), keyctlpkeysign(3), keyrings(7), keyutils(7)\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" } ] }