TI Driver for Elliptic Curve Diffie-Hellman key agreement scheme.
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.
Before starting a ECDH operation, the application must do the following:
To generate a public-private key pair for an agreed upon curve, the application must do the following:
After trading public keys with the other party, the application should do the following to calculate 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.
After the ECDH key exchange completes, the application should either start another operation or close the driver by calling ECDH_close()
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.
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:
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.
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.
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.
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>
Go to the source code of this file.
Data Structures | |
struct | ECDH_Config_ |
ECC Global configuration. More... | |
struct | ECDH_OperationGeneratePublicKey_ |
Struct containing the parameters required to generate a public key. More... | |
struct | ECDH_OperationComputeSharedSecret_ |
Struct containing the parameters required to compute the shared secret. More... | |
union | ECDH_Operation_ |
Union containing pointers to all supported operation structs. More... | |
struct | ECDH_Params_ |
ECC Parameters. More... | |
Macros | |
#define | ECDH_CMD_RESERVED (32) |
#define | ECDH_STATUS_RESERVED (-32) |
#define | ECDH_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | ECDH_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | ECDH_STATUS_UNDEFINEDCMD (-2) |
An error status code returned by ECDH_control() for undefined command codes. More... | |
#define | ECDH_STATUS_RESOURCE_UNAVAILABLE (-3) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | ECDH_STATUS_RESULT_POINT_AT_INFINITY (-4) |
The result of the operation is the point at infinity. More... | |
#define | ECDH_STATUS_RESULT_PRIVATE_KEY_LARGER_THAN_ORDER (-5) |
The private key passed in is larger than the order of the curve. More... | |
#define | ECDH_STATUS_RESULT_PUBLIC_KEY_NOT_ON_CURVE (-6) |
The public key of the other party does not lie upon the curve. More... | |
Typedefs | |
typedef struct ECDH_Config_ * | ECDH_Handle |
A handle that is returned from an ECDH_open() call. More... | |
typedef enum ECDH_ReturnBehavior_ | ECDH_ReturnBehavior |
The way in which ECC function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
typedef struct ECDH_Config_ | ECDH_Config |
ECC Global configuration. More... | |
typedef struct ECDH_OperationGeneratePublicKey_ | ECDH_OperationGeneratePublicKey |
Struct containing the parameters required to generate a public key. More... | |
typedef struct ECDH_OperationComputeSharedSecret_ | ECDH_OperationComputeSharedSecret |
Struct containing the parameters required to compute the shared secret. More... | |
typedef union ECDH_Operation_ | ECDH_Operation |
Union containing pointers to all supported operation structs. More... | |
typedef enum ECDH_OperationType_ | ECDH_OperationType |
Enum for the operation types supported by the driver. More... | |
typedef void(* | ECDH_CallbackFxn) (ECDH_Handle handle, int_fast16_t returnStatus, ECDH_Operation operation, ECDH_OperationType operationType) |
The definition of a callback function used by the ECDH driver when used in ECDH_RETURN_BEHAVIOR_CALLBACK. More... | |
typedef struct ECDH_Params_ | ECDH_Params |
ECC Parameters. More... | |
Enumerations | |
enum | ECDH_ReturnBehavior_ { ECDH_RETURN_BEHAVIOR_CALLBACK = 1, ECDH_RETURN_BEHAVIOR_BLOCKING = 2, ECDH_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which ECC function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
enum | ECDH_OperationType_ { ECDH_OPERATION_TYPE_GENERATE_PUBLIC_KEY = 1, ECDH_OPERATION_TYPE_COMPUTE_SHARED_SECRET = 2 } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | ECDH_init (void) |
This function initializes the ECC module. More... | |
void | ECDH_Params_init (ECDH_Params *params) |
Function to initialize the ECDH_Params struct to its defaults. More... | |
ECDH_Handle | ECDH_open (uint_least8_t index, ECDH_Params *params) |
This function opens a given ECC peripheral. More... | |
void | ECDH_close (ECDH_Handle handle) |
Function to close a ECC peripheral specified by the ECC handle. More... | |
int_fast16_t | ECDH_control (ECDH_Handle handle, uint32_t cmd, void *args) |
Function performs implementation specific features on a given ECDH_Handle. More... | |
void | ECDH_OperationGeneratePublicKey_init (ECDH_OperationGeneratePublicKey *operation) |
Function to initialize a ECDH_OperationGeneratePublicKey struct to its defaults. More... | |
void | ECDH_OperationComputeSharedSecret_init (ECDH_OperationComputeSharedSecret *operation) |
Function to initialize a ECDH_OperationComputeSharedSecret struct to its defaults. More... | |
int_fast16_t | ECDH_generatePublicKey (ECDH_Handle handle, ECDH_OperationGeneratePublicKey *operation) |
Generates a public key for use in key agreement. More... | |
int_fast16_t | ECDH_computeSharedSecret (ECDH_Handle handle, ECDH_OperationComputeSharedSecret *operation) |
Computes a shared secret. More... | |
Variables | |
const ECDH_Params | ECDH_defaultParams |
Default ECDH_Params structure. More... | |
typedef struct ECDH_Config_* ECDH_Handle |
A handle that is returned from an ECDH_open() call.
typedef enum ECDH_ReturnBehavior_ ECDH_ReturnBehavior |
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 struct ECDH_Config_ ECDH_Config |
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.
typedef struct ECDH_OperationGeneratePublicKey_ ECDH_OperationGeneratePublicKey |
Struct containing the parameters required to generate a public key.
Struct containing the parameters required to compute the shared secret.
typedef union ECDH_Operation_ ECDH_Operation |
Union containing pointers to all supported operation structs.
typedef enum ECDH_OperationType_ ECDH_OperationType |
Enum for the operation types supported by the driver.
typedef void(* ECDH_CallbackFxn) (ECDH_Handle handle, int_fast16_t returnStatus, ECDH_Operation operation, ECDH_OperationType operationType) |
The definition of a callback function used by the ECDH driver when used in ECDH_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the ECDH operation. |
returnStatus | The result of the ECDH operation. May contain an error code if the result is the point at infinity for example. |
operation | A union of pointers to operation structs. Only one type of pointer is valid per call to the callback function. Which type is currently valid is determined by /c operationType. The union allows easier access to the struct's fields without the need to typecase the result. |
operationType | This parameter determined which operation the callback refers to and which type to access through /c operation. |
typedef struct ECDH_Params_ ECDH_Params |
ECC Parameters.
ECC Parameters are used to with the ECDH_open() call. Default values for these parameters are set using ECDH_Params_init().
enum ECDH_ReturnBehavior_ |
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 |
enum ECDH_OperationType_ |
void ECDH_init | ( | void | ) |
This function initializes the ECC module.
void ECDH_Params_init | ( | ECDH_Params * | params | ) |
Function to initialize the ECDH_Params struct to its defaults.
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
ECDH_Handle ECDH_open | ( | uint_least8_t | index, |
ECDH_Params * | params | ||
) |
This function opens a given ECC peripheral.
index | Logical peripheral number for the ECC indexed into the ECDH_config table |
params | Pointer to an parameter block, if NULL it will use default values. |
void ECDH_close | ( | ECDH_Handle | handle | ) |
Function to close a ECC peripheral specified by the ECC handle.
handle | A ECC handle returned from ECDH_open() |
int_fast16_t ECDH_control | ( | ECDH_Handle | handle, |
uint32_t | cmd, | ||
void * | args | ||
) |
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.
Commands supported by ECC*.h follow an ECC*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.
See ECDH_control command codes for command codes.
See ECDH_control return status codes for status codes.
handle | A ECC handle returned from ECDH_open() |
cmd | ECC.h or ECC*.h commands. |
args | An optional R/W (read/write) command argument accompanied with cmd |
void ECDH_OperationGeneratePublicKey_init | ( | ECDH_OperationGeneratePublicKey * | operation | ) |
Function to initialize a ECDH_OperationGeneratePublicKey struct to its defaults.
operation | A pointer to ECDH_OperationGeneratePublicKey structure for initialization |
Defaults values are all zeros.
void ECDH_OperationComputeSharedSecret_init | ( | ECDH_OperationComputeSharedSecret * | operation | ) |
Function to initialize a ECDH_OperationComputeSharedSecret struct to its defaults.
operation | A pointer to ECDH_OperationComputeSharedSecret structure for initialization |
Defaults values are all zeros.
int_fast16_t ECDH_generatePublicKey | ( | ECDH_Handle | handle, |
ECDH_OperationGeneratePublicKey * | operation | ||
) |
Generates a public key for use in key agreement.
ECDH_generateKey() can be used for generating ephemeral keys.
handle | A ECC handle returned from ECDH_open() |
operation | A pointer to a struct containing the requisite parameters to execute the function. |
int_fast16_t ECDH_computeSharedSecret | ( | ECDH_Handle | handle, |
ECDH_OperationComputeSharedSecret * | operation | ||
) |
Computes a shared secret.
This secret can be used to generate shared keys for encryption and authentication.
handle | A ECC handle returned from ECDH_open() |
operation | A pointer to a struct containing the requisite |
const ECDH_Params ECDH_defaultParams |
Default ECDH_Params structure.