1KEYCTL_DH_COMPUTE(3)      Linux Key Management Calls      KEYCTL_DH_COMPUTE(3)
2
3
4

NAME

6       keyctl_dh_compute  -  Compute  a Diffie-Hellman shared secret or public
7       key
8       keyctl_dh_compute_kdf - Derive key from a Diffie-Hellman shared secret
9

SYNOPSIS

11       #include <keyutils.h>
12
13       long keyctl_dh_compute(key_serial_t private, key_serial_t prime,
14       key_serial_t base, char *buffer, size_t buflen);
15
16       long keyctl_dh_compute_alloc(key_serial_t private,
17       key_serial_t prime, key_serial_t base, void **_buffer);
18
19       long keyctl_dh_compute_kdf(key_serial_t private, key_serial_t prime,
20       key_serial_t base, char *hashname, char *otherinfo,
21       size_t otherinfolen, char *buffer, size_t buflen);
22

DESCRIPTION

24       keyctl_dh_compute() computes a  Diffie-Hellman  public  key  or  shared
25       secret.  That computation is:
26
27              base ^ private ( mod prime )
28
29       When  base  is  a key containing the shared generator value, the remote
30       public key is computed.  When base is a key containing the remote  pub‐
31       lic key, the shared secret is computed.
32
33       base,  private,  and  prime must all refer to user-type keys containing
34       the parameters for the computation.  Each of these keys must grant  the
35       caller read permission in order for them to be used.
36
37       buffer  and  buflen  specify  the buffer into which the computed result
38       will be placed.  buflen may be zero, in which case the  buffer  is  not
39       used and the minimum buffer length is fetched.
40
41       keyctl_dh_compute_alloc() is similar to keyctl_dh_compute() except that
42       it allocates a buffer big enough to hold the payload  data  and  places
43       the  data  in  it.  If successful, a pointer to the buffer is placed in
44       *_buffer.  The caller must free the buffer.
45
46       keyctl_dh_compute_kdf() derives a  key  from  a  Diffie-Hellman  shared
47       secret  according  to  the protocol specified in SP800-56A. The Diffie-
48       Hellman computation is based on the same primitives  as  discussed  for
49       keyctl_dh_compute().
50
51       To  implement  the  protocol  of SP800-56A base is a key containing the
52       remote public key to compute the  Diffie-Hellman  shared  secret.  That
53       shared secret is post-processed with a key derivation function.
54
55       The hashname specifies the Linux kernel crypto API name for a hash that
56       shall be used for the key derivation function,  such  as  sha256.   The
57       hashname must be a NULL terminated string.  See /proc/crypto for avail‐
58       able hashes on the system.
59
60       Following the specification of SP800-56A section 5.8.1.2 the  otherinfo
61       parameter may be provided. The format of the OtherInfo field is defined
62       by the caller. The caller may also specify NULL  as  a  valid  argument
63       when  no OtherInfo data shall be processed. The length of the otherinfo
64       parameter is specified with otherinfolen and is restricted to a maximum
65       length by the kernel.
66
67       The KDF returns the requested number of bytes specified with the genlen
68       or the buflen parameter depending on the invoked function.
69
70       buffer and buflen specify the buffer into  which  the  computed  result
71       will be placed.
72

RETURN VALUE

74       On  success  keyctl_dh_compute() returns the amount of data placed into
75       the buffer when buflen is non-zero.  When buflen is zero,  the  minimum
76       buffer length to hold the data is returned.
77
78       On  success keyctl_dh_compute_alloc() returns the amount of data in the
79       buffer.
80
81       On error, both functions set errno to an appropriate  code  and  return
82       the value -1.
83

ERRORS

85       ENOKEY One of the keys specified is invalid or not readable.
86
87       EINVAL The buffer pointer is invalid or buflen is too small.
88
89       EOPNOTSUPP
90              One of the keys was not a valid user key.
91
92       EMSGSIZE
93              When  using keyctl_dh_compute_kdf(), the size of either otherin‐
94              folen or buflen is too big.
95

LINKING

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

SEE ALSO

101       keyctl(1),
102       keyctl(2),
103       keyctl(3),
104       keyutils(7)
105
106
107
108Linux                             07 Apr 2016             KEYCTL_DH_COMPUTE(3)