Detailed Description

ECIES driver header.

Overview

The Elliptic Curve Integrated Encryption Scheme (ECIES) driver provides a public-key encryption scheme based on Elliptic Curve Cryptography. This driver supports the ECIES implementation defined in the SEC-1 v2.0 standard https://www.secg.org/sec1-v2.pdf except the cipher and MAC functions were changed to use AES-128-GCM:

Function	Implementation
Key Agreement	ECDH NIST P-256
KDF	ANSI X9.63
Hash	SHA-256
Cipher	AES-128-GCM
MAC	AES-128-GCM

Usage

Before starting a ECIES operation, the application must do the following:

Call ECIES_init() to initialize the driver.
Call ECIES_Params_init() to initialize the ECIES_Params to default values.
Modify the ECIES_Params as desired.
Call ECIES_open() to open an instance of the driver.

Synopsis

// Import ECIES Driver definitions
#include <ti/drivers/ECIES.h>
// Import driver configuration
#include "ti_drivers_config.h"
// Initialize driver
ECIES_init();
// Open driver instance
handle = ECIES_open(CONFIG_ECIES_0, NULL);
// Perform ECIES encryption
result = ECIES_encrypt(handle, &publicKey, input, sizeof(input), output, sizeof(output));
// Close driver instance
ECIES_close(handle);

Example

The ECIES_encrypt() function performs an ECIES encryption operation in a single call.

After an ECIES operation completes, the application may either start another operation or close the driver by calling ECIES_close().

#define INPUT_SIZE 24
CryptoKey publicKey;
ECIES_Params params;
ECIES_Handle handle;
int_fast16_t result;
uint8_t sharedInfo[] = {0x75, 0xee, 0xf8, 0x1a, 0xa3, 0x04, 0x1e, 0x33,
                        0xb8, 0x09, 0x71, 0x20, 0x3d, 0x2c, 0x0c, 0x52};
uint8_t input[INPUT_SIZE] = {0x22, 0x51, 0x8b, 0x10, 0xe7, 0x0f, 0x2a, 0x3f,
                             0x24, 0x38, 0x10, 0xae, 0x32, 0x54, 0x13, 0x9e,
                             0xfb, 0xee, 0x04, 0xaa, 0x57, 0xc7, 0xaf, 0x7d};
uint8_t output[ECIES_PADDING_BYTES + ECIES_PUBLIC_KEY_SIZE + INPUT_SIZE + ECIES_TAG_SIZE];
uint8_t publicKeyMaterial[] = {0x04,
                               // X coordinate
                               0x33,0x91,0x50,0x84,0x4E,0xC1,0x52,0x34,
                               0x80,0x7F,0xE8,0x62,0xA8,0x6B,0xE7,0x79,
                               0x77,0xDB,0xFB,0x3A,0xE3,0xD9,0x6F,0x4C,
                               0x22,0x79,0x55,0x13,0xAE,0xAA,0xB8,0x2F,
                               // Y coordinate
                               0xB1,0xC1,0x4D,0xDF,0xDC,0x8E,0xC1,0xB2,
                               0x58,0x3F,0x51,0xE8,0x5A,0x5E,0xB3,0xA1,
                               0x55,0x84,0x0F,0x20,0x34,0x73,0x0E,0x9B,
                               0x5A,0xDA,0x38,0xB6,0x74,0x33,0x6A,0x21};
// RNG initialization should be handled by the application after the RNG
// driver is seeded with the noise input from Radio Control Layer.
ECIES_init();
ECIES_Params_init(&params);
params.returnBehavior = ECIES_RETURN_BEHAVIOR_POLLING;
handle = ECIES_open(CONFIG_ECIES_0, &params);
assert(handle != NULL);
CryptoKeyPlaintext_initKey(&publicKey, publicKeyMaterial, sizeof(publicKeyMaterial));
result = ECIES_encrypt(handle, &publicKey, input, sizeof(input), output, sizeof(output));
assert(result == ECIES_STATUS_SUCCESS);
ECIES_close(handle);

#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/ANSIX936KDF.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>

Include dependency graph for ECIES.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ECIES_Config
	ECIES Global configuration. More...

struct	ECIES_Params
	ECIES Parameters. More...

Macros
#define	ECIES_STATUS_RESERVED ((int_fast16_t)-32)

#define	ECIES_STATUS_SUCCESS ((int_fast16_t)0)
	Successful status code. More...

#define	ECIES_STATUS_ERROR ((int_fast16_t)-1)
	Generic error status code. More...

#define	ECIES_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2)
	An error status code returned if the hardware or software resource is currently unavailable. More...

#define	ECIES_STATUS_INSUFFICIENT_OUTPUT_LENGTH ((int_fast16_t)-3)
	An error status code returned if the output length is insufficient. More...

#define	ECIES_STATUS_MAC_INVALID ((int_fast16_t)-4)
	An error status code returned if the MAC provided by the application for a decryption operation does not match the one calculated during the operation. More...

#define	ECIES_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED
	The operation does not support non-word-aligned input and/or output. More...

#define	ECIES_TAG_SIZE 16U
	ECIES authentication tag size in bytes. More...

#define	ECCParams_NISTP256_LENGTH 32U
	Length of NIST P256 curve parameters in bytes. More...

#define	ECIES_PUBLIC_KEY_SIZE (1U + (2U * ECCParams_NISTP256_LENGTH))
	ECIES public key size in bytes. More...

#define	ECIES_PADDING_BYTES 3U
	ECIES padding size in bytes. More...

Typedefs
typedef ECIES_Config *	ECIES_Handle
	A handle that is returned from an ECIES_open() call. More...

Enumerations
enum	ECIES_ReturnBehavior { ECIES_RETURN_BEHAVIOR_BLOCKING = 2, ECIES_RETURN_BEHAVIOR_POLLING = 4 }
	The way in which ECIES function calls return after performing an operation. More...

Functions
void	ECIES_init (void)
	Initializes the ECIES driver module. More...

void	ECIES_Params_init (ECIES_Params *params)
	Initializes `params` with default values. More...

ECIES_Handle	ECIES_open (uint_least8_t index, const ECIES_Params *params)
	Initializes a ECIES driver instance and returns a handle. More...

void	ECIES_close (ECIES_Handle handle)
	Closes a ECIES peripheral specified by `handle`. More...

int_fast16_t	ECIES_encrypt (ECIES_Handle handle, const CryptoKey publicKey, const void input, size_t inputLen, void *paddedOutput, size_t paddedOutputLen)
	Performs ECIES encryption of a message. More...

int_fast16_t	ECIES_decrypt (ECIES_Handle handle, const CryptoKey privateKey, const void paddedInput, size_t paddedInputLen, void *output, size_t outputLen)
	Performs ECIES decryption of a message. More...

ECIES_Handle	ECIES_construct (ECIES_Config config, const ECIES_Params params)
	Constructs a new ECIES object. More...

Variables
const ECIES_Config	ECIES_config []
	Global ECIES configuration struct. More...

const uint_least8_t	ECIES_count
	Global ECIES configuration count. More...

const ECIES_Params	ECIES_defaultParams
	Default ECIES_Params structure. More...

Macro Definition Documentation

§ ECIES_STATUS_RESERVED

#define ECIES_STATUS_RESERVED ((int_fast16_t)-32)

Common ECIES status code reservation offset. ECIES driver implementations should offset status codes with ECIES_STATUS_RESERVED growing negatively.

Example implementation specific status codes:

#define ECIESXYZ_STATUS_ERROR0    ECIES_STATUS_RESERVED - 0
#define ECIESXYZ_STATUS_ERROR1    ECIES_STATUS_RESERVED - 1
#define ECIESXYZ_STATUS_ERROR2    ECIES_STATUS_RESERVED - 2

§ ECIES_STATUS_SUCCESS

#define ECIES_STATUS_SUCCESS ((int_fast16_t)0)

Successful status code.

Functions return ECIES_STATUS_SUCCESS if the function was executed successfully.

§ ECIES_STATUS_ERROR

#define ECIES_STATUS_ERROR ((int_fast16_t)-1)

Generic error status code.

Functions return ECIES_STATUS_ERROR if the function was not executed successfully and no more specific error is applicable.

§ ECIES_STATUS_RESOURCE_UNAVAILABLE

#define ECIES_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2)

An error status code returned if the hardware or software resource is currently unavailable.

ECIES 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.

§ ECIES_STATUS_INSUFFICIENT_OUTPUT_LENGTH

#define ECIES_STATUS_INSUFFICIENT_OUTPUT_LENGTH ((int_fast16_t)-3)

An error status code returned if the output length is insufficient.

§ ECIES_STATUS_MAC_INVALID

#define ECIES_STATUS_MAC_INVALID ((int_fast16_t)-4)

An error status code returned if the MAC provided by the application for a decryption operation does not match the one calculated during the operation.

This code is returned by ECIES_decrypt() if the verification of the MAC fails.

§ ECIES_STATUS_UNALIGNED_IO_NOT_SUPPORTED

#define ECIES_STATUS_UNALIGNED_IO_NOT_SUPPORTED AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED

The operation does not support non-word-aligned input and/or output.

ECIES driver implementations may have restrictions on the alignment of input/output data due to performance limitations of the hardware.

§ ECIES_TAG_SIZE

#define ECIES_TAG_SIZE 16U

ECIES authentication tag size in bytes.

§ ECCParams_NISTP256_LENGTH

#define ECCParams_NISTP256_LENGTH 32U

Length of NIST P256 curve parameters in bytes.

§ ECIES_PUBLIC_KEY_SIZE

#define ECIES_PUBLIC_KEY_SIZE (1U + (2U * ECCParams_NISTP256_LENGTH))

ECIES public key size in bytes.

The size of the ECIES public key in uncompressed octet string format (0x04 || x || y)

§ ECIES_PADDING_BYTES

#define ECIES_PADDING_BYTES 3U

ECIES padding size in bytes.

The beginning of the input to ECIES_decrypt and the beginning of the output to ECIES_encrypt must be padded with 3-bytes in order to word-align the ciphertext or plaintext as required by the AESGCMLPF3 driver.

Typedef Documentation

§ ECIES_Handle

typedef ECIES_Config* ECIES_Handle

A handle that is returned from an ECIES_open() call.

Enumeration Type Documentation

§ ECIES_ReturnBehavior

enum ECIES_ReturnBehavior

The way in which ECIES function calls return after performing an operation.

Not all ECIES operations exhibit the specified return behavior. Functions that do not require significant computation and cannot offload that computation to a background thread behave like regular functions. Which functions exhibit the specified 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.

ECIES functions exhibiting the specified return behavior have restrictions on the context from which they may be called.

	Task	Hwi	Swi
ECIES_RETURN_BEHAVIOR_BLOCKING	X
ECIES_RETURN_BEHAVIOR_POLLING	X	X	X

Enumerator
ECIES_RETURN_BEHAVIOR_BLOCKING	The function call will block while the ECIES operation goes on in the background. ECIES operation results are available after the function returns.
ECIES_RETURN_BEHAVIOR_POLLING	The function call will continuously poll a flag while the ECIES operation goes on in the background. ECIES operation results are available after the function returns.

Function Documentation

§ ECIES_init()

void ECIES_init ( void )

Initializes the ECIES driver module.

Precondition: The ECIES_config structure must exist and be persistent before this function can be called. This function must also be called before any other ECIES driver APIs. This function call does not modify any peripheral registers.

§ ECIES_Params_init()

void ECIES_Params_init ( ECIES_Params * params )

Initializes params with default values.

Parameters

params A pointer to ECIES_Params structure for initialization.

Default values:
returnBehavior = ECIES_RETURN_BEHAVIOR_POLLING
timeout = SemaphoreP_WAIT_FOREVER

§ ECIES_open()

ECIES_Handle ECIES_open	(	uint_least8_t	index,
		const ECIES_Params *	params
	)

Initializes a ECIES driver instance and returns a handle.

Warning: The return behavior specified in the ECIES_Params struct must match the RNG's global return behavior setting for this function to succeed.

Precondition: ECIES controller has been initialized using ECIES_init()

Parameters

index	Logical peripheral number for the ECIES indexed into the ECIES_config table.
params	Pointer to a ECIES_Params struct, if NULL it will use default values.

Returns: A ECIES_Handle on success, otherwise NULL if an error occurs or if the driver instance has been opened already.

See also: ECIES_init(); ECIES_close()

§ ECIES_close()

void ECIES_close ( ECIES_Handle handle )

Closes a ECIES peripheral specified by handle.

Precondition: ECIES_open() has to be called first.

Parameters

handle A ECIES_Handle returned from ECIES_open()

See also: ECIES_open()

§ ECIES_encrypt()

int_fast16_t ECIES_encrypt	(	ECIES_Handle	handle,
		const CryptoKey *	publicKey,
		const void *	input,
		size_t	inputLen,
		void *	paddedOutput,
		size_t	paddedOutputLen
	)

Performs ECIES encryption of a message.

Performs authenticated encryption (AES-128-GCM) of a message to a NIST P-256 public key which is used to derive the AES-128-GCM encryption key and Initialization Vector (IV).

Note: The paddedOutput will be padded with ECIES_PADDING_BYTES of zeros. This padding must be discarded by the application.

Precondition: ECIES_open() has to be called first.

Parameters

handle	A ECIES_Handle returned from ECIES_open().
publicKey	A pointer to the NIST P-256 public key in uncompressed octet string format and big-endian byte order.
input	A pointer to the input buffer containing the data to encrypt.
inputLen	The length of `input` in bytes.
paddedOutput	A pointer to the location to write the output (pad \|\| Q \|\| C \|\| T) where pad is ECIES_PADDING_BYTES of zeros, Q is the public key, C is the ciphertext, and T is the authentication tag.
paddedOutputLen	Output buffer length in bytes. It should be at least (ECIES_PADDING_BYTES + ECIES_PUBLIC_KEY_SIZE + inputLen + ECIES_TAG_SIZE).

Return values

ECIES_STATUS_SUCCESS	The operation succeeded.
ECIES_STATUS_ERROR	The operation failed.
ECIES_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
ECIES_STATUS_INSUFFICIENT_OUTPUT_LENGTH	The outputLen is insufficient to write the output.
ECIES_STATUS_UNALIGNED_IO_NOT_SUPPORTED	The input and/or output buffer were not word-aligned.

See also: ECIES_open()

§ ECIES_decrypt()

int_fast16_t ECIES_decrypt	(	ECIES_Handle	handle,
		const CryptoKey *	privateKey,
		const void *	paddedInput,
		size_t	paddedInputLen,
		void *	output,
		size_t	outputLen
	)

Performs ECIES decryption of a message.

Performs authenticated decryption (AES-128-GCM) of a message to a NIST P-256 private key which is used to derive the AES-128-GCM decryption key and Initialization Vector (IV).

Note: The paddedInput must be padded with ECIES_PADDING_BYTES of zeros.

Precondition: ECIES_open() has to be called first.

Parameters

handle	A ECIES_Handle returned from ECIES_open().
privateKey	A pointer to the NIST P-256 private key in uncompressed octet string format and big-endian byte order.
paddedInput	A pointer to the input buffer containing (pad \|\| Q \|\| C \|\| T) where pad is ECIES_PADDING_BYTES of zeros, Q is the public key, C is the ciphertext, and T is the authentication tag.
paddedInputLen	The length of `input` in bytes.
output	A pointer to the location to write the output plaintext.
outputLen	Output buffer length in bytes. It should be at least inputLen - ECIES_PUBLIC_KEY_SIZE - ECIES_TAG_SIZE - ECIES_PADDING_BYTES.

Return values

ECIES_STATUS_SUCCESS	The operation succeeded.
ECIES_STATUS_ERROR	The operation failed.
ECIES_STATUS_RESOURCE_UNAVAILABLE	The required hardware resource was not available. Try again later.
ECIES_STATUS_INSUFFICIENT_OUTPUT_LENGTH	The outputLen is insufficient to write the output.
ECIES_STATUS_UNALIGNED_IO_NOT_SUPPORTED	The input and/or output buffer were not word-aligned.
ECIES_STATUS_MAC_INVALID	The provided authentication tag did not match the recomputed one.

See also: ECIES_open()

§ ECIES_construct()

ECIES_Handle ECIES_construct	(	ECIES_Config *	config,
		const ECIES_Params *	params
	)

Constructs a new ECIES object.

Unlike ECIES_open(), ECIES_construct() does not require the hwAttrs and object to be allocated in a ECIES_Config array that is indexed into. Instead, the ECIES_Config, hwAttrs, and object can be allocated at any location. This allows for relatively simple run-time allocation of temporary driver instances on the stack or the heap. The drawback is that this makes it more difficult to write device-agnostic code. If you use an ifdef with DeviceFamily, you can choose the correct object and hwAttrs to allocate. That compilation unit will be tied to the device it was compiled for at this point. To change devices, recompilation of the application with a different DeviceFamily setting is necessary.

Precondition: The ECIES_Config struct must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue.

Warning: The return behavior specified in the ECIES_Params struct must match the RNG's global return behavior setting for this function to succeed.

Parameters

config	A pointer to a ECIES_Config struct describing the location of the object and hwAttrs.
params	A pointer to a ECIES_Params struct to configure the driver instance.

Returns: Returns a ECIES_Handle on success or NULL on failure.

Variable Documentation

§ ECIES_config

const ECIES_Config ECIES_config[]

Global ECIES configuration struct.

Specifies context objects and hardware attributes for every driver instance.

This variable is supposed to be defined in the board file.

§ ECIES_count

const uint_least8_t ECIES_count

Global ECIES configuration count.

Specifies the number of available ECIES driver instances.

This variable is supposed to be defined in the board file.

§ ECIES_defaultParams

const ECIES_Params ECIES_defaultParams

Default ECIES_Params structure.

See also: ECIES_Params_init()

Detailed Description

Overview

Usage

Synopsis

Example

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

§ ECIES_STATUS_RESERVED

§ ECIES_STATUS_SUCCESS

§ ECIES_STATUS_ERROR

§ ECIES_STATUS_RESOURCE_UNAVAILABLE

§ ECIES_STATUS_INSUFFICIENT_OUTPUT_LENGTH

§ ECIES_STATUS_MAC_INVALID

§ ECIES_STATUS_UNALIGNED_IO_NOT_SUPPORTED

§ ECIES_TAG_SIZE

§ ECCParams_NISTP256_LENGTH

§ ECIES_PUBLIC_KEY_SIZE

§ ECIES_PADDING_BYTES

Typedef Documentation

§ ECIES_Handle

Enumeration Type Documentation

§ ECIES_ReturnBehavior

Function Documentation

§ ECIES_init()

§ ECIES_Params_init()

§ ECIES_open()

§ ECIES_close()

§ ECIES_encrypt()

§ ECIES_decrypt()

§ ECIES_construct()

Variable Documentation

§ ECIES_config

§ ECIES_count

§ ECIES_defaultParams