include/crypto/dh.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /*
   3  * Diffie-Hellman secret to be used with kpp API along with helper functions
   4  *
   5  * Copyright (c) 2016, Intel Corporation
   6  * Authors: Salvatore Benedetto <salvatore.benedetto@intel.com>
   7  */
   8 #ifndef _CRYPTO_DH_
   9 #define _CRYPTO_DH_
  10
  11 /**
  12  * DOC: DH Helper Functions
  13  *
  14  * To use DH with the KPP cipher API, the following data structure and
  15  * functions should be used.
  16  *
  17  * To use DH with KPP, the following functions should be used to operate on
  18  * a DH private key. The packet private key that can be set with
  19  * the KPP API function call of crypto_kpp_set_secret.
  20  */
  21
  22 /**
  23  * struct dh - define a DH private key
  24  *
  25  * @key:        Private DH key
  26  * @p:          Diffie-Hellman parameter P
  27  * @q:          Diffie-Hellman parameter Q
  28  * @g:          Diffie-Hellman generator G
  29  * @key_size:   Size of the private DH key
  30  * @p_size:     Size of DH parameter P
  31  * @q_size:     Size of DH parameter Q
  32  * @g_size:     Size of DH generator G
  33  */
  34 struct dh {
  35         void *key;
  36         void *p;
  37         void *q;
  38         void *g;
  39         unsigned int key_size;
  40         unsigned int p_size;
  41         unsigned int q_size;
  42         unsigned int g_size;
  43 };
  44
  45 /**
  46  * crypto_dh_key_len() - Obtain the size of the private DH key
  47  * @params:     private DH key
  48  *
  49  * This function returns the packet DH key size. A caller can use that
  50  * with the provided DH private key reference to obtain the required
  51  * memory size to hold a packet key.
  52  *
  53  * Return: size of the key in bytes
  54  */
  55 unsigned int crypto_dh_key_len(const struct dh *params);
  56
  57 /**
  58  * crypto_dh_encode_key() - encode the private key
  59  * @buf:        Buffer allocated by the caller to hold the packet DH
  60  *              private key. The buffer should be at least crypto_dh_key_len
  61  *              bytes in size.
  62  * @len:        Length of the packet private key buffer
  63  * @params:     Buffer with the caller-specified private key
  64  *
  65  * The DH implementations operate on a packet representation of the private
  66  * key.
  67  *
  68  * Return:      -EINVAL if buffer has insufficient size, 0 on success
  69  */
  70 int crypto_dh_encode_key(char *buf, unsigned int len, const struct dh *params);
  71
  72 /**
  73  * crypto_dh_decode_key() - decode a private key
  74  * @buf:        Buffer holding a packet key that should be decoded
  75  * @len:        Length of the packet private key buffer
  76  * @params:     Buffer allocated by the caller that is filled with the
  77  *              unpacked DH private key.
  78  *
  79  * The unpacking obtains the private key by pointing @p to the correct location
  80  * in @buf. Thus, both pointers refer to the same memory.
  81  *
  82  * Return:      -EINVAL if buffer has insufficient size, 0 on success
  83  */
  84 int crypto_dh_decode_key(const char *buf, unsigned int len, struct dh *params);
  85
  86 #endif