ecdsa.h File Reference

The Elliptic Curve Digital Signature Algorithm (ECDSA). 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 __attribute__((deprecated))

## Typedefs

typedef mbedtls_ecp_keypair | mbedtls_ecdsa_context
| The ECDSA context structure. More...

## 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. For more information, see RFC-6979: Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA). 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_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_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

The Elliptic Curve Digital Signature Algorithm (ECDSA).

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 __attribute__((deprecated))

Definition at line 207 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 55 of file ecdsa.h.

## Typedef Documentation

## mbedtls_ecdsa_context

typedef mbedtls_ecp_keypair mbedtls_ecdsa_context

The ECDSA context structure.

Definition at line 60 of file ecdsa.h.

## Function Documentation

## mbedtls_ecdsa_free()

void mbedtls_ecdsa_free | ( | mbedtls_ecdsa_context * | ctx | ) |

This function frees an ECDSA context.

Parameters

  ctx | The 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.

Parameters

  ctx | The ECDSA context to set.
  key | The EC key to use.

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX` code on failure.

See also
  ecp.h

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

Parameters

  ctx | The ECDSA context to store the keypair in.
  gid | The elliptic curve to use. One of the various `MBEDTLS_ECP_DP_XXX` macros depending on configuration.
  f_rng | The RNG function.
  p_rng | The RNG parameter.

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX` code on failure.

See also
  ecp.h

## mbedtls_ecdsa_init()

void mbedtls_ecdsa_init | ( | mbedtls_ecdsa_context * | ctx | ) |

This function initializes an ECDSA context.

Parameters

  ctx | The 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.

Parameters

  ctx | The ECDSA context.
  hash | The message hash.
  hlen | The size of the hash.
  sig | The signature to read and verify.
  slen | The size of `sig`.

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.

Returns
  `0` on success, MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid, MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if the signature is valid but its actual length is less than `siglen`, or an `MBEDTLS_ERR_ECP_XXX` or `MBEDTLS_ERR_MPI_XXX` error code on failure for any other reason.

See also
  ecp.h

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

Parameters

  grp | The ECP group.
  r | The first output integer.
  s | The second output integer.
  d | The private signing key.
  buf | The message hash.
  blen | The length of `buf`.
  f_rng | The RNG function.
  p_rng | The RNG parameter.

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.

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX` or `MBEDTLS_MPI_XXX` error code on failure.

See also
  ecp.h

## 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).

Parameters

  grp | The ECP group.
  r | The first output integer.
  s | The second output integer.
  d | The private signing key.
  buf | The message hash.
  blen | The length of `buf`.
  md_alg | The MD algorithm used to hash the 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.3, step 5.

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX` or `MBEDTLS_MPI_XXX` error code on failure.

See also
  ecp.h

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

Parameters

  grp | The ECP group.
  buf | The message hash.
  blen | The length of `buf`.
  Q | The public key to use for verification.
  r | The first integer of the signature.
  s | The second integer of the 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.

Returns
  `0` on success, MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid, or an `MBEDTLS_ERR_ECP_XXX` or `MBEDTLS_MPI_XXX` error code on failure for any other reason.

See also
  ecp.h

## 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).

Parameters

  ctx | The ECDSA context.
  md_alg | The message digest that was used to hash the message.
  hash | The message hash.
  hlen | The length of the hash.
  sig | The buffer that holds the signature.
  slen | The length of the signature written.
  f_rng | The RNG function.
  p_rng | The RNG parameter.

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.

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX`, `MBEDTLS_ERR_MPI_XXX` or `MBEDTLS_ERR_ASN1_XXX` error code on failure.

See also
  ecp.h

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

Deprecated:
  Superseded by mbedtls_ecdsa_write_signature() in 2.0.0

Parameters

  ctx | The ECDSA context.
  hash | The Message hash.
  hlen | The length of the hash.
  sig | The buffer that holds the signature.
  slen | The length of the signature written.
  md_alg | The MD algorithm used to hash the message.

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.

Returns
  `0` on success, or an `MBEDTLS_ERR_ECP_XXX`, `MBEDTLS_ERR_MPI_XXX` or `MBEDTLS_ERR_ASN1_XXX` error code on failure.

See also
  ecp.h