# keyctl_pkey_sign

## 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.
    


* * *