TI Driver for Edwards Curve Digital Signature Algorithm.
The Edwards Curve Digital Signature Algorithm (EdDSA) is a message authentication scheme between two parties based on operation on Edwards curves over finite fields. This driver supports the PureEdDSA scheme for Edwards curve Ed25519 as is described in RFC 8032: https://tools.ietf.org/html/rfc8032 . EdDSA variants, such as Ed25519ph or Ed25519ctx are currently not supported.
Signing a message with EdDSA 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 EDDSA operation, the application must do the following:
To generate an Ed25519 public key, the application must do the following:
To sign a message using Ed25519, 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 Edwards elliptic curves as defined in ti/drivers/cryptoutils/ecc/ECCParams.h. Several commonly used curves are provided. Check the device-specific EDDSA documentation for curve type (short Weierstrass, Montgomery, Edwards) support for your device. EDDSA 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. For EDDSA, these points are represented in their compressed form. This API uses points expressed in compressed affine coordinates by default and formatted in little endian. The point itself is stored as Y in little endian. If the X-coordinate is odd, the most significant bit of the public key is set (that is 0x80 || y). Otherwise, the public key is simply y and the even choice of x-coordinate is selected.
This API accepts and returns the keying material of public keys according to the following table:
| Curve Type | PublicKeying Material Array | Array Length | |-----------------—|--------------------------—|-----------------—| | Ed25519 | [{0x80 or 0x00} || Y] | Curve Param Length |
The signature components R and S as well as the hash must be formatted in little endian format. For the hash, this simply means passing the digest of the hash function SHA-512 directly into EDDSA_sign() or EDDSA_verify(). R and S will be interpreted as little-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 | EDDSA_Config |
EDDSA Global configuration. More... | |
struct | EDDSA_OperationGeneratePublicKey |
Struct containing the parameters required for generating an EdDSA private-public keypair. More... | |
struct | EDDSA_OperationSign |
Struct containing the parameters required for generating an EdDSA digital signature. More... | |
struct | EDDSA_OperationVerify |
Struct containing the parameters required for verifying an EdDSA digital signature. More... | |
union | EDDSA_Operation |
Union containing pointers to all supported operation structs. More... | |
struct | EDDSA_Params |
EDDSA Parameters. More... | |
Macros | |
#define | EDDSA_STATUS_RESERVED (-32) |
#define | EDDSA_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | EDDSA_STATUS_ERROR (-1) |
Generic error status code. More... | |
#define | EDDSA_STATUS_CANCELED (-2) |
The ongoing operation was canceled. More... | |
#define | EDDSA_STATUS_HASH_UNAVAILABLE (-3) |
An error status code returned if the hash hardware or software resource is currently unavailable. More... | |
#define | EDDSA_STATUS_PKA_UNAVAILABLE (-4) |
An error status code returned if the public-key accelerator hardware or software resource is currently unavailable. More... | |
#define | EDDSA_STATUS_POINT_AT_INFINITY (-5) |
The generated public key was the point at infinity. More... | |
#define | EDDSA_STATUS_INVALID_PRIVATE_KEY_SIZE (-6) |
The private key was not 32 bytes long. More... | |
#define | EDDSA_STATUS_INVALID_PUBLIC_KEY_SIZE (-7) |
The public key was not 32 bytes long. More... | |
#define | EDDSA_STATUS_PUBLIC_KEY_NOT_ON_CURVE (-8) |
The public key was not a valid point on curve Ed25519. More... | |
#define | EDDSA_STATUS_INVALID_R_SIZE (-9) |
The Ed25519 signature component R was not 32 bytes long. More... | |
#define | EDDSA_STATUS_INVALID_S_SIZE (-10) |
The Ed25519 signature component S was not 32 bytes long. More... | |
#define | EDDSA_STATUS_S_LARGER_THAN_ORDER (-11) |
The Ed25519 signature component S was larger than the order of Ed25519. More... | |
#define | EDDSA_STATUS_KEY_ID_PARAM_MISMATCH (-12) |
The Ed25519 operation was called with conflicting private and public key ID parameters. More... | |
#define | EDDSA_STATUS_KEYSTORE_INVALID_ID (-13) |
The KeyStore module could not find a key with the given ID. More... | |
#define | EDDSA_STATUS_KEYSTORE_GENERIC_FAILURE (-14) |
The KeyStore module entered a failure state when retrieving the key ID. More... | |
#define | EDDSA_STATUS_SHA2_HASH_FAILURE (-15) |
The SHA2 module returned an error while hashing. More... | |
Typedefs | |
typedef EDDSA_Config * | EDDSA_Handle |
A handle that is returned from an EDDSA_open() call. More... | |
typedef void(* | EDDSA_CallbackFxn) (EDDSA_Handle handle, int_fast16_t returnStatus, EDDSA_Operation operation, EDDSA_OperationType operationType) |
The definition of a callback function used by the EDDSA driver when used in EDDSA_RETURN_BEHAVIOR_CALLBACK. More... | |
Enumerations | |
enum | EDDSA_ReturnBehavior { EDDSA_RETURN_BEHAVIOR_CALLBACK = 1, EDDSA_RETURN_BEHAVIOR_BLOCKING = 2, EDDSA_RETURN_BEHAVIOR_POLLING = 4 } |
The way in which EDDSA function calls return after performing an encryption + authentication or decryption + verification operation. More... | |
enum | EDDSA_OperationType { EDDSA_OPERATION_TYPE_GENERATE_PUBLIC_KEY = 1, EDDSA_OPERATION_TYPE_SIGN = 2, EDDSA_OPERATION_TYPE_VERIFY = 3 } |
Enum for the operation types supported by the driver. More... | |
Functions | |
void | EDDSA_init (void) |
This function initializes the EDDSA module. More... | |
void | EDDSA_close (EDDSA_Handle handle) |
Function to close an EDDSA peripheral specified by the EDDSA handle. More... | |
EDDSA_Handle | EDDSA_open (uint_least8_t index, const EDDSA_Params *params) |
This function opens a given EDDSA peripheral. More... | |
void | EDDSA_Params_init (EDDSA_Params *params) |
Function to initialize the EDDSA_Params struct to its defaults. More... | |
void | EDDSA_OperationGeneratePublicKey_init (EDDSA_OperationGeneratePublicKey *operation) |
Function to initialize an EDDSA_OperationGeneratePublicKey struct to its defaults. More... | |
void | EDDSA_OperationSign_init (EDDSA_OperationSign *operation) |
Function to initialize an EDDSA_OperationSign struct to its defaults. More... | |
void | EDDSA_OperationVerify_init (EDDSA_OperationVerify *operation) |
Function to initialize an EDDSA_OperationSign struct to its defaults. More... | |
int_fast16_t | EDDSA_generatePublicKey (EDDSA_Handle handle, EDDSA_OperationGeneratePublicKey *operation) |
Generates an EdDSA private-public keypair. More... | |
int_fast16_t | EDDSA_sign (EDDSA_Handle handle, EDDSA_OperationSign *operation) |
Generates an EdDSA signature. More... | |
int_fast16_t | EDDSA_verify (EDDSA_Handle handle, EDDSA_OperationVerify *operation) |
Verifies a received EdDSA signature matches a hash and public key. More... | |
int_fast16_t | EDDSA_cancelOperation (EDDSA_Handle handle) |
Cancels an ongoing EDDSA operation. More... | |
EDDSA_Handle | EDDSA_construct (EDDSA_Config *config, const EDDSA_Params *params) |
Constructs a new EDDSA object. More... | |
#define EDDSA_STATUS_RESERVED (-32) |
Common EDDSA status code reservation offset. EDDSA driver implementations should offset status codes with EDDSA_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define EDDSA_STATUS_SUCCESS (0) |
Successful status code.
Functions return EDDSA_STATUS_SUCCESS if the function was executed successfully.
#define EDDSA_STATUS_ERROR (-1) |
Generic error status code.
Functions return EDDSA_STATUS_ERROR if the function was not executed successfully.
#define EDDSA_STATUS_CANCELED (-2) |
The ongoing operation was canceled.
#define EDDSA_STATUS_HASH_UNAVAILABLE (-3) |
An error status code returned if the hash hardware or software resource is currently unavailable.
EDDSA 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 because the hash module is unavailable.
#define EDDSA_STATUS_PKA_UNAVAILABLE (-4) |
An error status code returned if the public-key accelerator hardware or software resource is currently unavailable.
EDDSA 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 because the PKA module is unavailable.
#define EDDSA_STATUS_POINT_AT_INFINITY (-5) |
The generated public key was the point at infinity.
The point at infinity is not a valid public key, try EDDSA_generatePublicKey again.
#define EDDSA_STATUS_INVALID_PRIVATE_KEY_SIZE (-6) |
The private key was not 32 bytes long.
Ed25519 expects a 32 byte private key.
#define EDDSA_STATUS_INVALID_PUBLIC_KEY_SIZE (-7) |
The public key was not 32 bytes long.
Ed25519 expects a 32 byte public key. This is the compressed representation of a point on curve Ed25519.
#define EDDSA_STATUS_PUBLIC_KEY_NOT_ON_CURVE (-8) |
The public key was not a valid point on curve Ed25519.
Ed25519 expects a valid public key. This is the compressed representation of a point on curve Ed25519.
#define EDDSA_STATUS_INVALID_R_SIZE (-9) |
The Ed25519 signature component R was not 32 bytes long.
Signature component R must be 32 bytes long, representing a point on Ed25519.
#define EDDSA_STATUS_INVALID_S_SIZE (-10) |
The Ed25519 signature component S was not 32 bytes long.
Signature component S must be 32 bytes long, representing a scalar.
#define EDDSA_STATUS_S_LARGER_THAN_ORDER (-11) |
The Ed25519 signature component S was larger than the order of Ed25519.
The signature component S must be less than the order of the elliptic curve Ed25519.
#define EDDSA_STATUS_KEY_ID_PARAM_MISMATCH (-12) |
The Ed25519 operation was called with conflicting private and public key ID parameters.
The private and public key params have different ECC parameters.
#define EDDSA_STATUS_KEYSTORE_INVALID_ID (-13) |
The KeyStore module could not find a key with the given ID.
The KeyStore was provided an invalid ID#.
#define EDDSA_STATUS_KEYSTORE_GENERIC_FAILURE (-14) |
The KeyStore module entered a failure state when retrieving the key ID.
A KeyStore operation failed as a result of an invalid key type, invalid key policy, not enough buffer space, hardware failure, and so on.
#define EDDSA_STATUS_SHA2_HASH_FAILURE (-15) |
The SHA2 module returned an error while hashing.
The SHA2 module did not successfully hash a required value.
typedef EDDSA_Config* EDDSA_Handle |
A handle that is returned from an EDDSA_open() call.
typedef void(* EDDSA_CallbackFxn) (EDDSA_Handle handle, int_fast16_t returnStatus, EDDSA_Operation operation, EDDSA_OperationType operationType) |
The definition of a callback function used by the EDDSA driver when used in EDDSA_RETURN_BEHAVIOR_CALLBACK.
handle | Handle of the client that started the EDDSA operation. |
returnStatus | The result of the EDDSA 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 operation . |
enum EDDSA_ReturnBehavior |
The way in which EDDSA function calls return after performing an encryption + authentication or decryption + verification operation.
Not all EDDSA 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 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.
EDDSA functions exhibiting the specified return behavior have restrictions on the context from which they may be called.
Task | Hwi | Swi | |
---|---|---|---|
EDDSA_RETURN_BEHAVIOR_CALLBACK | X | X | X |
EDDSA_RETURN_BEHAVIOR_BLOCKING | X | ||
EDDSA_RETURN_BEHAVIOR_POLLING | X | X | X |
enum EDDSA_OperationType |
void EDDSA_init | ( | void | ) |
This function initializes the EDDSA module.
void EDDSA_close | ( | EDDSA_Handle | handle | ) |
Function to close an EDDSA peripheral specified by the EDDSA handle.
handle | An EDDSA handle returned from EDDSA_open() |
EDDSA_Handle EDDSA_open | ( | uint_least8_t | index, |
const EDDSA_Params * | params | ||
) |
This function opens a given EDDSA peripheral.
index | Logical peripheral number for the EDDSA indexed into the EDDSA_config table |
params | Pointer to an parameter block, if NULL it will use default values. |
void EDDSA_Params_init | ( | EDDSA_Params * | params | ) |
Function to initialize the EDDSA_Params struct to its defaults.
params | An pointer to EDDSA_Params structure for initialization |
Defaults values are: returnBehavior = EDDSA_RETURN_BEHAVIOR_BLOCKING callbackFxn = NULL timeout = SemaphoreP_WAIT_FOREVER custom = NULL
void EDDSA_OperationGeneratePublicKey_init | ( | EDDSA_OperationGeneratePublicKey * | operation | ) |
Function to initialize an EDDSA_OperationGeneratePublicKey struct to its defaults.
operation | A pointer to EDDSA_OperationGeneratePublicKey structure for initialization |
Defaults to all zeros.
void EDDSA_OperationSign_init | ( | EDDSA_OperationSign * | operation | ) |
Function to initialize an EDDSA_OperationSign struct to its defaults.
operation | A pointer to EDDSA_OperationSign structure for initialization |
Defaults to all zeros.
void EDDSA_OperationVerify_init | ( | EDDSA_OperationVerify * | operation | ) |
Function to initialize an EDDSA_OperationSign struct to its defaults.
operation | An pointer to EDDSA_OperationSign structure for initialization |
Defaults to all zeros.
int_fast16_t EDDSA_generatePublicKey | ( | EDDSA_Handle | handle, |
EDDSA_OperationGeneratePublicKey * | operation | ||
) |
Generates an EdDSA private-public keypair.
EDDSA_generatePublicKey() generates a private-public keypair (k
, A
) to generate EdDSA signatures with.
operation
first. The driver must have been opened by calling EDDSA_open() first.[in] | handle | An EDDSA handle returned from EDDSA_open() |
[in] | operation | A struct containing the pointers to the buffers necessary to perform the operation |
EDDSA_STATUS_SUCCESS | The operation succeeded. |
EDDSA_STATUS_ERROR | The operation failed. |
EDDSA_STATUS_CANCELED | The operation was canceled. |
EDDSA_STATUS_HASH_UNAVAILABLE | The required hash hardware resource was not available. Try again later. |
EDDSA_STATUS_PKA_UNAVAILABLE | The required PKA hardware resource was not available. Try again later. |
EDDSA_STATUS_POINT_AT_INFINITY | The computed public key is the point at infinity. Try again. |
EDDSA_STATUS_KEY_ID_PARAM_MISMATCH | The ID for the private and public key parameters do not match. |
EDDSA_STATUS_KEYSTORE_INVALID_ID | KeyStore could not find a key with the given key ID#. |
EDDSA_STATUS_KEYSTORE_GENERIC_FAILURE | The KeyStore entered some error state when storing the public or private key. |
int_fast16_t EDDSA_sign | ( | EDDSA_Handle | handle, |
EDDSA_OperationSign * | operation | ||
) |
Generates an EdDSA signature.
EDDSA_sign() generates a signature (R
, S
) of a message.
operation
first. The driver must have been opened by calling EDDSA_open() first.[in] | handle | An EDDSA handle returned from EDDSA_open() |
[in] | operation | A struct containing the pointers to the buffers necessary to perform the operation |
EDDSA_STATUS_SUCCESS | The operation succeeded. |
EDDSA_STATUS_ERROR | The operation failed. |
EDDSA_STATUS_CANCELED | The operation was canceled. |
EDDSA_STATUS_HASH_UNAVAILABLE | The required hash hardware resource was not available. Try again later. |
EDDSA_STATUS_PKA_UNAVAILABLE | The required PKA hardware resource was not available. Try again later. |
EDDSA_STATUS_INVALID_PRIVATE_KEY_SIZE | The private key size is an invalid size. |
EDDSA_STATUS_INVALID_PUBLIC_KEY_SIZE | The public key size is an invalid size. |
EDDSA_STATUS_KEY_ID_PARAM_MISMATCH | The ID for the private and public key parameters do not match. |
EDDSA_STATUS_KEYSTORE_INVALID_ID | KeyStore could not find a key with the given key ID#. |
EDDSA_STATUS_KEYSTORE_GENERIC_FAILURE | The KeyStore entered some error state when retrieving the public or private key. |
int_fast16_t EDDSA_verify | ( | EDDSA_Handle | handle, |
EDDSA_OperationVerify * | operation | ||
) |
Verifies a received EdDSA signature matches a hash and public key.
operation
first. The driver must have been opened by calling EDDSA_open() first.[in] | handle | An EDDSA handle returned from EDDSA_open() |
[in] | operation | A struct containing the pointers to the buffers necessary to perform the operation |
EDDSA_STATUS_SUCCESS | The operation succeeded. |
EDDSA_STATUS_ERROR | The operation failed. |
EDDSA_STATUS_CANCELED | The operation was canceled. |
EDDSA_STATUS_HASH_UNAVAILABLE | The required hash hardware resource was not available. Try again later. |
EDDSA_STATUS_PKA_UNAVAILABLE | The required PKA hardware resource was not available. Try again later. |
EDDSA_STATUS_INVALID_PUBLIC_KEY_SIZE | The public key size is an invalid size. |
EDDSA_STATUS_PUBLIC_KEY_NOT_ON_CURVE | The public key is not a valid point. |
EDDSA_STATUS_INVALID_R_SIZE | The signature component R is an invalid size. |
EDDSA_STATUS_INVALID_S_SIZE | The signature component S is an invalid size. |
EDDSA_STATUS_S_LARGER_THAN_ORDER | The signature component S is larger than the Edwards curve order. |
EDDSA_STATUS_KEYSTORE_INVALID_ID | KeyStore could not find a key with the given key ID#. |
EDDSA_STATUS_KEYSTORE_GENERIC_FAILURE | The KeyStore entered some error state when retrieving the public or private key. |
int_fast16_t EDDSA_cancelOperation | ( | EDDSA_Handle | handle | ) |
Cancels an ongoing EDDSA operation.
Asynchronously cancels an EDDSA operation. Only available when using EDDSA_RETURN_BEHAVIOR_CALLBACK or EDDSA_RETURN_BEHAVIOR_BLOCKING. The operation will terminate as though an error occurred. The return status code of the operation will be EDDSA_STATUS_CANCELED.
handle | Handle of the operation to cancel |
EDDSA_STATUS_SUCCESS | The operation was canceled. |
EDDSA_STATUS_ERROR | The operation was not canceled. There may be no operation to cancel. |
EDDSA_Handle EDDSA_construct | ( | EDDSA_Config * | config, |
const EDDSA_Params * | params | ||
) |
Constructs a new EDDSA object.
Unlike EDDSA_open(), EDDSA_construct() does not require the hwAttrs and object to be allocated in a EDDSA_Config array that is indexed into. Instead, the EDDSA_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 | EDDSA_Config describing the location of the object and hwAttrs. |
params | EDDSA_Params to configure the driver instance. |
config
points to must be zeroed out prior to calling this function. Otherwise, unexpected behavior may ensue.