TI Driver for Elliptic Curve Digital Signature Algorithm.
The Elliptic Curve Digital Signature Algorithm (ECDSA) is a message authentication scheme between two parties based on operation on elliptic curves over finite fields.
Signing a message with ECDSA proves to the recipient that the sender of the message is in possession of the private key corresponding to the transmitted public key used during verification. For most practical systems, this ensures message authentication and integrity.
Before starting an ECDSA operation, the application must do the following:
To sign a message using an agreed upon hash function and elliptic curve, the application must do the following:
After receiving the message, public key, r, and s, the application should do the following to verify the signature:
The API expects elliptic curves as defined in ti/drivers/cryptoutils/ecc/ECCParams.h. Several commonly used curves are provided. Check the device-specific ECDSA documentation for curve type (short Weierstrass, Montgomery, Edwards) support for your device. ECDSA support for a curve type on a device does not imply curve-type support for other ECC schemes.
Public keys 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. This API uses points expressed in uncompressed affine coordinates by default and formatted in octet string format. The octet string format requires a formatting byte in the first byte of the public key. When using uncompressed coordinates, this is the value 0x04. The point itself is stored as a concatenated array of X followed by Y. X and Y are big-endian.
This API accepts and returns the keying material of public keys according to the following table:
Curve Type | PublicKeying Material Array | Array Length |
---|---|---|
Short Weierstrass | [0x04, X, Y] | 1 + 2 * Curve Param Length |
Montgomery | [0x04, X, Y] | 1 + 2 * Curve Param Length |
Edwards | [0x04, X, Y] | 1 + 2 * Curve Param Length |
The signature components r and s as well as the hash must be formatted in octet string format. For the hash, this simply means passing the digest of the hash function such as SHA-256 directly into ECDSA_sign() or ECDSA_verify(). r and s will be interpreted as big-endian integers.
#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 | ECDSA_Config |
ECDSA Global configuration. More... | |
struct | ECDSA_OperationSign |
Struct containing the parameters required for signing a message. More... | |
struct | ECDSA_OperationVerify |
Struct containing the parameters required for verifying a message. More... | |
union | ECDSA_Operation |
Union containing pointers to all supported operation structs. More... | |
struct | ECDSA_Params |
ECDSA Parameters. More... | |
Macros | |
#define | ECDSA_STATUS_RESERVED (-32) |
#define | ECDSA_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | ECDSA_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | ECDSA_STATUS_RESOURCE_UNAVAILABLE (-2) |
An error status code returned if the hardware or software resource is currently unavailable. More... | |
#define | ECDSA_STATUS_R_LARGER_THAN_ORDER (-3) |
The r value passed in is larger than the order of the curve. More... | |
#define | ECDSA_STATUS_S_LARGER_THAN_ORDER (-4) |
The s value passed in is larger than the order of the curve. More... | |
#define | ECDSA_STATUS_PUBLIC_KEY_NOT_ON_CURVE (-5) |
The public key of the other party does not lie upon the curve. More... | |
#define | ECDSA_STATUS_PUBLIC_KEY_LARGER_THAN_PRIME (-6) |
A coordinate of the public key of the other party is too large. More... | |
#define | ECDSA_STATUS_POINT_AT_INFINITY (-7) |
The public key to verify against is the point at infinity. More... | |
#define | ECDSA_STATUS_CANCELED (-8) |
The ongoing operation was canceled. More... | |
#define | ECDSA_STATUS_INVALID_KEY_SIZE (-10) |
The provided CryptoKey does not match the expected size. More... | |
Typedefs | |
typedef ECDSA_Config * | ECDSA_Handle |
A handle that is returned from an ECDSA_open() call. More... | |
typedef void(* | ECDSA_CallbackFxn) (ECDSA_Handle handle, int_fast16_t returnStatus, ECDSA_Operation operation, ECDSA_OperationType operationType) |
The definition of a callback function used by the ECDSA driver when used in ECDSA_RETURN_BEHAVIOR_CALLBACK. More... | |
Enumerations | |
enum | ECDSA_ReturnBehavior { ECDSA_RETURN_BEHAVIOR_CALLBACK = 1, ECDSA_RETURN_BEHAVIOR_BLOCKING = 2, ECDSA_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which ECDSA function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
enum | ECDSA_OperationType { ECDSA_OPERATION_TYPE_SIGN = 1, ECDSA_OPERATION_TYPE_VERIFY = 2 } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | ECDSA_init (void) |
This function initializes the ECDSA module. More... | |
void | ECDSA_close (ECDSA_Handle handle) |
Function to close an ECDSA peripheral specified by the ECDSA handle. More... | |
ECDSA_Handle | ECDSA_open (uint_least8_t index, const ECDSA_Params *params) |
This function opens a given ECDSA peripheral. More... | |
void | ECDSA_Params_init (ECDSA_Params *params) |
Function to initialize the ECDSA_Params struct to its defaults. More... | |
void | ECDSA_OperationSign_init (ECDSA_OperationSign *operation) |
Function to initialize an ECDSA_OperationSign struct to its defaults. More... | |
void | ECDSA_OperationVerify_init (ECDSA_OperationVerify *operation) |
Function to initialize an ECDSA_OperationSign struct to its defaults. More... | |
int_fast16_t | ECDSA_sign (ECDSA_Handle handle, ECDSA_OperationSign *operation) |
Signs a hashed message. More... | |
int_fast16_t | ECDSA_verify (ECDSA_Handle handle, ECDSA_OperationVerify *operation) |
Verifies a received signature matches a hash and public key. More... | |
int_fast16_t | ECDSA_cancelOperation (ECDSA_Handle handle) |
Cancels an ongoing ECDSA operation. More... | |
ECDSA_Handle | ECDSA_construct (ECDSA_Config *config, const ECDSA_Params *params) |
Constructs a new ECDSA object. More... | |
Variables | |
const ECDSA_Params | ECDSA_defaultParams |
Default ECDSA_Params structure. More... | |
#define ECDSA_STATUS_RESERVED (-32) |
Common ECDSA status code reservation offset. ECDSA driver implementations should offset status codes with ECDSA_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define ECDSA_STATUS_SUCCESS (0) |
Successful status code.
Functions return ECDSA_STATUS_SUCCESS if the function was executed successfully.
#define ECDSA_STATUS_ERROR (-1) |
Generic error status code.
Functions return ECDSA_STATUS_ERROR if the function was not executed successfully.
#define ECDSA_STATUS_RESOURCE_UNAVAILABLE (-2) |
An error status code returned if the hardware or software resource is currently unavailable.
ECDSA 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 ECDSA_STATUS_R_LARGER_THAN_ORDER (-3) |
The r value passed in is larger than the order of the curve.
Signature components (r and s) must be integers in the interval [1, n - 1], where n is the order of the curve.
#define ECDSA_STATUS_S_LARGER_THAN_ORDER (-4) |
The s value passed in is larger than the order of the curve.
Signature components (r and s) must be integers in the interval [1, n - 1], where n is the order of the curve.
#define ECDSA_STATUS_PUBLIC_KEY_NOT_ON_CURVE (-5) |
The public key of the other party does not lie upon the curve.
The public key received from the other party does not lie upon the agreed upon curve.
#define ECDSA_STATUS_PUBLIC_KEY_LARGER_THAN_PRIME (-6) |
A coordinate of the public key of the other party is too large.
A coordinate of the public key received from the other party is larger than the prime of the curve. This implies that the point was not correctly generated on that curve.
#define ECDSA_STATUS_POINT_AT_INFINITY (-7) |
The public key to verify against is the point at infinity.
The point at infinity is not a valid input.
#define ECDSA_STATUS_CANCELED (-8) |
The ongoing operation was canceled.
#define ECDSA_STATUS_INVALID_KEY_SIZE (-10) |
The provided CryptoKey does not match the expected size.
The driver expects the private key to have the same length as other curve parameters and the public key to have a length of twice that plus one. If the provided CryptoKeys for the public and private keys do not match this scheme, this error will be returned.
typedef ECDSA_Config* ECDSA_Handle |
A handle that is returned from an ECDSA_open() call.
typedef void(* ECDSA_CallbackFxn) (ECDSA_Handle handle, int_fast16_t returnStatus, ECDSA_Operation operation, ECDSA_OperationType operationType) |
The definition of a callback function used by the ECDSA driver when used in ECDSA_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the ECDSA operation. |
returnStatus | The result of the ECDSA 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. |
enum ECDSA_ReturnBehavior |
The way in which ECDSA function calls return after performing an encryption + authentication or decryption + verification operation.
Not all ECDSA operations exhibit the specified return behavor. Functions that do not require significant computation and cannot offload that computation to a background threadbehave 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.
ECDSA functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
ECDSA_RETURN_BEHAVIOR_CALLBACK | X | X | X |
ECDSA_RETURN_BEHAVIOR_BLOCKING | X | ||
ECDSA_RETURN_BEHAVIOR_POLLING | X | X | X |
enum ECDSA_OperationType |
void ECDSA_init | ( | void | ) |
This function initializes the ECDSA module.
void ECDSA_close | ( | ECDSA_Handle | handle | ) |
Function to close an ECDSA peripheral specified by the ECDSA handle.
handle | An ECDSA handle returned from ECDSA_open() |
ECDSA_Handle ECDSA_open | ( | uint_least8_t | index, |
const ECDSA_Params * | params | ||
) |
This function opens a given ECDSA peripheral.
index | Logical peripheral number for the ECDSA indexed into the ECDSA_config table |
params | Pointer to an parameter block, if NULL it will use default values. |
void ECDSA_Params_init | ( | ECDSA_Params * | params | ) |
Function to initialize the ECDSA_Params struct to its defaults.
params | An pointer to ECDSA_Params structure for initialization |
Defaults values are: returnBehavior = ECDSA_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
void ECDSA_OperationSign_init | ( | ECDSA_OperationSign * | operation | ) |
Function to initialize an ECDSA_OperationSign struct to its defaults.
operation | A pointer to ECDSA_OperationSign structure for initialization |
Defaults values are all zeros.
void ECDSA_OperationVerify_init | ( | ECDSA_OperationVerify * | operation | ) |
Function to initialize an ECDSA_OperationSign struct to its defaults.
operation | An pointer to ECDSA_OperationSign structure for initialization |
Defaults values are all zeros.
int_fast16_t ECDSA_sign | ( | ECDSA_Handle | handle, |
ECDSA_OperationSign * | operation | ||
) |
Signs a hashed message.
ECDSA_sign() generates a signature (r
, s
) of a hash
of a message.
operation
first. The driver must have been opened by calling ECDSA_open() first.[in] | handle | An ECDSA handle returned from ECDSA_open() |
[in] | operation | A struct containing the pointers to the buffers necessary to perform the operation |
ECDSA_STATUS_SUCCESS | The operation succeeded. |
ECDSA_STATUS_ERROR | The operation failed. |
ECDSA_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
ECDSA_STATUS_CANCELED | The operation was canceled. |
int_fast16_t ECDSA_verify | ( | ECDSA_Handle | handle, |
ECDSA_OperationVerify * | operation | ||
) |
Verifies a received signature matches a hash and public key.
operation
first. The driver must have been opened by calling ECDSA_open() first.[in] | handle | An ECDSA handle returned from ECDSA_open() |
[in] | operation | A struct containing the pointers to the buffers necessary to perform the operation |
ECDSA_STATUS_SUCCESS | The operation succeeded. |
ECDSA_STATUS_ERROR | The operation failed. This is the return status if the signature did not match. |
ECDSA_STATUS_RESOURCE_UNAVAILABLE | The required hardware resource was not available. Try again later. |
ECDSA_STATUS_CANCELED | The operation was canceled. |
ECDSA_STATUS_R_LARGER_THAN_ORDER | The r value passed in is larger than the order of the curve. |
ECDSA_STATUS_S_LARGER_THAN_ORDER | The s value passed in is larger than the order of the curve. |
ECDSA_STATUS_PUBLIC_KEY_NOT_ON_CURVE | The public key of the other party does not lie upon the curve. |
ECDSA_STATUS_PUBLIC_KEY_LARGER_THAN_PRIME | One of the public key coordinates is larger the the curve's prime. |
ECDSA_STATUS_POINT_AT_INFINITY | The public key to verify against is the point at infinity. |
int_fast16_t ECDSA_cancelOperation | ( | ECDSA_Handle | handle | ) |
Cancels an ongoing ECDSA operation.
Asynchronously cancels an ECDSA operation. Only available when using ECDSA_RETURN_BEHAVIOR_CALLBACK or ECDSA_RETURN_BEHAVIOR_BLOCKING. The operation will terminate as though an error occured. The return status code of the operation will be ECDSA_STATUS_CANCELED.
handle | Handle of the operation to cancel |
ECDSA_STATUS_SUCCESS | The operation was canceled. |
ECDSA_STATUS_ERROR | The operation was not canceled. There may be no operation to cancel. |
ECDSA_Handle ECDSA_construct | ( | ECDSA_Config * | config, |
const ECDSA_Params * | params | ||
) |
Constructs a new ECDSA object.
Unlike ECDSA_open(), ECDSA_construct() does not require the hwAttrs and object to be allocated in a ECDSA_Config array that is indexed into. Instead, the ECDSA_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 | ECDSA_Config describing the location of the object and hwAttrs. |
params | ECDSA_Params to configure the driver instance. |
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue. const ECDSA_Params ECDSA_defaultParams |
Default ECDSA_Params structure.