keyctl_pkey_sign(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | LINKING | SEE ALSO | COLOPHON

KEYCTL_PKEY_SIGN(3)      Linux Public-Key Signatures     KEYCTL_PKEY_SIGN(3)

NAME         top

       keyctl_pkey_sign, keyctl_pkey_verify - Generate and verify signatures

SYNOPSIS         top

       #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);

DESCRIPTION         top

       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.

RETURN VALUE         top

       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.

ERRORS         top

       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.

LINKING         top

       This is a library function that can be found in libkeyutils.  When
       linking, -lkeyutils should be specified to the linker.

SEE ALSO         top

       keyctl(1), add_key(2), keyctl(2), keyctl(3), keyctl_pkey_query(3),
       keyrings(7), keyutils(7)

COLOPHON         top

       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 man-pages@man7.org] If you have a bug report for
       this manual page, send it to keyrings@linux-nfs.org.  This page was
       obtained from the project's upstream Git repository
       ⟨http://git.kernel.org/pub/scm/linux/kernel/git/dhowells/keyutils.git⟩
       on 2020-08-13.  (At that time, the date of the most recent commit
       that was found in the repository was 2020-07-07.)  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 man-pages@man7.org

Linux                            8 Nov 2018              KEYCTL_PKEY_SIGN(3)

Pages that refer to this page: keyctl(3)keyctl_pkey_decrypt(3)keyctl_pkey_encrypt(3)keyctl_pkey_query(3)asymmetric(7)asymmetric-key(7)