Kenji Arai / mbed-os_TYBLE16

Dependents:   TYBLE16_simple_data_logger TYBLE16_MP3_Air

Embed: (wiki syntax)

« Back to documentation index

ecdsa.h File Reference

ecdsa.h File Reference

This file contains ECDSA definitions and functions. More...

Go to the source code of this file.

Data Structures

struct  mbedtls_ecdsa_restart_ctx
 General context for resuming ECDSA operations. More...

Typedefs

typedef mbedtls_ecp_keypair mbedtls_ecdsa_context
 The ECDSA context structure.
typedef struct
mbedtls_ecdsa_restart_ver 
mbedtls_ecdsa_restart_ver_ctx
 Internal restart context for ecdsa_verify()
typedef struct
mbedtls_ecdsa_restart_sig 
mbedtls_ecdsa_restart_sig_ctx
 Internal restart context for ecdsa_sign()
typedef struct
mbedtls_ecdsa_restart_det 
mbedtls_ecdsa_restart_det_ctx
 Internal restart context for ecdsa_sign_det()

Functions

int mbedtls_ecdsa_can_do (mbedtls_ecp_group_id gid)
 This function checks whether a given group can be used for ECDSA.
int mbedtls_ecdsa_sign (mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, const mbedtls_mpi *d, const unsigned char *buf, size_t blen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 This function computes the ECDSA signature of a previously-hashed message.
int mbedtls_ecdsa_sign_det (mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, const mbedtls_mpi *d, const unsigned char *buf, size_t blen, mbedtls_md_type_t md_alg) MBEDTLS_DEPRECATED
 This function computes the ECDSA signature of a previously-hashed message, deterministic version.
int mbedtls_ecdsa_sign_det_ext (mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, const mbedtls_mpi *d, const unsigned char *buf, size_t blen, mbedtls_md_type_t md_alg, int(*f_rng_blind)(void *, unsigned char *, size_t), void *p_rng_blind)
 This function computes the ECDSA signature of a previously-hashed message, deterministic version.
int mbedtls_ecdsa_verify (mbedtls_ecp_group *grp, const unsigned char *buf, size_t blen, const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s)
 This function verifies the ECDSA signature of a previously-hashed message.
int mbedtls_ecdsa_write_signature (mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hlen, unsigned char *sig, size_t *slen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 This function computes the ECDSA signature and writes it to a buffer, serialized as defined in RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS).
int mbedtls_ecdsa_write_signature_restartable (mbedtls_ecdsa_context *ctx, mbedtls_md_type_t md_alg, const unsigned char *hash, size_t hlen, unsigned char *sig, size_t *slen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng, mbedtls_ecdsa_restart_ctx *rs_ctx)
 This function computes the ECDSA signature and writes it to a buffer, in a restartable way.
int mbedtls_ecdsa_write_signature_det (mbedtls_ecdsa_context *ctx, const unsigned char *hash, size_t hlen, unsigned char *sig, size_t *slen, mbedtls_md_type_t md_alg) MBEDTLS_DEPRECATED
 This function computes an ECDSA signature and writes it to a buffer, serialized as defined in RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS).
int mbedtls_ecdsa_read_signature (mbedtls_ecdsa_context *ctx, const unsigned char *hash, size_t hlen, const unsigned char *sig, size_t slen)
 This function reads and verifies an ECDSA signature.
int mbedtls_ecdsa_read_signature_restartable (mbedtls_ecdsa_context *ctx, const unsigned char *hash, size_t hlen, const unsigned char *sig, size_t slen, mbedtls_ecdsa_restart_ctx *rs_ctx)
 This function reads and verifies an ECDSA signature, in a restartable way.
int mbedtls_ecdsa_genkey (mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)
 This function generates an ECDSA keypair on the given curve.
int mbedtls_ecdsa_from_keypair (mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key)
 This function sets up an ECDSA context from an EC key pair.
void mbedtls_ecdsa_init (mbedtls_ecdsa_context *ctx)
 This function initializes an ECDSA context.
void mbedtls_ecdsa_free (mbedtls_ecdsa_context *ctx)
 This function frees an ECDSA context.
void mbedtls_ecdsa_restart_init (mbedtls_ecdsa_restart_ctx *ctx)
 Initialize a restart context.
void mbedtls_ecdsa_restart_free (mbedtls_ecdsa_restart_ctx *ctx)
 Free the components of a restart context.

Detailed Description

This file contains ECDSA definitions and functions.

The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography. The use of ECDSA for TLS is defined in RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS).

Definition in file ecdsa.h.


Typedef Documentation

The ECDSA context structure.

Warning:
Performing multiple operations concurrently on the same ECDSA context is not supported; objects of this type should not be shared between multiple threads.

Definition at line 80 of file ecdsa.h.

typedef struct mbedtls_ecdsa_restart_det mbedtls_ecdsa_restart_det_ctx

Internal restart context for ecdsa_sign_det()

Note:
Opaque struct, defined in ecdsa.c

Definition at line 104 of file ecdsa.h.

typedef struct mbedtls_ecdsa_restart_sig mbedtls_ecdsa_restart_sig_ctx

Internal restart context for ecdsa_sign()

Note:
Opaque struct, defined in ecdsa.c

Definition at line 96 of file ecdsa.h.

typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx

Internal restart context for ecdsa_verify()

Note:
Opaque struct, defined in ecdsa.c

Definition at line 89 of file ecdsa.h.


Function Documentation

int mbedtls_ecdsa_can_do ( mbedtls_ecp_group_id  gid )

This function checks whether a given group can be used for ECDSA.

Parameters:
gidThe ECP group ID to check.
Returns:
1 if the group can be used, 0 otherwise

Definition at line 386 of file ecdsa.c.

void mbedtls_ecdsa_free ( mbedtls_ecdsa_context ctx )

This function frees an ECDSA context.

Parameters:
ctxThe ECDSA context to free. This may be NULL, in which case this function does nothing. If it is not NULL, it must be initialized.

Definition at line 955 of file ecdsa.c.

int mbedtls_ecdsa_from_keypair ( mbedtls_ecdsa_context ctx,
const mbedtls_ecp_keypair key 
)

This function sets up an ECDSA context from an EC key pair.

See also:
ecp.h
Parameters:
ctxThe ECDSA context to setup. This must be initialized.
keyThe EC key to use. This must be initialized and hold a private-public key pair or a public key. In the former case, the ECDSA context may be used for signature creation and verification after this call. In the latter case, it may be used for signature verification.
Returns:
0 on success.
An MBEDTLS_ERR_ECP_XXX code on failure.

Definition at line 926 of file ecdsa.c.

int mbedtls_ecdsa_genkey ( mbedtls_ecdsa_context ctx,
mbedtls_ecp_group_id  gid,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

This function generates an ECDSA keypair on the given curve.

See also:
ecp.h
Parameters:
ctxThe ECDSA context to store the keypair in. This must be initialized.
gidThe elliptic curve to use. One of the various MBEDTLS_ECP_DP_XXX macros depending on configuration.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL if f_rng doesn't need a context argument.
Returns:
0 on success.
An MBEDTLS_ERR_ECP_XXX code on failure.

Definition at line 246 of file ecdsa_alt.c.

void mbedtls_ecdsa_init ( mbedtls_ecdsa_context ctx )

This function initializes an ECDSA context.

Parameters:
ctxThe ECDSA context to initialize. This must not be NULL.

Definition at line 945 of file ecdsa.c.

int mbedtls_ecdsa_read_signature ( mbedtls_ecdsa_context ctx,
const unsigned char *  hash,
size_t  hlen,
const unsigned char *  sig,
size_t  slen 
)

This function reads and verifies an ECDSA signature.

Note:
If the bitlength of the message hash is larger than the bitlength of the group order, then the hash is truncated as defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography, section 4.1.4, step 3.
See also:
ecp.h
Parameters:
ctxThe ECDSA context to use. This must be initialized and have a group and public key bound to it.
hashThe message hash that was signed. This must be a readable buffer of length size Bytes.
hlenThe size of the hash hash.
sigThe signature to read and verify. This must be a readable buffer of length slen Bytes.
slenThe size of sig in Bytes.
Returns:
0 on success.
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid signature in sig, but its length is less than siglen.
An MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code on failure for any other reason.

Definition at line 829 of file ecdsa.c.

int mbedtls_ecdsa_read_signature_restartable ( mbedtls_ecdsa_context ctx,
const unsigned char *  hash,
size_t  hlen,
const unsigned char *  sig,
size_t  slen,
mbedtls_ecdsa_restart_ctx rs_ctx 
)

This function reads and verifies an ECDSA signature, in a restartable way.

See also:
mbedtls_ecdsa_read_signature()
Note:
This function is like mbedtls_ecdsa_read_signature() but it can return early and restart according to the limit set with mbedtls_ecp_set_max_ops() to reduce blocking.
Parameters:
ctxThe ECDSA context to use. This must be initialized and have a group and public key bound to it.
hashThe message hash that was signed. This must be a readable buffer of length size Bytes.
hlenThe size of the hash hash.
sigThe signature to read and verify. This must be a readable buffer of length slen Bytes.
slenThe size of sig in Bytes.
rs_ctxThe restart context to use. This may be NULL to disable restarting. If it is not NULL, it must point to an initialized restart context.
Returns:
0 on success.
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid signature in sig, but its length is less than siglen.
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see mbedtls_ecp_set_max_ops().
Another MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX error code on failure for any other reason.

Definition at line 843 of file ecdsa.c.

void mbedtls_ecdsa_restart_free ( mbedtls_ecdsa_restart_ctx ctx )

Free the components of a restart context.

Parameters:
ctxThe restart context to free. This may be NULL, in which case this function does nothing. If it is not NULL, it must be initialized.

Definition at line 983 of file ecdsa.c.

void mbedtls_ecdsa_restart_init ( mbedtls_ecdsa_restart_ctx ctx )

Initialize a restart context.

Parameters:
ctxThe restart context to initialize. This must not be NULL.

Definition at line 967 of file ecdsa.c.

int mbedtls_ecdsa_sign ( mbedtls_ecp_group grp,
mbedtls_mpi r,
mbedtls_mpi s,
const mbedtls_mpi d,
const unsigned char *  buf,
size_t  blen,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

This function computes the ECDSA signature of a previously-hashed message.

Note:
The deterministic version implemented in mbedtls_ecdsa_sign_det() is usually preferred.
If the bitlength of the message hash is larger than the bitlength of the group order, then the hash is truncated as defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography, section 4.1.3, step 5.
See also:
ecp.h
Parameters:
grpThe context for the elliptic curve to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
rThe MPI context in which to store the first part the signature. This must be initialized.
sThe MPI context in which to store the second part the signature. This must be initialized.
dThe private signing key. This must be initialized.
bufThe content to be signed. This is usually the hash of the original data to be signed. This must be a readable buffer of length blen Bytes. It may be NULL if blen is zero.
blenThe length of buf in Bytes.
f_rngThe RNG function. This must not be NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL if f_rng doesn't need a context parameter.
Returns:
0 on success.
An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

Definition at line 61 of file ecdsa_alt.c.

int mbedtls_ecdsa_sign_det ( mbedtls_ecp_group grp,
mbedtls_mpi r,
mbedtls_mpi s,
const mbedtls_mpi d,
const unsigned char *  buf,
size_t  blen,
mbedtls_md_type_t  md_alg 
)

This function computes the ECDSA signature of a previously-hashed message, deterministic version.

For more information, see RFC-6979: Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA).

Note:
If the bitlength of the message hash is larger than the bitlength of the group order, then the hash is truncated as defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography, section 4.1.3, step 5.
Warning:
Since the output of the internal RNG is always the same for the same key and message, this limits the efficiency of blinding and leaks information through side channels. For secure behavior use mbedtls_ecdsa_sign_det_ext() instead.

(Optimally the blinding is a random value that is different on every execution. In this case the blinding is still random from the attackers perspective, but is the same on each execution. This means that this blinding does not prevent attackers from recovering secrets by combining several measurement traces, but may prevent some attacks that exploit relationships between secret data.)

See also:
ecp.h
Parameters:
grpThe context for the elliptic curve to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
rThe MPI context in which to store the first part the signature. This must be initialized.
sThe MPI context in which to store the second part the signature. This must be initialized.
dThe private signing key. This must be initialized and setup, for example through mbedtls_ecp_gen_privkey().
bufThe hashed content to be signed. This must be a readable buffer of length blen Bytes. It may be NULL if blen is zero.
blenThe length of buf in Bytes.
md_algThe hash algorithm used to hash the original data.
Returns:
0 on success.
An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

Definition at line 555 of file ecdsa.c.

int mbedtls_ecdsa_sign_det_ext ( mbedtls_ecp_group grp,
mbedtls_mpi r,
mbedtls_mpi s,
const mbedtls_mpi d,
const unsigned char *  buf,
size_t  blen,
mbedtls_md_type_t  md_alg,
int(*)(void *, unsigned char *, size_t)  f_rng_blind,
void *  p_rng_blind 
)

This function computes the ECDSA signature of a previously-hashed message, deterministic version.

For more information, see RFC-6979: Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA).

Note:
If the bitlength of the message hash is larger than the bitlength of the group order, then the hash is truncated as defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography, section 4.1.3, step 5.
See also:
ecp.h
Parameters:
grpThe context for the elliptic curve to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
rThe MPI context in which to store the first part the signature. This must be initialized.
sThe MPI context in which to store the second part the signature. This must be initialized.
dThe private signing key. This must be initialized and setup, for example through mbedtls_ecp_gen_privkey().
bufThe hashed content to be signed. This must be a readable buffer of length blen Bytes. It may be NULL if blen is zero.
blenThe length of buf in Bytes.
md_algThe hash algorithm used to hash the original data.
f_rng_blindThe RNG function used for blinding. This must not be NULL.
p_rng_blindThe RNG context to be passed to f_rng. This may be NULL if f_rng doesn't need a context parameter.
Returns:
0 on success.
An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

Definition at line 571 of file ecdsa.c.

int mbedtls_ecdsa_verify ( mbedtls_ecp_group grp,
const unsigned char *  buf,
size_t  blen,
const mbedtls_ecp_point Q,
const mbedtls_mpi r,
const mbedtls_mpi s 
)

This function verifies the ECDSA signature of a previously-hashed message.

Note:
If the bitlength of the message hash is larger than the bitlength of the group order, then the hash is truncated as defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography, section 4.1.4, step 3.
See also:
ecp.h
Parameters:
grpThe ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
bufThe hashed content that was signed. This must be a readable buffer of length blen Bytes. It may be NULL if blen is zero.
blenThe length of buf in Bytes.
QThe public key to use for verification. This must be initialized and setup.
rThe first integer of the signature. This must be initialized.
sThe second integer of the signature. This must be initialized.
Returns:
0 on success.
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature is invalid.
An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure for any other reason.

Definition at line 160 of file ecdsa_alt.c.

int mbedtls_ecdsa_write_signature ( mbedtls_ecdsa_context ctx,
mbedtls_md_type_t  md_alg,
const unsigned char *  hash,
size_t  hlen,
unsigned char *  sig,
size_t *  slen,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng 
)

This function computes the ECDSA signature and writes it to a buffer, serialized as defined in RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS).

Warning:
It is not thread-safe to use the same context in multiple threads.
Note:
The deterministic version is used if MBEDTLS_ECDSA_DETERMINISTIC is defined. For more information, see RFC-6979: Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA).
If the bitlength of the message hash is larger than the bitlength of the group order, then the hash is truncated as defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography, section 4.1.3, step 5.
See also:
ecp.h
Parameters:
ctxThe ECDSA context to use. This must be initialized and have a group and private key bound to it, for example via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
md_algThe message digest that was used to hash the message.
hashThe message hash to be signed. This must be a readable buffer of length blen Bytes.
hlenThe length of the hash hash in Bytes.
sigThe buffer to which to write the signature. This must be a writable buffer of length at least twice as large as the size of the curve used, plus 9. For example, 73 Bytes if a 256-bit curve is used. A buffer length of MBEDTLS_ECDSA_MAX_LEN is always safe.
slenThe address at which to store the actual length of the signature written. Must not be NULL.
f_rngThe RNG function. This must not be NULL if MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, it is used only for blinding and may be set to NULL, but doing so is DEPRECATED.
p_rngThe RNG context to be passed to f_rng. This may be NULL if f_rng is NULL or doesn't use a context.
Returns:
0 on success.
An MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or MBEDTLS_ERR_ASN1_XXX error code on failure.

Definition at line 795 of file ecdsa.c.

int mbedtls_ecdsa_write_signature_det ( mbedtls_ecdsa_context ctx,
const unsigned char *  hash,
size_t  hlen,
unsigned char *  sig,
size_t *  slen,
mbedtls_md_type_t  md_alg 
)

This function computes an ECDSA signature and writes it to a buffer, serialized as defined in RFC-4492: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS).

The deterministic version is defined in RFC-6979: Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA).

Warning:
It is not thread-safe to use the same context in multiple threads.
Note:
If the bitlength of the message hash is larger than the bitlength of the group order, then the hash is truncated as defined in Standards for Efficient Cryptography Group (SECG): SEC1 Elliptic Curve Cryptography, section 4.1.3, step 5.
See also:
ecp.h
Parameters:
ctxThe ECDSA context to use. This must be initialized and have a group and private key bound to it, for example via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
hashThe message hash to be signed. This must be a readable buffer of length blen Bytes.
hlenThe length of the hash hash in Bytes.
sigThe buffer to which to write the signature. This must be a writable buffer of length at least twice as large as the size of the curve used, plus 9. For example, 73 Bytes if a 256-bit curve is used. A buffer length of MBEDTLS_ECDSA_MAX_LEN is always safe.
slenThe address at which to store the actual length of the signature written. Must not be NULL.
md_algThe message digest that was used to hash the message.
Returns:
0 on success.
An MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or MBEDTLS_ERR_ASN1_XXX error code on failure.

Definition at line 812 of file ecdsa.c.

int mbedtls_ecdsa_write_signature_restartable ( mbedtls_ecdsa_context ctx,
mbedtls_md_type_t  md_alg,
const unsigned char *  hash,
size_t  hlen,
unsigned char *  sig,
size_t *  slen,
int(*)(void *, unsigned char *, size_t)  f_rng,
void *  p_rng,
mbedtls_ecdsa_restart_ctx rs_ctx 
)

This function computes the ECDSA signature and writes it to a buffer, in a restartable way.

See also:
mbedtls_ecdsa_write_signature()
Note:
This function is like mbedtls_ecdsa_write_signature() but it can return early and restart according to the limit set with mbedtls_ecp_set_max_ops() to reduce blocking.
Parameters:
ctxThe ECDSA context to use. This must be initialized and have a group and private key bound to it, for example via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
md_algThe message digest that was used to hash the message.
hashThe message hash to be signed. This must be a readable buffer of length blen Bytes.
hlenThe length of the hash hash in Bytes.
sigThe buffer to which to write the signature. This must be a writable buffer of length at least twice as large as the size of the curve used, plus 9. For example, 73 Bytes if a 256-bit curve is used. A buffer length of MBEDTLS_ECDSA_MAX_LEN is always safe.
slenThe address at which to store the actual length of the signature written. Must not be NULL.
f_rngThe RNG function. This must not be NULL if MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, it is unused and may be set to NULL.
p_rngThe RNG context to be passed to f_rng. This may be NULL if f_rng is NULL or doesn't use a context.
rs_ctxThe restart context to use. This may be NULL to disable restarting. If it is not NULL, it must point to an initialized restart context.
Returns:
0 on success.
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see mbedtls_ecp_set_max_ops().
Another MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or MBEDTLS_ERR_ASN1_XXX error code on failure.

Definition at line 747 of file ecdsa.c.