diff options
Diffstat (limited to 'man/asymmetric-key.7')
| -rw-r--r-- | man/asymmetric-key.7 | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/man/asymmetric-key.7 b/man/asymmetric-key.7 new file mode 100644 index 0000000000..5fc78cb057 --- /dev/null +++ b/man/asymmetric-key.7 @@ -0,0 +1,232 @@ +.\" +.\" Copyright (C) 2018 Red Hat, Inc. All Rights Reserved. +.\" Written by David Howells (dhowells@redhat.com) +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH ASYMMETRIC-KEY 7 "8 Nov 2018" Linux "Asymmetric Kernel Key Type" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +asymmetric \- Kernel key type for holding asymmetric keys +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH OVERVIEW +.PP +A kernel key of +.B 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. +.PP +Keys may be any asymmetric type (RSA, ECDSA, ...) and may have both private and +public components present or just the public component. +.PP +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 +.BR keyctl ( KEYCTL_PKEY_* ) +calls for querying and using the key. These are wrapped by +.B libkeyutils +as functions named +.BR keyctl_pkey_*() . +.PP +An asymmetric-type key can be loaded by the keyctl utility using a command +line like: +.PP +.in +4n +.EX +openssl x509 -in key.x509 -outform DER | +keyctl padd asymmetric foo @s +.EE +.in +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.PP +The asymmetric-type key can be viewed as a container that comprises of a +number of components: +.TP +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. +.IP +Available parsers include ones that can deal with +.RB "DER-encoded " X.509 ", DER-encoded " PKCS#8 " and DER-encoded " TPM "-wrapped blobs." +.TP +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. +.TP +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. +.IP +Identifier-based searches are selected by passing as the description to +.BR 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. +.TP +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 +.BR TPM . +.PP +Note that expiry times from the payload are ignored as these patches may be +used during boot before the system clock is set. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH PARSERS +.PP +The asymmetric key parsers can handle keys in a number of forms: +.TP +\fBX.509\fP +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. +.IP +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. +.TP +\fBPKCS#8\fP +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. +.TP +\fBTPM-Wrapped keys\fP +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. +.IP +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. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH USERSPACE API +.PP +In addition to the standard keyutils library functions, such as +.IR keyctl_update (), +there are five calls specific to the asymmetric key type (though they are open +to being used by other key types also): +.PP +.RS +\fIkeyctl_pkey_query\fP() +.br +\fIkeyctl_pkey_encrypt\fP() +.br +\fIkeyctl_pkey_decrypt\fP() +.br +\fIkeyctl_pkey_sign\fP() +.br +\fIkeyctl_pkey_verify\fP() +.RE +.PP +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. +.PP +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. +.PP +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. +.PP +Available parameters include: +.TP +enc=<type> +The encoding type for use in an encrypted blob or a signature. An example +might be "enc=pkcs1". +.TP +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 \fIkeyctl_pkey_sign\fP() or +\fIkeyctl_pkey_verify\fP() beforehand. An example might be "hash=sha256". +.PP +Note that not all parameters are used by all subtypes. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RESTRICTED KEYRINGS +.PP +An additional keyutils function, +.IR 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. +.PP +.in +4n +.EX + keyctl_restrict_keyring(keyring, "asymmetric", + "key_or_keyring:<signing-key>[:chain]"); +.EE +.in +.PP +Where \fI<signing-key>\fP 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 \fIchain\fP 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. +.PP +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. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH BLACKLISTING +.PP +When the attempt is made to add a key to the kernel, a hash of the public key +is checked against the +.BR blacklist. +This is a system keyring named +.B .blacklist +and contains keys of type +.BR blacklist . +If the blacklist contains a key whose description matches the hash of the new +key, that new key will be rejected with error +.BR EKEYREJECTED . +.PP +The blacklist keyring may be loaded from multiple sources, including a list +compiled into the kernel and the UEFI +.B 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. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH VERSIONS +The +.B asymmetric +key type first appeared in v3.7 of the Linux kernel, the +.B restriction +function in v4.11 and the +.B public key operations +in v4.20. +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (3), +.BR keyctl_pkey_encrypt (3), +.BR keyctl_pkey_query (3), +.BR keyctl_pkey_sign (3), +.BR keyrings (7), +.BR keyutils (7) |