# keyctl_dh_compute

## NAME



           keyctl_dh_compute - Compute a Diffie-Hellman shared secret or
           public key
           keyctl_dh_compute_kdf - Derive key from a Diffie-Hellman shared
           secret
    


## SYNOPSIS



           **#include <keyutils.h>**
    
           **long keyctl_dh_compute(key_serial_t** _private_**, key_serial_t** _prime_**,**
           **key_serial_t** _base_**, char ***_buffer_**, size_t** _buflen_**);**
    
           **long keyctl_dh_compute_alloc(key_serial_t** _private,_
           **key_serial_t** _prime_**, key_serial_t** _base_**, void ****__buffer_**);**
    
           **long keyctl_dh_compute_kdf(key_serial_t** _private_**, key_serial_t** _prime_**,**
           **key_serial_t** _base_**, char ***_hashname_**, char ***_otherinfo_**,**
           **size_t** _otherinfolen_**, char ***_buffer_**, size_t** _buflen_**);**
    


## DESCRIPTION



           **keyctl_dh_compute**() computes a Diffie-Hellman public key or shared
           secret.  That computation is:
    
                  _base_ ^ _private_ ( mod _prime_ )
    
           When _base_ is a key containing the shared generator value, the
           remote public key is computed.  When _base_ is a key containing the
           remote public key, the shared secret is computed.
    
           _base_ , _private_ , and _prime_ must all refer to **user** -type keys
           containing the parameters for the computation.  Each of these keys
           must grant the caller **read** permission in order for them to be
           used.
    
           _buffer_ and _buflen_ specify the buffer into which the computed
           result will be placed.  _buflen_ may be zero, in which case the
           buffer is not used and the minimum buffer length is fetched.
    
           **keyctl_dh_compute_alloc**() is similar to **keyctl_dh_compute**() except
           that it allocates a buffer big enough to hold the payload data and
           places the data in it.  If successful, a pointer to the buffer is
           placed in _*_buffer_.  The caller must free the buffer.
    
           **keyctl_dh_compute_kdf**() derives a key from a Diffie-Hellman shared
           secret according to the protocol specified in SP800-56A. The
           Diffie-Hellman computation is based on the same primitives as
           discussed for **keyctl_dh_compute**().
    
           To implement the protocol of SP800-56A _base_ is a key containing
           the remote public key to compute the Diffie-Hellman shared secret.
           That shared secret is post-processed with a key derivation
           function.
    
           The _hashname_ specifies the Linux kernel crypto API name for a hash
           that shall be used for the key derivation function, such as
           sha256.  The _hashname_ must be a NULL terminated string.  See
           _/proc/crypto_ for available hashes on the system.
    
           Following the specification of SP800-56A section 5.8.1.2 the
           _otherinfo_ parameter may be provided. The format of the OtherInfo
           field is defined by the caller. The caller may also specify NULL
           as a valid argument when no OtherInfo data shall be processed. The
           length of the _otherinfo_ parameter is specified with _otherinfolen_
           and is restricted to a maximum length by the kernel.
    
           The KDF returns the requested number of bytes specified with the
           _genlen_ or the _buflen_ parameter depending on the invoked function.
    
           _buffer_ and _buflen_ specify the buffer into which the computed
           result will be placed.
    


## RETURN VALUE



           On success **keyctl_dh_compute**() returns the amount of data placed
           into the buffer when _buflen_ is non-zero.  When _buflen_ is zero, the
           minimum buffer length to hold the data is returned.
    
           On success **keyctl_dh_compute_alloc**() returns the amount of data in
           the buffer.
    
           On error, both functions set errno to an appropriate code and
           return the value **-1**.
    


## ERRORS



           **ENOKEY** One of the keys specified is invalid or not readable.
    
           **EINVAL** The buffer pointer is invalid or buflen is too small.
    
           **EOPNOTSUPP**
                  One of the keys was not a valid user key.
    
           **EMSGSIZE**
                  When using **keyctl_dh_compute_kdf**(), the size of either
                  _otherinfolen_ or _buflen_ is too big.
    


## LINKING



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


* * *