ECC ROM driver

ECC ROM driver implementation for a CC26XX device. More...

Modules
	ECC_STATUS

Files
file	ECCROMCC26XX.h
	ECC ROM driver implementation for a CC26XX device.

Data Structures
struct	ECCROMCC26XX_CurveParams
	ECCROMCC26XX Curve Parameters. More...
struct	ECCROMCC26XX_Params
	ECCROMCC26XX Parameters. More...

Macros
#define	ECCROMCC26XX_NIST_P256_KEY_LEN_IN_BYTES   32
#define	ECCROMCC26XX_NIST_P256_WORKZONE_LEN_IN_BYTES   684
#define	ECCROMCC26XX_WORKZONE_LEN_IN_BYTES(len, win)   (4 * ((13 * (len)) + 13 + (3 * (len) * (1 << ((win) - 2)))))
	Compute ECC workzone length in bytes for a generic key length and window size. More...

Typedefs
typedef struct ECCROMCC26XX_CurveParams	ECCROMCC26XX_CurveParams
	ECCROMCC26XX Curve Parameters. More...
typedef void(*	ECCROMCC26XX_FreeCB) (uint8_t *pBuf)
	ECCROMCC26XX Free Callback. More...
typedef uint8_t *(*	ECCROMCC26XX_MallocCB) (uint16_t len)
	ECCROMCC26XX Malloc Callback. More...
typedef struct ECCROMCC26XX_Params	ECCROMCC26XX_Params
	ECCROMCC26XX Parameters. More...

Functions
int8_t	ECCROMCC26XX_genDHKey (uint8_t *privateKey, uint8_t *publicKeyX, uint8_t *publicKeyY, uint8_t *dHKeyX, uint8_t *dHKeyY, ECCROMCC26XX_Params *params)
	Generate Diffie-Hellman Shared Secret Key X and Y Coordinates. More...
int8_t	ECCROMCC26XX_genKeys (uint8_t *privateKey, uint8_t *publicKeyX, uint8_t *publicKeyY, ECCROMCC26XX_Params *params)
	Generate Public Key X and Y Coordinates. More...
void	ECCROMCC26XX_init (void)
	Initializes module's synchronization resources. Only needs to be called once, but safe to call multiple times. More...
void	ECCROMCC26XX_Params_init (ECCROMCC26XX_Params *params)
	Function to initialize the ECCROMCC26XX_Params struct to its defaults. params should not be modified until after this function is called. Default parameters use the NIST P-256 curve, timeout is set to wait indefinitely, malloc and free are NULL and status is set to ECCROMCC26XX_STATUS_SUCCESS. A client may call this function with the same params instance any number of times. More...

Detailed Description

ECC ROM driver implementation for a CC26XX device.

============================================================================

Driver Include

The ECC ROM header file should be included in an application as follows:

#include <ti/drivers/ecc/ECCROMCC26XX.h>

Overview

The ECCROMCC26XX driver provides reentrant access to the ROM based ECC module. Access is given first come, first serve and subsequent calls block until all preceding callers have returned or the caller times out in which case execution returns to the caller but the operation is not performed.

Note: this implementation differs in byte ordering from the NIST Standard. It is not expected that keys input from a different implementation will match the output here.

General Behavior

For code examples, see Use Cases below.

Initialing the driver

• The application initializes the ECCROMCC26XX driver by calling ECCROMCC26XX_init().
• This function may be called more than once, but it only needs to be called once per system reset.

// Initialize ECC ROM driver
ECCROMCC26XX_init();

// Generate Public Keys
status = ECCROMCC26XX_genKeys(privKey, pubKeyX, pubKeyY, &params);
if (!status) {
    System_printf("ECCROMCC26XX did not complete successfully");
}

Initializing client parameters

• Prior to calling either ECCROMCC26XX_genKeys() or ECCROMCC26XX_genDHKey(), parameters must be initialized with a call to ECCROMCC26XX_Params_init() and initialize an instance of ECCROMCC26XX_Params. Generally, it is expected that each client will initialize its own instance of ECCROMCC26XX_Params, but in some cases this is not necessary. Multiple clients may share the same ECCROMCC26XX_Params instance as long as they do not rely on the status field. This field could be overwritten by any of the clients whom share the instance. The clients should then rely on the return value of the API function which was called.
• ECCROMCC26XX_Params initialize their curves to NIST P-256 defaults, set their malloc and free functions to NULL and block indefinitely when waiting for the resource.
• Currently only NIST P-256 parameters are included in ROM. If a client wishes to use a different curve, that client must provide it. Curve parameters are uint32_t buffers where the first uint32_t block is a length header which specified the length of the buffer in uint32_t blocks, not including the header itself. the maximum curve length supported in 1020 bytes or 255 uint32_t blocks. For example, the NIST P-256 length header would be 8.
• keyLen should be the same as the length header of Curve parameters but in in bytes. For example, the NIST P-256 key length would be 32.
• workzone length is determined by the operation, curve length in uint32_t blocks and windowsize. the default value for NIST P-256 curves is only valid for those curves performing key and shared secret generation. The workzone length for any curve using the supported operation can be calculated with the ECCROMCC26XX_WORKZONE_LEN macro.
• windowSize determines the speed and memory trade-off of each operation. Valid windowSize values are 2 through 5, and 3 is recommended as the best trade-off.

// Declaration of this client's ECCROMCC26XX parameters.
ECCROMCC26XX_Params      params;

// Initialize this client's ECCROMCC26XX parameters.
ECCROMCC26XX_Params_init(&params);

// Set the Malloc and Free functions for internal buffer allocation.
params.malloc = (uint8_t *(*)(uint16_t))myMallocFunction;
params.free   = (void (*)(uint8_t *))myFreeFunction;

// If an indefinite timeout is undesirable, alter the timeout here.
// the value specified here will be a multiple of Clock.tickPeriod is
// specified as.
params.timeout = 1000; // wait a maximum of 1000 system time units

// If using non NIST P-256 curves, supply them here. Otherwise, skip this.
params.curve.keyLen      = myCurveLength; // in bytes.
params.curve.workzoneLen = ECCROMCC26XX_WORKZONE_LEN_IN_BYTES(myCurveLength/4, myWindowSize);
params.curve.windowSize  = myWindowSize;
params.curve.param_p     = myCurveParamP;
params.curve.param_r     = myCurveParamR;
params.curve.param_a     = myCurveParamA;
params.curve.param_b     = myCurveParamB;
params.curve.param_gx    = myCurveParamGx;
params.curve.param_gy    = myCurveParamGy;

Use Cases

### Performing a key and shared secret generation operation #

// Declaration of this client's ECCROMCC26XX parameters.
ECCROMCC26XX_Params      params;
// Declaration of local public keys
uint8_t localPrivateKey[32]  = {0};
uint8_t localPublicKeyX[32]  = {0};
uint8_t localPublicKeyY[32]  = {0};
uint8_t sharedSecretKeyX[32] = {0};
uint8_t sharedSecretKeyY[32] = {0};

// Declaration of a remote client's public keys.
// Assume they have already been generated.
extern remotePublicKeyX[32];
extern remotePublicKeyY[32];

// Fill localPrivateKey with 256 bits from a random number generator.
myRandomNumberGenerator(localPrivateKey, 32);

// Initialize ECC ROM driver
ECCROMCC26XX_init();

// Initialize this client's ECCROMCC26XX parameters.
ECCROMCC26XX_Params_init(&params);

// Generate public keys
ECCROMCC26XX_genKeys(localPrivateKey, localPublicKeyX,
                     localPublicKeyY, &params);

// Generate shared secret.
// Note: given your local Public Keys, the remote device can generate the
// same shared secret using its local private key.
ECCROMCC26XX_genDHKey(localPrivateKey, remotePublicKeyX,
                      remotePublicKeyY, sharedSecretKeyX,
                      sharedSecretKeyY, &params);

Supported transaction modes

• All key generation functions are blocking.

Error handling

If an error occur during key generation, an error status will be returned and stored in the status field of the ECCROMCC26XX_Params instance passed as an argument.

Supported Functions

API function	Description
ECCROMCC26XX_init()	Initializes module's synchronization resources
ECCROMCC26XX_Params_init()	Initialize parameters for Key Generation
ECCROMCC26XX_genKeys()	Generate Public Key X and Y Coordinates
ECCROMCC26XX_genDHKey()	Generate Diffie-Hellman Shared Secret

Unsupported functions:

Functionality that currently not supported:

- ECDSA Sign and Verify.

Macro Definition Documentation

ECCROMCC26XX_NIST_P256_KEY_LEN_IN_BYTES

#define ECCROMCC26XX_NIST_P256_KEY_LEN_IN_BYTES   32

ECC key length in bytes for NIST P-256 keys.

ECCROMCC26XX_NIST_P256_WORKZONE_LEN_IN_BYTES

#define ECCROMCC26XX_NIST_P256_WORKZONE_LEN_IN_BYTES   684

ECC Workzone length in bytes for NIST P-256 key and shared secret generation. For use with ECC Window Size 3 only. Used to store intermediary values in ECC calculations.

ECCROMCC26XX_WORKZONE_LEN_IN_BYTES

#define ECCROMCC26XX_WORKZONE_LEN_IN_BYTES	(		len,
			win
	)		(4 * ((13 * (len)) + 13 + (3 * (len) * (1 << ((win) - 2)))))

Compute ECC workzone length in bytes for a generic key length and window size.

len is the length of the key in uint32_t blocks. it must not exceed 255 blocks in length. win is the window size, such that 1 < win < 6. Recommended setting is 3.

This workzone length is only valid for key and shared secret and signature generation. A different workzone length would be used for verification.

Typedef Documentation

ECCROMCC26XX_CurveParams

typedef struct ECCROMCC26XX_CurveParams ECCROMCC26XX_CurveParams

ECCROMCC26XX Curve Parameters.

This holds the ECC Curve information to be used. Offset 0 of each param_* buffer contains the length of each parameter in uint32_t blocks, not including the first offset.

ECCROMCC26XX_FreeCB

typedef void(* ECCROMCC26XX_FreeCB) (uint8_t *pBuf)

ECCROMCC26XX Free Callback.

Required to free temporary key buffers during operation.

Parameters

pBuf	- pointer to buffer to free.

Returns

none

ECCROMCC26XX_MallocCB

typedef uint8_t*(* ECCROMCC26XX_MallocCB) (uint16_t len)

ECCROMCC26XX Malloc Callback.

Required to malloc temporary key buffers during operation.

Parameters

len	- length in bytes of buffer to malloc.

Returns

pointer to allocated buffer

ECCROMCC26XX_Params

typedef struct ECCROMCC26XX_Params ECCROMCC26XX_Params

ECCROMCC26XX Parameters.

Holds a client's parameters for performing an ECC operation.

Function Documentation

ECCROMCC26XX_genDHKey()

int8_t ECCROMCC26XX_genDHKey	(	uint8_t *	privateKey,
		uint8_t *	publicKeyX,
		uint8_t *	publicKeyY,
		uint8_t *	dHKeyX,
		uint8_t *	dHKeyY,
		ECCROMCC26XX_Params *	params
	)

Generate Diffie-Hellman Shared Secret Key X and Y Coordinates.

Precondition

ECCROMCC26XX_init must be called prior to this and params must be initialized with ECCROMCC26XX_Params_init(). Calling context: Task. Swi or Hwi should call only when timeout is set to 0.

Parameters

privateKey	32 byte input buffer of randomly generated bits.
publicKeyX	32 byte input buffer provided by client to store Public Key X Coordinate.
publicKeyY	32 byte input buffer provided by client to store Public Key Y Coordinate.
dHKeyX	32 byte output buffer provided by client to store Diffie-Hellman Key X Coordinate.
dHKeyY	32 byte output buffer provided by client to store Diffie-Hellman Key Y Coordinate.
params	Pointer to a parameter block, if NULL operation will fail

Returns

status

ECCROMCC26XX_genKeys()

int8_t ECCROMCC26XX_genKeys	(	uint8_t *	privateKey,
		uint8_t *	publicKeyX,
		uint8_t *	publicKeyY,
		ECCROMCC26XX_Params *	params
	)

Generate Public Key X and Y Coordinates.

Precondition

ECCROMCC26XX_init must be called prior to this and params must be initialized with ECCROMCC26XX_Params_init(). Calling context: Task. Swi or Hwi should call only when timeout is set to 0.

Parameters

privateKey	32 byte input buffer of randomly generated bits.
publicKeyX	32 byte output buffer provided by client to store Public Key X Coordinate.
publicKeyY	32 byte output buffer provided by client to store Public Key Y Coordinate.
params	Pointer to a parameter block, if NULL operation will fail.

Returns

status

ECCROMCC26XX_init()

void ECCROMCC26XX_init

(

void

)

Initializes module's synchronization resources. Only needs to be called once, but safe to call multiple times.

Precondition

This function must be called before any other ECCROMCC26XX driver APIs. Calling context: Task.

ECCROMCC26XX_Params_init()

void ECCROMCC26XX_Params_init

(

ECCROMCC26XX_Params *

params

)

Function to initialize the ECCROMCC26XX_Params struct to its defaults. params should not be modified until after this function is called. Default parameters use the NIST P-256 curve, timeout is set to wait indefinitely, malloc and free are NULL and status is set to ECCROMCC26XX_STATUS_SUCCESS. A client may call this function with the same params instance any number of times.

Precondition

Calling context: Hwi, Swi and Task.

Parameters

params

Parameter structure to initialize.