mbedtls_ecp_group
ecp.h
mbedtls_ecp_group_id mbedtls_ecp_group_id mbedtls_ecp_group::id id mbedtls_ecp_group::id

An internal group identifier.

mbedtls_mpi mbedtls_mpi mbedtls_ecp_group::P P mbedtls_ecp_group::P

The prime modulus of the base field.

mbedtls_mpi mbedtls_mpi mbedtls_ecp_group::A A mbedtls_ecp_group::A

For Short Weierstrass: `A` in the equation. Note that `A` 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_ecp_group_a_is_minus_3
mbedtls_mpi mbedtls_mpi mbedtls_ecp_group::B B mbedtls_ecp_group::B

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

mbedtls_ecp_point mbedtls_ecp_point mbedtls_ecp_group::G G mbedtls_ecp_group::G

The generator of the subgroup used.

mbedtls_mpi mbedtls_mpi mbedtls_ecp_group::N N mbedtls_ecp_group::N

The order of `G`.

size_t size_t mbedtls_ecp_group::pbits pbits mbedtls_ecp_group::pbits

The number of bits in `P`.

size_t size_t mbedtls_ecp_group::nbits nbits mbedtls_ecp_group::nbits

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

unsigned int unsigned int mbedtls_ecp_group::private_h private_h mbedtls_ecp_group::private_h
int(* int(* mbedtls_ecp_group::private_modp) (mbedtls_mpi *) )(mbedtls_mpi *) private_modp mbedtls_ecp_group::private_modp

The function for fast pseudo-reduction mod `P` (see above).

int(* int(* mbedtls_ecp_group::private_t_pre) (mbedtls_ecp_point *, void *) )(mbedtls_ecp_point *, void *) private_t_pre mbedtls_ecp_group::private_t_pre

Unused.

int(* int(* mbedtls_ecp_group::private_t_post) (mbedtls_ecp_point *, void *) )(mbedtls_ecp_point *, void *) private_t_post mbedtls_ecp_group::private_t_post

Unused.

void * void* mbedtls_ecp_group::private_t_data private_t_data mbedtls_ecp_group::private_t_data

Unused.

mbedtls_ecp_point * mbedtls_ecp_point* mbedtls_ecp_group::private_T private_T mbedtls_ecp_group::private_T

Pre-computed points for ecp_mul_comb().

size_t size_t mbedtls_ecp_group::private_T_size private_T_size mbedtls_ecp_group::private_T_size

The number of dynamic allocated pre-computed points.

const mbedtls_ecp_group_id const mbedtls_ecp_group_id mbedtls_ecp_group::id id mbedtls_ecp_group::id
const mbedtls_mpi const mbedtls_mpi mbedtls_ecp_group::P P mbedtls_ecp_group::P
const mbedtls_mpi const mbedtls_mpi mbedtls_ecp_group::A A mbedtls_ecp_group::A
const mbedtls_mpi const mbedtls_mpi mbedtls_ecp_group::B B mbedtls_ecp_group::B
const mbedtls_ecp_point const mbedtls_ecp_point mbedtls_ecp_group::G G mbedtls_ecp_group::G
const mbedtls_mpi const mbedtls_mpi mbedtls_ecp_group::N N mbedtls_ecp_group::N
const size_t const size_t mbedtls_ecp_group::pbits pbits mbedtls_ecp_group::pbits
const size_t const size_t mbedtls_ecp_group::nbits nbits mbedtls_ecp_group::nbits

The ECP group structure.

We consider two types of curve equations:

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

- Montgomery: `y^2 = x^3 + A x^2 + x mod P` (Curve25519, Curve448)

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

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

The default implementation only initializes `A` without setting it to the authentic value for curves with `A = -3`(SECP256R1, etc), in which case you need to load `A` 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 of `N` but the required size for private keys.

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

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` and `nbits` must have the same type and semantics as in the built-in 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.

mbedtls_ecp_group
A
B
N
P
G
private_T
mbedtls_ecp_point
private_X
private_Y
private_Z
mbedtls_mpi
- mbedtls_ecp_group
  A
- mbedtls_ecp_group
  A
- mbedtls_ecp_group
  B
- mbedtls_ecp_group
  B
- mbedtls_ecp_group
  G
- mbedtls_ecp_group
  G
- mbedtls_ecp_group
  id
- mbedtls_ecp_group
  id
- mbedtls_ecp_group
  N
- mbedtls_ecp_group
  N
- mbedtls_ecp_group
  nbits
- mbedtls_ecp_group
  nbits
- mbedtls_ecp_group
  P
- mbedtls_ecp_group
  P
- mbedtls_ecp_group
  pbits
- mbedtls_ecp_group
  pbits
- mbedtls_ecp_group
  private_h
- mbedtls_ecp_group
  private_modp
- mbedtls_ecp_group
  private_T
- mbedtls_ecp_group
  private_t_data
- mbedtls_ecp_group
  private_t_post
- mbedtls_ecp_group
  private_t_pre
- mbedtls_ecp_group
  private_T_size