|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | LINKING | SEE ALSO | COLOPHON |
|
|
|
KEYCTL_PKEY_SIGN(3) Linux Public-Key Signatures KEYCTL_PKEY_SIGN(3)
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)
This page is part of the keyutils (key management utilities)
project. Information about the project can be found at [unknown
-- if you know, please contact [email protected]] If you have a
bug report for this manual page, send it to
[email protected]. This page was obtained from the project's
upstream Git repository
⟨http://git.kernel.org/pub/scm/linux/kernel/git/dhowells/keyutils.git⟩
on 2025-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2023-03-20.) If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page,
or you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a
mail to [email protected]
Linux 8 Nov 2018 KEYCTL_PKEY_SIGN(3)
Pages that refer to this page: keyctl(3), keyctl_pkey_encrypt(3), keyctl_pkey_query(3), asymmetric-key(7)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|