ECIES driver header.
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 |
Before starting a ECIES operation, the application must do the following:
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().
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/ANSIX936KDF.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>
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... | |
#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 ECIES_STATUS_SUCCESS ((int_fast16_t)0) |
Successful status code.
Functions return ECIES_STATUS_SUCCESS if the function was executed successfully.
#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.
#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.
#define ECIES_STATUS_INSUFFICIENT_OUTPUT_LENGTH ((int_fast16_t)-3) |
An error status code returned if the output length is insufficient.
#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.
#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.
#define ECIES_TAG_SIZE 16U |
ECIES authentication tag size in bytes.
#define ECCParams_NISTP256_LENGTH 32U |
Length of NIST P256 curve parameters in bytes.
#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)
#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 ECIES_Config* ECIES_Handle |
A handle that is returned from an ECIES_open() call.
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 |
void ECIES_init | ( | void | ) |
Initializes the ECIES driver module.
void ECIES_Params_init | ( | ECIES_Params * | params | ) |
Initializes params
with default values.
params | A pointer to ECIES_Params structure for initialization. |
Default values:
returnBehavior = ECIES_RETURN_BEHAVIOR_POLLING
timeout = SemaphoreP_WAIT_FOREVER
ECIES_Handle ECIES_open | ( | uint_least8_t | index, |
const ECIES_Params * | params | ||
) |
Initializes a ECIES driver instance and returns a handle.
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. |
void ECIES_close | ( | ECIES_Handle | handle | ) |
Closes a ECIES peripheral specified by handle
.
handle | A ECIES_Handle returned from ECIES_open() |
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).
paddedOutput
will be padded with ECIES_PADDING_BYTES of zeros. This padding must be discarded by the application.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). |
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. |
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).
paddedInput
must be padded with ECIES_PADDING_BYTES of zeros.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. |
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. |
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.
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. |
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.
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.
const ECIES_Params ECIES_defaultParams |
Default ECIES_Params structure.