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 87