ECDH.h

Go to the documentation of this file.

/*
 * Copyright (c) 2017-2025, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 * @file ECDH.h
 *
 * @brief TI Driver for Elliptic Curve Diffie-Hellman key agreement scheme.
 *
 * @anchor ti_drivers_ECDH_Overview
 * # Overview #
 *
 * Elliptic Curve Diffie-Hellman (ECDH) is a key agreement scheme between
 * two parties based on the Diffie-Hellman key exchange protocol.
 *
 * It provides a means of generating a shared secret and derived symmetric key
 * between the two parties over an insecure channel.
 *
 * It does not provide authentication. As such, it does not guarantee that the
 * party you are exchanging keys with is truly the party you wish to establish a
 * secured channel with.
 *
 * The two parties each generate a private key and a public key. The private key
 * is a random integer in the interval [1, n - 1], where n is the order of a
 * previously agreed upon curve. The public key is generated
 * by multiplying the private key by the generator point of a previously agreed
 * upon elliptic curve such as NISTP256 or Curve 25519. The public key is itself
 * a point upon the elliptic curve. Each public key is then transmitted to the
 * other party over a potentially insecure channel. The other party's public key
 * is then multiplied with the private key, generating a shared secret. This
 * shared secret is also a point on the curve. However, the entropy in the secret
 * is not spread evenly throughout the shared secret. In order to generate one or more
 * shared symmetric keys, the shared secret must be run through a key derivation
 * function (KDF) that was previously agreed upon. Usually, only the X coordinate
 * is processed in this way as it contains all the entropy of the shared secret and
 * some curve implementations only provide the X coordinate. The key derivation function
 * can take many forms, from simply hashing the X coordinate of the shared secret
 * with SHA2 and truncating the result to generating multiple symmetric keys with
 * HKDF, an HMAC based KDF.
 *
 * Key derivation functions in the context of symmetric key generation after
 * elliptic curve based key exchange differ from KDFs used to generate keys from
 * passwords a user provides in a login. Those KDFs such as bcrypt purposefully
 * add additional computation to increase a system's resistance against brute
 * force or dictionary attacks.
 *
 * @anchor ti_drivers_ECDH_Usage
 * # Usage #
 *
 * ## Before starting an ECDH operation #
 *
 * Before starting an ECDH operation, the application must do the following:
 *      - Call ECDH_init() to initialize the driver
 *      - Call ECDH_Params_init() to initialize the ECDH_Params to default values.
 *      - Modify the ECDH_Params as desired
 *      - Call ECDH_open() to open an instance of the driver
 *
 * ## Generating your public-private key pair #
 * To generate a public-private key pair for an agreed upon curve, the application
 * must do the following:
 *      - Generate the keying material for the private key. This keying material must
 *        be an integer in the interval [1, n - 1], where n is the order of the curve.
 *        It can be stored in big-endian or little-endian format.
 *        The array should be the same length as the curve parameters of the curve used.
 *        The driver validates private keys against the provided curve by default.
 *      - Initialize the private key CryptoKey. CryptoKeys are opaque data structures and representations
 *        of keying material and its storage. Depending on how the keying material
 *        is stored (RAM or flash, key store), the CryptoKey must be
 *        initialized differently. The ECDH API can handle all types of CryptoKey.
 *        However, not all device-specific implementations support all types of CryptoKey.
 *        Devices without a key store will not support CryptoKeys with keying material
 *        stored in a key store for example.
 *        All devices support plaintext CryptoKeys.
 *      - Initialize a blank CryptoKey for the public key. The CryptoKey will keep track
 *        of where the keying material for the public key should be copied and how
 *        long it is. SEC 1-based big-endian format public keys should have key material twice the length
 *        of the private key plus one. Little-endian format public keys should have key material the
 *        length of the private key for Montgomery curve X-only public keys or have key material twice
 *        the length of the private for other curves
 *      - Initialize the ECDH_OperationGeneratePublicKey struct and then populate it. By
 *        default, big-endian public keys will be generated.
 *      - If using RFC 7748-style public keys, initialize the operation's public key
 *        data format to be ECDH_LITTLE_ENDIAN_KEY.
 *      - Call ECDH_generatePublicKey(). The generated keying material will be copied
 *        according the the CryptoKey passed in as the public key parameter. The CryptoKey
 *        will no longer be considered 'blank' after the operation.
 *
 * ## Calculating a shared secret #
 * After trading public keys with the other party, the application should do the following
 * to calculate the shared secret:
 *      - Initialize a CryptoKey as public key with the keying material received from the other
 *        party.
 *      - Initialize the private key CryptoKey with the key used to generate your
 *        public key. CryptoKeys are opaque data structures and representations
 *        of keying material and its storage. Depending on how the keying material
 *        is stored (RAM or flash, key store), the CryptoKey must be
 *        initialized differently. The ECDH API can handle all types of CryptoKey.
 *        However, not all device-specific implementations support all types of CryptoKey.
 *        Devices without a key store will not support CryptoKeys with keying material
 *        stored in a key store for example.
 *        All devices support plaintext CryptoKeys.
 *      - Initialize a blank CryptoKey with the same size as the previously initialized
 *        public key.
 *      - Initialize the ECDH_OperationComputeSharedSecret struct and then populate it. By
 *        default, big-endian input keys will be assumed and big-endian shared secrets
 *        will be generated.
 *      - If importing RFC 7748-style public keys, initialize the operation's key material
 *        endianess to be ECDH_LITTLE_ENDIAN_KEY.
 *      - Call ECDH_computeSharedSecret(). The shared secret will be copied to a location
 *        according to the shared secret CryptoKey passed to the function call. The driver
 *        will validate the supplied public key and reject invalid ones.
 *
 * ## Creating one or more symmetric keys from the shared secret #
 * After calculating the shared secret between the application and the other party,
 * the entropy in the shared secret must be evened out and stretched as needed. There are
 * uncountable methods and algorithms to stretch an original seed entropy (the share secret)
 * to generate symmetric keys.
 *      - Run the X coordinate of the resulting entropy through a key derivation function (KDF)
 *
 * ## After a key exchange #
 * After the ECDH key exchange completes, the application should either start another operation
 * or close the driver by calling ECDH_close()
 *
 * ## General usage #
 * The API expects elliptic curves as defined in ti/drivers/cryptoutils/ecc/ECCParams.h.
 * Several commonly used curves are provided. Check the device-specific ECDH documentation
 * for curve type (short Weierstrass, Montgomery, Edwards) support for your device.
 * ECDH support for a curve type on a device does not imply curve-type support for
 * other ECC schemes.
 *
 * ## Key Formatting
 * By default, the ECDH API expects the private and public keys to be formatted in
 * big-endian format. The details of octet string formatting can be found in
 * SEC 1: Elliptic Curve Cryptography.
 *
 * ## Limitations #
 * For CC27XX devices, the ECDH driver cannot accept private keys with a
 * value of 0x01 (entire value is 0x01).
 *
 * Private keys can be formatted as big-endian or little-endian integers of the same
 * length as the curve length.
 *
 * Public keys and shared secrets are points on an elliptic curve. These points can
 * be expressed in several ways. The most common one is in affine coordinates as an
 * X,Y pair.
 * This API uses points expressed in uncompressed affine coordinates by default.
 * The big-endian format requires a formatting byte in the first byte of the
 * public key. When using uncompressed affine coordinates, this is the value
 * 0x04.
 * The point itself is stored as a concatenated array of X followed by Y.
 * X and Y maybe in big-endian or little-endian. Some implementations do not require or
 * yield the Y coordinate for ECDH on certain curves. It is recommended that the full
 * keying material buffer of twice the curve param length is used to facilitate
 * code-reuse. Implementations that do not use the Y coordinate will zero-out
 * the Y-coordinate whenever they write a point to the CryptoKey.
 *
 * If device-supported, Montgomery curves can be stored as their X-only format
 * based on the RFC-7748 specification. Here, only the X coordinate is packed
 * in little-endian integers of the same length as the curve length.
 *
 * This API accepts and returns the keying material of public keys according
 * to the following table:
 *
 * | Curve Type         | Keying Material Array | Array Length               |
 * |--------------------|-----------------------|----------------------------|
 * | Short Weierstrass  | [0x04, X, Y]          | 1 + 2 * Curve Param Length |
 * | Montgomery         | [0x04, X, Y]          | 1 + 2 * Curve Param Length |
 * | Montgomery         | [X]                   | Curve Param Length         |
 * | Edwards            | [0x04, X, Y]          | 1 + 2 * Curve Param Length |
 *
 * Note: This driver will automatically prune the private key according to
 *       RFC 7748 for the following curve:
 *           X25519
 *
 * @anchor ti_drivers_ECDH_Synopsis
 * ## Synopsis
 * @anchor ti_drivers_ECDH_Synopsis_Code
 * @code
 * // Import ECDH Driver definitions
 * #include <ti/drivers/ECDH.h>
 *
 * ECDH_init();
 *
 * // Since we are using default ECDH_Params, we just pass in NULL for that parameter.
 * ecdhHandle = ECDH_open(0, NULL);
 *
 * // Initialize myPrivateKey and myPublicKey
 * CryptoKeyPlaintext_initKey(&myPrivateKey, myPrivateKeyingMaterial, sizeof(myPrivateKeyingMaterial));
 * CryptoKeyPlaintext_initBlankKey(&myPublicKey, myPublicKeyingMaterial, sizeof(myPublicKeyingMaterial));
 *
 * ECDH_OperationGeneratePublicKey_init(&operationGeneratePublicKey);
 * operationGeneratePublicKey.curve                 = &ECCParams_NISTP256;
 * operationGeneratePublicKey.myPrivateKey          = &myPrivateKey;
 * operationGeneratePublicKey.myPublicKey           = &myPublicKey;
 *
 * // Generate the keying material for myPublicKey and store it in myPublicKeyingMaterial
 * operationResult = ECDH_generatePublicKey(ecdhHandle, &operationGeneratePublicKey);
 *
 * // Now send the content of myPublicKeyingMaterial to the other party,
 * // receive their public key, and copy their public keying material to theirPublicKeyingMaterial
 *
 * // Initialize their public CryptoKey and the shared secret CryptoKey
 * CryptoKeyPlaintext_initKey(&theirPublicKey, theirPublicKeyingMaterial, sizeof(theirPublicKeyingMaterial));
 * CryptoKeyPlaintext_initBlankKey(&sharedSecret, sharedSecretKeyingMaterial, sizeof(sharedSecretKeyingMaterial));
 *
 * // The ECC_NISTP256 struct is provided in ti/drivers/types/EccParams.h and the corresponding device-specific
 * implementation ECDH_OperationComputeSharedSecret_init(&operationComputeSharedSecret);
 * operationComputeSharedSecret.curve                      = &ECCParams_NISTP256;
 * operationComputeSharedSecret.myPrivateKey               = &myPrivateKey;
 * operationComputeSharedSecret.theirPublicKey             = &theirPublicKey;
 * operationComputeSharedSecret.sharedSecret               = &sharedSecret;
 *
 * // Compute the shared secret and copy it to sharedSecretKeyingMaterial
 * operationResult = ECDH_computeSharedSecret(ecdhHandle, &operationComputeSharedSecret);
 *
 * // Close the driver
 * ECDH_close(ecdhHandle);
 *
 * @endcode
 *
 * ## Synopsis for X25519 X-only key exchange
 * @anchor ti_drivers_ECDH_X25519_Code
 * @code
 * // Import ECDH Driver definitions
 * #include <ti/drivers/ECDH.h>
 *
 * ECDH_init();
 *
 * // Since we are using default ECDH_Params, we just pass in NULL for that parameter.
 * ecdhHandle = ECDH_open(0, NULL);
 *
 * // For CC27XX devices only,
 * // Since the ECDH driver for CC27XX relies on one HW engine (the HSM) for all of its operations
 * // If the HSM boot up sequence fails, ECDH_open() will return NULL.
 * if (!ecdhHandle) {
 *     // Handle error
 * }
 *
 *
 * // Initialize myPrivateKey and myPublicKey
 * CryptoKeyPlaintext_initKey(&myPrivateKey, myPrivateKeyingMaterial, sizeof(myPrivateKeyingMaterial));
 * // Note that the public key size is only 32 bytes
 * CryptoKeyPlaintext_initBlankKey(&myPublicKey, myPublicKeyingMaterial, sizeof(myPublicKeyingMaterial));
 *
 * ECDH_OperationGeneratePublicKey_init(&operationGeneratePublicKey);
 * operationGeneratePublicKey.curve                 = &ECCParams_Curve25519;
 * operationGeneratePublicKey.myPrivateKey          = &myPrivateKey;
 * operationGeneratePublicKey.myPublicKey           = &myPublicKey;
 * // If generating public key in little-endian format, we use the following format:
 * operationGeneratePublicKey.keyMaterialEndianness = ECDH_LITTLE_ENDIAN_KEY;
 *
 * // Generate the keying material for myPublicKey and store it in myPublicKeyingMaterial
 * operationResult = ECDH_generatePublicKey(ecdhHandle, &operationGeneratePublicKey);
 *
 * // Now send the content of myPublicKeyingMaterial to the other party,
 * // receive their public key, and copy their public keying material to theirPublicKeyingMaterial
 *
 * // Initialize their public CryptoKey and the shared secret CryptoKey
 * CryptoKeyPlaintext_initKey(&theirPublicKey, theirPublicKeyingMaterial, sizeof(theirPublicKeyingMaterial));
 * CryptoKeyPlaintext_initBlankKey(&sharedSecret, sharedSecretKeyingMaterial, sizeof(sharedSecretKeyingMaterial));
 *
 * // The ECC_NISTP256 struct is provided in ti/drivers/types/EccParams.h and the corresponding device-specific
 * implementation ECDH_OperationComputeSharedSecret_init(&operationComputeSharedSecret);
 * operationComputeSharedSecret.curve                      = &ECCParams_Curve25519;
 * operationComputeSharedSecret.myPrivateKey               = &myPrivateKey;
 * operationComputeSharedSecret.theirPublicKey             = &theirPublicKey;
 * operationComputeSharedSecret.sharedSecret               = &sharedSecret;
 * // If receiving and generating keys in little-endian format, we use the following format:
 * operationComputeSharedSecret.keyMaterialEndianness      = ECDH_LITTLE_ENDIAN_KEY;
 *
 * // Compute the shared secret and copy it to sharedSecretKeyingMaterial
 * operationResult = ECDH_computeSharedSecret(ecdhHandle, &operationComputeSharedSecret);
 *
 * // Close the driver
 * ECDH_close(ecdhHandle);
 *
 * @endcode
 *
 * @anchor ti_drivers_ECDH_Examples
 * # Examples #
 *
 * ## ECDH exchange with plaintext CryptoKeys #
 *
 * @code
 *
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 * #include <ti/drivers/ECDH.h>
 *
 * #define CURVE_LENGTH 32
 *
 * ...
 *
 * // Our private key is 0x0000000000000000000000000000000000000000000000000000000000000001
 * // In practice, this value should come from a TRNG, PRNG, PUF, or device-specific pre-seeded key
 * uint8_t myPrivateKeyingMaterial[CURVE_LENGTH] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 *                                                  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 *                                                  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 *                                                  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01};
 * uint8_t myPublicKeyingMaterial[2 * CURVE_LENGTH + 1] = {0};
 * uint8_t theirPublicKeyingMaterial[2 * CURVE_LENGTH + 1] = {0};
 * uint8_t sharedSecretKeyingMaterial[2 * CURVE_LENGTH + 1] = {0};
 * uint8_t symmetricKeyingMaterial[16] = {0};
 *
 * CryptoKey myPrivateKey;
 * CryptoKey myPublicKey;
 * CryptoKey theirPublicKey;
 * CryptoKey sharedSecret;
 * CryptoKey symmetricKey;
 *
 * ECDH_Handle ecdhHandle;
 *
 * int_fast16_t operationResult;
 *
 * ECDH_OperationGeneratePublicKey operationGeneratePublicKey;
 *
 * // Since we are using default ECDH_Params, we just pass in NULL for that parameter.
 * ecdhHandle = ECDH_open(0, NULL);
 *
 * if (!ecdhHandle) {
 *     // Handle error
 * }
 *
 * // Initialize myPrivateKey and myPublicKey
 * CryptoKeyPlaintext_initKey(&myPrivateKey, myPrivateKeyingMaterial, sizeof(myPrivateKeyingMaterial));
 * CryptoKeyPlaintext_initBlankKey(&myPublicKey, myPublicKeyingMaterial, sizeof(myPublicKeyingMaterial));
 *
 * ECDH_OperationGeneratePublicKey_init(&operationGeneratePublicKey);
 * operationGeneratePublicKey.curve                 = &ECCParams_NISTP256;
 * operationGeneratePublicKey.myPrivateKey          = &myPrivateKey;
 * operationGeneratePublicKey.myPublicKey           =  &myPublicKey;
 *
 * // Generate the keying material for myPublicKey and store it in myPublicKeyingMaterial
 * operationResult = ECDH_generatePublicKey(ecdhHandle, &operationGeneratePublicKey);
 *
 * if (operationResult != ECDH_STATUS_SUCCESS) {
 *     // Handle error
 * }
 *
 * // Now send the content of myPublicKeyingMaterial to the other party,
 * // receive their public key, and copy their public keying material and the
 * // 0x04 byte to theirPublicKeyingMaterial
 *
 * // Initialise their public CryptoKey and the shared secret CryptoKey
 * CryptoKeyPlaintext_initKey(&theirPublicKey, theirPublicKeyingMaterial, sizeof(theirPublicKeyingMaterial));
 * CryptoKeyPlaintext_initBlankKey(&sharedSecret, sharedSecretKeyingMaterial, sizeof(sharedSecretKeyingMaterial));
 *
 * // The ECC_NISTP256 struct is provided in ti/drivers/types/EccParams.h and the corresponding device-specific
 * implementation ECDH_OperationComputeSharedSecret_init(&operationComputeSharedSecret);
 * operationComputeSharedSecret.curve                      = &ECCParams_NISTP256;
 * operationComputeSharedSecret.myPrivateKey               = &myPrivateKey;
 * operationComputeSharedSecret.theirPublicKey             = &theirPublicKey;
 * operationComputeSharedSecret.sharedSecret               = &sharedSecret;
 *
 * // Compute the shared secret and copy it to sharedSecretKeyingMaterial
 * operationResult = ECDH_computeSharedSecret(ecdhHandle, &operationComputeSharedSecret);
 *
 * if (operationResult != ECDH_STATUS_SUCCESS) {
 *     // Handle error
 * }
 *
 * CryptoKeyPlaintext_initBlankKey(&symmetricKey, symmetricKeyingMaterial, sizeof(symmetricKeyingMaterial));
 *
 * // Set up a KDF such as HKDF and open the requisite cryptographic primitive driver to implement it
 * // HKDF and SHA2 were chosen as an example and may not be available directly
 *
 * // At this point, you and the other party have both created the content within symmetricKeyingMaterial without
 * // someone else listening to your communication channel being able to do so
 *
 * @endcode
 *
 *
 */

#ifndef ti_drivers_ECDH__include
#define ti_drivers_ECDH__include

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>

#ifdef __cplusplus
extern "C" {
#endif

#define ECDH_STATUS_RESERVED (-32)

#define ECDH_STATUS_SUCCESS (0)

#define ECDH_STATUS_ERROR (-1)

#define ECDH_STATUS_RESOURCE_UNAVAILABLE (-2)

#define ECDH_STATUS_POINT_AT_INFINITY (-3)

#define ECDH_STATUS_PRIVATE_KEY_LARGER_EQUAL_ORDER (-4)

#define ECDH_STATUS_PRIVATE_KEY_ZERO (-5)

#define ECDH_STATUS_PUBLIC_KEY_NOT_ON_CURVE (-6)

#define ECDH_STATUS_PUBLIC_KEY_LARGER_THAN_PRIME (-7)

#define ECDH_STATUS_CANCELED (-8)

#define ECDH_STATUS_INVALID_KEY_SIZE (-9)

#define ECDH_STATUS_KEYSTORE_ERROR (-10)

typedef struct
{
    void *object;

    void const *hwAttrs;
} ECDH_Config;

typedef ECDH_Config *ECDH_Handle;

typedef enum
{
    ECDH_RETURN_BEHAVIOR_CALLBACK = 1, 
    ECDH_RETURN_BEHAVIOR_BLOCKING = 2, 
    ECDH_RETURN_BEHAVIOR_POLLING  = 4, 
} ECDH_ReturnBehavior;

typedef enum
{
    ECDH_BIG_ENDIAN_KEY    = 0, 
    ECDH_LITTLE_ENDIAN_KEY = 1, 
} ECDH_KeyMaterialEndianness;

#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX) || (DeviceFamily_PARENT == DeviceFamily_PARENT_CC35XX)

typedef enum
{
    ECDH_TYPE_SEC_P_224_R1 = 1,
    ECDH_TYPE_SEC_P_256_R1 = 2,
    ECDH_TYPE_SEC_P_384_R1 = 3,
    ECDH_TYPE_SEC_P_521_R1 = 4,
    ECDH_TYPE_BRP_P_256_R1 = 5,
    ECDH_TYPE_BRP_P_384_R1 = 6,
    ECDH_TYPE_BRP_P_512_R1 = 7,
    ECDH_TYPE_CURVE_25519  = 8,
} ECDH_CurveType;

typedef enum
{
    ECDH_CURVE_LENGTH_192 = 192,
    ECDH_CURVE_LENGTH_224 = 224,
    ECDH_CURVE_LENGTH_255 = 255,
    ECDH_CURVE_LENGTH_256 = 256,
    ECDH_CURVE_LENGTH_384 = 384,
    ECDH_CURVE_LENGTH_512 = 512,
    ECDH_CURVE_LENGTH_521 = 521,
} ECDH_CurveLength;
#endif

typedef struct
{
#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX) || (DeviceFamily_PARENT == DeviceFamily_PARENT_CC35XX)
    ECDH_CurveType curveType; 
#endif
    const ECCParams_CurveParams *curve; 
    const CryptoKey *myPrivateKey;      
    CryptoKey *myPublicKey;             
    ECDH_KeyMaterialEndianness keyMaterialEndianness; 
} ECDH_OperationGeneratePublicKey;

typedef struct
{
#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX) || (DeviceFamily_PARENT == DeviceFamily_PARENT_CC35XX)
    ECDH_CurveType curveType; 
#endif
    const ECCParams_CurveParams *curve;               
    const CryptoKey *myPrivateKey;                    
    const CryptoKey *theirPublicKey;                  
    CryptoKey *sharedSecret;                          
    ECDH_KeyMaterialEndianness keyMaterialEndianness; 
} ECDH_OperationComputeSharedSecret;

typedef union
{
    ECDH_OperationGeneratePublicKey *generatePublicKey; 
    ECDH_OperationComputeSharedSecret *computeSharedSecret; 
} ECDH_Operation;

typedef enum
{
    ECDH_OPERATION_TYPE_GENERATE_PUBLIC_KEY   = 1,
    ECDH_OPERATION_TYPE_COMPUTE_SHARED_SECRET = 2,
} ECDH_OperationType;

typedef void (*ECDH_CallbackFxn)(ECDH_Handle handle,
                                 int_fast16_t returnStatus,
                                 ECDH_Operation operation,
                                 ECDH_OperationType operationType);

typedef struct
{
    ECDH_ReturnBehavior returnBehavior; 
    ECDH_CallbackFxn callbackFxn;       
    uint32_t timeout;                   
    void *custom;                       
} ECDH_Params;

extern const ECDH_Params ECDH_defaultParams;

void ECDH_init(void);

void ECDH_Params_init(ECDH_Params *params);

ECDH_Handle ECDH_open(uint_least8_t index, const ECDH_Params *params);

void ECDH_close(ECDH_Handle handle);

void ECDH_OperationGeneratePublicKey_init(ECDH_OperationGeneratePublicKey *operation);

void ECDH_OperationComputeSharedSecret_init(ECDH_OperationComputeSharedSecret *operation);

int_fast16_t ECDH_generatePublicKey(ECDH_Handle handle, ECDH_OperationGeneratePublicKey *operation);

int_fast16_t ECDH_computeSharedSecret(ECDH_Handle handle, ECDH_OperationComputeSharedSecret *operation);

int_fast16_t ECDH_cancelOperation(ECDH_Handle handle);

ECDH_Handle ECDH_construct(ECDH_Config *config, const ECDH_Params *params);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_ECDH__include */