/*
 * Copyright (c) 2017, 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.
 *
 *
 * @warning This is a beta API. It may change in future releases.
 *
 * # 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. 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.
 *
 * # Usage #
 *
 * ## Before starting an ECDH operation #
 *
 * Before starting a CCM 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 should be stored in an array with the least significant byte of the integer
 *        hex representation stored in the lowest address of the array (little-endian).
 *        The array should be the same length as the curve parameters of the curve used.
 *        The driver can be configured to validate public and private keys against the
 *        provided curve.
 *      - Initialize the private key CryptoKey. CryptoKeys are opaque datastructures and representations
 *        of keying material and its storage. Depending on how the keying material
 *        is stored (RAM or flash, key store, key blob), the CryptoKey must be
 *        initialized differently. The ECDH API can handle all types of CryptoKey.
 *        However, not all device-specific implementions 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. It should have twice the length of the private 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 a blank CryptoKey with the same size as the previously initialized
 *        public key.
 *      - Call ECDH_computeSharedSecret(). The shared secret will be copied to a location
 *        according to the shared secret CryptoKey passed to the function call.
 *
 *
 * ## 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. The API
 * allows for any number of keys to be derived from the shared secret using an application-provided
 * key-derivation function. There are uncountable methods and algorithms to stretch an original
 * seed entropy (the share secret) to generate symmetric keys.
 *      - Initialize n blank CryptoKeys in an array. These CryptoKeys is where the generated
 *        king material will be copied to. The keying material they represent does
 *        not need to be a contiguous range or even of the same CryptoKey type. The array may
 *        contain Plaintext, key blob, or key store CryptoKeys. It may contain different types
 *        of CryptoKeys.
 *        While the API allows for full flexibility in key material location and length, not all
 *        key derivation functions support the full scope of flexibility. Check the KDF's documentation
 *        before using it.
 *      - Call ECDH_calculateSharedEntropy(). The generated keying material will be copied to a
 *        location according to the CryptoKeys passed to the function.
 *
 * ## 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 in short Weierstrass form as defined in
 * ti/drivers/types/ECCParams.h. Several commonly used curves are provided.
 *
 * 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. The Y value can be omitted when using point compression and doing
 * the calculations in the Montgomery domain with X,Z coordinates.
 * This API only uses points expressed in affine coordinates. The point is stored as a
 * concatenated array of X followed by Y.
 *
 * ## ECDH Driver Configuration #
 *
 * In order to use the ECDH APIs, the application is required
 * to provide device-specific ECDH configuration in the Board.c file.
 * The ECDH driver interface defines a configuration data structure:
 *
 * @code
 * typedef struct ECDH_Config_ {
 *     void                   *object;
 *     void          const    *hwAttrs;
 * } ECDH_Config;
 * @endcode
 *
 * The application must declare an array of ECDH_Config elements, named
 * ECDH_config[].  Each element of ECDH_config[] must be populated with
 * pointers to a device specific ECDH driver implementation's
 * driver object, hardware attributes.  The hardware attributes
 * define properties such as the ECDH peripheral's base address.
 * Each element in ECDH_config[] corresponds to
 * an ECDH instance, and none of the elements should have NULL pointers.
 * There is no correlation between the index and the
 * peripheral designation (such as ECDH0 or ECDH1).  For example, it is
 * possible to use ECDH_config[0] for ECDH1. Multiple drivers and driver
 * instances may all access the same underlying hardware. This is transparent
 * to the application. Mutual exclusion is performed automatically by the
 * drivers as necessary.
 *
 * Because the ECDH configuration is very device dependent, you will need to
 * check the doxygen for the device specific ECDH implementation.  There you
 * will find a description of the ECDH hardware attributes.  Please also
 * refer to the Board.c file of any of your examples to see the ECDH
 * configuration.
 *
 * ## ECDH Parameters #
 *
 * The #ECDH_Params structure is passed to the ECDH_open() call.  If NULL
 * is passed for the parameters, ECDH_open() uses default parameters.
 * An #ECDH_Params structure is initialized with default values by passing
 * it to ECDH_Params_init().
 * Some of the ECDH parameters are described below. To see brief descriptions
 * of all the parameters, see #ECDH_Params.
 *
 * ## ECDH Return Behavior
 * The ECDH driver supports three return behaviors when processing data: blocking, polling, and
 * callback. The ECDH driver defaults to blocking mode, if the application does not set it.
 * Once an ECDH driver is opened, the only way to change the return behavior
 * is to close and re-open the ECDH instance with the new return behavior.
 *
 * In blocking mode, a task's code execution is blocked until an ECDH
 * operation has completed. This ensures that only one ECDH operation
 * operates at a given time. Other tasks requesting ECDH operations while
 * a operation is currently taking place are also placed into a blocked
 * state. ECDH operations are executed in the order in which they were
 * received.  In blocking mode, you cannot perform ECDH operations
 * in the context of a software or hardware ISR.
 *
 * In callback mode, an ECDH operation functions asynchronously, which
 * means that it does not block code execution. After an ECDH operation
 * has been completed, the ECDH driver calls a user-provided hook function.
 * Callback mode is supported in the task, SWI, and HWI execution context,
 * However, if an ECDH operation is requested while a operation is taking place,
 * the call returns an error code.
 *
 * In polling mode, an ECDH operation behaves the almost the same way as
 * in blocking mode. Instead of pending on a semaphore and letting other
 * scheduled tasks run, the application task, SWI, or HWI continuously polls
 * a flag until the operation completes. If an ECDH operation is
 * requested while a operation is taking place, the call returns an error code.
 * When starting an ECDH operation in polling mode from HWI or SWI context,
 * the ECDH HWI and SWI must be configured to have a higher priority to pre-empt
 * the polling context.
 *
 * # Examples #
 *
 * ## ECDH exchange with plaintext CryptoKeys #
 *
 * @code
 *
 * #include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
 * #include <ti/drivers/ECDH.h>
 *
 * ...
 *
 * // 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[32] = {0x01, 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};
 * uint8_t myPublicKeyingMaterial[64] = {0};
 * uint8_t theirPublicKeyingMaterial[64] = {0};
 * uint8_t sharedSecretKeyingMaterial[64] = {0};
 * uint8_t symmetricKeyingMaterial[16] = {0};
 *
 * CryptoKey myPrivateKey;
 * CryptoKey myPublicKey;
 * CryptoKey theirPublicKey;
 * CryptoKey sharedSecret;
 * CryptoKey symmetricKey;
 *
 * ECDH_Handle ecdhHandle;
 *
 * int_fast16_t operationResult;
 *
 * // 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));
 *
 * // Generate the keying material for myPublicKey and store it in myPublicKeyingMaterial
 * operationResult = ECDH_generatePublicKey(ecdhHandle, &ECC_NISTP256, &myPrivateKey, &myPublicKey);
 *
 * if (operationResult != ECDH_STATUS_SUCCESS) {
 *     // Handle error
 * }
 *
 * // Now send the content of myPublicKeyingMaterial to theother party,
 * // receive their public key, and copy their public keying material to theirPublicKeyingMaterial
 *
 * // Initialise their public CryptoKey and the shared secret CryptoKey
 * CryptoKeyPlaintext_initKey(&theirPublicKey, theirPublicKeyingMaterial, sizeof(theirPublicKeyingMaterial));
 * CryptoKeyPlaintext_initBlankKey(&sharedSecret, sharedSecretKeyingMaterial, sizeof(sharedSecretKeyingMaterial));
 *
 * // Compute the shared secret and copy it to sharedSecretKeyingMaterial
 * // The ECC_NISTP256 struct is provided in ti/drivers/types/EccPArams.h and the corresponding device-specific implementation
 * operationResult = ECDH_computeSharedSecret(ecdhHandle, &ECC_NISTP256, &myPrivateKey, &theirPublicKey, &sharedSecret);
 *
 * 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
 * // Since we only have one symmetric CryptoKey we wish to generate, we can pass it directly to the function
 * operationResult = ECDH_calculateSharedEntropy(ecdhHandle, &sharedSecret, KDF_HKDF, sha2Handle, &symmetricKey, 1);
 *
 * if (operationResult != ECDH_STATUS_SUCCESS) {
 *     // Handle error
 * }
 *
 * // 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

#ifdef __cplusplus
extern "C" {
#endif

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

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

/**
 *  @defgroup ECDH_CONTROL ECDH_control command and status codes
 *  These ECC macros are reservations for ECC.h
 *  @{
 */

/*!
 * Common ECDH_control command code reservation offset.
 * ECC driver implementations should offset command codes with ECDH_CMD_RESERVED
 * growing positively
 *
 * Example implementation specific command codes:
 * @code
 * #define ECCXYZ_CMD_COMMAND0     ECDH_CMD_RESERVED + 0
 * #define ECCXYZ_CMD_COMMAND1     ECDH_CMD_RESERVED + 1
 * @endcode
 */
#define ECDH_CMD_RESERVED           (32)

/*!
 * Common ECDH_control status code reservation offset.
 * ECC driver implementations should offset status codes with
 * ECDH_STATUS_RESERVED growing negatively.
 *
 * Example implementation specific status codes:
 * @code
 * #define ECCXYZ_STATUS_ERROR0    ECDH_STATUS_RESERVED - 0
 * #define ECCXYZ_STATUS_ERROR1    ECDH_STATUS_RESERVED - 1
 * #define ECCXYZ_STATUS_ERROR2    ECDH_STATUS_RESERVED - 2
 * @endcode
 */
#define ECDH_STATUS_RESERVED        (-32)

/**
 *  @defgroup ECDH_STATUS Status Codes
 *  ECDH_STATUS_* macros are general status codes returned by ECC functions
 *  @{
 *  @ingroup ECDH_CONTROL
 */

/*!
 * @brief   Successful status code.
 *
 * Function return ECDH_STATUS_SUCCESS if the control code was executed
 * successfully.
 */
#define ECDH_STATUS_SUCCESS         (0)

/*!
 * @brief   Generic error status code.
 *
 * Functions return ECDH_STATUS_ERROR if the control code was not executed
 * successfully.
 */
#define ECDH_STATUS_ERROR           (-1)

/*!
 * @brief   An error status code returned by ECDH_control() for undefined
 * command codes.
 *
 * ECDH_control() returns ECDH_STATUS_UNDEFINEDCMD if the control code is not
 * recognized by the driver implementation.
 */
#define ECDH_STATUS_UNDEFINEDCMD    (-2)

/*!
 * @brief   An error status code returned if the hardware or software resource
 * is currently unavailable.
 *
 * ECC driver implementations may have hardware or software limitations on how
 * many clients can simultaneously perform operations. This status code is returned
 * if the mutual exclusion mechanism signals that an operation cannot currently be performed.
 */
#define ECDH_STATUS_RESOURCE_UNAVAILABLE (-3)

/*!
 * @brief   The result of the operation is the point at infinity.
 *
 * The operation yielded the point at infinity on this curve. This point is
 * not permitted for further use in ECC operations.
 */
#define ECDH_STATUS_RESULT_POINT_AT_INFINITY (-4)

/*!
 * @brief   The private key passed in is larger than the order of the curve.
 *
 * Private keys must be integers in the interval [1, n - 1], where n is the
 * order of the curve.
 */
#define ECDH_STATUS_RESULT_PRIVATE_KEY_LARGER_THAN_ORDER (-5)

/*!
 * @brief   The public key of the other party does not lie upon the curve.
 *
 * The public key received from the other party does not lie upon the agreed upon
 * curve.
 */
#define ECDH_STATUS_RESULT_PUBLIC_KEY_NOT_ON_CURVE (-6)


/** @}*/

/**
 *  @defgroup ECDH_CMD Command Codes
 *  ECDH_CMD_* macros are general command codes for ECDH_control(). Not all ECC
 *  driver implementations support these command codes.
 *  @{
 *  @ingroup ECDH_CONTROL
 */

/* Add ECDH_CMD_<commands> here */

/** @}*/

/** @}*/

/*!
 *  @brief  A handle that is returned from an ECDH_open() call.
 */
typedef struct ECDH_Config_    *ECDH_Handle;

/*!
 *  @brief  The definition of a callback function used by the ECC driver
 *          when used in ::ECDH_RETURN_BEHAVIOR_CALLBACK
 *
 *  @param  handle Handle of the client that started the ECC operation.
 *
 *  @param  operationStatus The result of the ECC operation. May contain an error code
 *          if the result is the point at infinity for example.
 */
typedef void (*ECDH_CallbackFxn) (ECDH_Handle handle, int_fast16_t operationStatus);

/*!
 * @brief   The way in which ECC function calls return after performing an
 * encryption + authentication or decryption + verification operation.
 *
 * Not all ECC operations exhibit the specified return behavor. Functions that do not
 * require significant computation and cannot offload that computation to a background thread
 * behave like regular functions. Which functions exhibit the specfied return behavior is not
 * implementation dependent. Specifically, a software-backed implementation run on the same
 * CPU as the application will emulate the return behavior while not actually offloading
 * the computation to the background thread.
 *
 * ECC functions exhibiting the specified return behavior have restrictions on the
 * context from which they may be called.
 *
 * |                                | Task  | Hwi   | Swi   |
 * |--------------------------------|-------|-------|-------|
 * |ECDH_RETURN_BEHAVIOR_CALLBACK | X     | X     | X     |
 * |ECDH_RETURN_BEHAVIOR_BLOCKING | X     |       |       |
 * |ECDH_RETURN_BEHAVIOR_POLLING  | X     | X     | X     |
 *
 */
typedef enum ECDH_ReturnBehavior_ {
    ECDH_RETURN_BEHAVIOR_CALLBACK = 1,    /*!< The function call will return immediately while the
                                             *   ECC operation goes on in the background. The registered
                                             *   callback function is called after the operation completes.
                                             *   The context the callback function is called (task, HWI, SWI)
                                             *   is implementation-dependent.
                                             */
    ECDH_RETURN_BEHAVIOR_BLOCKING = 2,    /*!< The function call will block while ECC operation goes
                                             *   on in the background. ECC operation results are available
                                             *   after the function returns.
                                             */
    ECDH_RETURN_BEHAVIOR_POLLING  = 4,    /*!< The function call will continuously poll a flag while ECC
                                             *   operation goes on in the background. ECC operation results
                                             *   are available after the function returns.
                                             */
} ECDH_ReturnBehavior;

/*!
 *  @brief  ECC Parameters
 *
 *  ECC Parameters are used to with the ECDH_open() call. Default values for
 *  these parameters are set using ECDH_Params_init().
 *
 *  @sa     ECDH_Params_init()
 */
typedef struct ECDH_Params_ {
    bool                    doNotValidateKeys;          /*!< Whether or not to validate public and private keys in operations. */
    ECDH_ReturnBehavior     returnBehavior;             /*!< Blocking, callback, or polling return behavior */
    ECDH_CallbackFxn        callbackFxn;                /*!< Callback function pointer */
    uint32_t                timeout;
    void                   *custom;                     /*!< Custom argument used by driver
                                                         *   implementation
                                                         */
} ECDH_Params;

/*!
 *  @brief ECC Global configuration
 *
 *  The ECDH_Config structure contains a set of pointers used to characterize
 *  the ECC driver implementation.
 *
 *  This structure needs to be defined before calling ECDH_init() and it must
 *  not be changed thereafter.
 *
 *  @sa     ECDH_init()
 */
typedef struct ECDH_Config_ {
    /*! Pointer to a driver specific data object */
    void               *object;

    /*! Pointer to a driver specific hardware attributes structure */
    void         const *hwAttrs;
} ECDH_Config;

/*!
 *  @brief  Function that implements a key derivation function (KDF)
 *
 *  Key derivation functions take a string of random entropy as their input and generate
 *  a deterministic pseudo-random bit stream of arbitrary length. Specialised KDFs may
 *  produce outputs of fixed length or with maximum lengths.
 *
 *  @param [in]     driverHandle        Handle of the of the driver used to execute the crypto
 *                                      primitive underlying the KDF. This primitive could be a
 *                                      cryptographic hash or a block cipher.
 *
 *  @param [in]     seedEntropy         The entropy used to seed the KDF. Reusing the same seed
 *                                      will yield the same pseudo-random bit stream.
 *
 *  @param [in]     seedEntropyLength   Length of the seed entropy.
 *
 *  @param [out]    derivedKeys         The CryptoKeys seeded with deterministic pseudo-random output of the KDF.
 *
 *  @param [in]     derivedKeysCount    The number of keys to seed.
 */
typedef int_fast16_t (*ECDH_KDFFxn) (void *driverHandle, const uint8_t *seedEntropy, size_t seedEntropyLength, CryptoKey derivedKeys[], uint32_t derivedKeysCount);

/*!
 *  @brief Default ECDH_Params structure
 *
 *  @sa     ECDH_Params_init()
 */
extern const ECDH_Params ECDH_defaultParams;

/*!
 *  @brief  This function initializes the ECC module.
 *
 *  @pre    The ECDH_config structure must exist and be persistent before this
 *          function can be called. This function must also be called before
 *          any other ECC driver APIs. This function call does not modify any
 *          peripheral registers.
 */
void ECDH_init(void);

/*!
 *  @brief  Function to initialize the ECDH_Params struct to its defaults
 *
 *  @param  params      An pointer to ECDH_Params structure for
 *                      initialization
 *
 *  Defaults values are:
 *      returnBehavior              = ECDH_RETURN_BEHAVIOR_BLOCKING
 *      callbackFxn                 = NULL
 *      timeout                     = SemaphoreP_WAIT_FOREVER
 *      custom                      = NULL
 */
void ECDH_Params_init(ECDH_Params *params);

/*!
 *  @brief  This function opens a given ECC peripheral.
 *
 *  @pre    ECC controller has been initialized using ECDH_init()
 *
 *  @param  index         Logical peripheral number for the ECC indexed into
 *                        the ECDH_config table
 *
 *  @param  params        Pointer to an parameter block, if NULL it will use
 *                        default values.
 *
 *  @return A ECDH_Handle on success or a NULL on an error or if it has been
 *          opened already.
 *
 *  @sa     ECDH_init()
 *  @sa     ECDH_close()
 */
ECDH_Handle ECDH_open(uint_least8_t index, ECDH_Params *params);

/*!
 *  @brief  Function to close a ECC peripheral specified by the ECC handle
 *
 *  @pre    ECDH_open() has to be called first.
 *
 *  @param  handle A ECC handle returned from ECDH_open()
 *
 *  @sa     ECDH_open()
 */
void ECDH_close(ECDH_Handle handle);

/*!
 *  @brief  Function performs implementation specific features on a given
 *          ECDH_Handle.
 *
 *  Commands for ECDH_control can originate from ECC.h or from implementation
 *  specific ECC*.h (_ECCCC26XX.h_, _EECCSP432.h_, etc.. ) files.
 *  While commands from ECC.h are API portable across driver implementations,
 *  not all implementations may support all these commands.
 *  Conversely, commands from driver implementation specific ECC*.h files add
 *  unique driver capabilities but are not API portable across all ECC driver
 *  implementations.
 *
 *  Commands supported by ECC.h follow an ECDH_CMD_\<cmd\> naming
 *  convention.<br>
 *  Commands supported by ECC*.h follow an ECC*_CMD_\<cmd\> naming
 *  convention.<br>
 *  Each control command defines @b arg differently. The types of @b arg are
 *  documented with each command.
 *
 *  See @ref ECDH_CMD "ECDH_control command codes" for command codes.
 *
 *  See @ref ECDH_STATUS "ECDH_control return status codes" for status codes.
 *
 *  @pre    ECDH_open() has to be called first.
 *
 *  @param  handle      A ECC handle returned from ECDH_open()
 *
 *  @param  cmd         ECC.h or ECC*.h commands.
 *
 *  @param  args        An optional R/W (read/write) command argument
 *                      accompanied with cmd
 *
 *  @return Implementation specific return codes. Negative values indicate
 *          unsuccessful operations.
 *
 *  @sa     ECDH_open()
 */
int_fast16_t ECDH_control(ECDH_Handle handle, uint32_t cmd, void *args);


/*!
 * @brief Generates a public key for use in key agreement.
 *
 *  ECDH_generateKey() can be used for generating ephemeral keys.
 *
 *  @param      handle          A ECC handle returned from ECDH_open()
 *  @param      eccParams       A pointer to the elliptic curve parameters for myPrivateKey
 *  @param      myPrivateKey    A pointer to the private ECC key from which the new public key will be generated. (maybe your static key)
 *  @param      myPublicKey     A pointer to a public ECC key which has been initialized blank.  Newly generated
 *                              key will be placed in this location.
 *
 *  \post ECDH_computeSharedSecret()
 *
 */
int_fast16_t ECDH_generatePublicKey(ECDH_Handle handle, const ECCParams_CurveParams *eccParams, const CryptoKey *myPrivateKey, CryptoKey *myPublicKey);

/*!
 *  @brief Computes a shared secret
 *
 *  This secret can be used to generate shared keys for encryption and authentication.
 *
 *  @param      handle              A ECC handle returned from ECDH_open()
 *  @param      eccParams           A pointer to the elliptic curve parameters for myPrivateKey (if ECDH_generateKey() was used, this should be the same private key)
 *  @param      myPrivateKey        A pointer to the private ECC key which will be used in to compute the shared secret
 *  @param      theirPublicKey      A pointer to the public key of the party with whom the shared secret will be generated
 *  @param      sharedSecret        A pointer to a CryptoKey which has been initialized blank.  The shared secret will be placed here.
 *
 *  \post ECDH_calculateSharedEntropy()
 */
int_fast16_t ECDH_computeSharedSecret(ECDH_Handle handle, const ECCParams_CurveParams *eccParams, const CryptoKey *myPrivateKey, const CryptoKey *theirPublicKey, CryptoKey *sharedSecret);

/*!
 *  @brief Calculates key material
 *
 *  \pre ECDH_computeSharedSecret()
 *
 *  @param      handle                      A ECC handle returned from ECDH_open()
 *
 *  @param      sharedSecret                The shared secret produced by ECDH_calculateSharedEntropy()
 *
 *  @param      kdf                         A pointer to the key derivation function to be used
 *
 *  @param      kdfPrimitiveDriverHandle    A pointer to the handle of a driver of a cryptographic primitive used to implement the KDF
 *
 *  @param      derivedKeys                 A an array of CryptoKeys to seed with calculated entropy
 *
 *  @param      derivedKeysCount            The number of CryptoKeys to seed with calculated entropy
 *
 */
int_fast16_t ECDH_calculateSharedEntropy(ECDH_Handle handle, const CryptoKey *sharedSecret, const ECDH_KDFFxn kdf, void *kdfPrimitiveDriverHandle, CryptoKey derivedKeys[], uint32_t derivedKeysCount);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_ECDH__include */