plucky (3) keyctl_pkey_verify.3.gz

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)