include/crypto/dh.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /*
0003  * Diffie-Hellman secret to be used with kpp API along with helper functions
0004  *
0005  * Copyright (c) 2016, Intel Corporation
0006  * Authors: Salvatore Benedetto <salvatore.benedetto@intel.com>
0007  */
0008 #ifndef _CRYPTO_DH_
0009 #define _CRYPTO_DH_
0010
0011 /**
0012  * DOC: DH Helper Functions
0013  *
0014  * To use DH with the KPP cipher API, the following data structure and
0015  * functions should be used.
0016  *
0017  * To use DH with KPP, the following functions should be used to operate on
0018  * a DH private key. The packet private key that can be set with
0019  * the KPP API function call of crypto_kpp_set_secret.
0020  */
0021
0022 /**
0023  * struct dh - define a DH private key
0024  *
0025  * @key:    Private DH key
0026  * @p:      Diffie-Hellman parameter P
0027  * @g:      Diffie-Hellman generator G
0028  * @key_size:   Size of the private DH key
0029  * @p_size: Size of DH parameter P
0030  * @g_size: Size of DH generator G
0031  */
0032 struct dh {
0033     const void *key;
0034     const void *p;
0035     const void *g;
0036     unsigned int key_size;
0037     unsigned int p_size;
0038     unsigned int g_size;
0039 };
0040
0041 /**
0042  * crypto_dh_key_len() - Obtain the size of the private DH key
0043  * @params: private DH key
0044  *
0045  * This function returns the packet DH key size. A caller can use that
0046  * with the provided DH private key reference to obtain the required
0047  * memory size to hold a packet key.
0048  *
0049  * Return: size of the key in bytes
0050  */
0051 unsigned int crypto_dh_key_len(const struct dh *params);
0052
0053 /**
0054  * crypto_dh_encode_key() - encode the private key
0055  * @buf:    Buffer allocated by the caller to hold the packet DH
0056  *      private key. The buffer should be at least crypto_dh_key_len
0057  *      bytes in size.
0058  * @len:    Length of the packet private key buffer
0059  * @params: Buffer with the caller-specified private key
0060  *
0061  * The DH implementations operate on a packet representation of the private
0062  * key.
0063  *
0064  * Return:  -EINVAL if buffer has insufficient size, 0 on success
0065  */
0066 int crypto_dh_encode_key(char *buf, unsigned int len, const struct dh *params);
0067
0068 /**
0069  * crypto_dh_decode_key() - decode a private key
0070  * @buf:    Buffer holding a packet key that should be decoded
0071  * @len:    Length of the packet private key buffer
0072  * @params: Buffer allocated by the caller that is filled with the
0073  *      unpacked DH private key.
0074  *
0075  * The unpacking obtains the private key by pointing @p to the correct location
0076  * in @buf. Thus, both pointers refer to the same memory.
0077  *
0078  * Return:  -EINVAL if buffer has insufficient size, 0 on success
0079  */
0080 int crypto_dh_decode_key(const char *buf, unsigned int len, struct dh *params);
0081
0082 /**
0083  * __crypto_dh_decode_key() - decode a private key without parameter checks
0084  * @buf:    Buffer holding a packet key that should be decoded
0085  * @len:    Length of the packet private key buffer
0086  * @params: Buffer allocated by the caller that is filled with the
0087  *      unpacked DH private key.
0088  *
0089  * Internal function providing the same services as the exported
0090  * crypto_dh_decode_key(), but without any of those basic parameter
0091  * checks conducted by the latter.
0092  *
0093  * Return:  -EINVAL if buffer has insufficient size, 0 on success
0094  */
0095 int __crypto_dh_decode_key(const char *buf, unsigned int len,
0096                struct dh *params);
0097
0098 #endif