This file provides an API for Elliptic Curves over GF(P) (ECP). More...

#include "bignum.h"

Include dependency graph for ecp.h:

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

Classes
struct	mbedtls_ecp_curve_info

struct	mbedtls_ecp_point
	The ECP point structure, in Jacobian coordinates. More...

struct	mbedtls_ecp_group
	The ECP group structure. More...

struct	mbedtls_ecp_keypair
	The ECP key-pair structure. More...

Macros
#define	MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80

#define	MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00

#define	MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80

#define	MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00

#define	MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80

#define	MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00

#define	MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80

#define	MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00

#define	MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80

#define	MBEDTLS_ERR_ECP_IN_PROGRESS -0x4B00

#define	MBEDTLS_ECP_DP_MAX 12

#define	MBEDTLS_ECP_BUDGET(ops) /* no-op; for compatibility */

#define	MBEDTLS_ECP_PF_UNCOMPRESSED 0

#define	MBEDTLS_ECP_PF_COMPRESSED 1

#define	MBEDTLS_ECP_TLS_NAMED_CURVE 3

SECTION: Module settings
The configuration options you can set for this module are in this section. Either change them in config.h, or define them using the compiler command line.
#define	MBEDTLS_ECP_MAX_BITS 521

#define	MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )

#define	MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )

#define	MBEDTLS_ECP_WINDOW_SIZE 6

#define	MBEDTLS_ECP_FIXED_POINT_OPTIM 1

Typedefs
typedef struct mbedtls_ecp_curve_info	mbedtls_ecp_curve_info

typedef struct mbedtls_ecp_point	mbedtls_ecp_point
	The ECP point structure, in Jacobian coordinates. More...

typedef struct mbedtls_ecp_group	mbedtls_ecp_group
	The ECP group structure. More...

typedef void	mbedtls_ecp_restart_ctx

typedef struct mbedtls_ecp_keypair	mbedtls_ecp_keypair
	The ECP key-pair structure. More...

Enumerations
enum	mbedtls_ecp_group_id { MBEDTLS_ECP_DP_NONE = 0, MBEDTLS_ECP_DP_SECP192R1, MBEDTLS_ECP_DP_SECP224R1, MBEDTLS_ECP_DP_SECP256R1, MBEDTLS_ECP_DP_SECP384R1, MBEDTLS_ECP_DP_SECP521R1, MBEDTLS_ECP_DP_BP256R1, MBEDTLS_ECP_DP_BP384R1, MBEDTLS_ECP_DP_BP512R1, MBEDTLS_ECP_DP_CURVE25519, MBEDTLS_ECP_DP_SECP192K1, MBEDTLS_ECP_DP_SECP224K1, MBEDTLS_ECP_DP_SECP256K1, MBEDTLS_ECP_DP_CURVE448 }

Functions
const mbedtls_ecp_curve_info *	mbedtls_ecp_curve_list (void)
	This function retrieves the information defined in mbedtls_ecp_curve_info() for all supported curves in order of preference. More...

const mbedtls_ecp_group_id *	mbedtls_ecp_grp_id_list (void)
	This function retrieves the list of internal group identifiers of all supported curves in the order of preference. More...

const mbedtls_ecp_curve_info *	mbedtls_ecp_curve_info_from_grp_id (mbedtls_ecp_group_id grp_id)
	This function retrieves curve information from an internal group identifier. More...

const mbedtls_ecp_curve_info *	mbedtls_ecp_curve_info_from_tls_id (uint16_t tls_id)
	This function retrieves curve information from a TLS NamedCurve value. More...

const mbedtls_ecp_curve_info *	mbedtls_ecp_curve_info_from_name (const char *name)
	This function retrieves curve information from a human-readable name. More...

void	mbedtls_ecp_point_init (mbedtls_ecp_point *pt)
	This function initializes a point as zero. More...

void	mbedtls_ecp_group_init (mbedtls_ecp_group *grp)
	This function initializes an ECP group context without loading any domain parameters. More...

void	mbedtls_ecp_keypair_init (mbedtls_ecp_keypair *key)
	This function initializes a key pair as an invalid one. More...

void	mbedtls_ecp_point_free (mbedtls_ecp_point *pt)
	This function frees the components of a point. More...

void	mbedtls_ecp_group_free (mbedtls_ecp_group *grp)
	This function frees the components of an ECP group. More...

void	mbedtls_ecp_keypair_free (mbedtls_ecp_keypair *key)
	This function frees the components of a key pair. More...

int	mbedtls_ecp_copy (mbedtls_ecp_point P, const mbedtls_ecp_point Q)
	This function copies the contents of point `Q` into point `P`. More...

int	mbedtls_ecp_group_copy (mbedtls_ecp_group dst, const mbedtls_ecp_group src)
	This function copies the contents of group `src` into group `dst`. More...

int	mbedtls_ecp_set_zero (mbedtls_ecp_point *pt)
	This function sets a point to the point at infinity. More...

int	mbedtls_ecp_is_zero (mbedtls_ecp_point *pt)
	This function checks if a point is the point at infinity. More...

int	mbedtls_ecp_point_cmp (const mbedtls_ecp_point P, const mbedtls_ecp_point Q)
	This function compares two points. More...

int	mbedtls_ecp_point_read_string (mbedtls_ecp_point P, int radix, const char x, const char *y)
	This function imports a non-zero point from two ASCII strings. More...

int	mbedtls_ecp_point_write_binary (const mbedtls_ecp_group grp, const mbedtls_ecp_point P, int format, size_t olen, unsigned char buf, size_t buflen)
	This function exports a point into unsigned binary data. More...

int	mbedtls_ecp_point_read_binary (const mbedtls_ecp_group grp, mbedtls_ecp_point P, const unsigned char *buf, size_t ilen)
	This function imports a point from unsigned binary data. More...

int	mbedtls_ecp_tls_read_point (const mbedtls_ecp_group grp, mbedtls_ecp_point pt, const unsigned char **buf, size_t len)
	This function imports a point from a TLS ECPoint record. More...

int	mbedtls_ecp_tls_write_point (const mbedtls_ecp_group grp, const mbedtls_ecp_point pt, int format, size_t olen, unsigned char buf, size_t blen)
	This function exports a point as a TLS ECPoint record defined in RFC 4492, Section 5.4. More...

int	mbedtls_ecp_group_load (mbedtls_ecp_group *grp, mbedtls_ecp_group_id id)
	This function sets up an ECP group context from a standardized set of domain parameters. More...

int	mbedtls_ecp_tls_read_group (mbedtls_ecp_group grp, const unsigned char *buf, size_t len)
	This function sets up an ECP group context from a TLS ECParameters record as defined in RFC 4492, Section 5.4. More...

int	mbedtls_ecp_tls_read_group_id (mbedtls_ecp_group_id grp, const unsigned char *buf, size_t len)
	This function extracts an elliptic curve group ID from a TLS ECParameters record as defined in RFC 4492, Section 5.4. More...

int	mbedtls_ecp_tls_write_group (const mbedtls_ecp_group grp, size_t olen, unsigned char *buf, size_t blen)
	This function exports an elliptic curve as a TLS ECParameters record as defined in RFC 4492, Section 5.4. More...

int	mbedtls_ecp_mul (mbedtls_ecp_group grp, mbedtls_ecp_point R, const mbedtls_mpi m, const mbedtls_ecp_point P, int(f_rng)(void , unsigned char , size_t), void p_rng)
	This function performs a scalar multiplication of a point by an integer: `R` = `m` * `P`. More...

int	mbedtls_ecp_mul_restartable (mbedtls_ecp_group grp, mbedtls_ecp_point R, const mbedtls_mpi m, const mbedtls_ecp_point P, int(f_rng)(void , unsigned char , size_t), void p_rng, mbedtls_ecp_restart_ctx *rs_ctx)
	This function performs multiplication of a point by an integer: `R` = `m` * `P` in a restartable way. More...

int	mbedtls_ecp_muladd (mbedtls_ecp_group grp, mbedtls_ecp_point R, const mbedtls_mpi m, const mbedtls_ecp_point P, const mbedtls_mpi n, const mbedtls_ecp_point Q)
	This function performs multiplication and addition of two points by integers: `R` = `m` * `P` + `n` * `Q`. More...

int	mbedtls_ecp_muladd_restartable (mbedtls_ecp_group grp, mbedtls_ecp_point R, const mbedtls_mpi m, const mbedtls_ecp_point P, const mbedtls_mpi n, const mbedtls_ecp_point Q, mbedtls_ecp_restart_ctx *rs_ctx)
	This function performs multiplication and addition of two points by integers: `R` = `m` * `P` + `n` * `Q` in a restartable way. More...

int	mbedtls_ecp_check_pubkey (const mbedtls_ecp_group grp, const mbedtls_ecp_point pt)
	This function checks that a point is a valid public key on this curve. More...

int	mbedtls_ecp_check_privkey (const mbedtls_ecp_group grp, const mbedtls_mpi d)
	This function checks that an `mbedtls_mpi` is a valid private key for this curve. More...

int	mbedtls_ecp_gen_privkey (const mbedtls_ecp_group grp, mbedtls_mpi d, int(f_rng)(void , unsigned char , size_t), void p_rng)
	This function generates a private key. More...

int	mbedtls_ecp_gen_keypair_base (mbedtls_ecp_group grp, const mbedtls_ecp_point G, mbedtls_mpi d, mbedtls_ecp_point Q, int(f_rng)(void , unsigned char , size_t), void p_rng)
	This function generates a keypair with a configurable base point. More...

int	mbedtls_ecp_gen_keypair (mbedtls_ecp_group grp, mbedtls_mpi d, mbedtls_ecp_point Q, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	This function generates an ECP keypair. More...

int	mbedtls_ecp_gen_key (mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair key, int(f_rng)(void , unsigned char , size_t), void *p_rng)
	This function generates an ECP key. More...

int	mbedtls_ecp_check_pub_priv (const mbedtls_ecp_keypair pub, const mbedtls_ecp_keypair prv)
	This function checks that the keypair objects `pub` and `prv` have the same group and the same public point, and that the private key in `prv` is consistent with the public key. More...

Detailed Description

This file provides an API for Elliptic Curves over GF(P) (ECP).

The use of ECP in cryptography and TLS is defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography and RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS).

RFC-2409: The Internet Key Exchange (IKE) defines ECP group types.

Macro Definition Documentation

◆ MBEDTLS_ECP_BUDGET

#define MBEDTLS_ECP_BUDGET ( ops ) /* no-op; for compatibility */

◆ MBEDTLS_ECP_DP_MAX

#define MBEDTLS_ECP_DP_MAX 12

The number of supported curves, plus one for MBEDTLS_ECP_DP_NONE.

Note: Montgomery curves are currently excluded.

◆ MBEDTLS_ECP_FIXED_POINT_OPTIM

#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1

Enable fixed-point speed-up.

◆ MBEDTLS_ECP_MAX_BITS

#define MBEDTLS_ECP_MAX_BITS 521

The maximum size of the groups, that is, of N and P.The maximum size of groups, in bits.

◆ MBEDTLS_ECP_MAX_BYTES

#define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 )

◆ MBEDTLS_ECP_MAX_PT_LEN

#define MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )

◆ MBEDTLS_ECP_PF_COMPRESSED

#define MBEDTLS_ECP_PF_COMPRESSED 1

Compressed point format.

◆ MBEDTLS_ECP_PF_UNCOMPRESSED

#define MBEDTLS_ECP_PF_UNCOMPRESSED 0

Uncompressed point format.

◆ MBEDTLS_ECP_TLS_NAMED_CURVE

#define MBEDTLS_ECP_TLS_NAMED_CURVE 3

The named_curve of ECCurveType.

◆ MBEDTLS_ECP_WINDOW_SIZE

#define MBEDTLS_ECP_WINDOW_SIZE 6

The maximum window size used.

◆ MBEDTLS_ERR_ECP_ALLOC_FAILED

#define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80

Memory allocation failed.

◆ MBEDTLS_ERR_ECP_BAD_INPUT_DATA

#define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80

Bad input parameters to function.

◆ MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL

#define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00

The buffer is too small to write to.

◆ MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE

#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80

The requested feature is not available, for example, the requested curve is not supported.

◆ MBEDTLS_ERR_ECP_HW_ACCEL_FAILED

#define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80

The ECP hardware accelerator failed.

◆ MBEDTLS_ERR_ECP_IN_PROGRESS

#define MBEDTLS_ERR_ECP_IN_PROGRESS -0x4B00

Operation in progress, call again with the same parameters to continue.

◆ MBEDTLS_ERR_ECP_INVALID_KEY

#define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80

Invalid private or public key.

◆ MBEDTLS_ERR_ECP_RANDOM_FAILED

#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00

Generation of random value, such as ephemeral key, failed.

◆ MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH

#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00

The buffer contains a valid signature followed by more data.

◆ MBEDTLS_ERR_ECP_VERIFY_FAILED

#define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00

The signature is not valid.

Typedef Documentation

◆ mbedtls_ecp_curve_info

typedef struct mbedtls_ecp_curve_info mbedtls_ecp_curve_info

Curve information, for use by other modules.

◆ mbedtls_ecp_group

typedef struct mbedtls_ecp_group mbedtls_ecp_group

The ECP group structure.

We consider two types of curve equations:

Short Weierstrass: y^2 = x^3 + A x + B mod P (SEC1 + RFC-4492)
Montgomery: y^2 = x^3 + A x^2 + x mod P (Curve25519, Curve448)

In both cases, the generator (G) for a prime-order subgroup is fixed.

For Short Weierstrass, this subgroup is the whole curve, and its cardinality is denoted by N. Our code requires that N is an odd prime as mbedtls_ecp_mul() requires an odd number, and mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.

For Montgomery curves, we do not store A, but (A + 2) / 4, which is the quantity used in the formulas. Additionally, nbits is not the size of N but the required size for private keys.

If modp is NULL, reduction modulo P is done using a generic algorithm. Otherwise, modp must point to a function that takes an mbedtls_mpi in the range of 0..2^(2*pbits)-1, and transforms it in-place to an integer which is congruent mod P to the given MPI, and is close enough to pbits in size, so that it may be efficiently brought in the 0..P-1 range by a few additions or subtractions. Therefore, it is only an approximative modular reduction. It must return 0 on success and non-zero on failure.

Note: Alternative implementations must keep the group IDs distinct. If two group structures have the same ID, then they must be identical.

◆ mbedtls_ecp_keypair

typedef struct mbedtls_ecp_keypair mbedtls_ecp_keypair

The ECP key-pair structure.

A generic key-pair that may be used for ECDSA and fixed ECDH, for example.

Note: Members are deliberately in the same order as in the mbedtls_ecdsa_context structure.

◆ mbedtls_ecp_point

typedef struct mbedtls_ecp_point mbedtls_ecp_point

The ECP point structure, in Jacobian coordinates.

Note: All functions expect and return points satisfying the following condition: Z == 0 or Z == 1. Other values of Z are used only by internal functions. The point is zero, or "at infinity", if Z == 0. Otherwise, X and Y are its standard (affine) coordinates.

◆ mbedtls_ecp_restart_ctx

typedef void mbedtls_ecp_restart_ctx

Enumeration Type Documentation

◆ mbedtls_ecp_group_id

enum mbedtls_ecp_group_id

Domain-parameter identifiers: curve, subgroup, and generator.

Note: Only curves over prime fields are supported.

Warning: This library does not support validation of arbitrary domain parameters. Therefore, only standardized domain parameters from trusted sources should be used. See mbedtls_ecp_group_load().

Enumerator
MBEDTLS_ECP_DP_NONE	Curve not defined.
MBEDTLS_ECP_DP_SECP192R1	Domain parameters for the 192-bit curve defined by FIPS 186-4 and SEC1.
MBEDTLS_ECP_DP_SECP224R1	Domain parameters for the 224-bit curve defined by FIPS 186-4 and SEC1.
MBEDTLS_ECP_DP_SECP256R1	Domain parameters for the 256-bit curve defined by FIPS 186-4 and SEC1.
MBEDTLS_ECP_DP_SECP384R1	Domain parameters for the 384-bit curve defined by FIPS 186-4 and SEC1.
MBEDTLS_ECP_DP_SECP521R1	Domain parameters for the 521-bit curve defined by FIPS 186-4 and SEC1.
MBEDTLS_ECP_DP_BP256R1	Domain parameters for 256-bit Brainpool curve.
MBEDTLS_ECP_DP_BP384R1	Domain parameters for 384-bit Brainpool curve.
MBEDTLS_ECP_DP_BP512R1	Domain parameters for 512-bit Brainpool curve.
MBEDTLS_ECP_DP_CURVE25519	Domain parameters for Curve25519.
MBEDTLS_ECP_DP_SECP192K1	Domain parameters for 192-bit "Koblitz" curve.
MBEDTLS_ECP_DP_SECP224K1	Domain parameters for 224-bit "Koblitz" curve.
MBEDTLS_ECP_DP_SECP256K1	Domain parameters for 256-bit "Koblitz" curve.
MBEDTLS_ECP_DP_CURVE448	Domain parameters for Curve448.

Function Documentation

◆ mbedtls_ecp_check_privkey()

int mbedtls_ecp_check_privkey	(	const mbedtls_ecp_group *	grp,
		const mbedtls_mpi *	d
	)

This function checks that an mbedtls_mpi is a valid private key for this curve.

Note: This function uses bare components rather than an mbedtls_ecp_keypair structure to ease use with other structures, such as mbedtls_ecdh_context or mbedtls_ecdsa_context.

Parameters

grp	The ECP group the private key should belong to. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
d	The integer to check. This must be initialized.

Returns: 0 if the point is a valid private key.; MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid private key for the given curve.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_check_pub_priv()

int mbedtls_ecp_check_pub_priv	(	const mbedtls_ecp_keypair *	pub,
		const mbedtls_ecp_keypair *	prv
	)

This function checks that the keypair objects pub and prv have the same group and the same public point, and that the private key in prv is consistent with the public key.

Parameters

pub	The keypair structure holding the public key. This must be initialized. If it contains a private key, that part is ignored.
prv	The keypair structure holding the full keypair. This must be initialized.

Returns: 0 on success, meaning that the keys are valid and match.; MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.; An MBEDTLS_ERR_ECP_XXX or an MBEDTLS_ERR_MPI_XXX error code on calculation failure.

◆ mbedtls_ecp_check_pubkey()

int mbedtls_ecp_check_pubkey	(	const mbedtls_ecp_group *	grp,
		const mbedtls_ecp_point *	pt
	)

This function checks that a point is a valid public key on this curve.

It only checks that the point is non-zero, has valid coordinates and lies on the curve. It does not verify that it is indeed a multiple of G. This additional check is computationally more expensive, is not required by standards, and should not be necessary if the group used has a small cofactor. In particular, it is useless for the NIST groups which all have a cofactor of 1.

Note: This function uses bare components rather than an mbedtls_ecp_keypair structure, to ease use with other structures, such as mbedtls_ecdh_context or mbedtls_ecdsa_context.

Parameters

grp	The ECP group the point should belong to. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
pt	The point to check. This must be initialized.

Returns: 0 if the point is a valid public key.; MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid public key for the given curve.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_copy()

int mbedtls_ecp_copy	(	mbedtls_ecp_point *	P,
		const mbedtls_ecp_point *	Q
	)

This function copies the contents of point Q into point P.

Parameters

P	The destination point. This must be initialized.
Q	The source point. This must be initialized.

Returns: 0 on success.; MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.; Another negative error code for other kinds of failure.

◆ mbedtls_ecp_curve_info_from_grp_id()

const mbedtls_ecp_curve_info* mbedtls_ecp_curve_info_from_grp_id ( mbedtls_ecp_group_id grp_id )

This function retrieves curve information from an internal group identifier.

Parameters

grp_id An MBEDTLS_ECP_DP_XXX value.

Returns: The associated curve information on success.; NULL on failure.

◆ mbedtls_ecp_curve_info_from_name()

const mbedtls_ecp_curve_info* mbedtls_ecp_curve_info_from_name ( const char * name )

This function retrieves curve information from a human-readable name.

Parameters

name	The human-readable name.

Returns: The associated curve information on success.; NULL on failure.

◆ mbedtls_ecp_curve_info_from_tls_id()

const mbedtls_ecp_curve_info* mbedtls_ecp_curve_info_from_tls_id ( uint16_t tls_id )

This function retrieves curve information from a TLS NamedCurve value.

Parameters

tls_id An MBEDTLS_ECP_DP_XXX value.

Returns: The associated curve information on success.; NULL on failure.

◆ mbedtls_ecp_curve_list()

const mbedtls_ecp_curve_info* mbedtls_ecp_curve_list ( void )

This function retrieves the information defined in mbedtls_ecp_curve_info() for all supported curves in order of preference.

Returns: A statically allocated array. The last entry is 0.

◆ mbedtls_ecp_gen_key()

int mbedtls_ecp_gen_key	(	mbedtls_ecp_group_id	grp_id,
		mbedtls_ecp_keypair *	key,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function generates an ECP key.

Parameters

grp_id	The ECP group identifier.
key	The destination key. This must be initialized.
f_rng	The RNG function to use. This must not be `NULL`.
p_rng	The RNG context to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't need a context argument.

Returns: 0 on success.; An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

◆ mbedtls_ecp_gen_keypair()

int mbedtls_ecp_gen_keypair	(	mbedtls_ecp_group *	grp,
		mbedtls_mpi *	d,
		mbedtls_ecp_point *	Q,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function generates an ECP keypair.

Note: This function uses bare components rather than an mbedtls_ecp_keypair structure to ease use with other structures, such as mbedtls_ecdh_context or mbedtls_ecdsa_context.

Parameters

grp	The ECP group to generate a key pair for. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
d	The destination MPI (secret part). This must be initialized.
Q	The destination point (public part). This must be initialized.
f_rng	The RNG function. This must not be `NULL`.
p_rng	The RNG context to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't need a context argument.

Returns: 0 on success.; An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

◆ mbedtls_ecp_gen_keypair_base()

int mbedtls_ecp_gen_keypair_base	(	mbedtls_ecp_group *	grp,
		const mbedtls_ecp_point *	G,
		mbedtls_mpi *	d,
		mbedtls_ecp_point *	Q,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function generates a keypair with a configurable base point.

Note: This function uses bare components rather than an mbedtls_ecp_keypair structure to ease use with other structures, such as mbedtls_ecdh_context or mbedtls_ecdsa_context.

Parameters

grp	The ECP group to generate a key pair for. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
G	The base point to use. This must be initialized and belong to `grp`. It replaces the default base point `grp->G` used by mbedtls_ecp_gen_keypair().
d	The destination MPI (secret part). This must be initialized.
Q	The destination point (public part). This must be initialized.
f_rng	The RNG function. This must not be `NULL`.
p_rng	The RNG context to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't need a context argument.

Returns: 0 on success.; An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

◆ mbedtls_ecp_gen_privkey()

int mbedtls_ecp_gen_privkey	(	const mbedtls_ecp_group *	grp,
		mbedtls_mpi *	d,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function generates a private key.

Parameters

grp	The ECP group to generate a private key for. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
d	The destination MPI (secret part). This must be initialized.
f_rng	The RNG function. This must not be `NULL`.
p_rng	The RNG parameter to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't need a context argument.

Returns: 0 on success.; An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

◆ mbedtls_ecp_group_copy()

int mbedtls_ecp_group_copy	(	mbedtls_ecp_group *	dst,
		const mbedtls_ecp_group *	src
	)

This function copies the contents of group src into group dst.

Parameters

dst	The destination group. This must be initialized.
src	The source group. This must be initialized.

Returns: 0 on success.; MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_group_free()

void mbedtls_ecp_group_free ( mbedtls_ecp_group * grp )

This function frees the components of an ECP group.

Parameters

grp	The group to free. This may be `NULL`, in which case this function returns immediately. If it is not `NULL`, it must point to an initialized ECP group.

◆ mbedtls_ecp_group_init()

void mbedtls_ecp_group_init ( mbedtls_ecp_group * grp )

This function initializes an ECP group context without loading any domain parameters.

Note: After this function is called, domain parameters for various ECP groups can be loaded through the mbedtls_ecp_load() or mbedtls_ecp_tls_read_group() functions.

◆ mbedtls_ecp_group_load()

int mbedtls_ecp_group_load	(	mbedtls_ecp_group *	grp,
		mbedtls_ecp_group_id	id
	)

This function sets up an ECP group context from a standardized set of domain parameters.

Note: The index should be a value of the NamedCurve enum, as defined in RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS), usually in the form of an MBEDTLS_ECP_DP_XXX macro.

Parameters

grp	The group context to setup. This must be initialized.
id	The identifier of the domain parameter set to load.

Returns: 0 on success.; MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if id doesn't correspond to a known group.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_grp_id_list()

const mbedtls_ecp_group_id* mbedtls_ecp_grp_id_list ( void )

This function retrieves the list of internal group identifiers of all supported curves in the order of preference.

Returns: A statically allocated array, terminated with MBEDTLS_ECP_DP_NONE.

◆ mbedtls_ecp_is_zero()

int mbedtls_ecp_is_zero ( mbedtls_ecp_point * pt )

This function checks if a point is the point at infinity.

Parameters

pt	The point to test. This must be initialized.

Returns: 1 if the point is zero.; 0 if the point is non-zero.; A negative error code on failure.

◆ mbedtls_ecp_keypair_free()

void mbedtls_ecp_keypair_free ( mbedtls_ecp_keypair * key )

This function frees the components of a key pair.

Parameters

key	The key pair to free. This may be `NULL`, in which case this function returns immediately. If it is not `NULL`, it must point to an initialized ECP key pair.

◆ mbedtls_ecp_keypair_init()

void mbedtls_ecp_keypair_init ( mbedtls_ecp_keypair * key )

This function initializes a key pair as an invalid one.

Parameters

key	The key pair to initialize.

◆ mbedtls_ecp_mul()

int mbedtls_ecp_mul	(	mbedtls_ecp_group *	grp,
		mbedtls_ecp_point *	R,
		const mbedtls_mpi *	m,
		const mbedtls_ecp_point *	P,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng
	)

This function performs a scalar multiplication of a point by an integer: R = m * P.

It is not thread-safe to use same group in multiple threads.

Note: To prevent timing attacks, this function executes the exact same sequence of base-field operations for any valid m. It avoids any if-branch or array index depending on the value of m.; If f_rng is not NULL, it is used to randomize intermediate results to prevent potential timing attacks targeting these results. We recommend always providing a non-NULL f_rng. The overhead is negligible.

Parameters

grp	The ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
R	The point in which to store the result of the calculation. This must be initialized.
m	The integer by which to multiply. This must be initialized.
P	The point to multiply. This must be initialized.
f_rng	The RNG function. This may be `NULL` if randomization of intermediate results isn't desired (discouraged).
p_rng	The RNG context to be passed to `p_rng`.

Returns: 0 on success.; MBEDTLS_ERR_ECP_INVALID_KEY if m is not a valid private key, or P is not a valid public key.; MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_mul_restartable()

int mbedtls_ecp_mul_restartable	(	mbedtls_ecp_group *	grp,
		mbedtls_ecp_point *	R,
		const mbedtls_mpi *	m,
		const mbedtls_ecp_point *	P,
		int()(void , unsigned char *, size_t)	f_rng,
		void *	p_rng,
		mbedtls_ecp_restart_ctx *	rs_ctx
	)

This function performs multiplication of a point by an integer: R = m * P in a restartable way.

See also: mbedtls_ecp_mul()

Note: This function does the same as mbedtls_ecp_mul(), but it can return early and restart according to the limit set with mbedtls_ecp_set_max_ops() to reduce blocking.

Parameters

grp	The ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
R	The point in which to store the result of the calculation. This must be initialized.
m	The integer by which to multiply. This must be initialized.
P	The point to multiply. This must be initialized.
f_rng	The RNG function. This may be `NULL` if randomization of intermediate results isn't desired (discouraged).
p_rng	The RNG context to be passed to `p_rng`.
rs_ctx	The restart context (NULL disables restart).

Returns: 0 on success.; MBEDTLS_ERR_ECP_INVALID_KEY if m is not a valid private key, or P is not a valid public key.; MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.; MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see mbedtls_ecp_set_max_ops().; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_muladd()

int mbedtls_ecp_muladd	(	mbedtls_ecp_group *	grp,
		mbedtls_ecp_point *	R,
		const mbedtls_mpi *	m,
		const mbedtls_ecp_point *	P,
		const mbedtls_mpi *	n,
		const mbedtls_ecp_point *	Q
	)

This function performs multiplication and addition of two points by integers: R = m * P + n * Q.

It is not thread-safe to use same group in multiple threads.

Note: In contrast to mbedtls_ecp_mul(), this function does not guarantee a constant execution flow and timing.

Parameters

grp	The ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
R	The point in which to store the result of the calculation. This must be initialized.
m	The integer by which to multiply `P`. This must be initialized.
P	The point to multiply by `m`. This must be initialized.
n	The integer by which to multiply `Q`. This must be initialized.
Q	The point to be multiplied by `n`. This must be initialized.

Returns: 0 on success.; MBEDTLS_ERR_ECP_INVALID_KEY if m or n are not valid private keys, or P or Q are not valid public keys.; MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_muladd_restartable()

int mbedtls_ecp_muladd_restartable	(	mbedtls_ecp_group *	grp,
		mbedtls_ecp_point *	R,
		const mbedtls_mpi *	m,
		const mbedtls_ecp_point *	P,
		const mbedtls_mpi *	n,
		const mbedtls_ecp_point *	Q,
		mbedtls_ecp_restart_ctx *	rs_ctx
	)

This function performs multiplication and addition of two points by integers: R = m * P + n * Q in a restartable way.

See also: mbedtls_ecp_muladd()

Note: This function works the same as mbedtls_ecp_muladd(), but it can return early and restart according to the limit set with mbedtls_ecp_set_max_ops() to reduce blocking.

Parameters

grp	The ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
R	The point in which to store the result of the calculation. This must be initialized.
m	The integer by which to multiply `P`. This must be initialized.
P	The point to multiply by `m`. This must be initialized.
n	The integer by which to multiply `Q`. This must be initialized.
Q	The point to be multiplied by `n`. This must be initialized.
rs_ctx	The restart context (NULL disables restart).

Returns: 0 on success.; MBEDTLS_ERR_ECP_INVALID_KEY if m or n are not valid private keys, or P or Q are not valid public keys.; MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.; MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see mbedtls_ecp_set_max_ops().; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_point_cmp()

int mbedtls_ecp_point_cmp	(	const mbedtls_ecp_point *	P,
		const mbedtls_ecp_point *	Q
	)

This function compares two points.

Note: This assumes that the points are normalized. Otherwise, they may compare as "not equal" even if they are.

Parameters

P	The first point to compare. This must be initialized.
Q	The second point to compare. This must be initialized.

Returns: 0 if the points are equal.; MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.

◆ mbedtls_ecp_point_free()

void mbedtls_ecp_point_free ( mbedtls_ecp_point * pt )

This function frees the components of a point.

Parameters

pt	The point to free.

◆ mbedtls_ecp_point_init()

void mbedtls_ecp_point_init ( mbedtls_ecp_point * pt )

This function initializes a point as zero.

Parameters

pt	The point to initialize.

◆ mbedtls_ecp_point_read_binary()

int mbedtls_ecp_point_read_binary	(	const mbedtls_ecp_group *	grp,
		mbedtls_ecp_point *	P,
		const unsigned char *	buf,
		size_t	ilen
	)

This function imports a point from unsigned binary data.

Note: This function does not check that the point actually belongs to the given group, see mbedtls_ecp_check_pubkey() for that.

Parameters

grp	The group to which the point should belong. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
P	The destination context to import the point to. This must be initialized.
buf	The input buffer. This must be a readable buffer of length `ilen` Bytes.
ilen	The length of the input buffer `buf` in Bytes.

Returns: 0 on success.; MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.; MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.; MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format is not implemented.

◆ mbedtls_ecp_point_read_string()

int mbedtls_ecp_point_read_string	(	mbedtls_ecp_point *	P,
		int	radix,
		const char *	x,
		const char *	y
	)

This function imports a non-zero point from two ASCII strings.

Parameters

P	The destination point. This must be initialized.
radix	The numeric base of the input.
x	The first affine coordinate, as a null-terminated string.
y	The second affine coordinate, as a null-terminated string.

Returns: 0 on success.; An MBEDTLS_ERR_MPI_XXX error code on failure.

◆ mbedtls_ecp_point_write_binary()

int mbedtls_ecp_point_write_binary	(	const mbedtls_ecp_group *	grp,
		const mbedtls_ecp_point *	P,
		int	format,
		size_t *	olen,
		unsigned char *	buf,
		size_t	buflen
	)

This function exports a point into unsigned binary data.

Parameters

grp	The group to which the point should belong. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
P	The point to export. This must be initialized.
format	The point format. This must be either MBEDTLS_ECP_PF_COMPRESSED or MBEDTLS_ECP_PF_UNCOMPRESSED.
olen	The address at which to store the length of the output in Bytes. This must not be `NULL`.
buf	The output buffer. This must be a writable buffer of length `buflen` Bytes.
buflen	The length of the output buffer `buf` in Bytes.

Returns: 0 on success.; MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer is too small to hold the point.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_set_zero()

int mbedtls_ecp_set_zero ( mbedtls_ecp_point * pt )

This function sets a point to the point at infinity.

Parameters

pt	The point to set. This must be initialized.

Returns: 0 on success.; MBEDTLS_ERR_MPI_ALLOC_FAILED on memory-allocation failure.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_tls_read_group()

int mbedtls_ecp_tls_read_group	(	mbedtls_ecp_group *	grp,
		const unsigned char **	buf,
		size_t	len
	)

This function sets up an ECP group context from a TLS ECParameters record as defined in RFC 4492, Section 5.4.

Note: The read pointer buf is updated to point right after the ECParameters record on exit.

Parameters

grp	The group context to setup. This must be initialized.
buf	The address of the pointer to the start of the input buffer.
len	The length of the input buffer `*buf` in Bytes.

Returns: 0 on success.; MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.; MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not recognized.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_tls_read_group_id()

int mbedtls_ecp_tls_read_group_id	(	mbedtls_ecp_group_id *	grp,
		const unsigned char **	buf,
		size_t	len
	)

This function extracts an elliptic curve group ID from a TLS ECParameters record as defined in RFC 4492, Section 5.4.

Note: The read pointer buf is updated to point right after the ECParameters record on exit.

Parameters

grp	The address at which to store the group id. This must not be `NULL`.
buf	The address of the pointer to the start of the input buffer.
len	The length of the input buffer `*buf` in Bytes.

Returns: 0 on success.; MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.; MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not recognized.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_tls_read_point()

int mbedtls_ecp_tls_read_point	(	const mbedtls_ecp_group *	grp,
		mbedtls_ecp_point *	pt,
		const unsigned char **	buf,
		size_t	len
	)

This function imports a point from a TLS ECPoint record.

Note: On function return, *buf is updated to point immediately after the ECPoint record.

Parameters

grp	The ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
pt	The destination point.
buf	The address of the pointer to the start of the input buffer.
len	The length of the buffer.

Returns: 0 on success.; An MBEDTLS_ERR_MPI_XXX error code on initialization failure.; MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.

◆ mbedtls_ecp_tls_write_group()

int mbedtls_ecp_tls_write_group	(	const mbedtls_ecp_group *	grp,
		size_t *	olen,
		unsigned char *	buf,
		size_t	blen
	)

This function exports an elliptic curve as a TLS ECParameters record as defined in RFC 4492, Section 5.4.

Parameters

grp	The ECP group to be exported. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
olen	The address at which to store the number of Bytes written. This must not be `NULL`.
buf	The buffer to write to. This must be a writable buffer of length `blen` Bytes.
blen	The length of the output buffer `buf` in Bytes.

Returns: 0 on success.; MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer is too small to hold the exported group.; Another negative error code on other kinds of failure.

◆ mbedtls_ecp_tls_write_point()

int mbedtls_ecp_tls_write_point	(	const mbedtls_ecp_group *	grp,
		const mbedtls_ecp_point *	pt,
		int	format,
		size_t *	olen,
		unsigned char *	buf,
		size_t	blen
	)

This function exports a point as a TLS ECPoint record defined in RFC 4492, Section 5.4.

Parameters

grp	The ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
pt	The point to be exported. This must be initialized.
format	The point format to use. This must be either MBEDTLS_ECP_PF_COMPRESSED or MBEDTLS_ECP_PF_UNCOMPRESSED.
olen	The address at which to store the length in Bytes of the data written.
buf	The target buffer. This must be a writable buffer of length `blen` Bytes.
blen	The length of the target buffer `buf` in Bytes.

Returns: 0 on success.; MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.; MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer is too small to hold the exported point.; Another negative error code on other kinds of failure.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MBEDTLS_ECP_BUDGET

◆ MBEDTLS_ECP_DP_MAX

◆ MBEDTLS_ECP_FIXED_POINT_OPTIM

◆ MBEDTLS_ECP_MAX_BITS

◆ MBEDTLS_ECP_MAX_BYTES

◆ MBEDTLS_ECP_MAX_PT_LEN

◆ MBEDTLS_ECP_PF_COMPRESSED

◆ MBEDTLS_ECP_PF_UNCOMPRESSED

◆ MBEDTLS_ECP_TLS_NAMED_CURVE

◆ MBEDTLS_ECP_WINDOW_SIZE

◆ MBEDTLS_ERR_ECP_ALLOC_FAILED

◆ MBEDTLS_ERR_ECP_BAD_INPUT_DATA

◆ MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL

◆ MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE

◆ MBEDTLS_ERR_ECP_HW_ACCEL_FAILED

◆ MBEDTLS_ERR_ECP_IN_PROGRESS

◆ MBEDTLS_ERR_ECP_INVALID_KEY

◆ MBEDTLS_ERR_ECP_RANDOM_FAILED

◆ MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH

◆ MBEDTLS_ERR_ECP_VERIFY_FAILED

Typedef Documentation

◆ mbedtls_ecp_curve_info

◆ mbedtls_ecp_group

◆ mbedtls_ecp_keypair

◆ mbedtls_ecp_point

◆ mbedtls_ecp_restart_ctx

Enumeration Type Documentation

◆ mbedtls_ecp_group_id

Function Documentation

◆ mbedtls_ecp_check_privkey()

◆ mbedtls_ecp_check_pub_priv()

◆ mbedtls_ecp_check_pubkey()

◆ mbedtls_ecp_copy()

◆ mbedtls_ecp_curve_info_from_grp_id()

◆ mbedtls_ecp_curve_info_from_name()

◆ mbedtls_ecp_curve_info_from_tls_id()

◆ mbedtls_ecp_curve_list()

◆ mbedtls_ecp_gen_key()

◆ mbedtls_ecp_gen_keypair()

◆ mbedtls_ecp_gen_keypair_base()

◆ mbedtls_ecp_gen_privkey()

◆ mbedtls_ecp_group_copy()

◆ mbedtls_ecp_group_free()

◆ mbedtls_ecp_group_init()

◆ mbedtls_ecp_group_load()

◆ mbedtls_ecp_grp_id_list()

◆ mbedtls_ecp_is_zero()

◆ mbedtls_ecp_keypair_free()

◆ mbedtls_ecp_keypair_init()

◆ mbedtls_ecp_mul()

◆ mbedtls_ecp_mul_restartable()

◆ mbedtls_ecp_muladd()

◆ mbedtls_ecp_muladd_restartable()

◆ mbedtls_ecp_point_cmp()

◆ mbedtls_ecp_point_free()

◆ mbedtls_ecp_point_init()

◆ mbedtls_ecp_point_read_binary()

◆ mbedtls_ecp_point_read_string()

◆ mbedtls_ecp_point_write_binary()

◆ mbedtls_ecp_set_zero()

◆ mbedtls_ecp_tls_read_group()

◆ mbedtls_ecp_tls_read_group_id()

◆ mbedtls_ecp_tls_read_point()

◆ mbedtls_ecp_tls_write_group()

◆ mbedtls_ecp_tls_write_point()