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:

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

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ MBEDTLS_DEPRECATED

◆ MBEDTLS_ECDSA_MAX_LEN

Typedef Documentation

◆ mbedtls_ecdsa_context

Function Documentation

◆ mbedtls_ecdsa_free()

◆ mbedtls_ecdsa_from_keypair()

◆ mbedtls_ecdsa_genkey()

◆ mbedtls_ecdsa_init()

◆ mbedtls_ecdsa_read_signature()

◆ mbedtls_ecdsa_sign()

◆ mbedtls_ecdsa_sign_det()

◆ mbedtls_ecdsa_verify()

◆ mbedtls_ecdsa_write_signature()

◆ mbedtls_ecdsa_write_signature_det()