blob: ad51188149d42f98c509acfbc3d7f1aaceb91be4 [file] [log] [blame]
Manuel Pégourié-Gonnard2aea1412013-01-26 16:33:44 +01001/**
2 * \file ecdsa.h
3 *
Rose Zadik817297f2018-03-27 11:30:14 +01004 * \brief This file contains ECDSA definitions and functions.
Manuel Pégourié-Gonnard2aea1412013-01-26 16:33:44 +01005 *
Rose Zadik817297f2018-03-27 11:30:14 +01006 * The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
7 * <em>Standards for Efficient Cryptography Group (SECG):
Rose Zadikbff87d92018-01-25 21:58:53 +00008 * SEC1 Elliptic Curve Cryptography</em>.
9 * The use of ECDSA for TLS is defined in <em>RFC-4492: Elliptic Curve
10 * Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)</em>.
11 *
Darryl Greena40a1012018-01-05 15:33:17 +000012 */
13/*
Rose Zadikbff87d92018-01-25 21:58:53 +000014 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +020015 * SPDX-License-Identifier: Apache-2.0
16 *
17 * Licensed under the Apache License, Version 2.0 (the "License"); you may
18 * not use this file except in compliance with the License.
19 * You may obtain a copy of the License at
20 *
21 * http://www.apache.org/licenses/LICENSE-2.0
22 *
23 * Unless required by applicable law or agreed to in writing, software
24 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
25 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
26 * See the License for the specific language governing permissions and
27 * limitations under the License.
Manuel Pégourié-Gonnard2aea1412013-01-26 16:33:44 +010028 *
Rose Zadikbff87d92018-01-25 21:58:53 +000029 * This file is part of Mbed TLS (https://tls.mbed.org)
Manuel Pégourié-Gonnard2aea1412013-01-26 16:33:44 +010030 */
Rose Zadikbff87d92018-01-25 21:58:53 +000031
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020032#ifndef MBEDTLS_ECDSA_H
33#define MBEDTLS_ECDSA_H
Manuel Pégourié-Gonnard2aea1412013-01-26 16:33:44 +010034
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050035#if !defined(MBEDTLS_CONFIG_FILE)
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010036#include "mbedtls/config.h"
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050037#else
38#include MBEDTLS_CONFIG_FILE
39#endif
40
Jaeden Ameroc49fbbf2019-07-04 20:01:14 +010041#include "mbedtls/ecp.h"
42#include "mbedtls/md.h"
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +010043
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010044/**
45 * \brief Maximum ECDSA signature size for a given curve bit size
Manuel Pégourié-Gonnard63e93192015-03-31 11:15:48 +020046 *
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010047 * \param bits Curve size in bits
48 * \return Maximum signature size in bytes
49 *
50 * \note This macro returns a compile-time constant if its argument
51 * is one. It may evaluate its argument multiple times.
52 */
53/*
Manuel Pégourié-Gonnard63e93192015-03-31 11:15:48 +020054 * Ecdsa-Sig-Value ::= SEQUENCE {
55 * r INTEGER,
56 * s INTEGER
57 * }
58 *
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010059 * For each of r and s, the value (V) may include an extra initial "0" bit.
Manuel Pégourié-Gonnard63e93192015-03-31 11:15:48 +020060 */
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010061#define MBEDTLS_ECDSA_MAX_SIG_LEN( bits ) \
62 ( /*T,L of SEQUENCE*/ ( ( bits ) >= 61 * 8 ? 3 : 2 ) + \
63 /*T,L of r,s*/ 2 * ( ( ( bits ) >= 127 * 8 ? 3 : 2 ) + \
64 /*V of r,s*/ ( ( bits ) + 8 ) / 8 ) )
65
Rose Zadikbff87d92018-01-25 21:58:53 +000066/** The maximal size of an ECDSA signature in Bytes. */
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010067#define MBEDTLS_ECDSA_MAX_LEN MBEDTLS_ECDSA_MAX_SIG_LEN( MBEDTLS_ECP_MAX_BITS )
Manuel Pégourié-Gonnard63e93192015-03-31 11:15:48 +020068
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +020069#ifdef __cplusplus
70extern "C" {
71#endif
72
Manuel Pégourié-Gonnardbec2f452013-06-27 10:17:07 +020073/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +020074 * \brief The ECDSA context structure.
Manuel Pégourié-Gonnardeaf55be2017-08-23 14:40:21 +020075 *
76 * \warning Performing multiple operations concurrently on the same
77 * ECDSA context is not supported; objects of this type
78 * should not be shared between multiple threads.
Manuel Pégourié-Gonnardbec2f452013-06-27 10:17:07 +020079 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020080typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
Manuel Pégourié-Gonnardbec2f452013-06-27 10:17:07 +020081
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +020082#if defined(MBEDTLS_ECP_RESTARTABLE)
83
84/**
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +020085 * \brief Internal restart context for ecdsa_verify()
86 *
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +020087 * \note Opaque struct, defined in ecdsa.c
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +020088 */
89typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx;
90
91/**
Manuel Pégourié-Gonnardb90883d2017-04-25 11:33:10 +020092 * \brief Internal restart context for ecdsa_sign()
93 *
94 * \note Opaque struct, defined in ecdsa.c
95 */
96typedef struct mbedtls_ecdsa_restart_sig mbedtls_ecdsa_restart_sig_ctx;
97
98#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
99/**
100 * \brief Internal restart context for ecdsa_sign_det()
101 *
102 * \note Opaque struct, defined in ecdsa.c
103 */
104typedef struct mbedtls_ecdsa_restart_det mbedtls_ecdsa_restart_det_ctx;
105#endif
106
107/**
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200108 * \brief General context for resuming ECDSA operations
109 */
110typedef struct
111{
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200112 mbedtls_ecp_restart_ctx ecp; /*!< base context for ECP restart and
113 shared administrative info */
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +0200114 mbedtls_ecdsa_restart_ver_ctx *ver; /*!< ecdsa_verify() sub-context */
Manuel Pégourié-Gonnardb90883d2017-04-25 11:33:10 +0200115 mbedtls_ecdsa_restart_sig_ctx *sig; /*!< ecdsa_sign() sub-context */
116#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
117 mbedtls_ecdsa_restart_det_ctx *det; /*!< ecdsa_sign_det() sub-context */
118#endif
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200119} mbedtls_ecdsa_restart_ctx;
120
121#else /* MBEDTLS_ECP_RESTARTABLE */
122
123/* Now we can declare functions that take a pointer to that */
124typedef void mbedtls_ecdsa_restart_ctx;
125
126#endif /* MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard2aea1412013-01-26 16:33:44 +0100127
128/**
Christoph M. Wintersteiger0082f9d2019-01-07 13:47:30 +0000129 * \brief This function checks whether a given group can be used
130 * for ECDSA.
131 *
132 * \param gid The ECP group ID to check.
133 *
134 * \return \c 1 if the group can be used, \c 0 otherwise
135 */
136int mbedtls_ecdsa_can_do( mbedtls_ecp_group_id gid );
137
138/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000139 * \brief This function computes the ECDSA signature of a
140 * previously-hashed message.
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100141 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500142 * \note The deterministic version implemented in
143 * mbedtls_ecdsa_sign_det() is usually preferred.
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100144 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000145 * \note If the bitlength of the message hash is larger than the
Rose Zadik817297f2018-03-27 11:30:14 +0100146 * bitlength of the group order, then the hash is truncated
147 * as defined in <em>Standards for Efficient Cryptography Group
148 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
149 * 4.1.3, step 5.
Janos Follath0a5154b2017-03-10 11:31:41 +0000150 *
Rose Zadik817297f2018-03-27 11:30:14 +0100151 * \see ecp.h
152 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500153 * \param grp The context for the elliptic curve to use.
154 * This must be initialized and have group parameters
155 * set, for example through mbedtls_ecp_group_load().
156 * \param r The MPI context in which to store the first part
157 * the signature. This must be initialized.
158 * \param s The MPI context in which to store the second part
159 * the signature. This must be initialized.
160 * \param d The private signing key. This must be initialized.
161 * \param buf The content to be signed. This is usually the hash of
162 * the original data to be signed. This must be a readable
163 * buffer of length \p blen Bytes. It may be \c NULL if
164 * \p blen is zero.
165 * \param blen The length of \p buf in Bytes.
166 * \param f_rng The RNG function. This must not be \c NULL.
167 * \param p_rng The RNG context to be passed to \p f_rng. This may be
168 * \c NULL if \p f_rng doesn't need a context parameter.
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100169 *
Rose Zadik817297f2018-03-27 11:30:14 +0100170 * \return \c 0 on success.
171 * \return An \c MBEDTLS_ERR_ECP_XXX
Rose Zadikbff87d92018-01-25 21:58:53 +0000172 * or \c MBEDTLS_MPI_XXX error code on failure.
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100173 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200174int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
175 const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100176 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
177
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200178#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100179/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000180 * \brief This function computes the ECDSA signature of a
181 * previously-hashed message, deterministic version.
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100182 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000183 * For more information, see <em>RFC-6979: Deterministic
184 * Usage of the Digital Signature Algorithm (DSA) and Elliptic
185 * Curve Digital Signature Algorithm (ECDSA)</em>.
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100186 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000187 * \note If the bitlength of the message hash is larger than the
188 * bitlength of the group order, then the hash is truncated as
Rose Zadik817297f2018-03-27 11:30:14 +0100189 * defined in <em>Standards for Efficient Cryptography Group
190 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
191 * 4.1.3, step 5.
Janos Follath0a5154b2017-03-10 11:31:41 +0000192 *
Rose Zadik817297f2018-03-27 11:30:14 +0100193 * \see ecp.h
194 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500195 * \param grp The context for the elliptic curve to use.
196 * This must be initialized and have group parameters
197 * set, for example through mbedtls_ecp_group_load().
198 * \param r The MPI context in which to store the first part
199 * the signature. This must be initialized.
200 * \param s The MPI context in which to store the second part
201 * the signature. This must be initialized.
202 * \param d The private signing key. This must be initialized
203 * and setup, for example through mbedtls_ecp_gen_privkey().
204 * \param buf The hashed content to be signed. This must be a readable
205 * buffer of length \p blen Bytes. It may be \c NULL if
206 * \p blen is zero.
207 * \param blen The length of \p buf in Bytes.
208 * \param md_alg The hash algorithm used to hash the original data.
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100209 *
Rose Zadik817297f2018-03-27 11:30:14 +0100210 * \return \c 0 on success.
Rose Zadik14d0d572018-04-16 16:09:30 +0100211 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
Rose Zadikbff87d92018-01-25 21:58:53 +0000212 * error code on failure.
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100213 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500214int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r,
215 mbedtls_mpi *s, const mbedtls_mpi *d,
216 const unsigned char *buf, size_t blen,
217 mbedtls_md_type_t md_alg );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200218#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100219
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100220/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000221 * \brief This function verifies the ECDSA signature of a
222 * previously-hashed message.
Manuel Pégourié-Gonnard3aeb5a72013-01-26 18:05:50 +0100223 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000224 * \note If the bitlength of the message hash is larger than the
225 * bitlength of the group order, then the hash is truncated as
Rose Zadik817297f2018-03-27 11:30:14 +0100226 * defined in <em>Standards for Efficient Cryptography Group
227 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
228 * 4.1.4, step 3.
Janos Follath0a5154b2017-03-10 11:31:41 +0000229 *
Rose Zadik817297f2018-03-27 11:30:14 +0100230 * \see ecp.h
231 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500232 * \param grp The ECP group to use.
233 * This must be initialized and have group parameters
234 * set, for example through mbedtls_ecp_group_load().
235 * \param buf The hashed content that was signed. This must be a readable
236 * buffer of length \p blen Bytes. It may be \c NULL if
237 * \p blen is zero.
238 * \param blen The length of \p buf in Bytes.
239 * \param Q The public key to use for verification. This must be
240 * initialized and setup.
Rose Zadikbff87d92018-01-25 21:58:53 +0000241 * \param r The first integer of the signature.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500242 * This must be initialized.
Rose Zadikbff87d92018-01-25 21:58:53 +0000243 * \param s The second integer of the signature.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500244 * This must be initialized.
Manuel Pégourié-Gonnard3aeb5a72013-01-26 18:05:50 +0100245 *
Rose Zadik817297f2018-03-27 11:30:14 +0100246 * \return \c 0 on success.
Rose Zadik14d0d572018-04-16 16:09:30 +0100247 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
248 * is invalid.
Rose Zadik817297f2018-03-27 11:30:14 +0100249 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
Rose Zadikbff87d92018-01-25 21:58:53 +0000250 * error code on failure for any other reason.
Manuel Pégourié-Gonnard3aeb5a72013-01-26 18:05:50 +0100251 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200252int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500253 const unsigned char *buf, size_t blen,
254 const mbedtls_ecp_point *Q, const mbedtls_mpi *r,
255 const mbedtls_mpi *s);
Manuel Pégourié-Gonnard3aeb5a72013-01-26 18:05:50 +0100256
257/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000258 * \brief This function computes the ECDSA signature and writes it
259 * to a buffer, serialized as defined in <em>RFC-4492:
260 * Elliptic Curve Cryptography (ECC) Cipher Suites for
261 * Transport Layer Security (TLS)</em>.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200262 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000263 * \warning It is not thread-safe to use the same context in
264 * multiple threads.
Manuel Pégourié-Gonnarddfdcac92015-03-31 11:41:42 +0200265 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000266 * \note The deterministic version is used if
267 * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
268 * information, see <em>RFC-6979: Deterministic Usage
269 * of the Digital Signature Algorithm (DSA) and Elliptic
270 * Curve Digital Signature Algorithm (ECDSA)</em>.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200271 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000272 * \note If the bitlength of the message hash is larger than the
273 * bitlength of the group order, then the hash is truncated as
Rose Zadikbff87d92018-01-25 21:58:53 +0000274 * defined in <em>Standards for Efficient Cryptography Group
275 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
276 * 4.1.3, step 5.
Janos Follath0a5154b2017-03-10 11:31:41 +0000277 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000278 * \see ecp.h
Rose Zadik817297f2018-03-27 11:30:14 +0100279 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500280 * \param ctx The ECDSA context to use. This must be initialized
281 * and have a group and private key bound to it, for example
282 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
Rose Zadik817297f2018-03-27 11:30:14 +0100283 * \param md_alg The message digest that was used to hash the message.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500284 * \param hash The message hash to be signed. This must be a readable
285 * buffer of length \p blen Bytes.
286 * \param hlen The length of the hash \p hash in Bytes.
287 * \param sig The buffer to which to write the signature. This must be a
288 * writable buffer of length at least twice as large as the
289 * size of the curve used, plus 9. For example, 73 Bytes if
290 * a 256-bit curve is used. A buffer length of
291 * #MBEDTLS_ECDSA_MAX_LEN is always safe.
292 * \param slen The address at which to store the actual length of
293 * the signature written. Must not be \c NULL.
294 * \param f_rng The RNG function. This must not be \c NULL if
295 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
296 * it is unused and may be set to \c NULL.
297 * \param p_rng The RNG context to be passed to \p f_rng. This may be
298 * \c NULL if \p f_rng is \c NULL or doesn't use a context.
Rose Zadik817297f2018-03-27 11:30:14 +0100299 *
300 * \return \c 0 on success.
301 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
302 * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200303 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500304int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx,
305 mbedtls_md_type_t md_alg,
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200306 const unsigned char *hash, size_t hlen,
307 unsigned char *sig, size_t *slen,
308 int (*f_rng)(void *, unsigned char *, size_t),
309 void *p_rng );
310
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200311/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200312 * \brief This function computes the ECDSA signature and writes it
313 * to a buffer, in a restartable way.
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200314 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200315 * \see \c mbedtls_ecdsa_write_signature()
316 *
317 * \note This function is like \c mbedtls_ecdsa_write_signature()
318 * but it can return early and restart according to the limit
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200319 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
320 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500321 * \param ctx The ECDSA context to use. This must be initialized
322 * and have a group and private key bound to it, for example
323 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200324 * \param md_alg The message digest that was used to hash the message.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500325 * \param hash The message hash to be signed. This must be a readable
326 * buffer of length \p blen Bytes.
327 * \param hlen The length of the hash \p hash in Bytes.
328 * \param sig The buffer to which to write the signature. This must be a
329 * writable buffer of length at least twice as large as the
330 * size of the curve used, plus 9. For example, 73 Bytes if
331 * a 256-bit curve is used. A buffer length of
332 * #MBEDTLS_ECDSA_MAX_LEN is always safe.
333 * \param slen The address at which to store the actual length of
334 * the signature written. Must not be \c NULL.
335 * \param f_rng The RNG function. This must not be \c NULL if
336 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
337 * it is unused and may be set to \c NULL.
338 * \param p_rng The RNG context to be passed to \p f_rng. This may be
339 * \c NULL if \p f_rng is \c NULL or doesn't use a context.
340 * \param rs_ctx The restart context to use. This may be \c NULL to disable
341 * restarting. If it is not \c NULL, it must point to an
342 * initialized restart context.
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200343 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200344 * \return \c 0 on success.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200345 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200346 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200347 * \return Another \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
348 * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200349 */
350int mbedtls_ecdsa_write_signature_restartable( mbedtls_ecdsa_context *ctx,
351 mbedtls_md_type_t md_alg,
352 const unsigned char *hash, size_t hlen,
353 unsigned char *sig, size_t *slen,
354 int (*f_rng)(void *, unsigned char *, size_t),
355 void *p_rng,
356 mbedtls_ecdsa_restart_ctx *rs_ctx );
357
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200358#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
359#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
360#if defined(MBEDTLS_DEPRECATED_WARNING)
361#define MBEDTLS_DEPRECATED __attribute__((deprecated))
Manuel Pégourié-Gonnarddfdcac92015-03-31 11:41:42 +0200362#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200363#define MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnarddfdcac92015-03-31 11:41:42 +0200364#endif
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100365/**
Rose Zadik817297f2018-03-27 11:30:14 +0100366 * \brief This function computes an ECDSA signature and writes
367 * it to a buffer, serialized as defined in <em>RFC-4492:
368 * Elliptic Curve Cryptography (ECC) Cipher Suites for
369 * Transport Layer Security (TLS)</em>.
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100370 *
Rose Zadik817297f2018-03-27 11:30:14 +0100371 * The deterministic version is defined in <em>RFC-6979:
372 * Deterministic Usage of the Digital Signature Algorithm (DSA)
373 * and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
Manuel Pégourié-Gonnarddfdcac92015-03-31 11:41:42 +0200374 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000375 * \warning It is not thread-safe to use the same context in
376 * multiple threads.
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100377 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000378 * \note If the bitlength of the message hash is larger than the
379 * bitlength of the group order, then the hash is truncated as
Rose Zadikbff87d92018-01-25 21:58:53 +0000380 * defined in <em>Standards for Efficient Cryptography Group
381 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
382 * 4.1.3, step 5.
Janos Follath0a5154b2017-03-10 11:31:41 +0000383 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000384 * \see ecp.h
Rose Zadik817297f2018-03-27 11:30:14 +0100385 *
Rose Zadikec5d4162018-04-17 15:55:28 +0100386 * \deprecated Superseded by mbedtls_ecdsa_write_signature() in
387 * Mbed TLS version 2.0 and later.
Rose Zadik817297f2018-03-27 11:30:14 +0100388 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500389 * \param ctx The ECDSA context to use. This must be initialized
390 * and have a group and private key bound to it, for example
391 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
392 * \param hash The message hash to be signed. This must be a readable
393 * buffer of length \p blen Bytes.
394 * \param hlen The length of the hash \p hash in Bytes.
395 * \param sig The buffer to which to write the signature. This must be a
396 * writable buffer of length at least twice as large as the
397 * size of the curve used, plus 9. For example, 73 Bytes if
398 * a 256-bit curve is used. A buffer length of
399 * #MBEDTLS_ECDSA_MAX_LEN is always safe.
400 * \param slen The address at which to store the actual length of
401 * the signature written. Must not be \c NULL.
402 * \param md_alg The message digest that was used to hash the message.
Rose Zadik817297f2018-03-27 11:30:14 +0100403 *
404 * \return \c 0 on success.
405 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
406 * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100407 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200408int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100409 const unsigned char *hash, size_t hlen,
410 unsigned char *sig, size_t *slen,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200411 mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
412#undef MBEDTLS_DEPRECATED
413#endif /* MBEDTLS_DEPRECATED_REMOVED */
414#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100415
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200416/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000417 * \brief This function reads and verifies an ECDSA signature.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200418 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000419 * \note If the bitlength of the message hash is larger than the
420 * bitlength of the group order, then the hash is truncated as
Rose Zadikbff87d92018-01-25 21:58:53 +0000421 * defined in <em>Standards for Efficient Cryptography Group
422 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
423 * 4.1.4, step 3.
Janos Follath0a5154b2017-03-10 11:31:41 +0000424 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000425 * \see ecp.h
Rose Zadik817297f2018-03-27 11:30:14 +0100426 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500427 * \param ctx The ECDSA context to use. This must be initialized
428 * and have a group and public key bound to it.
429 * \param hash The message hash that was signed. This must be a readable
430 * buffer of length \p size Bytes.
431 * \param hlen The size of the hash \p hash.
432 * \param sig The signature to read and verify. This must be a readable
433 * buffer of length \p slen Bytes.
434 * \param slen The size of \p sig in Bytes.
Rose Zadik817297f2018-03-27 11:30:14 +0100435 *
436 * \return \c 0 on success.
437 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
Rose Zadikabc9ec72018-04-23 06:16:40 +0100438 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
439 * signature in \p sig, but its length is less than \p siglen.
Rose Zadik817297f2018-03-27 11:30:14 +0100440 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
441 * error code on failure for any other reason.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200442 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200443int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200444 const unsigned char *hash, size_t hlen,
445 const unsigned char *sig, size_t slen );
446
447/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200448 * \brief This function reads and verifies an ECDSA signature,
449 * in a restartable way.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200450 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200451 * \see \c mbedtls_ecdsa_read_signature()
452 *
453 * \note This function is like \c mbedtls_ecdsa_read_signature()
454 * but it can return early and restart according to the limit
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200455 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
456 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500457 * \param ctx The ECDSA context to use. This must be initialized
458 * and have a group and public key bound to it.
459 * \param hash The message hash that was signed. This must be a readable
460 * buffer of length \p size Bytes.
461 * \param hlen The size of the hash \p hash.
462 * \param sig The signature to read and verify. This must be a readable
463 * buffer of length \p slen Bytes.
464 * \param slen The size of \p sig in Bytes.
465 * \param rs_ctx The restart context to use. This may be \c NULL to disable
466 * restarting. If it is not \c NULL, it must point to an
467 * initialized restart context.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200468 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200469 * \return \c 0 on success.
470 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
471 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
472 * signature in \p sig, but its length is less than \p siglen.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200473 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200474 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200475 * \return Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
476 * error code on failure for any other reason.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200477 */
478int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx,
479 const unsigned char *hash, size_t hlen,
480 const unsigned char *sig, size_t slen,
481 mbedtls_ecdsa_restart_ctx *rs_ctx );
Christoph M. Wintersteigeref17e3b2019-02-15 12:52:09 +0000482
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200483/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000484 * \brief This function generates an ECDSA keypair on the given curve.
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200485 *
Rose Zadik817297f2018-03-27 11:30:14 +0100486 * \see ecp.h
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200487 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000488 * \param ctx The ECDSA context to store the keypair in.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500489 * This must be initialized.
Rose Zadikbff87d92018-01-25 21:58:53 +0000490 * \param gid The elliptic curve to use. One of the various
491 * \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500492 * \param f_rng The RNG function to use. This must not be \c NULL.
493 * \param p_rng The RNG context to be passed to \p f_rng. This may be
494 * \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200495 *
Rose Zadik817297f2018-03-27 11:30:14 +0100496 * \return \c 0 on success.
497 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200498 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200499int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200500 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
501
502/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500503 * \brief This function sets up an ECDSA context from an EC key pair.
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200504 *
Rose Zadik817297f2018-03-27 11:30:14 +0100505 * \see ecp.h
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200506 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500507 * \param ctx The ECDSA context to setup. This must be initialized.
508 * \param key The EC key to use. This must be initialized and hold
509 * a private-public key pair or a public key. In the former
510 * case, the ECDSA context may be used for signature creation
511 * and verification after this call. In the latter case, it
512 * may be used for signature verification.
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200513 *
Rose Zadik817297f2018-03-27 11:30:14 +0100514 * \return \c 0 on success.
515 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200516 */
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500517int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx,
518 const mbedtls_ecp_keypair *key );
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200519
520/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000521 * \brief This function initializes an ECDSA context.
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200522 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000523 * \param ctx The ECDSA context to initialize.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500524 * This must not be \c NULL.
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200525 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200526void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200527
528/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000529 * \brief This function frees an ECDSA context.
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200530 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500531 * \param ctx The ECDSA context to free. This may be \c NULL,
532 * in which case this function does nothing. If it
533 * is not \c NULL, it must be initialized.
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200534 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200535void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200536
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200537#if defined(MBEDTLS_ECP_RESTARTABLE)
538/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500539 * \brief Initialize a restart context.
540 *
541 * \param ctx The restart context to initialize.
542 * This must not be \c NULL.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200543 */
544void mbedtls_ecdsa_restart_init( mbedtls_ecdsa_restart_ctx *ctx );
545
546/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500547 * \brief Free the components of a restart context.
548 *
549 * \param ctx The restart context to free. This may be \c NULL,
550 * in which case this function does nothing. If it
551 * is not \c NULL, it must be initialized.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200552 */
553void mbedtls_ecdsa_restart_free( mbedtls_ecdsa_restart_ctx *ctx );
554#endif /* MBEDTLS_ECP_RESTARTABLE */
555
Manuel Pégourié-Gonnard2aea1412013-01-26 16:33:44 +0100556#ifdef __cplusplus
557}
558#endif
559
Paul Bakker9af723c2014-05-01 13:03:14 +0200560#endif /* ecdsa.h */