Loading...
Searching...
No Matches
mbedtls_ecp_group Struct Reference

The ECP group structure. More...

`#include <ecp.h>`

Collaboration diagram for mbedtls_ecp_group:
[legend]

## Data Fields

mbedtls_ecp_group_id | id
mbedtls_mpi | P
mbedtls_mpi | A
mbedtls_mpi | B
mbedtls_ecp_point | G
mbedtls_mpi | N
size_t | pbits
size_t | nbits
unsigned int | private_h
int(* | private_modp )(mbedtls_mpi *)
int(* | private_t_pre )(mbedtls_ecp_point *, void *)
int(* | private_t_post )(mbedtls_ecp_point *, void *)
void * | private_t_data
mbedtls_ecp_point * | private_T
size_t | private_T_size
const mbedtls_ecp_group_id | id
const mbedtls_mpi | P
const mbedtls_mpi | A
const mbedtls_mpi | B
const mbedtls_ecp_point | G
const mbedtls_mpi | N
const size_t | pbits
const size_t | nbits

## Detailed Description

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);
mbedtls_mpi_sub_int
int mbedtls_mpi_sub_int(mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint b)
Perform a signed subtraction of an MPI and an integer: X = A - b.
mbedtls_mpi_copy
int mbedtls_mpi_copy(mbedtls_mpi *X, const mbedtls_mpi *Y)
Make a copy of an MPI.
mbedtls_mpi_init
void mbedtls_mpi_init(mbedtls_mpi *X)
Initialize an MPI context.
mbedtls_mpi_free
void mbedtls_mpi_free(mbedtls_mpi *X)
This function frees the components of an MPI context.
mbedtls_ecp_group_init
void mbedtls_ecp_group_init(mbedtls_ecp_group *grp)
This function initializes an ECP group context without loading any domain parameters.
mbedtls_ecp_group_load
int mbedtls_ecp_group_load(mbedtls_ecp_group *grp, mbedtls_ecp_group_id id)
This function sets up an ECP group context from a standardized set of domain parameters.
mbedtls_ecp_group_free
void mbedtls_ecp_group_free(mbedtls_ecp_group *grp)
This function frees the components of an ECP group.
mbedtls_ecp_group_a_is_minus_3
static 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.
Definition ecp.h:1022
mbedtls_ecp_group::A
mbedtls_mpi A
Definition ecp.h:236

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.

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` 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.

Definition at line 233 of file ecp.h.

## Field Documentation

## A [1/2]

mbedtls_mpi 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`.

Definition at line 236 of file ecp.h.

Referenced by mbedtls_ecp_group_a_is_minus_3().

## A [2/2]

const mbedtls_mpi mbedtls_ecp_group::A

Definition at line 13 of file ecp_alt.h.

## B [1/2]

mbedtls_mpi mbedtls_ecp_group::B

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

Definition at line 241 of file ecp.h.

## B [2/2]

const mbedtls_mpi mbedtls_ecp_group::B

Definition at line 14 of file ecp_alt.h.

## G [1/2]

mbedtls_ecp_point mbedtls_ecp_group::G

The generator of the subgroup used.

Definition at line 243 of file ecp.h.

## G [2/2]

const mbedtls_ecp_point mbedtls_ecp_group::G

Definition at line 15 of file ecp_alt.h.

## id [1/2]

mbedtls_ecp_group_id mbedtls_ecp_group::id

An internal group identifier.

Definition at line 234 of file ecp.h.

## id [2/2]

const mbedtls_ecp_group_id mbedtls_ecp_group::id

Definition at line 11 of file ecp_alt.h.

## N [1/2]

mbedtls_mpi mbedtls_ecp_group::N

The order of `G`.

Definition at line 244 of file ecp.h.

## N [2/2]

const mbedtls_mpi mbedtls_ecp_group::N

Definition at line 16 of file ecp_alt.h.

## nbits [1/2]

size_t mbedtls_ecp_group::nbits

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

Definition at line 246 of file ecp.h.

## nbits [2/2]

const size_t mbedtls_ecp_group::nbits

Definition at line 18 of file ecp_alt.h.

## P [1/2]

mbedtls_mpi mbedtls_ecp_group::P

The prime modulus of the base field.

Definition at line 235 of file ecp.h.

## P [2/2]

const mbedtls_mpi mbedtls_ecp_group::P

Definition at line 12 of file ecp_alt.h.

## pbits [1/2]

size_t mbedtls_ecp_group::pbits

The number of bits in `P`.

Definition at line 245 of file ecp.h.

## pbits [2/2]

const size_t mbedtls_ecp_group::pbits

Definition at line 17 of file ecp_alt.h.

## private_h

unsigned int mbedtls_ecp_group::private_h

Definition at line 251 of file ecp.h.

## private_modp

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

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

Definition at line 252 of file ecp.h.

## private_T

mbedtls_ecp_point* mbedtls_ecp_group::private_T

Pre-computed points for ecp_mul_comb().

Definition at line 257 of file ecp.h.

## private_t_data

void* mbedtls_ecp_group::private_t_data

Unused.

Definition at line 256 of file ecp.h.

## private_t_post

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

Unused.

Definition at line 255 of file ecp.h.

## private_t_pre

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

Unused.

Definition at line 254 of file ecp.h.

## private_T_size

size_t mbedtls_ecp_group::private_T_size

The number of dynamic allocated pre-computed points.

Definition at line 258 of file ecp.h.

The documentation for this struct was generated from the following files:

- ecp.h
- ecp_alt.h