ecdsa.h File Reference

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

#include "ecp.h"
#include "md.h"

Include dependency graph for ecdsa.h:

Go to the source code of this file.

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

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_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_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 up 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).

Macro Definition Documentation

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.

Typedef Documentation

mbedtls_ecdsa_context

typedef mbedtls_ecp_keypair 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.

mbedtls_ecdsa_restart_ctx

typedef void mbedtls_ecdsa_restart_ctx

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. This may be NULL, in which case this function does nothing. If it is not NULL, it must be initialized.

mbedtls_ecdsa_from_keypair()

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

ctx	The ECDSA context to setup. This must be initialized.
key	The 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.

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

ctx	The ECDSA context to store the keypair in. This must be initialized.
gid	The elliptic curve to use. One of the various MBEDTLS_ECP_DP_XXX macros depending on configuration.
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.

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

ctx	The ECDSA context to initialize. This must not be NULL.

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

ctx	The ECDSA context to use. This must be initialized and have a group and public key bound to it.
hash	The message hash that was signed. This must be a readable buffer of length size Bytes.
hlen	The size of the hash hash.
sig	The signature to read and verify. This must be a readable buffer of length slen Bytes.
slen	The 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.

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

ctx	The ECDSA context to use. This must be initialized and have a group and public key bound to it.
hash	The message hash that was signed. This must be a readable buffer of length size Bytes.
hlen	The size of the hash hash.
sig	The signature to read and verify. This must be a readable buffer of length slen Bytes.
slen	The size of sig in Bytes.
rs_ctx	The 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.

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

grp	The context for the elliptic curve to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
r	The MPI context in which to store the first part the signature. This must be initialized.
s	The MPI context in which to store the second part the signature. This must be initialized.
d	The private signing key. This must be initialized.
buf	The 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.
blen	The length of buf in Bytes.
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 parameter.

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

grp	The ECP group to use. This must be initialized and have group parameters set, for example through mbedtls_ecp_group_load().
buf	The hashed content that was signed. This must be a readable buffer of length blen Bytes. It may be NULL if blen is zero.
blen	The length of buf in Bytes.
Q	The public key to use for verification. This must be initialized and setup.
r	The first integer of the signature. This must be initialized.
s	The 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.

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

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

ctx	The 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_alg	The message digest that was used to hash the message.
hash	The message hash to be signed. This must be a readable buffer of length blen Bytes.
hlen	The length of the hash hash in Bytes.
sig	The 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.
slen	The address at which to store the actual length of the signature written. Must not be NULL.
f_rng	The RNG function. This must not be NULL if #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, it is unused and may be set to NULL.
p_rng	The 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.

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

ctx	The 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_alg	The message digest that was used to hash the message.
hash	The message hash to be signed. This must be a readable buffer of length blen Bytes.
hlen	The length of the hash hash in Bytes.
sig	The 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.
slen	The address at which to store the actual length of the signature written. Must not be NULL.
f_rng	The RNG function. This must not be NULL if #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, it is unused and may be set to NULL.
p_rng	The RNG context to be passed to f_rng. This may be NULL if f_rng is NULL or doesn't use a context.
rs_ctx	The 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.