Elliptic curve ECDSA and ECDH. More...

Data Structures
struct	M2MB_CRYPTO_ECC_AFFINE_POINT_T
	Structure representing the X,Y coordinates of a point. The point is zero, or "at infinity", if infinity == 1. Otherwise, X and Y are its standard (affine) coordinates. key_size respresents the x or y coordinates content length (for 160 bit key, size should be 20). More...

Macros
#define	M2MB_CRYPTO_ECC_BIGLEN 18
	Number of 32-bytes required for a big number.

#define	M2MB_MAX_ECC_KEY_SIZE 32
	Maximum size for key size (x or y coordinates in binary format, private key).

Enumerations
enum	M2MB_CRYPTO_ECC_DOMAIN_GROUP_ID_E { M2MB_CRYPTO_ECC_DP_BP256R1, M2MB_CRYPTO_ECC_DP_SECP256R1, M2MB_CRYPTO_ECC_DP_CUSTOM }

enum	M2MB_CRYPTO_ECC_DP_E { M2MB_CRYPTO_ECC_DP_P, M2MB_CRYPTO_ECC_DP_A, M2MB_CRYPTO_ECC_DP_B, M2MB_CRYPTO_ECC_DP_G_X, M2MB_CRYPTO_ECC_DP_G_Y, M2MB_CRYPTO_ECC_DP_N, M2MB_CRYPTO_ECC_DP_H }
	Enumeration representing all the ECC Domain Parameters.

Functions
M2MB_RESULT_E	m2mb_crypto_ecc_init (M2MB_CRYPTO_ECC_CONTEXT *ctx, M2MB_CRYPTO_ECC_DOMAIN_GROUP_ID_E curve_domain_params)
	Allocates an M2MB_CRYPTO_ECC_CONTEXT structure. More...

M2MB_RESULT_E	m2mb_crypto_ecc_dp_init (M2MB_CRYPTO_ECC_CONTEXT ctx, UINT8 p, UINT8 a, UINT8 b, UINT8 g_x, UINT8 g_y, UINT8 n, UINT32 *h)
	Allocates an M2MB_CRYPTO_ECC_CONTEXT structure. More...

M2MB_RESULT_E	m2mb_crypto_ecc_dp_import (M2MB_CRYPTO_ECC_CONTEXT ctx, M2MB_CRYPTO_ECC_DP_E domain, UINT32 len, const UINT8 *param)
	Imports an ECC Domain Parameter to the given context. More...

M2MB_RESULT_E	m2mb_crypto_ecdsa_sign (M2MB_CRYPTO_ECC_CONTEXT ctx, UINT8 msg, UINT32 msg_len, UINT8 sig, SIZE_T sig_len)
	ECDSA signature function. More...

M2MB_RESULT_E	m2mb_crypto_ecdsa_verify (M2MB_CRYPTO_ECC_CONTEXT ctx, UINT8 msg, UINT32 msg_len, M2MB_CRYPTO_ECC_AFFINE_POINT_T pubkey, UINT8 *sig, SIZE_T sig_len)
	ECDSA signature verification function. More...

M2MB_RESULT_E	m2mb_crypto_ecdh_shared_key_derive (M2MB_CRYPTO_ECC_CONTEXT ctx, UINT8 shared_keyblob, UINT16 shared_keyblob_len, const M2MB_CRYPTO_ECC_AFFINE_POINT_T *pubkey)
	Function to derive the shared key for the DH algorithm. More...

M2MB_RESULT_E	m2mb_crypto_ecc_keypair_generate (M2MB_CRYPTO_ECC_CONTEXT ctx)
	Function to generate an ECC keypair. More...

M2MB_RESULT_E	m2mb_crypto_ecc_keyblob_export (M2MB_CRYPTO_ECC_CONTEXT ctx, UINT8 keyblob, UINT16 keyblob_length)
	Exports an ECC key pair blob from the given context. The blob is encrypted with a device specific key and can only be used on the same HW originating it. More...

M2MB_RESULT_E	m2mb_crypto_ecc_keyblob_import (M2MB_CRYPTO_ECC_CONTEXT ctx, const UINT8 *keyblob, UINT32 keyblob_length)
	Imports an ECC key pair keyblob into the context. More...

M2MB_RESULT_E	m2mb_crypto_ecc_public_key_export (M2MB_CRYPTO_ECC_CONTEXT ctx, M2MB_CRYPTO_ECC_AFFINE_POINT_T *pubkey)
	Exports an ECC public key from the given context. More...

M2MB_RESULT_E	m2mb_crypto_ecc_public_key_import (M2MB_CRYPTO_ECC_CONTEXT ctx, const M2MB_CRYPTO_ECC_AFFINE_POINT_T *pubkey)
	Imports an ECC public key to the given context. More...

M2MB_RESULT_E	m2mb_crypto_ecc_private_key_import (M2MB_CRYPTO_ECC_CONTEXT ctx, const UINT8 *privkey, UINT16 privkey_len)
	Imports an ECC private key to the given context. More...

M2MB_RESULT_E	m2mb_crypto_ecc_deinit (M2MB_CRYPTO_ECC_CONTEXT ctx)
	Free an M2MB_CRYPTO_ECC_CONTEXT structure. More...

Detailed Description

Elliptic curve ECDSA and ECDH.

Enumeration Type Documentation

◆ M2MB_CRYPTO_ECC_DOMAIN_GROUP_ID_E

enum M2MB_CRYPTO_ECC_DOMAIN_GROUP_ID_E

Domain parameters (curve, subgroup and generator) identifiers.

Only curves over prime fields are supported.

Warning: Only well known domain parameters from trusted sources are used.

Enumerator
M2MB_CRYPTO_ECC_DP_BP256R1	256-bits Brainpool curve
M2MB_CRYPTO_ECC_DP_SECP256R1	256-bits NIST curve
M2MB_CRYPTO_ECC_DP_CUSTOM	Custom domain parameter imported via m2mb_crypto_ecc_dp_init()

Function Documentation

◆ m2mb_crypto_ecc_deinit()

M2MB_RESULT_E m2mb_crypto_ecc_deinit ( M2MB_CRYPTO_ECC_CONTEXT ctx )

Free an M2MB_CRYPTO_ECC_CONTEXT structure.

This function free a previously allocated ECC context.

Parameters

[in] ctx Pointer to a context structure to be free by this function.

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note

◆ m2mb_crypto_ecc_dp_import()

M2MB_RESULT_E m2mb_crypto_ecc_dp_import	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		M2MB_CRYPTO_ECC_DP_E	domain,
		UINT32	len,
		const UINT8 *	param
	)

Imports an ECC Domain Parameter to the given context.

This function imports an ECC Domain Parameter for the given context. Except for the cofactor M2MB_CRYPTO_ECC_DP_H, all the values in param must be sent as a hexadecimals ASCII string i.e "188DA80EB03090F67CBF20EB43A18800F4FF0AFD82FF1012" ( example ).

The value of M2MB_CRYPTO_ECC_DP_H must be a number ( <= 4 and preferably equals to 1 ), as in the example below.

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_ecc_init().
[in]	domain	The type of the Domain Parameter.
[in]	len	The length of the Domain Parameter.
[in]	param	The Domain Parameter.

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: m2mb_crypto_ecc_init() must be called before using this function.

Example

UINT32 h_value = 1;
 
//Key length 160 bits
CHAR p[] = "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFF",     //p value
CHAR a[] = "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF7FFFFFFC",     //a value
CHAR b[] = "1C97BEFC54BD7A8B65ACF89F81D4D4ADC565FA45",     //b value
...
len = strlen(p) + 1;
res = m2mb_crypto_ecc_dp_import(ctx2, M2MB_CRYPTO_ECC_DP_P, len, (UINT8*)p );
...
...
res = m2mb_crypto_ecc_dp_import(ctx2, M2MB_CRYPTO_ECC_DP_H, sizeof( h_value ), (UINT8*)&h_value);

◆ m2mb_crypto_ecc_dp_init()

M2MB_RESULT_E m2mb_crypto_ecc_dp_init	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		UINT8 *	p,
		UINT8 *	a,
		UINT8 *	b,
		UINT8 *	g_x,
		UINT8 *	g_y,
		UINT8 *	n,
		UINT32 *	h
	)

Allocates an M2MB_CRYPTO_ECC_CONTEXT structure.

This function allocates an ECC context to be later used by any ECC function, manually specifying the domain parameters.

Parameters

[out]	ctx	Pointer to a context structure to be allocated by this function. Any consecutive call to ECDSA and ECDH functions must use this context.
[in]	p	Pointer to the prime number
[in]	a	Pointer to the "a" constant in the ECC equation
[in]	b	Pointer to the "b" constant in the ECC equation
[in]	g_x	Pointer to the x coordinate of the base point
[in]	g_y	Pointer to the y coordinate of the base point
[in]	n	Pointer to the order of the base point
[in]	h	Pointer to the cofactor, must be <= 4 and preferably equals 1

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note

◆ m2mb_crypto_ecc_init()

M2MB_RESULT_E m2mb_crypto_ecc_init	(	M2MB_CRYPTO_ECC_CONTEXT *	ctx,
		M2MB_CRYPTO_ECC_DOMAIN_GROUP_ID_E	curve_domain_params
	)

Allocates an M2MB_CRYPTO_ECC_CONTEXT structure.

This function allocates an ECC context to be later used by any ECC function.

Parameters

[out]	ctx	Pointer to a context structure to be allocated by this function. Any consecutive call to ECDSA and ECDH functions must use this context.
[in]	curve_domain_params	This will indicate the curve, subgroup and generator, from a predefined list, or set for custom DP to be set later by m2mb_crypto_ecc_dp_init().

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note

◆ m2mb_crypto_ecc_keyblob_export()

M2MB_RESULT_E m2mb_crypto_ecc_keyblob_export	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		UINT8 *	keyblob,
		UINT16 *	keyblob_length
	)

Exports an ECC key pair blob from the given context. The blob is encrypted with a device specific key and can only be used on the same HW originating it.

This function exports an ECC key pair for the given context. Assumption made is that the context already have keys, i.e. keys were created using the m2mb_crypto_ecc_keypair_generate()

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_ecc_init().
[out]	keyblob	The buffer that will hold the result keyblob representing the exported ECC key pair (encrypted with device unique key). If keyblob ptr is NULL, this function will return the number of bytes required for the keyblob via the keyblob_length pointer.
[out]	keyblob_length	The length of the ECC key blob

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: m2mb_crypto_ecc_init() & m2mb_crypto_ecc_keypair_generate() must be called before using this function.

◆ m2mb_crypto_ecc_keyblob_import()

M2MB_RESULT_E m2mb_crypto_ecc_keyblob_import	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		const UINT8 *	keyblob,
		UINT32	keyblob_length
	)

Imports an ECC key pair keyblob into the context.

This function imports a given keyblob (which was previously created by m2mb_crypto_ecc_keypair_generate and was exported by m2mb_crypto_ecc_keyblob_export()) to the provided context. This basically allows using of an old keys with an existing context. The blob is encrypted with a device specific key and can only be used on the same HW originating it.

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_ecc_init().
[in]	keyblob	The keyblob previously exported using m2mb_crypto_ecc_keyblob_export() that will be imported into the given context. These keys can then be used for ECC operations like sign & verify.
[in]	keyblob_length	The length of the ECC key blob

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: m2mb_crypto_ecc_init() must be called before using this function.

◆ m2mb_crypto_ecc_keypair_generate()

M2MB_RESULT_E m2mb_crypto_ecc_keypair_generate ( M2MB_CRYPTO_ECC_CONTEXT ctx )

Function to generate an ECC keypair.

This function generates an ECC keypair. Same key can be used for both ECDH and ECDSA. The key is stored into the domain context and can be later exported via the m2mb_crypto_ecc_keyblob_export(). The domain parameters must be set prior to using this function (m2mb_crypto_ecc_init()).

Parameters

[in] ctx Pointer to a previously allocated domain context structure.

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: The domain parameters must be set prior to using this function (m2mb_crypto_ecc_init()).

◆ m2mb_crypto_ecc_private_key_import()

M2MB_RESULT_E m2mb_crypto_ecc_private_key_import	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		const UINT8 *	privkey,
		UINT16	privkey_len
	)

Imports an ECC private key to the given context.

This function imports an ECC private key for the given context. The ECC private key information will be stored into the given context.

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_ecc_init().
[in]	privkey	The imported ECC private key (plain private key) in binary format.
[in]	privkey_len	The length of the privkey data.

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: m2mb_crypto_ecc_init() must be called before using this function.

◆ m2mb_crypto_ecc_public_key_export()

M2MB_RESULT_E m2mb_crypto_ecc_public_key_export	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		M2MB_CRYPTO_ECC_AFFINE_POINT_T *	pubkey
	)

Exports an ECC public key from the given context.

This function exports an ECC public key for the given context. The ECC public key information will be exported from the given context (assuming context has keys associated).

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_ecc_init().
[out]	pubkey	The exported ECC public key (plain public key). The public key is represented as the x,y coordinates of a point on the given curve.

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: m2mb_crypto_ecc_init() & m2mb_crypto_ecc_keypair_generate() must be called before using this function.

◆ m2mb_crypto_ecc_public_key_import()

M2MB_RESULT_E m2mb_crypto_ecc_public_key_import	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		const M2MB_CRYPTO_ECC_AFFINE_POINT_T *	pubkey
	)

Imports an ECC public key to the given context.

This function imports an ECC public key for the given context. The ECC public key information will be stored into the given context.

Parameters

[in]	ctx	Pointer to a context structure previously allocated by m2mb_crypto_ecc_init().
[in]	pubkey	The imported ECC public key (plain public key). The public key is represented as the x,y coordinates of a point on the given curve.

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: m2mb_crypto_ecc_init() must be called before using this function.

◆ m2mb_crypto_ecdh_shared_key_derive()

M2MB_RESULT_E m2mb_crypto_ecdh_shared_key_derive	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		UINT8 *	shared_keyblob,
		UINT16 *	shared_keyblob_len,
		const M2MB_CRYPTO_ECC_AFFINE_POINT_T *	pubkey
	)

Function to derive the shared key for the DH algorithm.

This function calculates the shared key (using own private with recipients public) used for the diffie hellman key agreement algorithm. Key exchange for ECDH is based on the following math (D is the private key, H is the public key, G is the base point of the subgroup): DaHb = Da(DbG) = Db(DaG) = DbHa The domain parameters must be set prior to using this function (m2mb_crypto_ecc_init()). The private key used for the key derivation is taken from the context, assuming m2mb_crypto_ecc_keypair_generate() was previously called.

Parameters

[in]	ctx	Pointer to an already allocated domain context structure.
[out]	shared_keyblob	The derived shared/session key. If shared_keyblob ptr is NULL, this function will return the number of bytes required for the shared_key via the shared_keyblob_len pointer. The key is encrypted with a device specific key and can only be used on the same HW originating it.
[in]	shared_keyblob_len	The shared_keyblob size, in bytes.
[in]	pubkey	The other ends public key, represented as the x,y coordinates of a point on the selected curve.

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: The domain parameters must be set prior to using this function (m2mb_crypto_ecc_init()). The private key used for key derivation is taken from the context (created via m2mb_crypto_ecc_keypair_generate()).

◆ m2mb_crypto_ecdsa_sign()

M2MB_RESULT_E m2mb_crypto_ecdsa_sign	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		UINT8 *	msg,
		UINT32	msg_len,
		UINT8 *	sig,
		SIZE_T	sig_len
	)

ECDSA signature function.

This function signs the provided msg. The private key used for signing the message is taken from the context (created via m2mb_crypto_ecc_keypair_generate()). The domain parameters must be set prior to using this function (m2mb_crypto_ecc_init()).

Parameters

[in]	ctx	Pointer to an allocated domain context structure.
[in]	msg	The message to be signed.
[in]	msg_len	The length of the message provided.
[out]	sig	The result signature
[in]	sig_len	The size, in bytes, of the signature buffer.

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: The domain parameters must be set prior to using this function (m2mb_crypto_ecc_init()). The private key used for signing the message is taken from the context (created via m2mb_crypto_ecc_keypair_generate()).

◆ m2mb_crypto_ecdsa_verify()

M2MB_RESULT_E m2mb_crypto_ecdsa_verify	(	M2MB_CRYPTO_ECC_CONTEXT	ctx,
		UINT8 *	msg,
		UINT32	msg_len,
		M2MB_CRYPTO_ECC_AFFINE_POINT_T *	pubkey,
		UINT8 *	sig,
		SIZE_T	sig_len
	)

ECDSA signature verification function.

This function verifies the provided signature with the provided message. The domain parameters must be set prior to using this function (m2mb_crypto_ecc_init()).

Parameters

[in]	ctx	Pointer to an allocated domain context structure.
[in]	msg	The message to be verified against the signature.
[in]	msg_len	The length of the message provided.
[in]	pubkey	The public key to use for the verification (plaintext). Respresented as the x,y coordinates of a point on the selected curve. If set to NULL, the key from the context will be used, if exist.
[in]	sig	The signature to be verified.
[in]	sig_len	The size, in bytes, of the signature.

Returns: M2MB_RESULT_SUCCESS on success; see M2MB_RESULT_E for different values in case of fail

Note: The domain parameters must be set prior to using this function (m2mb_crypto_ecc_init()).

Data Structures

Macros

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ M2MB_CRYPTO_ECC_DOMAIN_GROUP_ID_E

Function Documentation

◆ m2mb_crypto_ecc_deinit()

◆ m2mb_crypto_ecc_dp_import()

◆ m2mb_crypto_ecc_dp_init()

◆ m2mb_crypto_ecc_init()

◆ m2mb_crypto_ecc_keyblob_export()

◆ m2mb_crypto_ecc_keyblob_import()

◆ m2mb_crypto_ecc_keypair_generate()

◆ m2mb_crypto_ecc_private_key_import()

◆ m2mb_crypto_ecc_public_key_export()

◆ m2mb_crypto_ecc_public_key_import()

◆ m2mb_crypto_ecdh_shared_key_derive()

◆ m2mb_crypto_ecdsa_sign()

◆ m2mb_crypto_ecdsa_verify()