NAME

       keyctl_pkey_sign, keyctl_pkey_verify - Generate and verify signatures

SYNOPSIS

       #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

       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

       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

       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

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

SEE ALSO

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

Linux                                              8 Nov 2018                                KEYCTL_PKEY_SIGN(3)