File ecp.h
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 RFC4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS).
RFC2409: The Internet Key Exchange (IKE) defines ECP group types.
Defines

MBEDTLS_ERR_ECP_BAD_INPUT_DATA
Bad input parameters to function.

MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL
The buffer is too small to write to.

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

MBEDTLS_ERR_ECP_VERIFY_FAILED
The signature is not valid.

MBEDTLS_ERR_ECP_ALLOC_FAILED
Memory allocation failed.

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

MBEDTLS_ERR_ECP_INVALID_KEY
Invalid private or public key.

MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH
The buffer contains a valid signature followed by more data.

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

MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED

MBEDTLS_ECP_MONTGOMERY_ENABLED

MBEDTLS_ECP_DP_MAX
The number of supported curves, plus one for MBEDTLS_ECP_DP_NONE.

MBEDTLS_ECP_MAX_BITS
The maximum size of the groups, that is, of
N
andP
.

MBEDTLS_ECP_MAX_BYTES

MBEDTLS_ECP_MAX_PT_LEN

MBEDTLS_ECP_OPS_CHK
basic ops count for ecp_check_pubkey()

MBEDTLS_ECP_OPS_DBL
basic ops count for ecp_double_jac()

MBEDTLS_ECP_OPS_ADD
basic ops count for see ecp_add_mixed()

MBEDTLS_ECP_OPS_INV
empirical equivalent for mpi_mod_inv()

MBEDTLS_ECP_BUDGET(ops)

MBEDTLS_ECP_PF_UNCOMPRESSED
The uncompressed point format for Short Weierstrass curves (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX).

MBEDTLS_ECP_PF_COMPRESSED
The compressed point format for Short Weierstrass curves (MBEDTLS_ECP_DP_SECP_XXX and MBEDTLS_ECP_DP_BP_XXX).
Warning
While this format is supported for all concerned curves for writing, when it comes to parsing, it is not supported for all curves. Specifically, parsing compressed points on MBEDTLS_ECP_DP_SECP224R1 and MBEDTLS_ECP_DP_SECP224K1 is not supported.

MBEDTLS_ECP_TLS_NAMED_CURVE
The named_curve of ECCurveType.
Typedefs

typedef struct mbedtls_ecp_curve_info mbedtls_ecp_curve_info
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.

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
orZ == 1
. Other values ofZ
are used only by internal functions. The point is zero, or “at infinity”, ifZ == 0
. Otherwise,X
andY
are its standard (affine) coordinates.

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 + RFC4492)Montgomery:
y^2 = x^3 + A x^2 + x mod P
(Curve25519, Curve448)
G
) for a primeorder subgroup is fixed.For Short Weierstrass, this subgroup is the whole curve, and its cardinality is denoted by
N
. Our code requires thatN
is an odd prime as mbedtls_ecp_mul() requires an odd number, and mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.The default implementation only initializes
A
without setting it to the authentic value for curves withA = 3
(SECP256R1, etc), in which case you need to loadA
by yourself when using domain parameters directly, for example:mbedtls_mpi_init(&A); mbedtls_ecp_group_init(&grp); CHECK_RETURN(mbedtls_ecp_group_load(&grp, grp_id)); if (mbedtls_ecp_group_a_is_minus_3(&grp)) { CHECK_RETURN(mbedtls_mpi_sub_int(&A, &grp.P, 3)); } else { CHECK_RETURN(mbedtls_mpi_copy(&A, &grp.A)); } do_something_with_a(&A); cleanup: mbedtls_mpi_free(&A); mbedtls_ecp_group_free(&grp);
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 ofN
but the required size for private keys.If
modp
is NULL, reduction moduloP
is done using a generic algorithm. Otherwise,modp
must point to a function that takes anmbedtls_mpi
in the range of0..2^(2*pbits)1
, and transforms it inplace to an integer which is congruent modP
to the given MPI, and is close enough topbits
in size, so that it may be efficiently brought in the 0..P1 range by a few additions or subtractions. Therefore, it is only an approximate modular reduction. It must return 0 on success and nonzero on failure.Note
Alternative implementations of the ECP module must obey the following constraints.
Group IDs must be distinct: if two group structures have the same ID, then they must be identical.
The fields
id
,P
,A
,B
,G
,N
,pbits
andnbits
must have the same type and semantics as in the builtin implementation. They must be available for reading, but direct modification of these fields does not need to be supported. They do not need to be at the same offset in the structure.

typedef struct mbedtls_ecp_restart_mul mbedtls_ecp_restart_mul_ctx
Internal restart context for multiplication.
Note
Opaque struct

typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx
Internal restart context for ecp_muladd()
Note
Opaque struct

typedef struct mbedtls_ecp_keypair mbedtls_ecp_keypair
The ECP keypair structure.
A generic keypair 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.
Enums

enum mbedtls_ecp_group_id
Domainparameter 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().
Values:

enumerator MBEDTLS_ECP_DP_NONE
Curve not defined.

enumerator MBEDTLS_ECP_DP_SECP192R1
Domain parameters for the 192bit curve defined by FIPS 1864 and SEC1.

enumerator MBEDTLS_ECP_DP_SECP224R1
Domain parameters for the 224bit curve defined by FIPS 1864 and SEC1.

enumerator MBEDTLS_ECP_DP_SECP256R1
Domain parameters for the 256bit curve defined by FIPS 1864 and SEC1.

enumerator MBEDTLS_ECP_DP_SECP384R1
Domain parameters for the 384bit curve defined by FIPS 1864 and SEC1.

enumerator MBEDTLS_ECP_DP_SECP521R1
Domain parameters for the 521bit curve defined by FIPS 1864 and SEC1.

enumerator MBEDTLS_ECP_DP_BP256R1
Domain parameters for 256bit Brainpool curve.

enumerator MBEDTLS_ECP_DP_BP384R1
Domain parameters for 384bit Brainpool curve.

enumerator MBEDTLS_ECP_DP_BP512R1
Domain parameters for 512bit Brainpool curve.

enumerator MBEDTLS_ECP_DP_CURVE25519
Domain parameters for Curve25519.

enumerator MBEDTLS_ECP_DP_SECP192K1
Domain parameters for 192bit “Koblitz” curve.

enumerator MBEDTLS_ECP_DP_SECP224K1
Domain parameters for 224bit “Koblitz” curve.

enumerator MBEDTLS_ECP_DP_SECP256K1
Domain parameters for 256bit “Koblitz” curve.

enumerator MBEDTLS_ECP_DP_CURVE448
Domain parameters for Curve448.

enumerator MBEDTLS_ECP_DP_NONE
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.
 Parameters:
grp – Group structure
rs_ctx – Restart context
ops – Number of basic ops to do
 Returns:
0
if doingops
basic ops is still allowed, Returns:
MBEDTLS_ERR_ECP_IN_PROGRESS otherwise.

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 \c _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 ECDHEECDSA).
Note
A “basic operation” is defined as a rough equivalent of a multiplication in GF(p) for the NIST P256 curve. As an indication, with default settings, a scalar multiplication (full run of
mbedtls_ecp_mul()
) is:about 3300 basic operations for P256
about 9400 basic operations for P384
Note
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 P256 208 208 160 136 124 P384 682 416 320 272 248 P521 1364 832 640 544 496Note
This setting is currently ignored by Curve25519.
Warning
Using the PSA interruptible interfaces with keys in local storage and no accelerator driver will also call this function to set the values specified via those interfaces, overwriting values previously set. Care should be taken if mixing these two interfaces.
 Parameters:
max_ops – Maximum number of basic operations done in a row. Default: 0 (unlimited). Lower (nonzero) values mean ECC functions will block for a lesser maximum amount of time.

int mbedtls_ecp_restart_is_enabled(void)
Check if restart is enabled (max_ops != 0)
 Returns:
0
ifmax_ops
== 0 (restart disabled) Returns:
1
otherwise (restart enabled)

mbedtls_ecp_curve_type mbedtls_ecp_get_type(const mbedtls_ecp_group *grp)

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.

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.

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.
 Returns:
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_id – An
MBEDTLS_ECP_DP_XXX
value. Returns:
The associated curve information on success.
 Returns:
NULL on failure.

const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name(const char *name)
This function retrieves curve information from a humanreadable name.
 Parameters:
name – The humanreadable name.
 Returns:
The associated curve information on success.
 Returns:
NULL on failure.

void mbedtls_ecp_point_init(mbedtls_ecp_point *pt)
This function initializes a point as zero.
 Parameters:
pt – The point to initialize.

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.

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.

void mbedtls_ecp_point_free(mbedtls_ecp_point *pt)
This function frees the components of a point.
 Parameters:
pt – The point to 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 notNULL
, it must point to an initialized ECP group.

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 notNULL
, it must point to an initialized ECP key pair.

void mbedtls_ecp_restart_init(mbedtls_ecp_restart_ctx *ctx)
Initialize a restart context.
 Parameters:
ctx – The restart context to initialize. This must not be
NULL
.

void mbedtls_ecp_restart_free(mbedtls_ecp_restart_ctx *ctx)
Free the components of a restart context.
 Parameters:
ctx – The restart context to free. This may be
NULL
, in which case this function returns immediately. If it is notNULL
, it must point to an initialized restart context.

int mbedtls_ecp_copy(mbedtls_ecp_point *P, const mbedtls_ecp_point *Q)
This function copies the contents of point
Q
into pointP
. Parameters:
P – The destination point. This must be initialized.
Q – The source point. This must be initialized.
 Returns:
0
on success. Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
Another negative error code for other kinds of failure.

int mbedtls_ecp_group_copy(mbedtls_ecp_group *dst, const mbedtls_ecp_group *src)
This function copies the contents of group
src
into groupdst
. Parameters:
dst – The destination group. This must be initialized.
src – The source group. This must be initialized.
 Returns:
0
on success. Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
Another negative error code on other kinds of failure.

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. Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
Another negative error code on other kinds of failure.

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. Returns:
0
if the point is nonzero. Returns:
A negative error code on 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:
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. Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the points are not equal.

int mbedtls_ecp_point_read_string(mbedtls_ecp_point *P, int radix, const char *x, const char *y)
This function imports a nonzero 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 nullterminated string.
y – The second affine coordinate, as a nullterminated string.
 Returns:
0
on success. Returns:
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:
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. (For groups without these formats, this parameter is ignored. But it still has to be either of the above values.)
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. Returns:
MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer is too small to hold the point.
 Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format or the export for the given group is not implemented.
 Returns:
Another negative error code on other kinds of failure.

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.
Note
For compressed points, see MBEDTLS_ECP_PF_COMPRESSED for limitations.
 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. Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
 Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the import for the given group is not implemented.

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. Returns:
An
MBEDTLS_ERR_MPI_XXX
error code on initialization failure. Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.

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. Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the input is invalid.
 Returns:
MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the target buffer is too small to hold the exported point.
 Returns:
Another negative error code on other kinds of failure.

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 RFC4492: 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. Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if
id
doesn’t correspond to a known group. Returns:
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:
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. Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
 Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not recognized.
 Returns:
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:
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. Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid.
 Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the group is not recognized.
 Returns:
Another negative error code on other kinds of failure.

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. Returns:
MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer is too small to hold the exported group.
 Returns:
Another negative error code on other kinds of failure.

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
.It is not threadsafe to use same group in multiple threads.
Note
To prevent timing attacks, this function executes the exact same sequence of basefield operations for any valid
m
. It avoids any ifbranch or array index depending on the value ofm
. It also usesf_rng
to randomize some intermediate results. 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 must not be
NULL
.p_rng – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
doesn’t need a context.
 Returns:
0
on success. Returns:
MBEDTLS_ERR_ECP_INVALID_KEY if
m
is not a valid private key, orP
is not a valid public key. Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
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 (*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.See also
Note
This function does the same as
mbedtls_ecp_mul()
, but it can return early and restart according to the limit set withmbedtls_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 must not be
NULL
.p_rng – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
doesn’t need a context.rs_ctx – The restart context (NULL disables restart).
 Returns:
0
on success. Returns:
MBEDTLS_ERR_ECP_INVALID_KEY if
m
is not a valid private key, orP
is not a valid public key. Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see
mbedtls_ecp_set_max_ops()
. Returns:
Another negative error code on other kinds of failure.

static inline int mbedtls_ecp_group_a_is_minus_3(const mbedtls_ecp_group *grp)
This function checks if domain parameter A of the curve is
3
.Note
This function is only defined for short Weierstrass curves. It may not be included in builds without any short Weierstrass curve.
 Parameters:
grp – The ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
 Returns:
1
ifA = 3
. Returns:
0
Otherwise.

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 threadsafe 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.
Note
This function is only defined for short Weierstrass curves. It may not be included in builds without any short Weierstrass curve.
 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. Returns:
MBEDTLS_ERR_ECP_INVALID_KEY if
m
orn
are not valid private keys, orP
orQ
are not valid public keys. Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if
grp
does not designate a short Weierstrass curve. Returns:
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
Note
This function works the same as
mbedtls_ecp_muladd()
, but it can return early and restart according to the limit set withmbedtls_ecp_set_max_ops()
to reduce blocking.Note
This function is only defined for short Weierstrass curves. It may not be included in builds without any short Weierstrass curve.
 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. Returns:
MBEDTLS_ERR_ECP_INVALID_KEY if
m
orn
are not valid private keys, orP
orQ
are not valid public keys. Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if
grp
does not designate a short Weierstrass curve. Returns:
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see
mbedtls_ecp_set_max_ops()
. Returns:
Another negative error code on other kinds of 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 nonzero, 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. Returns:
MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid public key for the given curve.
 Returns:
Another negative error code on other kinds of failure.

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. Returns:
MBEDTLS_ERR_ECP_INVALID_KEY if the point is not a valid private key for the given curve.
 Returns:
Another negative error code on other kinds of failure.

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.
 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 beNULL
iff_rng
doesn’t need a context argument.
 Returns:
0
on success. Returns:
An
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_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 (*f_rng)(void*, unsigned char*, size_t), 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 pointgrp>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 beNULL
iff_rng
doesn’t need a context argument.
 Returns:
0
on success. Returns:
An
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_MPI_XXX
error code on failure.

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.
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 beNULL
iff_rng
doesn’t need a context argument.
 Returns:
0
on success. Returns:
An
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_MPI_XXX
error code on failure.

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.
 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 beNULL
iff_rng
doesn’t need a context argument.
 Returns:
0
on success. Returns:
An
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_MPI_XXX
error code on failure.

int mbedtls_ecp_set_public_key(mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, const mbedtls_ecp_point *Q)
Set the public key in a key pair object.
Note
This function does not check that the point actually belongs to the given group. Call mbedtls_ecp_check_pubkey() on
Q
before calling this function to check that.Note
This function does not check that the public key matches the private key that is already in
key
, if any. To check the consistency of the resulting key pair object, call mbedtls_ecp_check_pub_priv() after setting both the public key and the private key. Parameters:
grp_id – The ECP group identifier.
key – The key pair object. It must be initialized. If its group has already been set, it must match
grp_id
. If its group has not been set, it will be set togrp_id
. If the public key has already been set, it is overwritten.Q – The public key to copy. This must be a point on the curve indicated by
grp_id
.
 Returns:
0
on success. Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if
key
does not matchgrp_id
. Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for the group is not implemented.
 Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
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.
Note
This function does not set the public key in the key pair object. Without a public key, the key pair object cannot be used with operations that require the public key. Call mbedtls_ecp_keypair_calc_public() to set the public key from the private key. Alternatively, you can call mbedtls_ecp_set_public_key() to set the public key part, and then optionally mbedtls_ecp_check_pub_priv() to check that the private and public parts are consistent.
Note
If a public key has already been set in the key pair object, this function does not check that it is consistent with the private key. Call mbedtls_ecp_check_pub_priv() after setting both the public key and the private key to make that check.
 Parameters:
grp_id – The ECP group identifier.
key – The destination key.
buf – The buffer containing the binary representation of the key. (Big endian integer for Weierstrass curves, byte string for Montgomery curves.)
buflen – The length of the buffer in bytes.
 Returns:
0
on success. Returns:
MBEDTLS_ERR_ECP_INVALID_KEY error if the key is invalid.
 Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
 Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the operation for the group is not implemented.
 Returns:
Another negative error code on different kinds of failure.

int mbedtls_ecp_write_key_ext(const mbedtls_ecp_keypair *key, size_t *olen, unsigned char *buf, size_t buflen)
This function exports an elliptic curve private key.
 Parameters:
key – The private key.
olen – On success, the length of the private key. This is always (
grp>nbits
+ 7) / 8 bytes wheregrp>nbits
is the private key size in bits.buf – The output buffer for containing the binary representation of the key.
buflen – The total length of the buffer in bytes. MBEDTLS_ECP_MAX_BYTES is always sufficient.
 Returns:
0
on success. Returns:
MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the
key
representation is larger than the available space inbuf
. Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if no private key is set in
key
. Returns:
Another negative error code on different kinds of failure.

int mbedtls_ecp_write_public_key(const mbedtls_ecp_keypair *key, int format, size_t *olen, unsigned char *buf, size_t buflen)
This function exports an elliptic curve public key.
Note
If the public key was not set in
key
, the output is unspecified. Future versions may return an error in that case. Parameters:
key – The public key.
format – The 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.)
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. Returns:
MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL if the output buffer is too small to hold the point.
 Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format or the export for the given group is not implemented.
 Returns:
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 (*f_rng)(void*, unsigned char*, size_t), void *p_rng)
This function checks that the keypair objects
pub
andprv
have the same group and the same public point, and that the private key inprv
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.
f_rng – The RNG function. This must not be
NULL
.p_rng – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
doesn’t need a context.
 Returns:
0
on success, meaning that the keys are valid and match. Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the keys are invalid or do not match.
 Returns:
An
MBEDTLS_ERR_ECP_XXX
or anMBEDTLS_ERR_MPI_XXX
error code on calculation failure.

int mbedtls_ecp_keypair_calc_public(mbedtls_ecp_keypair *key, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng)
Calculate the public key from a private key in a key pair.
 Parameters:
key – A keypair structure. It must have a private key set. If the public key is set, it will be overwritten.
f_rng – The RNG function. This must not be
NULL
.p_rng – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
doesn’t need a context.
 Returns:
0
on success. The key pair object can be used for operations that require the public key. Returns:
An
MBEDTLS_ERR_ECP_XXX
or anMBEDTLS_ERR_MPI_XXX
error code on calculation failure.

mbedtls_ecp_group_id mbedtls_ecp_keypair_get_group_id(const mbedtls_ecp_keypair *key)
Query the group that a key pair belongs to.
 Parameters:
key – The key pair to query.
 Returns:
The group ID for the group registered in the key pair object. This is
MBEDTLS_ECP_DP_NONE
if no group has been set in the key pair object.

int mbedtls_ecp_export(const mbedtls_ecp_keypair *key, mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q)
This function exports generic keypair parameters.
Each of the output parameters can be a null pointer if you do not need that parameter.
Note
If the private key or the public key was not set in
key
, the corresponding output is unspecified. Future versions may return an error in that case. Parameters:
key – The key pair to export from.
grp – Slot for exported ECP group. It must either be null or point to an initialized ECP group.
d – Slot for the exported secret value. It must either be null or point to an initialized mpi.
Q – Slot for the exported public value. It must either be null or point to an initialized ECP point.
 Returns:
0
on success, Returns:
MBEDTLS_ERR_MPI_ALLOC_FAILED on memoryallocation failure.
 Returns:
MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if key id doesn’t correspond to a known group.
 Returns:
Another negative error code on other kinds of failure.

int mbedtls_ecp_self_test(int verbose)
The ECP checkup routine.
 Returns:
0
on success. Returns:
1
on failure.

struct mbedtls_ecp_curve_info
 #include <ecp.h>
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.
Public Members

mbedtls_ecp_group_id grp_id
An internal identifier.

uint16_t tls_id
The TLS NamedCurve identifier.

uint16_t bit_size
The curve size in bits.

const char *name
A humanfriendly name.

mbedtls_ecp_group_id grp_id

struct mbedtls_ecp_point
 #include <ecp.h>
The ECP point structure, in Jacobian coordinates.
Note
All functions expect and return points satisfying the following condition:
Z == 0
orZ == 1
. Other values ofZ
are used only by internal functions. The point is zero, or “at infinity”, ifZ == 0
. Otherwise,X
andY
are its standard (affine) coordinates.Public Members

mbedtls_mpi private_X
The X coordinate of the ECP point.

mbedtls_mpi private_Y
The Y coordinate of the ECP point.

mbedtls_mpi private_Z
The Z coordinate of the ECP point.

mbedtls_mpi private_X

struct mbedtls_ecp_group
 #include <ecp.h>
The ECP group structure.
We consider two types of curve equations:
Short Weierstrass:
y^2 = x^3 + A x + B mod P
(SEC1 + RFC4492)Montgomery:
y^2 = x^3 + A x^2 + x mod P
(Curve25519, Curve448)
G
) for a primeorder subgroup is fixed.For Short Weierstrass, this subgroup is the whole curve, and its cardinality is denoted by
N
. Our code requires thatN
is an odd prime as mbedtls_ecp_mul() requires an odd number, and mbedtls_ecdsa_sign() requires that it is prime for blinding purposes.The default implementation only initializes
A
without setting it to the authentic value for curves withA = 3
(SECP256R1, etc), in which case you need to loadA
by yourself when using domain parameters directly, for example:mbedtls_mpi_init(&A); mbedtls_ecp_group_init(&grp); CHECK_RETURN(mbedtls_ecp_group_load(&grp, grp_id)); if (mbedtls_ecp_group_a_is_minus_3(&grp)) { CHECK_RETURN(mbedtls_mpi_sub_int(&A, &grp.P, 3)); } else { CHECK_RETURN(mbedtls_mpi_copy(&A, &grp.A)); } do_something_with_a(&A); cleanup: mbedtls_mpi_free(&A); mbedtls_ecp_group_free(&grp);
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 ofN
but the required size for private keys.If
modp
is NULL, reduction moduloP
is done using a generic algorithm. Otherwise,modp
must point to a function that takes anmbedtls_mpi
in the range of0..2^(2*pbits)1
, and transforms it inplace to an integer which is congruent modP
to the given MPI, and is close enough topbits
in size, so that it may be efficiently brought in the 0..P1 range by a few additions or subtractions. Therefore, it is only an approximate modular reduction. It must return 0 on success and nonzero on failure.Note
Alternative implementations of the ECP module must obey the following constraints.
Group IDs must be distinct: if two group structures have the same ID, then they must be identical.
The fields
id
,P
,A
,B
,G
,N
,pbits
andnbits
must have the same type and semantics as in the builtin implementation. They must be available for reading, but direct modification of these fields does not need to be supported. They do not need to be at the same offset in the structure.
Public Members

mbedtls_ecp_group_id id
An internal group identifier.

mbedtls_mpi P
The prime modulus of the base field.

mbedtls_mpi A
For Short Weierstrass:
A
in the equation. Note thatA
is not set to the authentic value in some cases. Refer to detailed description of mbedtls_ecp_group if using domain parameters in the structure. For Montgomery curves:(A + 2) / 4
.

mbedtls_mpi B
For Short Weierstrass:
B
in the equation. For Montgomery curves: unused.

mbedtls_ecp_point G
The generator of the subgroup used.

mbedtls_mpi N
The order of
G
.

size_t pbits
The number of bits in
P
.

size_t nbits
For Short Weierstrass: The number of bits in
P
. For Montgomery curves: the number of bits in the private keys.

unsigned int private_h

int (*private_modp)(mbedtls_mpi*)
The function for fast pseudoreduction mod
P
(see above).

int (*private_t_pre)(mbedtls_ecp_point*, void*)
Unused.

int (*private_t_post)(mbedtls_ecp_point*, void*)
Unused.

void *private_t_data
Unused.

mbedtls_ecp_point *private_T
Precomputed points for ecp_mul_comb().

size_t private_T_size
The number of dynamic allocated precomputed points.

struct mbedtls_ecp_restart_ctx
 #include <ecp.h>
General context for resuming ECC operations.
Public Members

unsigned private_ops_done
current ops count

unsigned private_depth
call depth (0 = toplevel)

mbedtls_ecp_restart_mul_ctx *private_rsm
ecp_mul_comb() subcontext

mbedtls_ecp_restart_muladd_ctx *private_ma
ecp_muladd() subcontext

unsigned private_ops_done

struct mbedtls_ecp_keypair
 #include <ecp.h>
The ECP keypair structure.
A generic keypair 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.
Public Members

mbedtls_ecp_group private_grp
Elliptic curve and base point

mbedtls_mpi private_d
our secret value

mbedtls_ecp_point private_Q
our public value

mbedtls_ecp_group private_grp