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.

Dependencies

This driver is dependent on TRNGCC26XX driver for random number generation. TRNGCC26XX driver should always be included in the project.

General Behavior

For code examples, see Use Cases below.

Initialzing 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);
// Generate signature for hashed message
// Given the local private key and hash, the remote device can generate 64
// byte signature split into two 32 byte buffers
uint8_t hash[32]  = {0};
uint8_t sign1[32]  = {0};
uint8_t sign1[32]  = {0};
// Fill with SHA256 hashed message
mySha2HashGenerator(hash);
ECCROMCC26XX_signHash(localPrivateKey,hash,32,sign1,sign2,&params)
// Verify signature for hashed message
// Given the local public keys, hash, and generated signature the remote
// device can verify the signature generated using the local private keys
ECCROMCC26XX_verifyHash(localPublicKeyX,localPublicKeyY,sign1,sign2,hash,
                        32,&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
ECCROMCC26XX_signHash()	Generates
ECCROMCC26XX_verifyHash()	Verifies a previously generated signature