[KEYUTILS PATCH] Add manpages for asymmetric key type and ops

[David Howells <dhowells@redhat.com>]

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 <dhowells@redhat.com>
---
 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=<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)
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 <private> <prime> <base> <output_length> <hash_type>
 .br
 \fBkeyctl\fR dh_compute_kdf_oi <private> <prime> <base> <output_length> <hash_type>
+.br
+\fBkeyctl\fR pkey_query <key> <pass> [k=v]*
+.br
+\fBkeyctl\fR pkey_encrypt <key> <pass> <datafile> [k=v]* ><encfile>
+.br
+\fBkeyctl\fR pkey_decrypt <key> <pass> <encfile> [k=v]* ><datafile>
+.br
+\fBkeyctl\fR pkey_sign <key> <pass> <datafile> [k=v]* ><sigfile>
+.br
+\fBkeyctl\fR pkey_decrypt <key> <pass> <datafile> <sigfile> [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 <key> <pass> [k=v]*
+.br
+\fBkeyctl\fR pkey_encrypt <key> <pass> <datafile> [k=v]* > <encfile>
+.br
+\fBkeyctl\fR pkey_decrypt <key> <pass> <encfile> [k=v]* > <datafile>
+.br
+\fBkeyctl\fR pkey_sign <key> <pass> <datafile> [k=v]* > <sigfile>
+.br
+\fBkeyctl\fR pkey_verify <key> <pass> <datafile> <sigfile> [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=<name>".
+.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=<name>") or the encoding form ("enc=<type>").
+.PP
+.RS
+.nf
+k=`keyctl padd asymmetric "" @s <key.pkcs8.der`
+keyctl pkey_query $k 0 enc=pkcs1 hash=sha256
+keyctl pkey_encrypt $k 0 foo.hash enc=pkcs1 >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 <keyutils.h>
+.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 <keyutils.h>
 .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 <keyutils.h>
+.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=<name>\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