include/crypto/ecdh.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /*
0003  * ECDH params to be used with kpp API
0004  *
0005  * Copyright (c) 2016, Intel Corporation
0006  * Authors: Salvatore Benedetto <salvatore.benedetto@intel.com>
0007  */
0008 #ifndef _CRYPTO_ECDH_
0009 #define _CRYPTO_ECDH_
0010
0011 /**
0012  * DOC: ECDH Helper Functions
0013  *
0014  * To use ECDH with the KPP cipher API, the following data structure and
0015  * functions should be used.
0016  *
0017  * The ECC curves known to the ECDH implementation are specified in this
0018  * header file.
0019  *
0020  * To use ECDH with KPP, the following functions should be used to operate on
0021  * an ECDH private key. The packet private key that can be set with
0022  * the KPP API function call of crypto_kpp_set_secret.
0023  */
0024
0025 /* Curves IDs */
0026 #define ECC_CURVE_NIST_P192 0x0001
0027 #define ECC_CURVE_NIST_P256 0x0002
0028 #define ECC_CURVE_NIST_P384 0x0003
0029
0030 /**
0031  * struct ecdh - define an ECDH private key
0032  *
0033  * @key:    Private ECDH key
0034  * @key_size:   Size of the private ECDH key
0035  */
0036 struct ecdh {
0037     char *key;
0038     unsigned short key_size;
0039 };
0040
0041 /**
0042  * crypto_ecdh_key_len() - Obtain the size of the private ECDH key
0043  * @params: private ECDH key
0044  *
0045  * This function returns the packet ECDH key size. A caller can use that
0046  * with the provided ECDH 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_ecdh_key_len(const struct ecdh *params);
0052
0053 /**
0054  * crypto_ecdh_encode_key() - encode the private key
0055  * @buf:    Buffer allocated by the caller to hold the packet ECDH
0056  *      private key. The buffer should be at least crypto_ecdh_key_len
0057  *      bytes in size.
0058  * @len:    Length of the packet private key buffer
0059  * @p:      Buffer with the caller-specified private key
0060  *
0061  * The ECDH 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_ecdh_encode_key(char *buf, unsigned int len, const struct ecdh *p);
0067
0068 /**
0069  * crypto_ecdh_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  * @p:      Buffer allocated by the caller that is filled with the
0073  *      unpacked ECDH 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_ecdh_decode_key(const char *buf, unsigned int len, struct ecdh *p);
0081
0082 #endif