Detailed Description

============================================================================

This file contains a common definition for eliptic curve structures used throughout the ECC based drivers.

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

Include dependency graph for ECCParams.h:

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

Go to the source code of this file.

Data Structures
struct	ECCParams_ECCPoint

struct	ECCParams_CurveParams
	A structure containing the parameters of an elliptic curve in short Weierstrass form. More...

Macros
#define	ECCParams_STATUS_SUCCESS (0)
	Successful status code. More...

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

#define	ECCParams_CURVE_TYPE_NONE 0U

#define	ECCParams_CURVE_TYPE_SHORT_WEIERSTRASS_AN3 1U

#define	ECCParams_CURVE_TYPE_SHORT_WEIERSTRASS_GEN 2U

#define	ECCParams_CURVE_TYPE_MONTGOMERY 3U

#define	ECCParams_CURVE_TYPE_EDWARDS 4U

#define	ECCPARAMS_CURVE25519_LENGTH 32u
	Length of Curve25519 parameters in bytes. More...

#define	ECCParams_FormatCurve25519PrivateKey ECCParams_formatCurve25519PrivateKey

Typedefs
typedef uint32_t	ECCParams_CurveType
	Enumeration of curve equations supported. More...

typedef struct ECCParams_ECCPoint	ECCParams_ECCPoint

typedef struct ECCParams_CurveParams	ECCParams_CurveParams
	A structure containing the parameters of an elliptic curve in short Weierstrass form. More...

Functions
int_fast16_t	ECCParams_formatCurve25519PrivateKey (CryptoKey *myPrivateKey)
	Formats a CryptoKey to conform to Curve25519 private key requirements. More...

int_fast16_t	ECCParams_getUncompressedGeneratorPoint (const ECCParams_CurveParams curveParams, uint8_t buffer, size_t length)
	Extracts the curve generator point from an ecliptic curve description. More...

Variables
const ECCParams_CurveParams	ECCParams_NISTP224
	The NISTP224 curve in short Weierstrass form. More...

const ECCParams_CurveParams	ECCParams_NISTP256
	The NISTP256 curve in short Weierstrass form. More...

const ECCParams_CurveParams	ECCParams_NISTP384
	The NISTP384 curve in short Weierstrass form. More...

const ECCParams_CurveParams	ECCParams_NISTP521
	The NISTP521 curve in short Weierstrass form. More...

const ECCParams_CurveParams	ECCParams_BrainpoolP256R1
	The BrainpoolP256R1 curve in short Weierstrass form. More...

const ECCParams_CurveParams	ECCParams_BrainpoolP384R1
	The BrainpoolP384R1 curve in short Weierstrass form. More...

const ECCParams_CurveParams	ECCParams_BrainpoolP512R1
	The BrainpoolP512R1 curve in short Weierstrass form. More...

const ECCParams_CurveParams	ECCParams_Wei25519
	A short Weierstrass equivalent representation of Ed25519. More...

const ECCParams_CurveParams	ECCParams_Curve25519
	The Curve25519 curve in Montgomery form. More...

const ECCParams_CurveParams	ECCParams_Ed25519
	The Ed25519 curve in Edwards form. More...

Macro Definition Documentation

§ ECCParams_STATUS_SUCCESS

#define ECCParams_STATUS_SUCCESS (0)

Successful status code.

Function return ECCParams_STATUS_SUCCESS if the control code was executed successfully.

§ ECCParams_STATUS_ERROR

#define ECCParams_STATUS_ERROR (-1)

Generic error status code.

Functions return ECCParams_STATUS_ERROR if the control code was not executed successfully.

§ ECCParams_CURVE_TYPE_NONE

#define ECCParams_CURVE_TYPE_NONE 0U

§ ECCParams_CURVE_TYPE_SHORT_WEIERSTRASS_AN3

#define ECCParams_CURVE_TYPE_SHORT_WEIERSTRASS_AN3 1U

§ ECCParams_CURVE_TYPE_SHORT_WEIERSTRASS_GEN

#define ECCParams_CURVE_TYPE_SHORT_WEIERSTRASS_GEN 2U

§ ECCParams_CURVE_TYPE_MONTGOMERY

#define ECCParams_CURVE_TYPE_MONTGOMERY 3U

§ ECCParams_CURVE_TYPE_EDWARDS

#define ECCParams_CURVE_TYPE_EDWARDS 4U

§ ECCPARAMS_CURVE25519_LENGTH

#define ECCPARAMS_CURVE25519_LENGTH 32u

Length of Curve25519 parameters in bytes.

§ ECCParams_FormatCurve25519PrivateKey

#define ECCParams_FormatCurve25519PrivateKey ECCParams_formatCurve25519PrivateKey

Typedef Documentation

§ ECCParams_CurveType

typedef uint32_t ECCParams_CurveType

Enumeration of curve equations supported.

Elliptic curves can be expressed using multiple equations of polynomials over finite fields. All forms can be converted to one another using parameter substitution. Each curve has a default curve equations it was designed to use.

Some curve implementations have restrictions on which algorithms and schemes they work with. For example, Curve25519 was explicitely designed with ECDH in mind. It only uses and yields the X coordinate of a point on the elliptic curve in common implementations. Some implementations do provide X and Y affine coordinates but most do not. Therefore, ECDSA and ECJPAKE do not have compatible implementations for Curve25519 on some devices as the Y coordinate is required by them.

Check the header files of each device-specific implementation for information regarding curve-support for specific schemes on a device.

Name	Equation
Short Weierstrass	y^3 = x^2 + a*x + b mod p
Montgomery	By^2 = x^3 + Ax^2 + x mod p
Edwards	x^2 + y^2 = 1 + dx^2y^2 mod p

§ ECCParams_ECCPoint

typedef struct ECCParams_ECCPoint ECCParams_ECCPoint

§ ECCParams_CurveParams

typedef struct ECCParams_CurveParams ECCParams_CurveParams

A structure containing the parameters of an elliptic curve in short Weierstrass form.

Elliptical Curve Cryptography (ECC) prime curve.

The equation used to define the curve is expressed in the short Weierstrass form y^3 = x^2 + a*x + b

Function Documentation

§ ECCParams_formatCurve25519PrivateKey()

int_fast16_t ECCParams_formatCurve25519PrivateKey ( CryptoKey * myPrivateKey )

Formats a CryptoKey to conform to Curve25519 private key requirements.

Curve25519 has specific private key requirements specified by the curve definition. Specifically, the bottom three and the top bit may not be set and the second to last bit must be set.

Parameters

myPrivateKey An initialized CryptoKey describing the entropy for a Curve25519 private key. Platform-specific restrictions for the location of the keying material apply. Some implementations do not support modifying keying material in flash for example.

Precondition: Initialize the CryptoKey with a 32-byte buffer in a compliant location.

§ ECCParams_getUncompressedGeneratorPoint()

int_fast16_t ECCParams_getUncompressedGeneratorPoint	(	const ECCParams_CurveParams *	curveParams,
		uint8_t *	buffer,
		size_t	length
	)

Extracts the curve generator point from an ecliptic curve description.

The curve parameters ECCParams_CurveParams::generatorX and ECCParams_CurveParams::generatorY are extracted from curveParams and written as a concatenated octet string in big endian order to buffer. The format is defined in SEC 1: Elliptic Curve Cryptography section 2.3.3.

The curve point has the format 0x04 || X || Y and the length is 2 * size_of_x_or_y + 1 where 0x04 specifies octet string format. If the buffer length exceeds the curve point length, the remaining buffer space is zeroed.

Parameters

curveParams	Points to the input curve parameters
buffer	Points to the destination where the generator point will be written to. Make sure that `buffer` is large enough to hold
length	Maximum length of `buffer` in bytes.

Return values

ECCParams_STATUS_SUCCESS on success, ECCParams_STATUS_ERROR if the provided buffer length is insufficient to hold the curve point.

Variable Documentation

§ ECCParams_NISTP224

const ECCParams_CurveParams ECCParams_NISTP224

The NISTP224 curve in short Weierstrass form.

§ ECCParams_NISTP256

const ECCParams_CurveParams ECCParams_NISTP256

The NISTP256 curve in short Weierstrass form.

§ ECCParams_NISTP384

const ECCParams_CurveParams ECCParams_NISTP384

The NISTP384 curve in short Weierstrass form.

§ ECCParams_NISTP521

const ECCParams_CurveParams ECCParams_NISTP521

The NISTP521 curve in short Weierstrass form.

§ ECCParams_BrainpoolP256R1

const ECCParams_CurveParams ECCParams_BrainpoolP256R1

The BrainpoolP256R1 curve in short Weierstrass form.

§ ECCParams_BrainpoolP384R1

const ECCParams_CurveParams ECCParams_BrainpoolP384R1

The BrainpoolP384R1 curve in short Weierstrass form.

§ ECCParams_BrainpoolP512R1

const ECCParams_CurveParams ECCParams_BrainpoolP512R1

The BrainpoolP512R1 curve in short Weierstrass form.

§ ECCParams_Wei25519

const ECCParams_CurveParams ECCParams_Wei25519

A short Weierstrass equivalent representation of Ed25519.

§ ECCParams_Curve25519

const ECCParams_CurveParams ECCParams_Curve25519

The Curve25519 curve in Montgomery form.

§ ECCParams_Ed25519

const ECCParams_CurveParams ECCParams_Ed25519

The Ed25519 curve in Edwards form.