keyctl_pkey_sign, keyctl_pkey_verify - Generate and verify signatures
#include <keyutils.h>
long keyctl_pkey_sign(key_serial_t key, const char *info,
const void *data, size_t data_len,
void *sig, size_t sig_len);
long keyctl_pkey_verify(key_serial_t key, const char *info,
const void *data, size_t data_len,
const void *sig, size_t sig_len);
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.
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.
The caller must have
search permission on a key to be able to perform
either operation.
When invoking the function,
key indicates the key that will provide the
cryptographic material and
info points to a space- or tab-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.
data and
datalen indicate the address and size of the buffer of
data to be signed and
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.
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 hash=<name> for use in constructing the signature metadata.
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.
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.
On success
keyctl_pkey_sign() returns the amount of data written into the
signature buffer.
keyctl_pkey_verify() will return 0 in this case as it
doesn't write to userspace.
On error the value
-1 will be returned and
errno will have been
set to an appropriate error.
- ENOKEY
- The key specified is invalid.
- EKEYEXPIRED
- The key specified has expired.
- EKEYREVOKED
- The key specified has been revoked.
- EACCES
- The key exists, but is not searchable by the calling
process.
-
EINVAL, EBADMSG, EOVERFLOW
- Some part of the key material or signature data is
bad.
- EKEYREJECTED
- Signature verification failed.
- ENOPKG
- Some facility needed to complete the requested operation is
not available. This is most probably a requested or required digest or
encryption algorithm.
- EFAULT
- Bad address.
This is a library function that can be found in
libkeyutils. When
linking,
-lkeyutils should be specified to the linker.
keyctl(1),
add_key(2),
keyctl(2),
keyctl(3),
keyctl_pkey_query(3),
keyrings(7),
keyutils(7)