mbed TLS v3.1.0
|
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"
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... | |
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_info * | mbedtls_ecp_curve_list (void) |
This function retrieves the information defined in mbedtls_ecp_curve_info() for all supported curves. 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... | |
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... | |
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_BUDGET | ( | ops | ) |
#define MBEDTLS_ECP_DP_MAX 14 |
The number of supported curves, plus one for MBEDTLS_ECP_DP_NONE.
#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_ADD 11 |
#define MBEDTLS_ECP_OPS_CHK 3 |
#define MBEDTLS_ECP_OPS_DBL 8 |
#define MBEDTLS_ECP_OPS_INV 120 |
#define MBEDTLS_ECP_PF_UNCOMPRESSED 0 |
#define MBEDTLS_ECP_TLS_NAMED_CURVE 3 |
#define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 |
#define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 |
#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 |
#define MBEDTLS_ERR_ECP_IN_PROGRESS -0x4B00 |
#define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 |
#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 |
#define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 |
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_keypair mbedtls_ecp_keypair |
The ECP key-pair structure.
A generic key-pair that may be used for ECDSA and fixed ECDH, for example.
typedef struct mbedtls_ecp_point mbedtls_ecp_point |
The ECP point structure, in Jacobian coordinates.
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 |
typedef struct mbedtls_ecp_restart_muladd mbedtls_ecp_restart_muladd_ctx |
enum mbedtls_ecp_group_id |
Domain-parameter identifiers: curve, subgroup, and generator.
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.
grp | Group structure |
rs_ctx | Restart context |
ops | Number of basic ops to do |
0
if doing ops
basic ops is still allowed, 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 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. |
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, | ||
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.
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 be NULL if f_rng doesn't need a context. |
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 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 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. |
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. This must be initialized. |
Q | The source point. This must be initialized. |
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. |
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.
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. 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 be NULL if f_rng doesn't need a context argument. |
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 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 be NULL if f_rng doesn't need a context argument. |
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 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 point grp->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 be NULL if f_rng doesn't need a context argument. |
0
on success. 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.
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 be NULL if f_rng doesn't need a context argument. |
0
on success. 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
.
dst | The destination group. This must be initialized. |
src | The source group. This must be initialized. |
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. 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.
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_DP_XXX
macro.grp | The group context to setup. This must be initialized. |
id | The identifier of the domain parameter set to load. |
0
on success. id
doesn't correspond to a known group. 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 the point at infinity.
pt | The point to test. This must be initialized. |
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. 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.
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 a scalar 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
. If also uses f_rng
to randomize some intermediate results.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 be NULL if f_rng doesn't need a context. |
0
on success. m
is not a valid private key, or P
is not a valid public key. 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.
mbedtls_ecp_mul()
, but it can return early and restart according to the limit set with mbedtls_ecp_set_max_ops()
to reduce blocking.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 be NULL if f_rng doesn't need a context. |
rs_ctx | The restart context (NULL disables restart). |
0
on success. m
is not a valid private key, or P
is not a valid public key. mbedtls_ecp_set_max_ops()
. 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 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. |
0
on success. m
or n
are not valid private keys, or P
or Q
are not valid public keys. grp
does not designate a short Weierstrass curve. 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.
mbedtls_ecp_muladd()
mbedtls_ecp_muladd()
, but it can return early and restart according to the limit set with mbedtls_ecp_set_max_ops()
to reduce blocking.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). |
0
on success. m
or n
are not valid private keys, or P
or Q
are not valid public keys. grp
does not designate a short Weierstrass curve. mbedtls_ecp_set_max_ops()
. 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. This must be initialized. |
Q | The second point to compare. This must be initialized. |
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. 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. |
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. This must be initialized. |
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. 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. |
0
on success. 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.
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. |
0
on success. void mbedtls_ecp_restart_free | ( | mbedtls_ecp_restart_ctx * | ctx | ) |
Free the components of a restart context.
ctx | The 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.
ctx | The restart context to initialize. This must not be NULL . |
int mbedtls_ecp_restart_is_enabled | ( | void | ) |
Check if restart is enabled (max_ops != 0)
0
if max_ops
== 0 (restart disabled) 1
otherwise (restart enabled) int mbedtls_ecp_self_test | ( | int | verbose | ) |
The ECP checkup routine.
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).
max_ops | Maximum 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. |
mbedtls_ecp_mul()
) is: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 496int mbedtls_ecp_set_zero | ( | mbedtls_ecp_point * | pt | ) |
This function sets a point to the point at infinity.
pt | The point to set. This must be initialized. |
0
on success. 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.
buf
is updated to point right after the ECParameters record on exit.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. |
0
on success. 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.
buf
is updated to point right after the ECParameters record on exit.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. |
0
on success. 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 immediately after the ECPoint record.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. |
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 exports an elliptic curve as a TLS ECParameters record as defined in RFC 4492, Section 5.4.
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. |
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 defined in RFC 4492, Section 5.4.
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. |
0
on success. int mbedtls_ecp_write_key | ( | mbedtls_ecp_keypair * | key, |
unsigned char * | buf, | ||
size_t | buflen | ||
) |
This function exports an elliptic curve private key.
key | The private key. |
buf | The output buffer for containing the binary representation of the key. (Big endian integer for Weierstrass curves, byte string for Montgomery curves.) |
buflen | The total length of the buffer in bytes. |
0
on success. key
representation is larger than the available space in buf
.