include/crypto/ecdh.h

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