mbed TLS v2.9.0
|
This file provides an API for Elliptic Curves over GF(P) (ECP). More...
#include "bignum.h"
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_group |
The ECP group structure. More... | |
struct | mbedtls_ecp_keypair |
The ECP key-pair structure. More... | |
Macros | |
#define | MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 |
#define | MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 |
#define | MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 |
#define | MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 |
#define | MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 |
#define | MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 |
#define | MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 |
#define | MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 |
#define | MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 |
#define | MBEDTLS_ECP_DP_MAX 12 |
#define | MBEDTLS_ECP_PF_UNCOMPRESSED 0 |
#define | MBEDTLS_ECP_PF_COMPRESSED 1 |
#define | MBEDTLS_ECP_TLS_NAMED_CURVE 3 |
SECTION: Module settings | |
The configuration options you can set for this module are in this section. Either change them in config.h, or define them using the compiler command line. | |
#define | MBEDTLS_ECP_MAX_BITS 521 |
#define | MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 ) |
#define | MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 ) |
#define | MBEDTLS_ECP_WINDOW_SIZE 6 |
#define | MBEDTLS_ECP_FIXED_POINT_OPTIM 1 |
Functions | |
const mbedtls_ecp_curve_info * | mbedtls_ecp_curve_list (void) |
This function retrieves the information defined in mbedtls_ecp_curve_info() for all supported curves in order of preference. More... | |
const mbedtls_ecp_group_id * | mbedtls_ecp_grp_id_list (void) |
This function retrieves the list of internal group identifiers of all supported curves in the order of preference. More... | |
const mbedtls_ecp_curve_info * | mbedtls_ecp_curve_info_from_grp_id (mbedtls_ecp_group_id grp_id) |
This function retrieves curve information from an internal group identifier. More... | |
const mbedtls_ecp_curve_info * | mbedtls_ecp_curve_info_from_tls_id (uint16_t tls_id) |
This function retrieves curve information from a TLS NamedCurve value. More... | |
const mbedtls_ecp_curve_info * | mbedtls_ecp_curve_info_from_name (const char *name) |
This function retrieves curve information from a human-readable name. More... | |
void | mbedtls_ecp_point_init (mbedtls_ecp_point *pt) |
This function initializes a point as zero. More... | |
void | mbedtls_ecp_group_init (mbedtls_ecp_group *grp) |
This function initializes an ECP group context without loading any domain parameters. More... | |
void | mbedtls_ecp_keypair_init (mbedtls_ecp_keypair *key) |
This function initializes a key pair as an invalid one. More... | |
void | mbedtls_ecp_point_free (mbedtls_ecp_point *pt) |
This function frees the components of a point. More... | |
void | mbedtls_ecp_group_free (mbedtls_ecp_group *grp) |
This function frees the components of an ECP group. More... | |
void | mbedtls_ecp_keypair_free (mbedtls_ecp_keypair *key) |
This function frees the components of a key pair. More... | |
int | mbedtls_ecp_copy (mbedtls_ecp_point *P, const mbedtls_ecp_point *Q) |
This function copies the contents of point Q into point P . More... | |
int | mbedtls_ecp_group_copy (mbedtls_ecp_group *dst, const mbedtls_ecp_group *src) |
This function copies the contents of group src into group dst . More... | |
int | mbedtls_ecp_set_zero (mbedtls_ecp_point *pt) |
This function sets a point to zero. More... | |
int | mbedtls_ecp_is_zero (mbedtls_ecp_point *pt) |
This function checks if a point is zero. 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. More... | |
int | mbedtls_ecp_group_load (mbedtls_ecp_group *grp, mbedtls_ecp_group_id id) |
This function sets a group using standardized domain parameters. More... | |
int | mbedtls_ecp_tls_read_group (mbedtls_ecp_group *grp, const unsigned char **buf, size_t len) |
This function sets a group from a TLS ECParameters record. More... | |
int | mbedtls_ecp_tls_write_group (const mbedtls_ecp_group *grp, size_t *olen, unsigned char *buf, size_t blen) |
This function writes the TLS ECParameters record for a group. 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 multiplication of a point by an integer: R = m * P . 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_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_keypair_base (mbedtls_ecp_group *grp, const mbedtls_ecp_point *G, mbedtls_mpi *d, mbedtls_ecp_point *Q, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) |
This function generates a keypair with a configurable base point. More... | |
int | mbedtls_ecp_gen_keypair (mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) |
This function generates an ECP keypair. More... | |
int | mbedtls_ecp_gen_key (mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng) |
This function generates an ECP key. More... | |
int | mbedtls_ecp_check_pub_priv (const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv) |
This function checks that the keypair objects pub and prv have the same group and the same public point, and that the private key in prv is consistent with the public key. More... | |
int | mbedtls_ecp_self_test (int verbose) |
The ECP checkup routine. More... | |
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.
#define MBEDTLS_ECP_DP_MAX 12 |
The number of supported curves, plus one for MBEDTLS_ECP_DP_NONE.
#define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 |
#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_PF_UNCOMPRESSED 0 |
#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 |
#define MBEDTLS_ECP_WINDOW_SIZE 6 |
#define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 |
#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_HW_ACCEL_FAILED -0x4B80 |
#define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 |
#define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 |
#define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 |
#define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 |
enum mbedtls_ecp_group_id |
Domain-parameter identifiers: curve, subgroup, and generator.
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.
grp | The group used. |
d | The integer to check. |
0
if the point is a valid private key. int mbedtls_ecp_check_pub_priv | ( | const mbedtls_ecp_keypair * | pub, |
const mbedtls_ecp_keypair * | prv | ||
) |
This function checks that the keypair objects pub
and prv
have the same group and the same public point, and that the private key in prv
is consistent with the public key.
pub | The keypair structure holding the public key. If it contains a private key, that part is ignored. |
prv | The keypair structure holding the full keypair. |
0
on success, meaning that the keys are valid and match. 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 \p 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.
grp | The curve the point should lie on. |
pt | The point to check. |
0
if the point is a valid public key. int mbedtls_ecp_copy | ( | mbedtls_ecp_point * | P, |
const mbedtls_ecp_point * | Q | ||
) |
This function copies the contents of point Q
into point P
.
P | The destination point. |
Q | The source point. |
0
on success. 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.
grp_id | An MBEDTLS_ECP_DP_XXX value. |
const mbedtls_ecp_curve_info* mbedtls_ecp_curve_info_from_name | ( | const char * | name | ) |
This function retrieves curve information from a human-readable name.
name | The human-readable name. |
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.
tls_id | An MBEDTLS_ECP_DP_XXX value. |
const mbedtls_ecp_curve_info* mbedtls_ecp_curve_list | ( | void | ) |
This function retrieves the information defined in mbedtls_ecp_curve_info() for all supported curves in order of preference.
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.
grp_id | The ECP group identifier. |
key | The destination key. |
f_rng | The RNG function. |
p_rng | The RNG context. |
0
on success. 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.
grp | The ECP group. |
d | The destination MPI (secret part). |
Q | The destination point (public part). |
f_rng | The RNG function. |
p_rng | The RNG context. |
0
on success. 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.
grp | The ECP group. |
G | The chosen base point. |
d | The destination MPI (secret part). |
Q | The destination point (public part). |
f_rng | The RNG function. |
p_rng | The RNG context. |
0
on success. MBEDTLS_ERR_ECP_XXX
or MBEDTLS_MPI_XXX
error code on failure. 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
.
dst | The destination group. |
src | The source group. |
0
on success. void mbedtls_ecp_group_free | ( | mbedtls_ecp_group * | grp | ) |
This function frees the components of an ECP group.
grp | The group to free. |
void mbedtls_ecp_group_init | ( | mbedtls_ecp_group * | grp | ) |
This function initializes an ECP group context without loading any domain parameters.
int mbedtls_ecp_group_load | ( | mbedtls_ecp_group * | grp, |
mbedtls_ecp_group_id | id | ||
) |
This function sets a group using standardized domain parameters.
MBEDTLS_ECP_DP_XXX
macro.grp | The destination group. |
id | The identifier of the domain parameter set to load. |
0
on success, MBEDTLS_ERR_MPI_XXX
error code on initialization 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.
int mbedtls_ecp_is_zero | ( | mbedtls_ecp_point * | pt | ) |
This function checks if a point is zero.
pt | The point to test. |
1
if the point is zero. 0
if the point is non-zero. void mbedtls_ecp_keypair_free | ( | mbedtls_ecp_keypair * | key | ) |
This function frees the components of a key pair.
key | The key pair to free. |
void mbedtls_ecp_keypair_init | ( | mbedtls_ecp_keypair * | key | ) |
This function initializes a key pair as an invalid one.
key | The 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 multiplication of a point by an integer: R
= m
* P
.
It is not thread-safe to use same group in multiple threads.
m
. It avoids any if-branch or array index depending on the value of m
.f_rng
is not NULL, it is used to randomize intermediate results to prevent potential timing attacks targeting these results. We recommend always providing a non-NULL f_rng
. The overhead is negligible.grp | The ECP group. |
R | The destination point. |
m | The integer by which to multiply. |
P | The point to multiply. |
f_rng | The RNG function. |
p_rng | The RNG context. |
0
on success. m
is not a valid private key, or P
is not a valid public key. 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.
grp | The ECP group. |
R | The destination point. |
m | The integer by which to multiply P . |
P | The point to multiply by m . |
n | The integer by which to multiply Q . |
Q | The point to be multiplied by n . |
0
on success. m
or n
are not valid private keys, or P
or Q
are not valid public keys. int mbedtls_ecp_point_cmp | ( | const mbedtls_ecp_point * | P, |
const mbedtls_ecp_point * | Q | ||
) |
This function compares two points.
P | The first point to compare. |
Q | The second point to compare. |
0
if the points are equal. void mbedtls_ecp_point_free | ( | mbedtls_ecp_point * | pt | ) |
This function frees the components of a point.
pt | The point to free. |
void mbedtls_ecp_point_init | ( | mbedtls_ecp_point * | pt | ) |
This function initializes a point as zero.
pt | The 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.
grp | The group to which the point should belong. |
P | The point to import. |
buf | The input buffer. |
ilen | The length of the input. |
0
on success. 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.
P | The destination point. |
radix | The numeric base of the input. |
x | The first affine coordinate, as a null-terminated string. |
y | The second affine coordinate, as a null-terminated string. |
0
on success. 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.
grp | The group to which the point should belong. |
P | The point to export. |
format | The point format. Should be an MBEDTLS_ECP_PF_XXX macro. |
olen | The length of the output. |
buf | The output buffer. |
buflen | The length of the output buffer. |
0
on success. int mbedtls_ecp_self_test | ( | int | verbose | ) |
The ECP checkup routine.
0
on success. 1
on failure. int mbedtls_ecp_set_zero | ( | mbedtls_ecp_point * | pt | ) |
This function sets a point to zero.
pt | The point to set. |
0
on success. int mbedtls_ecp_tls_read_group | ( | mbedtls_ecp_group * | grp, |
const unsigned char ** | buf, | ||
size_t | len | ||
) |
This function sets a group from a TLS ECParameters record.
buf
is updated to point right after the ECParameters record on exit.grp | The destination group. |
buf | The address of the pointer to the start of the input buffer. |
len | The length of the buffer. |
0
on success. MBEDTLS_ERR_MPI_XXX
error code on initialization 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.
buf
is updated to point to immediately after the ECPoint record.grp | The ECP group used. |
pt | The destination point. |
buf | The address of the pointer to the start of the input buffer. |
len | The length of the buffer. |
0
on success. MBEDTLS_ERR_MPI_XXX
error code on initialization failure. int mbedtls_ecp_tls_write_group | ( | const mbedtls_ecp_group * | grp, |
size_t * | olen, | ||
unsigned char * | buf, | ||
size_t | blen | ||
) |
This function writes the TLS ECParameters record for a group.
grp | The ECP group used. |
olen | The number of Bytes written. |
buf | The buffer to write to. |
blen | The length of the buffer. |
0
on success. 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.
grp | The ECP group used. |
pt | The point format to export to. The point format is an MBEDTLS_ECP_PF_XXX constant. |
format | The export format. |
olen | The length of the data written. |
buf | The buffer to write to. |
blen | The length of the buffer. |
0
on success.