From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.0 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY,SPF_PASS,WEIRD_QUOTING autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 5B683C0044C for ; Wed, 7 Nov 2018 14:42:14 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id EC3322085B for ; Wed, 7 Nov 2018 14:42:13 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org EC3322085B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-security-module-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726766AbeKHAMv convert rfc822-to-8bit (ORCPT ); Wed, 7 Nov 2018 19:12:51 -0500 Received: from mx1.redhat.com ([209.132.183.28]:62608 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726670AbeKHAMu (ORCPT ); Wed, 7 Nov 2018 19:12:50 -0500 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 6D81589AD2; Wed, 7 Nov 2018 14:42:12 +0000 (UTC) Received: from warthog.procyon.org.uk (ovpn-120-113.rdu2.redhat.com [10.10.120.113]) by smtp.corp.redhat.com (Postfix) with ESMTP id 001DD5D73F; Wed, 7 Nov 2018 14:42:10 +0000 (UTC) Organization: Red Hat UK Ltd. Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United Kingdom. Registered in England and Wales under Company Registration No. 3798903 From: David Howells To: Denis Kenzior cc: dhowells@redhat.com, keyrings@vger.kernel.org, linux-security-module@vger.kernel.org, mtk.manpages@gmail.com Subject: [KEYUTILS PATCH] Add manpages for asymmetric key type and ops MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-ID: <13897.1541601730.1@warthog.procyon.org.uk> Content-Transfer-Encoding: 8BIT Date: Wed, 07 Nov 2018 14:42:10 +0000 Message-ID: <13898.1541601730@warthog.procyon.org.uk> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.26]); Wed, 07 Nov 2018 14:42:12 +0000 (UTC) Sender: owner-linux-security-module@vger.kernel.org Precedence: bulk List-ID: Add man pages for asymmetric key type and ops Add manual pages for the asymmetric key type and its specialised keyctl operations. Signed-off-by: David Howells --- asymmetric-key.7 | 232 ++++++++++++++++++++++++++++++++++++++++++++++++++ keyctl.1 | 63 +++++++++++++ keyctl.3 | 10 ++ keyctl_pkey_decrypt.3 | 1 keyctl_pkey_encrypt.3 | 113 ++++++++++++++++++++++++ keyctl_pkey_query.3 | 52 +++++++---- keyctl_pkey_sign.3 | 134 ++++++++++++++++++++++++++++ keyctl_pkey_verify.3 | 1 8 files changed, 589 insertions(+), 17 deletions(-) diff --git a/man/asymmetric-key.7 b/man/asymmetric-key.7 new file mode 100644 index 0000000..5fc78cb --- /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= +The encoding type for use in an encrypted blob or a signature. An example +might be "enc=pkcs1". +.TP +hash= +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:[:chain]"); +.EE +.in +.PP +Where \fI\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) diff --git a/man/keyctl.1 b/man/keyctl.1 index a3d7a35..9eacfd2 100644 --- a/man/keyctl.1 +++ b/man/keyctl.1 @@ -98,6 +98,16 @@ keyctl \- key management facility control \fBkeyctl\fR dh_compute_kdf .br \fBkeyctl\fR dh_compute_kdf_oi +.br +\fBkeyctl\fR pkey_query [k=v]* +.br +\fBkeyctl\fR pkey_encrypt [k=v]* > +.br +\fBkeyctl\fR pkey_decrypt [k=v]* > +.br +\fBkeyctl\fR pkey_sign [k=v]* > +.br +\fBkeyctl\fR pkey_decrypt [k=v]* .SH DESCRIPTION This program is used to control the key management facility in various ways using a variety of subcommands. @@ -746,6 +756,59 @@ operation. This command allows the caller to provide the other input data (OI data) compliant to SP800-56A via stdin. .fi .RE +.SS Perform public-key operations with an asymmetric key +\fBkeyctl\fR pkey_query [k=v]* +.br +\fBkeyctl\fR pkey_encrypt [k=v]* > +.br +\fBkeyctl\fR pkey_decrypt [k=v]* > +.br +\fBkeyctl\fR pkey_sign [k=v]* > +.br +\fBkeyctl\fR pkey_verify [k=v]* +.PP +These commands query an asymmetric key, encrypt data with it, decrypt the +encrypted data, generate a signature over some data and verify that signature. +For encrypt, decrypt and sign, the resulting data is written to stdout; verify +reads the data and the signature files and compares them. +.PP +[\fB!\fP] NOTE that the data is of very limited capacity, with no more bits +than the size of the key. For signatures, the caller is expected to digest +the actual data and pass in the result of the digest as the datafile. The +name of the digest should be specified on the end of the command line as +"hash=". +.PP +The +.I key +ID indicates the key to use; +.I pass +is a placeholder for future password provision and should be "0" for the +moment; +.I datafile +is the unencrypted data to be encrypted, signed or to have its signature +checked; +.I encfile +is a file containing encrypted data; and +.I sigfile +is a file containing a signature. +.PP +A list of parameters in "key[=val]" form can be included on the end of the +command line. These specify things like the digest algorithm used +("hash=") or the encoding form ("enc="). +.PP +.RS +.nf +k=`keyctl padd asymmetric "" @s foo.enc +keyctl pkey_decrypt $k 0 foo.enc enc=pkcs1 >foo.hash +keyctl pkey_sign $k 0 foo.hash enc=pkcs1 hash=sha256 >foo.sig +keyctl pkey_verify $k 0 foo.hash foo.sig enc=pkcs1 hash=sha256 +.fi +.RE +.PP +See asymmetric-key(7) for more information. + .SH ERRORS There are a number of common errors returned by this program: diff --git a/man/keyctl.3 b/man/keyctl.3 index 5360f5b..ef3d09b 100644 --- a/man/keyctl.3 +++ b/man/keyctl.3 @@ -67,6 +67,16 @@ and then telling the linker it should link in the library: .br .BR keyctl_negate (3) .br +.BR keyctl_pkey_dec (3) +.br +.BR keyctl_pkey_enc (3) +.br +.BR keyctl_pkey_query (3) +.br +.BR keyctl_pkey_sign (3) +.br +.BR keyctl_pkey_verify (3) +.br .BR keyctl_read (3) .br .BR keyctl_read_alloc (3) diff --git a/man/keyctl_pkey_decrypt.3 b/man/keyctl_pkey_decrypt.3 new file mode 100644 index 0000000..47b1937 --- /dev/null +++ b/man/keyctl_pkey_decrypt.3 @@ -0,0 +1 @@ +.so keyctl_pkey_encrypt.3 diff --git a/man/keyctl_pkey_encrypt.3 b/man/keyctl_pkey_encrypt.3 new file mode 100644 index 0000000..44c640e --- /dev/null +++ b/man/keyctl_pkey_encrypt.3 @@ -0,0 +1,113 @@ +.\" +.\" 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 KEYCTL_PKEY_ENCRYPT 3 "8 Nov 2018" Linux "Linux Public-Key Encryption" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_pkey_encrypt, keyctl_pkey_decrypt \- Encrypt and decrypt data +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "long keyctl_pkey_encrypt(key_serial_t " key ", const char *" info , +.BI " const void *" data ", size_t " data_len , +.BI " void *" enc ", size_t " enc_len ");" +.sp +.BI "long keyctl_pkey_decrypt(key_serial_t " key ", const char *" info , +.BI " const void *" enc ", size_t " enc_len , +.BI " void *" data ", size_t " data_len ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_pkey_encrypt () +asks the kernel to use the crypto material attached to a key to encrypt a blob +of data and +.BR keyctl_pkey_decrypt () +asks the kernel to use the key to reverse the operation and recover the +original data. Note that these operations may involve the kernel calling out +to cryptographic hardware. The caller must have +.B search +permission on a key to be able to use them in this manner. +.PP +.PP +When invoking the function, +.I key +indicates the key that will provide the cryptographic material and +.I info +points to a comma-separated string of "key[=value]" parameters that indicate +things like encoding forms and passwords to unlock the key; see +asymmetric-key(7) for more information. +.PP +.IR data " and " datalen +indicate the address and size of the decrypted data buffer and +.IR enc " and " enclen +indicate the address and size of the encrypted data buffer. The encrypt +function draws data from the decrypted data buffer and places the output into +the encryption buffer. The decrypt function does the reverse, drawing from +the encryption buffer and writing into the data buffer. +.PP +.BR keyctl_pkey_query (2) +can be called to find out how large the buffers need to be. +.PP +Note that not all asymmetric-type keys will support these operations; further, +the operations available may depend on which components of the key material are +available: typically encryption only requires the public key, but decryption +requires the private key as well. Which operations are supported on a +particular key can also be determined using the query function. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_pkey_encrypt "() and " keyctl_pkey_decrypt () +return the amount of data written into the output buffer. On error, the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified has been revoked. +.TP +.B EACCES +The key exists, but is not +.B searchable +by the calling process. +.TP +.B ENOPKG +Some facility needed to complete the requested operation is not available. +This is most probably a requested or required digest or encryption algorithm. +.TP +.B EFAULT +Bad address. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR keyctl (3), +.BR keyctl_pkey_query (3), +.BR keyctl_pkey_sign (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_pkey_query.3 b/man/keyctl_pkey_query.3 index db092ba..dbeb0fd 100644 --- a/man/keyctl_pkey_query.3 +++ b/man/keyctl_pkey_query.3 @@ -7,7 +7,7 @@ .\" as published by the Free Software Foundation; either version .\" 2 of the Licence, or (at your option) any later version. .\" -.TH KEYCTL_PKEY_QUERY 3 "2 Nov 2018" Linux "Linux Key Management Calls" +.TH KEYCTL_PKEY_QUERY 3 "8 Nov 2018" Linux "Linux Key Management Calls" .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SH NAME keyctl_pkey_query \- Query public key parameters @@ -17,28 +17,42 @@ keyctl_pkey_query \- Query public key parameters .B #include .sp .BI "long keyctl_pkey_query(key_serial_t " key ", const char *" info , -.BI "struct keyctl_pkey_query *" result ");" +.BI " struct keyctl_pkey_query *" result ");" .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SH DESCRIPTION .BR keyctl_pkey_query () -queries the public key parameters associated with an asymmetric-type kernel -key. -.PP +queries the public key parameters associated with a kernel +key that supports these operations (typically +.BR asymmetric -type). The caller must have .B search -permission on a key to be able to query its parameters. +permission on the target key to be able to query its parameters. +.PP +When invoking the function, +.I key +indicates the key to be queried, +.I info +points to a comma-separated string of "key[=value]" parameters and +.I result +points to a buffer in which the result will be placed. .PP -If successful, the following struct is filled in: +The parameters that can be used in the +.I info +parameter string are dependent on the type of key. Parameters can specify such +things as encoding types (such as "enc=pkcs1"); see asymmetric-key(7) for more +information. +.PP +If successful, the result is written into the following struct: .PP .in +4n .EX struct keyctl_pkey_query { - unsigned int supported_ops; - unsigned int key_size; - unsigned short max_data_size; - unsigned short max_sig_size; - unsigned short max_enc_size; - unsigned short max_dec_size; + unsigned int supported_ops; + unsigned int key_size; + unsigned short max_data_size; + unsigned short max_sig_size; + unsigned short max_enc_size; + unsigned short max_dec_size; }; .EE .in @@ -66,9 +80,7 @@ The field indicates the number of bits in the key size and the .IR max_data_size ", " max_sig_size ", " max_enc_size " and " max_dec_size fields indicate the maximum sizes in bytes of a blob of data to be signed, a -signature blob, a blob to be encrypted and a blob to be decrypted. - - +signature blob, a blob to be encrypted and a blob to be decrypted respectively. .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .SH RETURN VALUE On success @@ -97,6 +109,10 @@ The key exists, but is not .B searchable by the calling process. .TP +.B ENOPKG +Some facility needed to complete the requested operation is not available. +This is most probably a requested or required digest or encryption algorithm. +.TP .B EFAULT Bad address. .\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -113,7 +129,9 @@ should be specified to the linker. .BR keyctl (1), .BR add_key (2), .BR keyctl (2), -.BR request_key (2), .BR keyctl (3), +.BR keyctl_pkey_encrypt (3), +.BR keyctl_pkey_sign (3), +.BR asymmetric-key (7), .BR keyrings (7), .BR keyutils (7) diff --git a/man/keyctl_pkey_sign.3 b/man/keyctl_pkey_sign.3 new file mode 100644 index 0000000..fa37456 --- /dev/null +++ b/man/keyctl_pkey_sign.3 @@ -0,0 +1,134 @@ +.\" +.\" 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 KEYCTL_PKEY_SIGN 3 "8 Nov 2018" Linux "Linux Public-Key Signatures" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +keyctl_pkey_sign, keyctl_pkey_verify \- Generate and verify signatures +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "long keyctl_pkey_sign(key_serial_t " key ", const char *" info , +.BI " const void *" data ", size_t " data_len , +.BI " void *" sig ", size_t " sig_len ");" +.sp +.BI "long keyctl_pkey_verify(key_serial_t " key ", const char *" info , +.BI " const void *" data ", size_t " data_len , +.BI " const void *" sig ", size_t " sig_len ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR keyctl_pkey_sign () +asks the kernel to use the crypto data attached to a key to generate a +detached signature for a blob of data. Note that this may involve calling out +to cryptographic hardware. +.PP +.BR keyctl_pkey_verify () +asks the kernel to use the key to generate a verify the signature against the +same blob of data. This may also involve calling out to cryptographic +hardware. +.PP +The caller must have +.B search +permission on a key to be able to perform either operation. +.PP +.PP +When invoking the function, +.I key +indicates the key that will provide the cryptographic material and +.I info +points to a comma-separated string of "key[=value]" parameters that indicate +things like encoding forms and passwords to unlock the key; see +asymmetric-key(7) for more information. +.PP +.IR data " and " datalen +indicate the address and size of the buffer of data to be signed and +.IR sig " and " siglen +indicate the address and size of the signature buffer. The sign function +draws data from the data buffer, generates a signature from it and places the +output into the signature buffer. The verify function also draws data from +the data buffer, then decrypts the signature and compares the result. +.PP +Note that the data buffer is strictly limited in capacity, typically unable to +hold more bits than the size of the key. The caller is expected to have +pre-digested the actual data and will thus pass the digest output to this +function. The name of the digest used should be passed as part of the info +string as \fPhash=\fR for use in constructing the signature metadata. +.PP +.BR keyctl_pkey_query (2) +can be called to find out how large the buffers need to be and what the +maximum size of the data can be for a specific signature encoding. +.PP +Note that not all asymmetric-type keys will support these operations; further, +the operations available may depend on which components of the key material are +available: typically encryption only requires the public key, but decryption +requires the private key as well. Which operations are supported on a +particular key can also be determined using the query function. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +On success +.BR keyctl_pkey_sign () +returns the amount of data written into the signature buffer. +.BR keyctl_pkey_verify () +will return 0 in this case as it doesn't write to userspace. +.PP +On error the value +.B -1 +will be returned and +.I errno +will have been set to an appropriate error. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +.TP +.B ENOKEY +The key specified is invalid. +.TP +.B EKEYEXPIRED +The key specified has expired. +.TP +.B EKEYREVOKED +The key specified has been revoked. +.TP +.B EACCES +The key exists, but is not +.B searchable +by the calling process. +.TP +.BR EINVAL ", " EBADMSG ", " EOVERFLOW +Some part of the key material or signature data is bad. +.TP +.BR EKEYREJECTED +Signature verification failed. +.TP +.B ENOPKG +Some facility needed to complete the requested operation is not available. +This is most probably a requested or required digest or encryption algorithm. +.TP +.B EFAULT +Bad address. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +This is a library function that can be found in +.IR libkeyutils . +When linking, +.B \-lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.ad l +.nh +.BR keyctl (1), +.BR add_key (2), +.BR keyctl (2), +.BR keyctl (3), +.BR keyctl_pkey_query (3), +.BR keyctl_pkey_sign (3), +.BR keyrings (7), +.BR keyutils (7) diff --git a/man/keyctl_pkey_verify.3 b/man/keyctl_pkey_verify.3 new file mode 100644 index 0000000..6b2927a --- /dev/null +++ b/man/keyctl_pkey_verify.3 @@ -0,0 +1 @@ +.so keyctl_pkey_verify.3