mbed TLS v3.1.0
Data Structures | Macros | Typedefs | Enumerations | Functions
ecp.h File Reference

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

#include "mbedtls/private_access.h"
#include "mbedtls/build_info.h"
#include "mbedtls/bignum.h"
#include "ecp_alt.h"
Include dependency graph for ecp.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  mbedtls_ecp_curve_info
 
struct  mbedtls_ecp_point
 The ECP point structure, in Jacobian coordinates. More...
 
struct  mbedtls_ecp_restart_ctx
 General context for resuming ECC operations. 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_IN_PROGRESS   -0x4B00
 
#define MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED
 
#define MBEDTLS_ECP_MONTGOMERY_ENABLED
 
#define MBEDTLS_ECP_DP_MAX   14
 
#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_OPS_CHK   3
 
#define MBEDTLS_ECP_OPS_DBL   8
 
#define MBEDTLS_ECP_OPS_ADD   11
 
#define MBEDTLS_ECP_OPS_INV   120
 
#define MBEDTLS_ECP_BUDGET(ops)
 
#define MBEDTLS_ECP_PF_UNCOMPRESSED   0
 
#define MBEDTLS_ECP_PF_COMPRESSED   1
 
#define MBEDTLS_ECP_TLS_NAMED_CURVE   3
 

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_restart_mul 
mbedtls_ecp_restart_mul_ctx
 Internal restart context for multiplication. More...
 
typedef struct
mbedtls_ecp_restart_muladd 
mbedtls_ecp_restart_muladd_ctx
 Internal restart context for ecp_muladd() More...
 
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
}
 
enum  mbedtls_ecp_curve_type { MBEDTLS_ECP_TYPE_NONE = 0, MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS, MBEDTLS_ECP_TYPE_MONTGOMERY }
 

Functions

int mbedtls_ecp_check_budget (const mbedtls_ecp_group *grp, mbedtls_ecp_restart_ctx *rs_ctx, unsigned ops)
 Internal; for restartable functions in other modules. Check and update basic ops budget. More...
 
void mbedtls_ecp_set_max_ops (unsigned max_ops)
 Set the maximum number of basic operations done in a row. More...
 
int mbedtls_ecp_restart_is_enabled (void)
 Check if restart is enabled (max_ops != 0) More...
 
mbedtls_ecp_curve_type mbedtls_ecp_get_type (const mbedtls_ecp_group *grp)
 
const mbedtls_ecp_curve_infombedtls_ecp_curve_list (void)
 This function retrieves the information defined in mbedtls_ecp_curve_info() for all supported curves. More...
 
const mbedtls_ecp_group_idmbedtls_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_infombedtls_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_infombedtls_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_infombedtls_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...
 
void mbedtls_ecp_restart_init (mbedtls_ecp_restart_ctx *ctx)
 Initialize a restart context. More...
 
void mbedtls_ecp_restart_free (mbedtls_ecp_restart_ctx *ctx)
 Free the components of a restart context. 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_read_key (mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, const unsigned char *buf, size_t buflen)
 This function reads an elliptic curve private key. More...
 
int mbedtls_ecp_write_key (mbedtls_ecp_keypair *key, unsigned char *buf, size_t buflen)
 This function exports an elliptic curve private key. More...
 
int mbedtls_ecp_check_pub_priv (const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 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...
 
int mbedtls_ecp_self_test (int verbose)
 The ECP checkup routine. 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.

Definition in file ecp.h.

Macro Definition Documentation

#define MBEDTLS_ECP_BUDGET (   ops)
Value:
(unsigned) (ops) ) );
int mbedtls_ecp_check_budget(const mbedtls_ecp_group *grp, mbedtls_ecp_restart_ctx *rs_ctx, unsigned ops)
Internal; for restartable functions in other modules. Check and update basic ops budget.
#define MBEDTLS_MPI_CHK(f)
Definition: bignum.h:52

Definition at line 400 of file ecp.h.

#define MBEDTLS_ECP_DP_MAX   14

The number of supported curves, plus one for MBEDTLS_ECP_DP_NONE.

Definition at line 134 of file ecp.h.

#define MBEDTLS_ECP_MAX_BITS   521

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

Definition at line 317 of file ecp.h.

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

Definition at line 346 of file ecp.h.

#define MBEDTLS_ECP_MAX_PT_LEN   ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 )

Definition at line 347 of file ecp.h.

#define MBEDTLS_ECP_MONTGOMERY_ENABLED

Definition at line 81 of file ecp.h.

#define MBEDTLS_ECP_OPS_ADD   11

basic ops count for see ecp_add_mixed()

Definition at line 381 of file ecp.h.

#define MBEDTLS_ECP_OPS_CHK   3

basic ops count for ecp_check_pubkey()

Definition at line 379 of file ecp.h.

#define MBEDTLS_ECP_OPS_DBL   8

basic ops count for ecp_double_jac()

Definition at line 380 of file ecp.h.

#define MBEDTLS_ECP_OPS_INV   120

empirical equivalent for mpi_mod_inv()

Definition at line 382 of file ecp.h.

#define MBEDTLS_ECP_PF_COMPRESSED   1

Compressed point format.

Definition at line 433 of file ecp.h.

#define MBEDTLS_ECP_PF_UNCOMPRESSED   0

Uncompressed point format.

Definition at line 432 of file ecp.h.

#define MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED

Definition at line 77 of file ecp.h.

#define MBEDTLS_ECP_TLS_NAMED_CURVE   3

The named_curve of ECCurveType.

Definition at line 438 of file ecp.h.

#define MBEDTLS_ERR_ECP_ALLOC_FAILED   -0x4D80

Memory allocation failed.

Definition at line 54 of file ecp.h.

#define MBEDTLS_ERR_ECP_BAD_INPUT_DATA   -0x4F80

Bad input parameters to function.

Definition at line 46 of file ecp.h.

#define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL   -0x4F00

The buffer is too small to write to.

Definition at line 48 of file ecp.h.

Referenced by mbedtls_psa_tls_ecpoint_to_psa_ec().

#define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE   -0x4E80

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

Definition at line 50 of file ecp.h.

#define MBEDTLS_ERR_ECP_IN_PROGRESS   -0x4B00

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

Definition at line 62 of file ecp.h.

#define MBEDTLS_ERR_ECP_INVALID_KEY   -0x4C80

Invalid private or public key.

Definition at line 58 of file ecp.h.

#define MBEDTLS_ERR_ECP_RANDOM_FAILED   -0x4D00

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

Definition at line 56 of file ecp.h.

Referenced by mbedtls_psa_err_translate_pk().

#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH   -0x4C00

The buffer contains a valid signature followed by more data.

Definition at line 60 of file ecp.h.

#define MBEDTLS_ERR_ECP_VERIFY_FAILED   -0x4E00

The signature is not valid.

Definition at line 52 of file ecp.h.

Typedef Documentation

Curve information, for use by other modules.

The fields of this structure are part of the public API and can be accessed directly by applications. Future versions of the library may add extra fields or reorder existing fields.

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.

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.
typedef struct mbedtls_ecp_restart_mul mbedtls_ecp_restart_mul_ctx

Internal restart context for multiplication.

Note
Opaque struct

Definition at line 356 of file ecp.h.

typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx

Internal restart context for ecp_muladd()

Note
Opaque struct

Definition at line 363 of file ecp.h.

Enumeration Type Documentation

Enumerator
MBEDTLS_ECP_TYPE_NONE 
MBEDTLS_ECP_TYPE_SHORT_WEIERSTRASS 
MBEDTLS_ECP_TYPE_MONTGOMERY 

Definition at line 139 of file ecp.h.

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.

Definition at line 113 of file ecp.h.

Function Documentation

int mbedtls_ecp_check_budget ( const mbedtls_ecp_group *  grp,
mbedtls_ecp_restart_ctx rs_ctx,
unsigned  ops 
)

Internal; for restartable functions in other modules. Check and update basic ops budget.

Parameters
grpGroup structure
rs_ctxRestart context
opsNumber of basic ops to do
Returns
0 if doing ops basic ops is still allowed,
MBEDTLS_ERR_ECP_IN_PROGRESS otherwise.
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
grpThe ECP group the private key should belong to. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
dThe 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.
int mbedtls_ecp_check_pub_priv ( const mbedtls_ecp_keypair pub,
const mbedtls_ecp_keypair prv,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

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
pubThe keypair structure holding the public key. This must be initialized. If it contains a private key, that part is ignored.
prvThe keypair structure holding the full keypair. This must be initialized.
f_rngThe RNG function. This must not be NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL if f_rng doesn't need a context.
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.
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
grpThe ECP group the point should belong to. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
ptThe 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.
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
PThe destination point. This must be initialized.
QThe 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.
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_idAn MBEDTLS_ECP_DP_XXX value.
Returns
The associated curve information on success.
NULL on failure.
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
nameThe human-readable name.
Returns
The associated curve information on success.
NULL on failure.
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_idAn MBEDTLS_ECP_DP_XXX value.
Returns
The associated curve information on success.
NULL on failure.

Referenced by mbedtls_psa_parse_tls_ecc_group().

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.

Note
This function returns information about all curves supported by the library. Some curves may not be supported for all algorithms. Call mbedtls_ecdh_can_do() or mbedtls_ecdsa_can_do() to check if a curve is supported for ECDH or ECDSA.
Returns
A statically allocated array. The last entry is 0.
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_idThe ECP group identifier.
keyThe destination key. This must be initialized.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe 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.
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
grpThe ECP group to generate a key pair for. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
dThe destination MPI (secret part). This must be initialized.
QThe destination point (public part). This must be initialized.
f_rngThe RNG function. This must not be NULL.
p_rngThe 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.
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
grpThe ECP group to generate a key pair for. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
GThe 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().
dThe destination MPI (secret part). This must be initialized.
QThe destination point (public part). This must be initialized.
f_rngThe RNG function. This must not be NULL.
p_rngThe 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.
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
grpThe ECP group to generate a private key for. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
dThe destination MPI (secret part). This must be initialized.
f_rngThe RNG function. This must not be NULL.
p_rngThe 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_curve_type mbedtls_ecp_get_type ( const mbedtls_ecp_group *  grp)
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
dstThe destination group. This must be initialized.
srcThe 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.
void mbedtls_ecp_group_free ( mbedtls_ecp_group *  grp)

This function frees the components of an ECP group.

Parameters
grpThe 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.
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_group_load() or mbedtls_ecp_tls_read_group() functions.
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
grpThe group context to setup. This must be initialized.
idThe 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.
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.

Note
This function returns information about all curves supported by the library. Some curves may not be supported for all algorithms. Call mbedtls_ecdh_can_do() or mbedtls_ecdsa_can_do() to check if a curve is supported for ECDH or ECDSA.
Returns
A statically allocated array, terminated with MBEDTLS_ECP_DP_NONE.
int mbedtls_ecp_is_zero ( mbedtls_ecp_point pt)

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

Parameters
ptThe 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.
void mbedtls_ecp_keypair_free ( mbedtls_ecp_keypair key)

This function frees the components of a key pair.

Parameters
keyThe 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.
void mbedtls_ecp_keypair_init ( mbedtls_ecp_keypair key)

This function initializes a key pair as an invalid one.

Parameters
keyThe key pair to initialize.
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 also uses f_rng to randomize some intermediate results.
Parameters
grpThe ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
RThe point in which to store the result of the calculation. This must be initialized.
mThe integer by which to multiply. This must be initialized.
PThe point to multiply. This must be initialized.
f_rngThe RNG function. This must not be NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL if f_rng doesn't need a context.
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.
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
grpThe ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
RThe point in which to store the result of the calculation. This must be initialized.
mThe integer by which to multiply. This must be initialized.
PThe point to multiply. This must be initialized.
f_rngThe RNG function. This must not be NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL if f_rng doesn't need a context.
rs_ctxThe 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.
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.
This function is only defined for short Weierstrass curves. It may not be included in builds without any short Weierstrass curve.
Parameters
grpThe ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
RThe point in which to store the result of the calculation. This must be initialized.
mThe integer by which to multiply P. This must be initialized.
PThe point to multiply by m. This must be initialized.
nThe integer by which to multiply Q. This must be initialized.
QThe 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.
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if grp does not designate a short Weierstrass curve.
Another negative error code on other kinds of failure.
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.
This function is only defined for short Weierstrass curves. It may not be included in builds without any short Weierstrass curve.
Parameters
grpThe ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
RThe point in which to store the result of the calculation. This must be initialized.
mThe integer by which to multiply P. This must be initialized.
PThe point to multiply by m. This must be initialized.
nThe integer by which to multiply Q. This must be initialized.
QThe point to be multiplied by n. This must be initialized.
rs_ctxThe 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_FEATURE_UNAVAILABLE if grp does not designate a short Weierstrass curve.
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.
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
PThe first point to compare. This must be initialized.
QThe 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.
void mbedtls_ecp_point_free ( mbedtls_ecp_point pt)

This function frees the components of a point.

Parameters
ptThe point to free.
void mbedtls_ecp_point_init ( mbedtls_ecp_point pt)

This function initializes a point as zero.

Parameters
ptThe point to initialize.
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
grpThe group to which the point should belong. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
PThe destination context to import the point to. This must be initialized.
bufThe input buffer. This must be a readable buffer of length ilen Bytes.
ilenThe 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 import for the given group is not implemented.
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
PThe destination point. This must be initialized.
radixThe numeric base of the input.
xThe first affine coordinate, as a null-terminated string.
yThe second affine coordinate, as a null-terminated string.
Returns
0 on success.
An MBEDTLS_ERR_MPI_XXX error code on failure.
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
grpThe group to which the point should belong. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
PThe point to export. This must be initialized.
formatThe point format. This must be either MBEDTLS_ECP_PF_COMPRESSED or MBEDTLS_ECP_PF_UNCOMPRESSED. (For groups without these formats, this parameter is ignored. But it still has to be either of the above values.)
olenThe address at which to store the length of the output in Bytes. This must not be NULL.
bufThe output buffer. This must be a writable buffer of length buflen Bytes.
buflenThe 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.
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format or the export for the given group is not implemented.
Another negative error code on other kinds of failure.
int mbedtls_ecp_read_key ( mbedtls_ecp_group_id  grp_id,
mbedtls_ecp_keypair key,
const unsigned char *  buf,
size_t  buflen 
)

This function reads an elliptic curve private key.

Parameters
grp_idThe ECP group identifier.
keyThe destination key.
bufThe buffer containing the binary representation of the key. (Big endian integer for Weierstrass curves, byte string for Montgomery curves.)
buflenThe length of the buffer in bytes.
Returns
0 on success.
MBEDTLS_ERR_ECP_INVALID_KEY error if the key is invalid.
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for the group is not implemented.
Another negative error code on different kinds of failure.
void mbedtls_ecp_restart_free ( mbedtls_ecp_restart_ctx ctx)

Free the components of a restart context.

Parameters
ctxThe restart context to free. This may be NULL, in which case this function returns immediately. If it is not NULL, it must point to an initialized restart context.
void mbedtls_ecp_restart_init ( mbedtls_ecp_restart_ctx ctx)

Initialize a restart context.

Parameters
ctxThe restart context to initialize. This must not be NULL.
int mbedtls_ecp_restart_is_enabled ( void  )

Check if restart is enabled (max_ops != 0)

Returns
0 if max_ops == 0 (restart disabled)
1 otherwise (restart enabled)
int mbedtls_ecp_self_test ( int  verbose)

The ECP checkup routine.

Returns
0 on success.
1 on failure.
void mbedtls_ecp_set_max_ops ( unsigned  max_ops)

Set the maximum number of basic operations done in a row.

If more operations are needed to complete a computation, MBEDTLS_ERR_ECP_IN_PROGRESS will be returned by the function performing the computation. It is then the caller's responsibility to either call again with the same parameters until it returns 0 or an error code; or to free the restart context if the operation is to be aborted.

It is strictly required that all input parameters and the restart context be the same on successive calls for the same operation, but output parameters need not be the same; they must not be used until the function finally returns 0.

This only applies to functions whose documentation mentions they may return MBEDTLS_ERR_ECP_IN_PROGRESS (or MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS for functions in the SSL module). For functions that accept a "restart context" argument, passing NULL disables restart and makes the function equivalent to the function with the same name with _restartable removed. For functions in the ECDH module, restart is disabled unless the function accepts an "ECDH context" argument and mbedtls_ecdh_enable_restart() was previously called on that context. For function in the SSL module, restart is only enabled for specific sides and key exchanges (currently only for clients and ECDHE-ECDSA).

Parameters
max_opsMaximum number of basic operations done in a row. Default: 0 (unlimited). Lower (non-zero) values mean ECC functions will block for a lesser maximum amount of time.
Note
A "basic operation" is defined as a rough equivalent of a multiplication in GF(p) for the NIST P-256 curve. As an indication, with default settings, a scalar multiplication (full run of mbedtls_ecp_mul()) is:
  • about 3300 basic operations for P-256
  • about 9400 basic operations for P-384
Very low values are not always respected: sometimes functions need to block for a minimum number of operations, and will do so even if max_ops is set to a lower value. That minimum depends on the curve size, and can be made lower by decreasing the value of MBEDTLS_ECP_WINDOW_SIZE. As an indication, here is the lowest effective value for various curves and values of that parameter (w for short): w=6 w=5 w=4 w=3 w=2 P-256 208 208 160 136 124 P-384 682 416 320 272 248 P-521 1364 832 640 544 496
This setting is currently ignored by Curve25519.
int mbedtls_ecp_set_zero ( mbedtls_ecp_point pt)

This function sets a point to the point at infinity.

Parameters
ptThe 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.
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
grpThe group context to setup. This must be initialized.
bufThe address of the pointer to the start of the input buffer.
lenThe 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.
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
grpThe address at which to store the group id. This must not be NULL.
bufThe address of the pointer to the start of the input buffer.
lenThe 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.
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
grpThe ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
ptThe destination point.
bufThe address of the pointer to the start of the input buffer.
lenThe 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.
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
grpThe ECP group to be exported. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
olenThe address at which to store the number of Bytes written. This must not be NULL.
bufThe buffer to write to. This must be a writable buffer of length blen Bytes.
blenThe 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.
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
grpThe ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
ptThe point to be exported. This must be initialized.
formatThe point format to use. This must be either MBEDTLS_ECP_PF_COMPRESSED or MBEDTLS_ECP_PF_UNCOMPRESSED.
olenThe address at which to store the length in Bytes of the data written.
bufThe target buffer. This must be a writable buffer of length blen Bytes.
blenThe 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.
int mbedtls_ecp_write_key ( mbedtls_ecp_keypair key,
unsigned char *  buf,
size_t  buflen 
)

This function exports an elliptic curve private key.

Parameters
keyThe private key.
bufThe output buffer for containing the binary representation of the key. (Big endian integer for Weierstrass curves, byte string for Montgomery curves.)
buflenThe total length of the buffer in bytes.
Returns
0 on success.
MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the key representation is larger than the available space in buf.
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for the group is not implemented.
Another negative error code on different kinds of failure.