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)