mbed TLS v2.14.1
Macros | Typedefs | Functions
ecdsa.h File Reference

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

#include "ecp.h"
#include "md.h"
Include dependency graph for ecdsa.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define MBEDTLS_ECDSA_MAX_LEN   ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
 
#define MBEDTLS_DEPRECATED
 

Typedefs

typedef mbedtls_ecp_keypair mbedtls_ecdsa_context
 The ECDSA context structure. More...
 
typedef void mbedtls_ecdsa_restart_ctx
 

Functions

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. More...
 
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. More...
 
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. More...
 
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). More...
 
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. More...
 
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). More...
 
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. More...
 
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. More...
 
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. More...
 
int mbedtls_ecdsa_from_keypair (mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key)
 This function sets an ECDSA context from an EC key pair. More...
 
void mbedtls_ecdsa_init (mbedtls_ecdsa_context *ctx)
 This function initializes an ECDSA context. More...
 
void mbedtls_ecdsa_free (mbedtls_ecdsa_context *ctx)
 This function frees an ECDSA context. More...
 

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.

Macro Definition Documentation

◆ MBEDTLS_DEPRECATED

#define MBEDTLS_DEPRECATED

Definition at line 297 of file ecdsa.h.

◆ MBEDTLS_ECDSA_MAX_LEN

#define MBEDTLS_ECDSA_MAX_LEN   ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )

The maximal size of an ECDSA signature in Bytes.

Definition at line 56 of file ecdsa.h.

Typedef Documentation

◆ mbedtls_ecdsa_context

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 69 of file ecdsa.h.

◆ mbedtls_ecdsa_restart_ctx

Definition at line 113 of file ecdsa.h.

Function Documentation

◆ mbedtls_ecdsa_free()

void mbedtls_ecdsa_free ( mbedtls_ecdsa_context ctx)

This function frees an ECDSA context.

Parameters
ctxThe ECDSA context to free.

◆ mbedtls_ecdsa_from_keypair()

int mbedtls_ecdsa_from_keypair ( mbedtls_ecdsa_context ctx,
const mbedtls_ecp_keypair key 
)

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

See also
ecp.h
Parameters
ctxThe ECDSA context to set.
keyThe EC key to use.
Returns
0 on success.
An MBEDTLS_ERR_ECP_XXX code on failure.

◆ mbedtls_ecdsa_genkey()

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.
gidThe elliptic curve to use. One of the various MBEDTLS_ECP_DP_XXX macros depending on configuration.
f_rngThe RNG function.
p_rngThe RNG context.
Returns
0 on success.
An MBEDTLS_ERR_ECP_XXX code on failure.

◆ mbedtls_ecdsa_init()

void mbedtls_ecdsa_init ( mbedtls_ecdsa_context ctx)

This function initializes an ECDSA context.

Parameters
ctxThe ECDSA context to initialize.

◆ mbedtls_ecdsa_read_signature()

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.
hashThe message hash.
hlenThe size of the hash.
sigThe signature to read and verify.
slenThe size of sig.
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.

◆ mbedtls_ecdsa_read_signature_restartable()

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.
hashThe message hash.
hlenThe size of the hash.
sigThe signature to read and verify.
slenThe size of sig.
rs_ctxThe restart context (NULL disables restart).
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.

◆ mbedtls_ecdsa_sign()

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 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 ECP group.
rThe first output integer.
sThe second output integer.
dThe private signing key.
bufThe message hash.
blenThe length of buf.
f_rngThe RNG function.
p_rngThe RNG context.
Returns
0 on success.
An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

◆ mbedtls_ecdsa_sign_det()

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.
See also
ecp.h
Parameters
grpThe ECP group.
rThe first output integer.
sThe second output integer.
dThe private signing key.
bufThe message hash.
blenThe length of buf.
md_algThe MD algorithm used to hash the message.
Returns
0 on success.
An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

◆ mbedtls_ecdsa_verify()

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.
bufThe message hash.
blenThe length of buf.
QThe public key to use for verification.
rThe first integer of the signature.
sThe second integer of the signature.
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.

◆ mbedtls_ecdsa_write_signature()

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).
The sig buffer must be 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.
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.
md_algThe message digest that was used to hash the message.
hashThe message hash.
hlenThe length of the hash.
sigThe buffer that holds the signature.
slenThe length of the signature written.
f_rngThe RNG function.
p_rngThe RNG context.
Returns
0 on success.
An MBEDTLS_ERR_ECP_XXX, MBEDTLS_ERR_MPI_XXX or MBEDTLS_ERR_ASN1_XXX error code on failure.

◆ mbedtls_ecdsa_write_signature_det()

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
The sig buffer must be 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.
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
Deprecated:
Superseded by mbedtls_ecdsa_write_signature() in Mbed TLS version 2.0 and later.
Parameters
ctxThe ECDSA context.
hashThe message hash.
hlenThe length of the hash.
sigThe buffer that holds the signature.
slenThe length of the signature written.
md_algThe MD algorithm 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.

◆ mbedtls_ecdsa_write_signature_restartable()

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.
md_algThe message digest that was used to hash the message.
hashThe message hash.
hlenThe length of the hash.
sigThe buffer that holds the signature.
slenThe length of the signature written.
f_rngThe RNG function.
p_rngThe RNG context.
rs_ctxThe restart context (NULL disables restart).
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.