TI Driver for Elliptic Curve Password Authenticated Key Exchange by Juggling.
Elliptic Curve Password Authenticated Key Exchange by Juggling (EC-JPAKE) is a key agreement scheme that establishes a secure channel over an insecure network. It only requires sharing a password offline and does not require public key infrastructure or trusted third parties such as certificate authorities.
At the end of the EC-JPAKE scheme, both parties derive a shared secret from which a session key is derived.
The scheme is symmetric. Both parties perform the exact same operations to end up with the shared secret.
Since the scheme is symmetric, the steps involved will be illustrated using Alice and Bob as relevant parties.
Before starting a ECJPAKE operation, the application must do the following:
The API expects elliptic curves 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 currently 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 ECJPAKE APIs, the application is required to provide device-specific ECJPAKE configuration in the Board.c file. The ECJPAKE driver interface defines a configuration data structure:
The application must declare an array of ECJPAKE_Config elements, named ECJPAKE_config[]. Each element of ECJPAKE_config[] must be populated with pointers to a device specific ECJPAKE driver implementation's driver object, hardware attributes. Each element in ECJPAKE_config[] corresponds to an ECJPAKE instance, and none of the elements should have NULL pointers. There is no correlation between the index and the peripheral designation (such as ECJPAKE0 or ECJPAKE1). For example, it is possible to use ECJPAKE_config[0] for ECJPAKE1. 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 ECJPAKE configuration is highly device dependent, you will need to check the doxygen for the device specific ECJPAKE implementation. There you will find a description of the ECJPAKE hardware attributes. Please also refer to the Board.c file of any of your examples to see the ECJPAKE configuration.
The ECJPAKE_Params structure is passed to the ECJPAKE_open() call. If NULL is passed for the parameters, ECJPAKE_open() uses default parameters. An ECJPAKE_Params structure is initialized with default values by passing it to ECJPAKE_Params_init(). Some of the ECJPAKE parameters are described below. To see brief descriptions of all the parameters, see ECJPAKE_Params.
#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 | ECJPAKE_Config_ |
ECJPAKE Global configuration. More... | |
struct | ECJPAKE_OperationRoundOneGenerateKeys_ |
Struct containing the parameters required to generate the first round of keys. More... | |
struct | ECJPAKE_OperationGenerateZKP_ |
Struct containing the parameters required to generate a ZKP. More... | |
struct | ECJPAKE_OperationVerifyZKP_ |
Struct containing the parameters required to verify a ZKP. More... | |
struct | ECJPAKE_OperationRoundTwoGenerateKeys_ |
Struct containing the parameters required to generate the second round keys. More... | |
struct | ECJPAKE_OperationComputeSharedSecret_ |
Struct containing the parameters required to compute the shared secret. More... | |
union | ECJPAKE_Operation_ |
Union containing pointers to all supported operation structs. More... | |
struct | ECJPAKE_Params_ |
ECJPAKE Parameters. More... | |
Macros | |
#define | ECJPAKE_CMD_RESERVED (32) |
#define | ECJPAKE_STATUS_RESERVED (-32) |
#define | ECJPAKE_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | ECJPAKE_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | ECJPAKE_STATUS_UNDEFINEDCMD (-2) |
An error status code returned by ECJPAKE_control() for undefined command codes. More... | |
#define | ECJPAKE_STATUS_RESOURCE_UNAVAILABLE (-3) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | ECJPAKE_STATUS_INVALID_PUBLIC_KEY (-4) |
The public key of the other party is not valid. More... | |
Typedefs | |
typedef struct ECJPAKE_Config_ * | ECJPAKE_Handle |
A handle that is returned from an ECJPAKE_open() call. More... | |
typedef enum ECJPAKE_ReturnBehavior_ | ECJPAKE_ReturnBehavior |
The way in which ECJPAKE function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
typedef struct ECJPAKE_Config_ | ECJPAKE_Config |
ECJPAKE Global configuration. More... | |
typedef struct ECJPAKE_OperationRoundOneGenerateKeys_ | ECJPAKE_OperationRoundOneGenerateKeys |
Struct containing the parameters required to generate the first round of keys. More... | |
typedef struct ECJPAKE_OperationGenerateZKP_ | ECJPAKE_OperationGenerateZKP |
Struct containing the parameters required to generate a ZKP. More... | |
typedef struct ECJPAKE_OperationVerifyZKP_ | ECJPAKE_OperationVerifyZKP |
Struct containing the parameters required to verify a ZKP. More... | |
typedef struct ECJPAKE_OperationRoundTwoGenerateKeys_ | ECJPAKE_OperationRoundTwoGenerateKeys |
Struct containing the parameters required to generate the second round keys. More... | |
typedef struct ECJPAKE_OperationComputeSharedSecret_ | ECJPAKE_OperationComputeSharedSecret |
Struct containing the parameters required to compute the shared secret. More... | |
typedef union ECJPAKE_Operation_ | ECJPAKE_Operation |
Union containing pointers to all supported operation structs. More... | |
typedef enum ECJPAKE_OperationType_ | ECJPAKE_OperationType |
Enum for the operation types supported by the driver. More... | |
typedef void(* | ECJPAKE_CallbackFxn) (ECJPAKE_Handle handle, int_fast16_t returnStatus, ECJPAKE_Operation operation, ECJPAKE_OperationType operationType) |
The definition of a callback function used by the ECJPAKE driver when used in ECJPAKE_RETURN_BEHAVIOR_CALLBACK. More... | |
typedef struct ECJPAKE_Params_ | ECJPAKE_Params |
ECJPAKE Parameters. More... | |
Enumerations | |
enum | ECJPAKE_ReturnBehavior_ { ECJPAKE_RETURN_BEHAVIOR_CALLBACK = 1, ECJPAKE_RETURN_BEHAVIOR_BLOCKING = 2, ECJPAKE_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which ECJPAKE function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
enum | ECJPAKE_OperationType_ { ECJPAKE_OPERATION_TYPE_ROUND_ONE_GENERATE_KEYS = 1, ECJPAKE_OPERATION_TYPE_GENERATE_ZKP = 2, ECJPAKE_OPERATION_TYPE_VERIFY_ZKP = 3, ECJPAKE_OPERATION_TYPE_ROUND_TWO_GENERATE_KEYS = 4, ECJPAKE_OPERATION_TYPE_COMPUTE_SHARED_SECRET = 5 } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | ECJPAKE_init (void) |
This function initializes the ECJPAKE module. More... | |
void | ECJPAKE_OperationRoundOneGenerateKeys_init (ECJPAKE_OperationRoundOneGenerateKeys *operation) |
Function to initialize a ECJPAKE_OperationRoundOneGenerateKeys struct to its defaults. More... | |
void | ECJPAKE_OperationGenerateZKP_init (ECJPAKE_OperationGenerateZKP *operation) |
Function to initialize a ECJPAKE_OperationGenerateZKP struct to its defaults. More... | |
void | ECJPAKE_OperationVerifyZKP_init (ECJPAKE_OperationVerifyZKP *operation) |
Function to initialize a ECJPAKE_OperationVerifyZKP struct to its defaults. More... | |
void | ECJPAKE_OperationRoundTwoGenerateKeys_init (ECJPAKE_OperationRoundTwoGenerateKeys *operation) |
Function to initialize a ECJPAKE_OperationRoundTwoGenerateKeys struct to its defaults. More... | |
void | ECJPAKE_OperationComputeSharedSecret_init (ECJPAKE_OperationComputeSharedSecret *operation) |
Function to initialize a ECJPAKE_OperationComputeSharedSecret struct to its defaults. More... | |
void | ECJPAKE_close (ECJPAKE_Handle handle) |
Function to close a ECJPAKE peripheral specified by the ECJPAKE handle. More... | |
int_fast16_t | ECJPAKE_control (ECJPAKE_Handle handle, uint32_t cmd, void *args) |
Function performs implementation specific features on a given ECJPAKE_Handle. More... | |
ECJPAKE_Handle | ECJPAKE_open (uint_least8_t index, ECJPAKE_Params *params) |
This function opens a given ECJPAKE peripheral. More... | |
void | ECJPAKE_Params_init (ECJPAKE_Params *params) |
Function to initialize the ECJPAKE_Params struct to its defaults. More... | |
int_fast16_t | ECJPAKE_roundOneGenerateKeys (ECJPAKE_Handle handle, ECJPAKE_OperationRoundOneGenerateKeys *operation) |
Generates all public and private keying material for the first round of the EC-JPAKE scheme. More... | |
int_fast16_t | ECJPAKE_generateZKP (ECJPAKE_Handle handle, ECJPAKE_OperationGenerateZKP *operation) |
Generates the r component of a Schnorr Zero-Knowledge Proof (ZKP) signature. More... | |
int_fast16_t | ECJPAKE_verifyZKP (ECJPAKE_Handle handle, ECJPAKE_OperationVerifyZKP *operation) |
Verifies a Schnorr Zero-Knowledge Proof (ZKP) signature. More... | |
int_fast16_t | ECJPAKE_roundTwoGenerateKeys (ECJPAKE_Handle handle, ECJPAKE_OperationRoundTwoGenerateKeys *operation) |
Generates all public and private keying material for the first round of the EC-JPAKE scheme. More... | |
int_fast16_t | ECJPAKE_computeSharedSecret (ECJPAKE_Handle handle, ECJPAKE_OperationComputeSharedSecret *operation) |
Computes the shared secret. More... | |
typedef struct ECJPAKE_Config_* ECJPAKE_Handle |
A handle that is returned from an ECJPAKE_open() call.
typedef enum ECJPAKE_ReturnBehavior_ ECJPAKE_ReturnBehavior |
The way in which ECJPAKE function calls return after performing an encryption + authentication or decryption + verification operation.
Not all ECJPAKE 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 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.
ECJPAKE functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
ECJPAKE_RETURN_BEHAVIOR_CALLBACK | X | X | X |
ECJPAKE_RETURN_BEHAVIOR_BLOCKING | X | ||
ECJPAKE_RETURN_BEHAVIOR_POLLING | X | X | X |
typedef struct ECJPAKE_Config_ ECJPAKE_Config |
ECJPAKE Global configuration.
The ECJPAKE_Config structure contains a set of pointers used to characterize the ECJPAKE driver implementation.
This structure needs to be defined before calling ECJPAKE_init() and it must not be changed thereafter.
Struct containing the parameters required to generate the first round of keys.
typedef struct ECJPAKE_OperationGenerateZKP_ ECJPAKE_OperationGenerateZKP |
Struct containing the parameters required to generate a ZKP.
typedef struct ECJPAKE_OperationVerifyZKP_ ECJPAKE_OperationVerifyZKP |
Struct containing the parameters required to verify a ZKP.
Struct containing the parameters required to generate the second round keys.
Struct containing the parameters required to compute the shared secret.
typedef union ECJPAKE_Operation_ ECJPAKE_Operation |
Union containing pointers to all supported operation structs.
typedef enum ECJPAKE_OperationType_ ECJPAKE_OperationType |
Enum for the operation types supported by the driver.
typedef void(* ECJPAKE_CallbackFxn) (ECJPAKE_Handle handle, int_fast16_t returnStatus, ECJPAKE_Operation operation, ECJPAKE_OperationType operationType) |
The definition of a callback function used by the ECJPAKE driver when used in ECJPAKE_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the ECJPAKE operation. |
returnStatus | The result of the ECJPAKE 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 ECJPAKE_Params_ ECJPAKE_Params |
ECJPAKE Parameters.
ECJPAKE Parameters are used to with the ECJPAKE_open() call. Default values for these parameters are set using ECJPAKE_Params_init().
The way in which ECJPAKE function calls return after performing an encryption + authentication or decryption + verification operation.
Not all ECJPAKE 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 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.
ECJPAKE functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
ECJPAKE_RETURN_BEHAVIOR_CALLBACK | X | X | X |
ECJPAKE_RETURN_BEHAVIOR_BLOCKING | X | ||
ECJPAKE_RETURN_BEHAVIOR_POLLING | X | X | X |
void ECJPAKE_init | ( | void | ) |
This function initializes the ECJPAKE module.
void ECJPAKE_OperationRoundOneGenerateKeys_init | ( | ECJPAKE_OperationRoundOneGenerateKeys * | operation | ) |
Function to initialize a ECJPAKE_OperationRoundOneGenerateKeys struct to its defaults.
operation | A pointer to ECJPAKE_OperationRoundOneGenerateKeys structure for initialization |
Defaults values are all zeros.
void ECJPAKE_OperationGenerateZKP_init | ( | ECJPAKE_OperationGenerateZKP * | operation | ) |
Function to initialize a ECJPAKE_OperationGenerateZKP struct to its defaults.
operation | A pointer to ECJPAKE_OperationGenerateZKP structure for initialization |
Defaults values are all zeros.
void ECJPAKE_OperationVerifyZKP_init | ( | ECJPAKE_OperationVerifyZKP * | operation | ) |
Function to initialize a ECJPAKE_OperationVerifyZKP struct to its defaults.
operation | A pointer to ECJPAKE_OperationVerifyZKP structure for initialization |
Defaults values are all zeros.
void ECJPAKE_OperationRoundTwoGenerateKeys_init | ( | ECJPAKE_OperationRoundTwoGenerateKeys * | operation | ) |
Function to initialize a ECJPAKE_OperationRoundTwoGenerateKeys struct to its defaults.
operation | A pointer to ECJPAKE_OperationRoundTwoGenerateKeys structure for initialization |
Defaults values are all zeros.
void ECJPAKE_OperationComputeSharedSecret_init | ( | ECJPAKE_OperationComputeSharedSecret * | operation | ) |
Function to initialize a ECJPAKE_OperationComputeSharedSecret struct to its defaults.
operation | A pointer to ECJPAKE_OperationComputeSharedSecret structure for initialization |
Defaults values are all zeros.
void ECJPAKE_close | ( | ECJPAKE_Handle | handle | ) |
Function to close a ECJPAKE peripheral specified by the ECJPAKE handle.
handle | A ECJPAKE handle returned from ECJPAKE_open() |
int_fast16_t ECJPAKE_control | ( | ECJPAKE_Handle | handle, |
uint32_t | cmd, | ||
void * | args | ||
) |
Function performs implementation specific features on a given ECJPAKE_Handle.
Commands for ECJPAKE_control can originate from ECJPAKE.h or from implementation specific ECJPAKE*.h (ECJPAKECC26X2.h, ECJPAKESP432.h, etc.. ) files. While commands from ECJPAKE.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific ECJPAKE*.h files add unique driver capabilities but are not API portable across all ECJPAKE driver implementations.
Commands supported by ECJPAKE.h follow an ECJPAKE_CMD_<cmd> naming convention.
Commands supported by ECJPAKE*.h follow an ECJPAKE*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.
See ECJPAKE_control command codes for command codes.
See ECJPAKE_control return status codes for status codes.
handle | A ECJPAKE handle returned from ECJPAKE_open() |
cmd | ECJPAKE.h or ECJPAKE*.h commands. |
args | An optional R/W (read/write) command argument accompanied with cmd |
ECJPAKE_Handle ECJPAKE_open | ( | uint_least8_t | index, |
ECJPAKE_Params * | params | ||
) |
This function opens a given ECJPAKE peripheral.
index | Logical peripheral number for the ECJPAKE indexed into the ECJPAKE_config table |
params | Pointer to an parameter block, if NULL it will use default values. |
void ECJPAKE_Params_init | ( | ECJPAKE_Params * | params | ) |
Function to initialize the ECJPAKE_Params struct to its defaults.
params | An pointer to ECJPAKE_Params structure for initialization |
Defaults values are: returnBehavior = ECJPAKE_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
int_fast16_t ECJPAKE_roundOneGenerateKeys | ( | ECJPAKE_Handle | handle, |
ECJPAKE_OperationRoundOneGenerateKeys * | operation | ||
) |
Generates all public and private keying material for the first round of the EC-JPAKE scheme.
This function generates all public and private keying material required for the first round of the EC-JPAKE scheme.
[in] | handle | A ECJPAKE handle returned from ECJPAKE_open() |
[in] | operation | A pointer to a struct containing the requisite parameters to execute the function. |
int_fast16_t ECJPAKE_generateZKP | ( | ECJPAKE_Handle | handle, |
ECJPAKE_OperationGenerateZKP * | operation | ||
) |
Generates the r
component of a Schnorr Zero-Knowledge Proof (ZKP) signature.
This function generates the r
component of a ZKP using the hash and private keys. The hash must be computed prior. This function does not compute the hash for the application. There is no strictly defined bit-level implementation guideline for generating the hash in the EC-JPAKE scheme. Hence, interoperability could not be guaranteed between different EC-JPAKE implementations. Usually, the hash will be a concatenation of the public V, public key, generator point, and user ID. There may be other components such as length fields mixed in.
[in] | handle | A ECJPAKE handle returned from ECJPAKE_open() |
[in] | operation | A pointer to a struct containing the requisite parameters to execute the function. |
r
, public V, user ID) together with the public keys to the other party. int_fast16_t ECJPAKE_verifyZKP | ( | ECJPAKE_Handle | handle, |
ECJPAKE_OperationVerifyZKP * | operation | ||
) |
Verifies a Schnorr Zero-Knowledge Proof (ZKP) signature.
This function computes if a received Schnorr ZKP correctly verifies a received public key.
[in] | handle | A ECJPAKE handle returned from ECJPAKE_open() |
[in] | operation | A pointer to a struct containing the requisite parameters to execute the function. |
int_fast16_t ECJPAKE_roundTwoGenerateKeys | ( | ECJPAKE_Handle | handle, |
ECJPAKE_OperationRoundTwoGenerateKeys * | operation | ||
) |
Generates all public and private keying material for the first round of the EC-JPAKE scheme.
This function generates all public and private keying material required for the first round of the EC-JPAKE scheme.
[in] | handle | A ECJPAKE handle returned from ECJPAKE_open() |
[in] | operation | A pointer to a struct containing the requisite parameters to execute the function. |
int_fast16_t ECJPAKE_computeSharedSecret | ( | ECJPAKE_Handle | handle, |
ECJPAKE_OperationComputeSharedSecret * | operation | ||
) |
Computes the shared secret.
This function computes the shared secret between both parties. The shared secret is a point on the elliptic curve and is used to further derive the symmetric session key via a key derivation function.
[in] | handle | A ECJPAKE handle returned from ECJPAKE_open() |
[in] | operation | A pointer to a struct containing the requisite parameters to execute the function. |