File ecdsa.h
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).
Defines
-
MBEDTLS_ECDSA_MAX_SIG_LEN(bits)
Maximum ECDSA signature size for a given curve bit size.
Note
This macro returns a compile-time constant if its argument is one. It may evaluate its argument multiple times.
- Parameters:
bits – Curve size in bits
- Returns:
Maximum signature size in bytes
-
MBEDTLS_ECDSA_MAX_LEN
The maximal size of an ECDSA signature in Bytes.
Typedefs
-
typedef mbedtls_ecp_keypair mbedtls_ecdsa_context
The ECDSA context structure.
Note
pk_wrap module assumes that “ecdsa_context” is identical to “ecp_keypair” (see for example structure “mbedtls_eckey_info” where ECDSA sign/verify functions are used also for EC key)
Warning
Performing multiple operations concurrently on the same ECDSA context is not supported; objects of this type should not be shared between multiple threads.
-
typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx
Internal restart context for ecdsa_verify()
Note
Opaque struct, defined in ecdsa.c
-
typedef struct mbedtls_ecdsa_restart_sig mbedtls_ecdsa_restart_sig_ctx
Internal restart context for ecdsa_sign()
Note
Opaque struct, defined in ecdsa.c
-
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
Functions
-
int mbedtls_ecdsa_can_do(mbedtls_ecp_group_id gid)
This function checks whether a given group can be used for ECDSA.
- Parameters:
gid – The ECP group ID to check.
- Returns:
1
if the group can be used,0
otherwise
-
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.
See also
ecp.h
Note
The deterministic version implemented in mbedtls_ecdsa_sign_det_ext() is usually preferred.
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.
- 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 beNULL
ifblen
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 beNULL
iff_rng
doesn’t need a context parameter.
- Returns:
0
on success.- Returns:
An
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_MPI_XXX
error code on failure.
-
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.
For more information, see RFC-6979: Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA).
See also
ecp.h
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.
- 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 and setup, for example through mbedtls_ecp_gen_privkey().
buf – The hashed content to be signed. This must be a readable buffer of length
blen
Bytes. It may beNULL
ifblen
is zero.blen – The length of
buf
in Bytes.md_alg – The hash algorithm used to hash the original data.
f_rng_blind – The RNG function used for blinding. This must not be
NULL
.p_rng_blind – The RNG context to be passed to
f_rng_blind
. This may beNULL
iff_rng_blind
doesn’t need a context parameter.
- Returns:
0
on success.- Returns:
An
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_MPI_XXX
error code on failure.
-
int mbedtls_ecdsa_sign_restartable(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, int (*f_rng_blind)(void*, unsigned char*, size_t), void *p_rng_blind, mbedtls_ecdsa_restart_ctx *rs_ctx)
This function computes the ECDSA signature of a previously-hashed message, in a restartable way.
See also
ecp.h
Note
The deterministic version implemented in mbedtls_ecdsa_sign_det_restartable() is usually preferred.
Note
This function is like
mbedtls_ecdsa_sign()
but it can return early and restart according to the limit set withmbedtls_ecp_set_max_ops()
to reduce blocking.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.
- 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 and setup, for example through mbedtls_ecp_gen_privkey().
buf – The hashed content to be signed. This must be a readable buffer of length
blen
Bytes. It may beNULL
ifblen
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 beNULL
iff_rng
doesn’t need a context parameter.f_rng_blind – The RNG function used for blinding. This must not be
NULL
.p_rng_blind – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
doesn’t need a context parameter.rs_ctx – The restart context to use. This may be
NULL
to disable restarting. If it is notNULL
, it must point to an initialized restart context.
- Returns:
0
on success.- Returns:
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see
mbedtls_ecp_set_max_ops()
.- Returns:
Another
MBEDTLS_ERR_ECP_XXX
,MBEDTLS_ERR_MPI_XXX
orMBEDTLS_ERR_ASN1_XXX
error code on failure.
-
int mbedtls_ecdsa_sign_det_restartable(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, mbedtls_ecdsa_restart_ctx *rs_ctx)
This function computes the ECDSA signature of a previously-hashed message, in a restartable way.
See also
ecp.h
Note
This function is like
mbedtls_ecdsa_sign_det_ext()
but it can return early and restart according to the limit set withmbedtls_ecp_set_max_ops()
to reduce blocking.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.
- 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 and setup, for example through mbedtls_ecp_gen_privkey().
buf – The hashed content to be signed. This must be a readable buffer of length
blen
Bytes. It may beNULL
ifblen
is zero.blen – The length of
buf
in Bytes.md_alg – The hash algorithm used to hash the original data.
f_rng_blind – The RNG function used for blinding. This must not be
NULL
.p_rng_blind – The RNG context to be passed to
f_rng_blind
. This may beNULL
iff_rng_blind
doesn’t need a context parameter.rs_ctx – The restart context to use. This may be
NULL
to disable restarting. If it is notNULL
, it must point to an initialized restart context.
- Returns:
0
on success.- Returns:
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see
mbedtls_ecp_set_max_ops()
.- Returns:
Another
MBEDTLS_ERR_ECP_XXX
,MBEDTLS_ERR_MPI_XXX
orMBEDTLS_ERR_ASN1_XXX
error code on failure.
-
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.
See also
ecp.h
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.
- 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 beNULL
ifblen
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.- Returns:
An
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_MPI_XXX
error code on failure.
-
int mbedtls_ecdsa_verify_restartable(mbedtls_ecp_group *grp, const unsigned char *buf, size_t blen, const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s, mbedtls_ecdsa_restart_ctx *rs_ctx)
This function verifies the ECDSA signature of a previously-hashed message, in a restartable manner.
See also
ecp.h
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.
- 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 beNULL
ifblen
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.
rs_ctx – The restart context to use. This may be
NULL
to disable restarting. If it is notNULL
, it must point to an initialized restart context.
- Returns:
0
on success.- Returns:
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see
mbedtls_ecp_set_max_ops()
.- Returns:
An
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_MPI_XXX
error code on failure.
-
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 sig_size, 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).
See also
ecp.h
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).
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
It is not thread-safe to use the same context in multiple threads.
- 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
hlen
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.
sig_size – The size of the
sig
buffer in bytes.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 used only for blinding and may be set toNULL
, but doing so is DEPRECATED.p_rng – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
isNULL
or doesn’t use a context.
- Returns:
0
on success.- Returns:
An
MBEDTLS_ERR_ECP_XXX
,MBEDTLS_ERR_MPI_XXX
orMBEDTLS_ERR_ASN1_XXX
error code on failure.
-
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 sig_size, 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.
See also
Note
This function is like
mbedtls_ecdsa_write_signature()
but it can return early and restart according to the limit set withmbedtls_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
hlen
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.
sig_size – The size of the
sig
buffer in bytes.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 toNULL
.p_rng – The RNG context to be passed to
f_rng
. This may beNULL
iff_rng
isNULL
or doesn’t use a context.rs_ctx – The restart context to use. This may be
NULL
to disable restarting. If it is notNULL
, it must point to an initialized restart context.
- Returns:
0
on success.- Returns:
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see
mbedtls_ecp_set_max_ops()
.- Returns:
Another
MBEDTLS_ERR_ECP_XXX
,MBEDTLS_ERR_MPI_XXX
orMBEDTLS_ERR_ASN1_XXX
error code on failure.
-
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.
See also
ecp.h
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.
- 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
hlen
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.- Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
- Returns:
MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid signature in
sig
, but its length is less thansiglen
.- Returns:
An
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_ERR_MPI_XXX
error code on failure for any other reason.
-
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
Note
This function is like
mbedtls_ecdsa_read_signature()
but it can return early and restart according to the limit set withmbedtls_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
hlen
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 notNULL
, it must point to an initialized restart context.
- Returns:
0
on success.- Returns:
MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
- Returns:
MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid signature in
sig
, but its length is less thansiglen
.- Returns:
MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of operations was reached: see
mbedtls_ecp_set_max_ops()
.- Returns:
Another
MBEDTLS_ERR_ECP_XXX
orMBEDTLS_ERR_MPI_XXX
error code on failure for any other reason.
-
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.
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 beNULL
iff_rng
doesn’t need a context argument.
- Returns:
0
on success.- Returns:
An
MBEDTLS_ERR_ECP_XXX
code on failure.
-
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.- Returns:
An
MBEDTLS_ERR_ECP_XXX
code on failure.
-
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
.
-
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 notNULL
, it must be initialized.
-
void mbedtls_ecdsa_restart_init(mbedtls_ecdsa_restart_ctx *ctx)
Initialize a restart context.
- Parameters:
ctx – The restart context to initialize. This must not be
NULL
.
-
void mbedtls_ecdsa_restart_free(mbedtls_ecdsa_restart_ctx *ctx)
Free the components of a restart context.
- Parameters:
ctx – The restart context to free. This may be
NULL
, in which case this function does nothing. If it is notNULL
, it must be initialized.
-
struct mbedtls_ecdsa_restart_ctx
- #include <ecdsa.h>
General context for resuming ECDSA operations.
Public Members
-
mbedtls_ecp_restart_ctx private_ecp
base context for ECP restart and shared administrative info
-
mbedtls_ecdsa_restart_ver_ctx *private_ver
ecdsa_verify() sub-context
-
mbedtls_ecdsa_restart_sig_ctx *private_sig
ecdsa_sign() sub-context
-
mbedtls_ecdsa_restart_det_ctx *private_det
ecdsa_sign_det() sub-context
-
mbedtls_ecp_restart_ctx private_ecp