Detailed Description

TI Driver for Edwards Curve Digital Signature Algorithm.

Overview

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.

Steps involved

Public Key Generation. The sender generates an EdDSA private-public keypair with private key k and public key A. For Ed25519, these are 32 bytes in little endian. The private key k comes from the DRBG. This private key is hashed, pruned (clear bits 0,1,2,255 and set bit 254), and used as a scalar to generate public key A.
Signature Generation. The sender hashes part of the private key k and message to be signed M. This result is used as a scalar to generate EdDSA signature component R which is a point on Ed25519. The signature component R, public key A, and message M are hashed to find a value that is used to generate the EdDSA signature component S which is a scalar. The signature for message M is {R,S}.
Signature Verification. The recipient receives signature {R,S}. The scalar S value is checked to be less than the order of the Edwards curve. The signature component R, public key A, and message M are hashed to find a scalar to recalculate R. The recipient accepts the signature if the received and calculated R match. Otherwise, they reject the signature.

Note: From here, we use EDDSA rather than EdDSA to be consistent with driver naming conventions.

Usage

Before starting an EDDSA operation

Before starting an EDDSA operation, the application must do the following:

Call EDDSA_init() to initialize the driver
Call EDDSA_Params_init() to initialize the EDDSA_Params to default values.
Modify the EDDSA_Params as desired
Call EDDSA_open() to open an instance of the driver

Generating an Ed25519 Public Key

To generate an Ed25519 public key, the application must do the following:

Initialize an EDDSA_OperationGeneratePublicKey struct by calling EDDSA_OperationGeneratePublicKey_init().
Initialize the public key CryptoKey. CryptoKeys are opaque data structures and representations of keying material and its storage. Depending on how the keying material is stored (RAM or flash, key store), the CryptoKey must be initialized differently. The EDDSA API can handle all types of CryptoKey. However, not all device-specific implementations support all types of CryptoKey. Devices without a key store will not support CryptoKeys with keying material stored in a key store for example. All devices support plaintext CryptoKeys.
Initialize the private key CryptoKey and set its value as a random or selected 32-byte value
Call EDDSA_operationGeneratePublicKey(). The public key information will be written to the buffers provided in the function call. myPublicKey is the public key A generated from part of a hash of the private key. Ensure the return value is EDDSA_STATUS_SUCCESS.

Signing a message

To sign a message using Ed25519, the application must do the following:

Initialize an EDDSA_OperationSign struct by calling EDDSA_OperationSign_init().
Initialize and set the preHashedMessage buffer and corresponding preHashedMessageLength. Note that this function accepts any length. This is the message to sign.
Initialize the signature components R and S as 32 byte arrays.
Use the CryptoKeys myPrivateKey and myPublicKey generated from EDDSA_OperationGeneratePublicKey().
Call EDDSA_sign(). The R and S vectors will be written to the buffers provided in the function call. Ensure the return value is EDDSA_STATUS_SUCCESS.

Verifying a message

After receiving the message, public key, R, and S, the application should do the following to verify the signature:

Initialize an EDDSA_OperationVerify struct by calling EDDSA_OperationVerify_init().
Initialize and set the preHashedMessage buffer and corresponding preHashedMessageLength. Note that this function accepts any length. This is the message to verify.
Initialize a CryptoKey as public key with the keying material received from the other party.
Call EDDSA_verify(). Ensure the return value is EDDSA_STATUS_SUCCESS. The driver will validate the received public key against the provided curve.

General usage

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.

Parameter formatting

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.

Synopsis

// Import EdDSA Driver definitions
#include <ti/drivers/EDDSA.h>
// Create default parameters
EDDSA_Handle eddsaHandle;
EDDSA_Params params;
EDDSA_init();
EDDSA_Params_init(&params);
params.returnBehavior = EDDSA_RETURN_BEHAVIOR_BLOCKING;
eddsaHandle = EDDSA_open(0, &params);
if (!eddsaHandle) {
    // Handle error
}
CryptoKey myPrivateKey;
CryptoKey myPublicKey;
CryptoKey theirPublicKey;
// Initialize myPrivateKey
CryptoKeyPlaintext_initKey(&myPrivateKey,
                           myPrivateKeyingMaterial,
                           sizeof(myPrivateKeyingMaterial));
// Initialize myPublicKey
CryptoKeyPlaintext_initKey(&myPublicKey,
                           myPublicKeyMaterial,
                           sizeof(myPublicKeyMaterial));
// Initialize the operation
EDDSA_OperationGeneratePublicKey_init(&operationGeneratePublicKey);
operationGeneratePublicKey.curve             = &ECCParams_Ed25519;
operationGeneratePublicKey.myPrivateKey      = &myPrivateKey;
operationGeneratePublicKey.myPublicKey       = &myPublicKey;
operationResult = EDDSA_generatePublicKey(eddsaHandle,
                                          &operationGeneratePublicKey);
if (operationResult != EDDSA_STATUS_SUCCESS) {
    // Handle error
}
// Initialize the operation
EDDSA_OperationSign_init(&operationSign);
operationSign.curve                   = &ECCParams_Ed25519;
operationSign.myPrivateKey            = &myPrivateKey;
operationSign.myPublicKey             = &myPublicKey;
operationSign.preHashedMessage        = preHashedMessage;
operationSign.preHashedMessageLength  = preHashedMessageLength;
operationSign.R                       = sigR;
operationSign.S                       = sigS;
// Generate the signature
operationResult = EDDSA_sign(eddsaHandle, &operationSign);
if (operationResult != EDDSA_STATUS_SUCCESS) {
    // Handle error
}
// Initialize theirPublicKey
CryptoKeyPlaintext_initKey(&theirPublicKey,
                           theirPublicKeyingMaterial,
                           sizeof(theirPublicKeyingMaterial));
EDDSA_OperationVerify_init(&operationVerify);
operationVerify.curve                  = &ECCParams_Ed25519;
operationVerify.theirPublicKey         = &theirPublicKey;
operationVerify.preHashedMessage       = preHashedMessage;
operationVerify.preHashedMessageLength = preHashedMessageLength;
operationVerify.R                      = sigR;
operationVerify.S                      = sigS;
// Verify the EdDSA signature
operationResult = EDDSA_verify(eddsaHandle, &operationVerify);
if (operationResult != EDDSA_STATUS_SUCCESS) {
    // Handle error
}
// Close the driver
EDDSA_close(eddsaHandle);

Examples

#include <ti/drivers/cryptoutils/cryptokey/CryptoKeyPlaintext.h>
#include <ti/drivers/EDDSA.h>
EDDSA_Handle eddsaHandle;
EDDSA_Params params;
CryptoKey theirPublicKey;
int_fast16_t operationResult;
EDDSA_OperationVerify operationVerify;
// This vector is test vector 2 from Section 7.1 of RFC 8032.
uint8_t publicKey[32] =  {0x3D,0x40,0x17,0xC3,0xE8,0x43,0x89,0x5A,
                          0x92,0xB7,0x0A,0xA7,0x4D,0x1B,0x7E,0xBC,
                          0x9C,0x98,0x2C,0xCF,0x2E,0xC4,0x96,0x8C,
                          0xC0,0xCD,0x55,0xF1,0x2A,0xF4,0x66,0x0C};
uint8_t sigR[32] = {0x92,0xA0,0x09,0xA9,0xF0,0xD4,0xCA,0xB8,
                    0x72,0x0E,0x82,0x0B,0x5F,0x64,0x25,0x40,
                    0xA2,0xB2,0x7B,0x54,0x16,0x50,0x3F,0x8F,
                    0xB3,0x76,0x22,0x23,0xEB,0xDB,0x69,0xDA};
uint8_t sigS[32] = {0x08,0x5A,0xC1,0xE4,0x3E,0x15,0x99,0x6E,
                    0x45,0x8F,0x36,0x13,0xD0,0xF1,0x1D,0x8C,
                    0x38,0x7B,0x2E,0xAE,0xB4,0x30,0x2A,0xEE,
                    0xB0,0x0D,0x29,0x16,0x12,0xBB,0x0C,0x00};
uint8_t preHashedMessage[1] = {0x72};
uint32_t preHashedMessageLength = 1;
// Initialize EDDSA driver
EDDSA_init();
EDDSA_Params_init(&params);
params.returnBehavior = EDDSA_RETURN_BEHAVIOR_BLOCKING;
eddsaHandle = EDDSA_open(0, &params);
if (!eddsaHandle) {
    // Handle error
}
// Initialize theirPublicKey
CryptoKeyPlaintext_initKey(&theirPublicKey,
                           publicKey,
                           sizeof(publicKey));
EDDSA_OperationVerify_init(&operationVerify);
operationVerify.curve                  = &ECCParams_Ed25519;
operationVerify.theirPublicKey         = &theirPublicKey;
operationVerify.preHashedMessage       = preHashedMessage;
operationVerify.preHashedMessageLength = preHashedMessageLength;
operationVerify.R                      = sigR;
operationVerify.S                      = sigS;
// Verify the EdDSA signature
operationResult = EDDSA_verify(eddsaHandle, &operationVerify);
if (operationResult != EDDSA_STATUS_SUCCESS) {
    // Handle error
}

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/cryptoutils/cryptokey/CryptoKey.h>
#include <ti/drivers/cryptoutils/ecc/ECCParams.h>

Include dependency graph for EDDSA.h:

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

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

Macro Definition Documentation

§ EDDSA_STATUS_RESERVED

#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 EDDSAXYZ_STATUS_ERROR0    EDDSA_STATUS_RESERVED - 0
#define EDDSAXYZ_STATUS_ERROR1    EDDSA_STATUS_RESERVED - 1
#define EDDSAXYZ_STATUS_ERROR2    EDDSA_STATUS_RESERVED - 2

§ EDDSA_STATUS_SUCCESS

#define EDDSA_STATUS_SUCCESS (0)

Successful status code.

Functions return EDDSA_STATUS_SUCCESS if the function was executed successfully.

§ EDDSA_STATUS_ERROR

#define EDDSA_STATUS_ERROR (-1)

Generic error status code.

Functions return EDDSA_STATUS_ERROR if the function was not executed successfully.

§ EDDSA_STATUS_CANCELED

#define EDDSA_STATUS_CANCELED (-2)

The ongoing operation was canceled.

§ EDDSA_STATUS_HASH_UNAVAILABLE

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

§ EDDSA_STATUS_PKA_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.

§ EDDSA_STATUS_POINT_AT_INFINITY

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

§ EDDSA_STATUS_INVALID_PRIVATE_KEY_SIZE

#define EDDSA_STATUS_INVALID_PRIVATE_KEY_SIZE (-6)

The private key was not 32 bytes long.

Ed25519 expects a 32 byte private key.

§ EDDSA_STATUS_INVALID_PUBLIC_KEY_SIZE

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

§ EDDSA_STATUS_PUBLIC_KEY_NOT_ON_CURVE

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

§ EDDSA_STATUS_INVALID_R_SIZE

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

§ EDDSA_STATUS_INVALID_S_SIZE

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

§ EDDSA_STATUS_S_LARGER_THAN_ORDER

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

§ EDDSA_STATUS_KEY_ID_PARAM_MISMATCH

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

§ EDDSA_STATUS_KEYSTORE_INVALID_ID

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

§ EDDSA_STATUS_KEYSTORE_GENERIC_FAILURE

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

§ EDDSA_STATUS_SHA2_HASH_FAILURE

#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 Documentation

§ EDDSA_Handle

typedef EDDSA_Config* EDDSA_Handle

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

§ EDDSA_CallbackFxn

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.

Parameters

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

Enumeration Type Documentation

§ EDDSA_ReturnBehavior

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

Enumerator
EDDSA_RETURN_BEHAVIOR_CALLBACK	The function call will return immediately while the EDDSA operation goes on in the background. The registered callback function is called after the operation completes. The context the callback function is called (task, HWI, SWI) is implementation-dependent.
EDDSA_RETURN_BEHAVIOR_BLOCKING	The function call will block while EDDSA operation goes on in the background. EDDSA operation results are available after the function returns.
EDDSA_RETURN_BEHAVIOR_POLLING	The function call will continuously poll a flag while EDDSA operation goes on in the background. EDDSA operation results are available after the function returns.

§ EDDSA_OperationType

enum EDDSA_OperationType

Enum for the operation types supported by the driver.

Enumerator
EDDSA_OPERATION_TYPE_GENERATE_PUBLIC_KEY
EDDSA_OPERATION_TYPE_SIGN
EDDSA_OPERATION_TYPE_VERIFY

Function Documentation

§ EDDSA_init()

void EDDSA_init ( void )

This function initializes the EDDSA module.

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

§ EDDSA_close()

void EDDSA_close ( EDDSA_Handle handle )

Function to close an EDDSA peripheral specified by the EDDSA handle.

Precondition: EDDSA_open() has to be called first.

Parameters

handle An EDDSA handle returned from EDDSA_open()

See also: EDDSA_open()

§ EDDSA_open()

EDDSA_Handle EDDSA_open	(	uint_least8_t	index,
		const EDDSA_Params *	params
	)

This function opens a given EDDSA peripheral.

Precondition: EDDSA controller has been initialized using EDDSA_init()

Parameters

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.

Returns: An EDDSA_Handle on success or a NULL on an error or if it has been opened already.

See also: EDDSA_init(); EDDSA_close()

§ EDDSA_Params_init()

void EDDSA_Params_init ( EDDSA_Params * params )

Function to initialize the EDDSA_Params struct to its defaults.

Parameters

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

§ EDDSA_OperationGeneratePublicKey_init()

void EDDSA_OperationGeneratePublicKey_init ( EDDSA_OperationGeneratePublicKey * operation )

Function to initialize an EDDSA_OperationGeneratePublicKey struct to its defaults.

Parameters

operation A pointer to EDDSA_OperationGeneratePublicKey structure for initialization

Defaults to all zeros.

§ EDDSA_OperationSign_init()

void EDDSA_OperationSign_init ( EDDSA_OperationSign * operation )

Function to initialize an EDDSA_OperationSign struct to its defaults.

Parameters

operation A pointer to EDDSA_OperationSign structure for initialization

Defaults to all zeros.

§ EDDSA_OperationVerify_init()

void EDDSA_OperationVerify_init ( EDDSA_OperationVerify * operation )

Function to initialize an EDDSA_OperationSign struct to its defaults.

Parameters

operation An pointer to EDDSA_OperationSign structure for initialization

Defaults to all zeros.

§ EDDSA_generatePublicKey()

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.

Precondition: EDDSA_OperationSign_init() must be called on operation first. The driver must have been opened by calling EDDSA_open() first.

Parameters

[in]	handle	An EDDSA handle returned from EDDSA_open()
[in]	operation	A struct containing the pointers to the buffers necessary to perform the operation

See also: EDDSA_sign(); EDDSA_verify()

Return values

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.

§ EDDSA_sign()

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.

Precondition: EDDSA_OperationSign_init() must be called on operation first. The driver must have been opened by calling EDDSA_open() first.

Parameters

[in]	handle	An EDDSA handle returned from EDDSA_open()
[in]	operation	A struct containing the pointers to the buffers necessary to perform the operation

See also: EDDSA_generatePublicKey(); EDDSA_verify()

Return values

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.

§ EDDSA_verify()

int_fast16_t EDDSA_verify	(	EDDSA_Handle	handle,
		EDDSA_OperationVerify *	operation
	)

Verifies a received EdDSA signature matches a hash and public key.

Precondition: EDDSA_OperationVerify_init() must be called on operation first. The driver must have been opened by calling EDDSA_open() first.

Parameters

[in]	handle	An EDDSA handle returned from EDDSA_open()
[in]	operation	A struct containing the pointers to the buffers necessary to perform the operation

See also: EDDSA_sign()

Return values

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.

§ EDDSA_cancelOperation()

int_fast16_t EDDSA_cancelOperation ( EDDSA_Handle handle )

Cancels an ongoing EDDSA operation.

Deprecated:: This function will be deprecated in the 3Q20 SDK release. The asynchronicity of the function can not be handled by all accelerators.

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.

Parameters

handle Handle of the operation to cancel

Return values

EDDSA_STATUS_SUCCESS	The operation was canceled.
EDDSA_STATUS_ERROR	The operation was not canceled. There may be no operation to cancel.

§ EDDSA_construct()

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.

Parameters

config	EDDSA_Config describing the location of the object and hwAttrs.
params	EDDSA_Params to configure the driver instance.

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

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

Detailed Description

Overview

Steps involved

Usage

Before starting an EDDSA operation

Generating an Ed25519 Public Key

Signing a message

Verifying a message

General usage

Parameter formatting

Synopsis

Examples

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ EDDSA_STATUS_RESERVED

§ EDDSA_STATUS_SUCCESS

§ EDDSA_STATUS_ERROR

§ EDDSA_STATUS_CANCELED

§ EDDSA_STATUS_HASH_UNAVAILABLE

§ EDDSA_STATUS_PKA_UNAVAILABLE

§ EDDSA_STATUS_POINT_AT_INFINITY

§ EDDSA_STATUS_INVALID_PRIVATE_KEY_SIZE

§ EDDSA_STATUS_INVALID_PUBLIC_KEY_SIZE

§ EDDSA_STATUS_PUBLIC_KEY_NOT_ON_CURVE

§ EDDSA_STATUS_INVALID_R_SIZE

§ EDDSA_STATUS_INVALID_S_SIZE

§ EDDSA_STATUS_S_LARGER_THAN_ORDER

§ EDDSA_STATUS_KEY_ID_PARAM_MISMATCH

§ EDDSA_STATUS_KEYSTORE_INVALID_ID

§ EDDSA_STATUS_KEYSTORE_GENERIC_FAILURE

§ EDDSA_STATUS_SHA2_HASH_FAILURE

Typedef Documentation

§ EDDSA_Handle

§ EDDSA_CallbackFxn

Enumeration Type Documentation

§ EDDSA_ReturnBehavior

§ EDDSA_OperationType

Function Documentation

§ EDDSA_init()

§ EDDSA_close()

§ EDDSA_open()

§ EDDSA_Params_init()

§ EDDSA_OperationGeneratePublicKey_init()

§ EDDSA_OperationSign_init()

§ EDDSA_OperationVerify_init()

§ EDDSA_generatePublicKey()

§ EDDSA_sign()

§ EDDSA_verify()

§ EDDSA_cancelOperation()

§ EDDSA_construct()