blob: f4c8c7d557a446a5789679a743e1b32ed3db3c04 [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 Amero203fdf72019-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 Amero203fdf72019-07-04 20:01:14 +010041#include "mbedtls/ecp.h"
42#include "mbedtls/md.h"
Jaeden Amero59ebddf2019-07-10 11:03:03 +010043#include "mbedtls/platform_util.h"
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +010044
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010045/**
46 * \brief Maximum ECDSA signature size for a given curve bit size
Manuel Pégourié-Gonnard63e93192015-03-31 11:15:48 +020047 *
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010048 * \param bits Curve size in bits
49 * \return Maximum signature size in bytes
50 *
51 * \note This macro returns a compile-time constant if its argument
52 * is one. It may evaluate its argument multiple times.
53 */
54/*
Manuel Pégourié-Gonnard63e93192015-03-31 11:15:48 +020055 * Ecdsa-Sig-Value ::= SEQUENCE {
56 * r INTEGER,
57 * s INTEGER
58 * }
59 *
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010060 * 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 +020061 */
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010062#define MBEDTLS_ECDSA_MAX_SIG_LEN( bits ) \
63 ( /*T,L of SEQUENCE*/ ( ( bits ) >= 61 * 8 ? 3 : 2 ) + \
64 /*T,L of r,s*/ 2 * ( ( ( bits ) >= 127 * 8 ? 3 : 2 ) + \
65 /*V of r,s*/ ( ( bits ) + 8 ) / 8 ) )
66
Rose Zadikbff87d92018-01-25 21:58:53 +000067/** The maximal size of an ECDSA signature in Bytes. */
Manuel Pégourié-Gonnard2f2b3962018-11-12 15:06:57 +010068#define MBEDTLS_ECDSA_MAX_LEN MBEDTLS_ECDSA_MAX_SIG_LEN( MBEDTLS_ECP_MAX_BITS )
Manuel Pégourié-Gonnard63e93192015-03-31 11:15:48 +020069
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +020070#ifdef __cplusplus
71extern "C" {
72#endif
73
Manuel Pégourié-Gonnardbec2f452013-06-27 10:17:07 +020074/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +020075 * \brief The ECDSA context structure.
Manuel Pégourié-Gonnardeaf55be2017-08-23 14:40:21 +020076 *
77 * \warning Performing multiple operations concurrently on the same
78 * ECDSA context is not supported; objects of this type
79 * should not be shared between multiple threads.
Manuel Pégourié-Gonnardbec2f452013-06-27 10:17:07 +020080 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020081typedef mbedtls_ecp_keypair mbedtls_ecdsa_context;
Manuel Pégourié-Gonnardbec2f452013-06-27 10:17:07 +020082
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +020083#if defined(MBEDTLS_ECP_RESTARTABLE)
84
85/**
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +020086 * \brief Internal restart context for ecdsa_verify()
87 *
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +020088 * \note Opaque struct, defined in ecdsa.c
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +020089 */
90typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx;
91
92/**
Manuel Pégourié-Gonnardb90883d2017-04-25 11:33:10 +020093 * \brief Internal restart context for ecdsa_sign()
94 *
95 * \note Opaque struct, defined in ecdsa.c
96 */
97typedef struct mbedtls_ecdsa_restart_sig mbedtls_ecdsa_restart_sig_ctx;
98
99#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
100/**
101 * \brief Internal restart context for ecdsa_sign_det()
102 *
103 * \note Opaque struct, defined in ecdsa.c
104 */
105typedef struct mbedtls_ecdsa_restart_det mbedtls_ecdsa_restart_det_ctx;
106#endif
107
108/**
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200109 * \brief General context for resuming ECDSA operations
110 */
111typedef struct
112{
Manuel Pégourié-Gonnard12e4a8b2018-09-12 10:55:15 +0200113 mbedtls_ecp_restart_ctx ecp; /*!< base context for ECP restart and
114 shared administrative info */
Manuel Pégourié-Gonnarda0c5bcc2017-04-21 11:33:57 +0200115 mbedtls_ecdsa_restart_ver_ctx *ver; /*!< ecdsa_verify() sub-context */
Manuel Pégourié-Gonnardb90883d2017-04-25 11:33:10 +0200116 mbedtls_ecdsa_restart_sig_ctx *sig; /*!< ecdsa_sign() sub-context */
117#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
118 mbedtls_ecdsa_restart_det_ctx *det; /*!< ecdsa_sign_det() sub-context */
119#endif
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200120} mbedtls_ecdsa_restart_ctx;
121
122#else /* MBEDTLS_ECP_RESTARTABLE */
123
124/* Now we can declare functions that take a pointer to that */
125typedef void mbedtls_ecdsa_restart_ctx;
126
127#endif /* MBEDTLS_ECP_RESTARTABLE */
Manuel Pégourié-Gonnard2aea1412013-01-26 16:33:44 +0100128
129/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000130 * \brief This function computes the ECDSA signature of a
131 * previously-hashed message.
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100132 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500133 * \note The deterministic version implemented in
134 * mbedtls_ecdsa_sign_det() is usually preferred.
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100135 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000136 * \note If the bitlength of the message hash is larger than the
Rose Zadik817297f2018-03-27 11:30:14 +0100137 * bitlength of the group order, then the hash is truncated
138 * as defined in <em>Standards for Efficient Cryptography Group
139 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
140 * 4.1.3, step 5.
Janos Follath0a5154b2017-03-10 11:31:41 +0000141 *
Rose Zadik817297f2018-03-27 11:30:14 +0100142 * \see ecp.h
143 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500144 * \param grp The context for the elliptic curve to use.
145 * This must be initialized and have group parameters
146 * set, for example through mbedtls_ecp_group_load().
147 * \param r The MPI context in which to store the first part
148 * the signature. This must be initialized.
149 * \param s The MPI context in which to store the second part
150 * the signature. This must be initialized.
151 * \param d The private signing key. This must be initialized.
152 * \param buf The content to be signed. This is usually the hash of
153 * the original data to be signed. This must be a readable
154 * buffer of length \p blen Bytes. It may be \c NULL if
155 * \p blen is zero.
156 * \param blen The length of \p buf in Bytes.
157 * \param f_rng The RNG function. This must not be \c NULL.
158 * \param p_rng The RNG context to be passed to \p f_rng. This may be
159 * \c NULL if \p f_rng doesn't need a context parameter.
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100160 *
Rose Zadik817297f2018-03-27 11:30:14 +0100161 * \return \c 0 on success.
162 * \return An \c MBEDTLS_ERR_ECP_XXX
Rose Zadikbff87d92018-01-25 21:58:53 +0000163 * or \c MBEDTLS_MPI_XXX error code on failure.
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100164 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100165MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200166int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
167 const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100168 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
169
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200170#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100171/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000172 * \brief This function computes the ECDSA signature of a
173 * previously-hashed message, deterministic version.
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100174 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000175 * For more information, see <em>RFC-6979: Deterministic
176 * Usage of the Digital Signature Algorithm (DSA) and Elliptic
177 * Curve Digital Signature Algorithm (ECDSA)</em>.
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100178 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000179 * \note If the bitlength of the message hash is larger than the
180 * bitlength of the group order, then the hash is truncated as
Rose Zadik817297f2018-03-27 11:30:14 +0100181 * defined in <em>Standards for Efficient Cryptography Group
182 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
183 * 4.1.3, step 5.
Janos Follath0a5154b2017-03-10 11:31:41 +0000184 *
Rose Zadik817297f2018-03-27 11:30:14 +0100185 * \see ecp.h
186 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500187 * \param grp The context for the elliptic curve to use.
188 * This must be initialized and have group parameters
189 * set, for example through mbedtls_ecp_group_load().
190 * \param r The MPI context in which to store the first part
191 * the signature. This must be initialized.
192 * \param s The MPI context in which to store the second part
193 * the signature. This must be initialized.
194 * \param d The private signing key. This must be initialized
195 * and setup, for example through mbedtls_ecp_gen_privkey().
196 * \param buf The hashed content to be signed. This must be a readable
197 * buffer of length \p blen Bytes. It may be \c NULL if
198 * \p blen is zero.
199 * \param blen The length of \p buf in Bytes.
200 * \param md_alg The hash algorithm used to hash the original data.
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100201 *
Rose Zadik817297f2018-03-27 11:30:14 +0100202 * \return \c 0 on success.
Rose Zadik14d0d572018-04-16 16:09:30 +0100203 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
Rose Zadikbff87d92018-01-25 21:58:53 +0000204 * error code on failure.
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100205 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100206MBEDTLS_DEPRECATED
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500207int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r,
208 mbedtls_mpi *s, const mbedtls_mpi *d,
209 const unsigned char *buf, size_t blen,
210 mbedtls_md_type_t md_alg );
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200211#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
Manuel Pégourié-Gonnard4daaef72014-01-06 14:25:56 +0100212
Manuel Pégourié-Gonnardb309ab22013-01-26 17:24:59 +0100213/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000214 * \brief This function verifies the ECDSA signature of a
215 * previously-hashed message.
Manuel Pégourié-Gonnard3aeb5a72013-01-26 18:05:50 +0100216 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000217 * \note If the bitlength of the message hash is larger than the
218 * bitlength of the group order, then the hash is truncated as
Rose Zadik817297f2018-03-27 11:30:14 +0100219 * defined in <em>Standards for Efficient Cryptography Group
220 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
221 * 4.1.4, step 3.
Janos Follath0a5154b2017-03-10 11:31:41 +0000222 *
Rose Zadik817297f2018-03-27 11:30:14 +0100223 * \see ecp.h
224 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500225 * \param grp The ECP group to use.
226 * This must be initialized and have group parameters
227 * set, for example through mbedtls_ecp_group_load().
228 * \param buf The hashed content that was signed. This must be a readable
229 * buffer of length \p blen Bytes. It may be \c NULL if
230 * \p blen is zero.
231 * \param blen The length of \p buf in Bytes.
232 * \param Q The public key to use for verification. This must be
233 * initialized and setup.
Rose Zadikbff87d92018-01-25 21:58:53 +0000234 * \param r The first integer of the signature.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500235 * This must be initialized.
Rose Zadikbff87d92018-01-25 21:58:53 +0000236 * \param s The second integer of the signature.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500237 * This must be initialized.
Manuel Pégourié-Gonnard3aeb5a72013-01-26 18:05:50 +0100238 *
Rose Zadik817297f2018-03-27 11:30:14 +0100239 * \return \c 0 on success.
Rose Zadik14d0d572018-04-16 16:09:30 +0100240 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
241 * is invalid.
Rose Zadik817297f2018-03-27 11:30:14 +0100242 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
Rose Zadikbff87d92018-01-25 21:58:53 +0000243 * error code on failure for any other reason.
Manuel Pégourié-Gonnard3aeb5a72013-01-26 18:05:50 +0100244 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100245MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200246int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp,
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500247 const unsigned char *buf, size_t blen,
248 const mbedtls_ecp_point *Q, const mbedtls_mpi *r,
249 const mbedtls_mpi *s);
Manuel Pégourié-Gonnard3aeb5a72013-01-26 18:05:50 +0100250
251/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000252 * \brief This function computes the ECDSA signature and writes it
253 * to a buffer, serialized as defined in <em>RFC-4492:
254 * Elliptic Curve Cryptography (ECC) Cipher Suites for
255 * Transport Layer Security (TLS)</em>.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200256 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000257 * \warning It is not thread-safe to use the same context in
258 * multiple threads.
Manuel Pégourié-Gonnarddfdcac92015-03-31 11:41:42 +0200259 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000260 * \note The deterministic version is used if
261 * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
262 * information, see <em>RFC-6979: Deterministic Usage
263 * of the Digital Signature Algorithm (DSA) and Elliptic
264 * Curve Digital Signature Algorithm (ECDSA)</em>.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200265 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000266 * \note If the bitlength of the message hash is larger than the
267 * bitlength of the group order, then the hash is truncated as
Rose Zadikbff87d92018-01-25 21:58:53 +0000268 * defined in <em>Standards for Efficient Cryptography Group
269 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
270 * 4.1.3, step 5.
Janos Follath0a5154b2017-03-10 11:31:41 +0000271 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000272 * \see ecp.h
Rose Zadik817297f2018-03-27 11:30:14 +0100273 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500274 * \param ctx The ECDSA context to use. This must be initialized
275 * and have a group and private key bound to it, for example
276 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
Rose Zadik817297f2018-03-27 11:30:14 +0100277 * \param md_alg The message digest that was used to hash the message.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500278 * \param hash The message hash to be signed. This must be a readable
279 * buffer of length \p blen Bytes.
280 * \param hlen The length of the hash \p hash in Bytes.
281 * \param sig The buffer to which to write the signature. This must be a
282 * writable buffer of length at least twice as large as the
283 * size of the curve used, plus 9. For example, 73 Bytes if
284 * a 256-bit curve is used. A buffer length of
285 * #MBEDTLS_ECDSA_MAX_LEN is always safe.
286 * \param slen The address at which to store the actual length of
287 * the signature written. Must not be \c NULL.
288 * \param f_rng The RNG function. This must not be \c NULL if
289 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
290 * it is unused and may be set to \c NULL.
291 * \param p_rng The RNG context to be passed to \p f_rng. This may be
292 * \c NULL if \p f_rng is \c NULL or doesn't use a context.
Rose Zadik817297f2018-03-27 11:30:14 +0100293 *
294 * \return \c 0 on success.
295 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
296 * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200297 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100298MBEDTLS_DEPRECATED
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500299int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx,
300 mbedtls_md_type_t md_alg,
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200301 const unsigned char *hash, size_t hlen,
302 unsigned char *sig, size_t *slen,
303 int (*f_rng)(void *, unsigned char *, size_t),
304 void *p_rng );
305
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200306/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200307 * \brief This function computes the ECDSA signature and writes it
308 * to a buffer, in a restartable way.
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200309 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200310 * \see \c mbedtls_ecdsa_write_signature()
311 *
312 * \note This function is like \c mbedtls_ecdsa_write_signature()
313 * but it can return early and restart according to the limit
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200314 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
315 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500316 * \param ctx The ECDSA context to use. This must be initialized
317 * and have a group and private key bound to it, for example
318 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200319 * \param md_alg The message digest that was used to hash the message.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500320 * \param hash The message hash to be signed. This must be a readable
321 * buffer of length \p blen Bytes.
322 * \param hlen The length of the hash \p hash in Bytes.
323 * \param sig The buffer to which to write the signature. This must be a
324 * writable buffer of length at least twice as large as the
325 * size of the curve used, plus 9. For example, 73 Bytes if
326 * a 256-bit curve is used. A buffer length of
327 * #MBEDTLS_ECDSA_MAX_LEN is always safe.
328 * \param slen The address at which to store the actual length of
329 * the signature written. Must not be \c NULL.
330 * \param f_rng The RNG function. This must not be \c NULL if
331 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
332 * it is unused and may be set to \c NULL.
333 * \param p_rng The RNG context to be passed to \p f_rng. This may be
334 * \c NULL if \p f_rng is \c NULL or doesn't use a context.
335 * \param rs_ctx The restart context to use. This may be \c NULL to disable
336 * restarting. If it is not \c NULL, it must point to an
337 * initialized restart context.
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200338 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200339 * \return \c 0 on success.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200340 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200341 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200342 * \return Another \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
343 * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200344 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100345MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnardaddb10e2017-04-21 12:54:46 +0200346int mbedtls_ecdsa_write_signature_restartable( mbedtls_ecdsa_context *ctx,
347 mbedtls_md_type_t md_alg,
348 const unsigned char *hash, size_t hlen,
349 unsigned char *sig, size_t *slen,
350 int (*f_rng)(void *, unsigned char *, size_t),
351 void *p_rng,
352 mbedtls_ecdsa_restart_ctx *rs_ctx );
353
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200354#if defined(MBEDTLS_ECDSA_DETERMINISTIC)
355#if ! defined(MBEDTLS_DEPRECATED_REMOVED)
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100356/**
Rose Zadik817297f2018-03-27 11:30:14 +0100357 * \brief This function computes an ECDSA signature and writes
358 * it to a buffer, serialized as defined in <em>RFC-4492:
359 * Elliptic Curve Cryptography (ECC) Cipher Suites for
360 * Transport Layer Security (TLS)</em>.
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100361 *
Rose Zadik817297f2018-03-27 11:30:14 +0100362 * The deterministic version is defined in <em>RFC-6979:
363 * Deterministic Usage of the Digital Signature Algorithm (DSA)
364 * and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
Manuel Pégourié-Gonnarddfdcac92015-03-31 11:41:42 +0200365 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000366 * \warning It is not thread-safe to use the same context in
367 * multiple threads.
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100368 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000369 * \note If the bitlength of the message hash is larger than the
370 * bitlength of the group order, then the hash is truncated as
Rose Zadikbff87d92018-01-25 21:58:53 +0000371 * defined in <em>Standards for Efficient Cryptography Group
372 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
373 * 4.1.3, step 5.
Janos Follath0a5154b2017-03-10 11:31:41 +0000374 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000375 * \see ecp.h
Rose Zadik817297f2018-03-27 11:30:14 +0100376 *
Rose Zadikec5d4162018-04-17 15:55:28 +0100377 * \deprecated Superseded by mbedtls_ecdsa_write_signature() in
378 * Mbed TLS version 2.0 and later.
Rose Zadik817297f2018-03-27 11:30:14 +0100379 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500380 * \param ctx The ECDSA context to use. This must be initialized
381 * and have a group and private key bound to it, for example
382 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair().
383 * \param hash The message hash to be signed. This must be a readable
384 * buffer of length \p blen Bytes.
385 * \param hlen The length of the hash \p hash in Bytes.
386 * \param sig The buffer to which to write the signature. This must be a
387 * writable buffer of length at least twice as large as the
388 * size of the curve used, plus 9. For example, 73 Bytes if
389 * a 256-bit curve is used. A buffer length of
390 * #MBEDTLS_ECDSA_MAX_LEN is always safe.
391 * \param slen The address at which to store the actual length of
392 * the signature written. Must not be \c NULL.
393 * \param md_alg The message digest that was used to hash the message.
Rose Zadik817297f2018-03-27 11:30:14 +0100394 *
395 * \return \c 0 on success.
396 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
397 * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100398 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200399int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx,
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100400 const unsigned char *hash, size_t hlen,
401 unsigned char *sig, size_t *slen,
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200402 mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED;
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200403#endif /* MBEDTLS_DEPRECATED_REMOVED */
404#endif /* MBEDTLS_ECDSA_DETERMINISTIC */
Manuel Pégourié-Gonnard937340b2014-01-06 10:27:16 +0100405
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200406/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000407 * \brief This function reads and verifies an ECDSA signature.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200408 *
Janos Follath0a5154b2017-03-10 11:31:41 +0000409 * \note If the bitlength of the message hash is larger than the
410 * bitlength of the group order, then the hash is truncated as
Rose Zadikbff87d92018-01-25 21:58:53 +0000411 * defined in <em>Standards for Efficient Cryptography Group
412 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
413 * 4.1.4, step 3.
Janos Follath0a5154b2017-03-10 11:31:41 +0000414 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000415 * \see ecp.h
Rose Zadik817297f2018-03-27 11:30:14 +0100416 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500417 * \param ctx The ECDSA context to use. This must be initialized
418 * and have a group and public key bound to it.
419 * \param hash The message hash that was signed. This must be a readable
420 * buffer of length \p size Bytes.
421 * \param hlen The size of the hash \p hash.
422 * \param sig The signature to read and verify. This must be a readable
423 * buffer of length \p slen Bytes.
424 * \param slen The size of \p sig in Bytes.
Rose Zadik817297f2018-03-27 11:30:14 +0100425 *
426 * \return \c 0 on success.
427 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
Rose Zadikabc9ec72018-04-23 06:16:40 +0100428 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
429 * signature in \p sig, but its length is less than \p siglen.
Rose Zadik817297f2018-03-27 11:30:14 +0100430 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
431 * error code on failure for any other reason.
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200432 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100433MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200434int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx,
Manuel Pégourié-Gonnardb694b482013-08-08 13:30:57 +0200435 const unsigned char *hash, size_t hlen,
436 const unsigned char *sig, size_t slen );
437
438/**
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200439 * \brief This function reads and verifies an ECDSA signature,
440 * in a restartable way.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200441 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200442 * \see \c mbedtls_ecdsa_read_signature()
443 *
444 * \note This function is like \c mbedtls_ecdsa_read_signature()
445 * but it can return early and restart according to the limit
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200446 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
447 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500448 * \param ctx The ECDSA context to use. This must be initialized
449 * and have a group and public key bound to it.
450 * \param hash The message hash that was signed. This must be a readable
451 * buffer of length \p size Bytes.
452 * \param hlen The size of the hash \p hash.
453 * \param sig The signature to read and verify. This must be a readable
454 * buffer of length \p slen Bytes.
455 * \param slen The size of \p sig in Bytes.
456 * \param rs_ctx The restart context to use. This may be \c NULL to disable
457 * restarting. If it is not \c NULL, it must point to an
458 * initialized restart context.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200459 *
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200460 * \return \c 0 on success.
461 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
462 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
463 * signature in \p sig, but its length is less than \p siglen.
Manuel Pégourié-Gonnardda19f4c2018-06-12 12:40:54 +0200464 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200465 * operations was reached: see \c mbedtls_ecp_set_max_ops().
Manuel Pégourié-Gonnardf0bbd7e2018-10-15 13:22:41 +0200466 * \return Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
467 * error code on failure for any other reason.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200468 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100469MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200470int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx,
471 const unsigned char *hash, size_t hlen,
472 const unsigned char *sig, size_t slen,
473 mbedtls_ecdsa_restart_ctx *rs_ctx );
474
475/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000476 * \brief This function generates an ECDSA keypair on the given curve.
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200477 *
Rose Zadik817297f2018-03-27 11:30:14 +0100478 * \see ecp.h
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200479 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000480 * \param ctx The ECDSA context to store the keypair in.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500481 * This must be initialized.
Rose Zadikbff87d92018-01-25 21:58:53 +0000482 * \param gid The elliptic curve to use. One of the various
483 * \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500484 * \param f_rng The RNG function to use. This must not be \c NULL.
485 * \param p_rng The RNG context to be passed to \p f_rng. This may be
486 * \c NULL if \p f_rng doesn't need a context argument.
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200487 *
Rose Zadik817297f2018-03-27 11:30:14 +0100488 * \return \c 0 on success.
489 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200490 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100491MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200492int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
Manuel Pégourié-Gonnard8eebd012013-08-09 16:21:34 +0200493 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng );
494
495/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500496 * \brief This function sets up an ECDSA context from an EC key pair.
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200497 *
Rose Zadik817297f2018-03-27 11:30:14 +0100498 * \see ecp.h
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200499 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500500 * \param ctx The ECDSA context to setup. This must be initialized.
501 * \param key The EC key to use. This must be initialized and hold
502 * a private-public key pair or a public key. In the former
503 * case, the ECDSA context may be used for signature creation
504 * and verification after this call. In the latter case, it
505 * may be used for signature verification.
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200506 *
Rose Zadik817297f2018-03-27 11:30:14 +0100507 * \return \c 0 on success.
508 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200509 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100510MBEDTLS_DEPRECATED
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500511int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx,
512 const mbedtls_ecp_keypair *key );
Manuel Pégourié-Gonnardf4999932013-08-12 17:02:59 +0200513
514/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000515 * \brief This function initializes an ECDSA context.
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200516 *
Rose Zadikbff87d92018-01-25 21:58:53 +0000517 * \param ctx The ECDSA context to initialize.
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500518 * This must not be \c NULL.
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200519 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100520MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200521void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx );
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200522
523/**
Rose Zadikbff87d92018-01-25 21:58:53 +0000524 * \brief This function frees an ECDSA context.
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200525 *
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500526 * \param ctx The ECDSA context to free. This may be \c NULL,
527 * in which case this function does nothing. If it
528 * is not \c NULL, it must be initialized.
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200529 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100530MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200531void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx );
Manuel Pégourié-Gonnard7c8934e2013-06-27 12:54:02 +0200532
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200533#if defined(MBEDTLS_ECP_RESTARTABLE)
534/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500535 * \brief Initialize a restart context.
536 *
537 * \param ctx The restart context to initialize.
538 * This must not be \c NULL.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200539 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100540MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200541void mbedtls_ecdsa_restart_init( mbedtls_ecdsa_restart_ctx *ctx );
542
543/**
Andrzej Kurekc470b6b2019-01-31 08:20:20 -0500544 * \brief Free the components of a restart context.
545 *
546 * \param ctx The restart context to free. This may be \c NULL,
547 * in which case this function does nothing. If it
548 * is not \c NULL, it must be initialized.
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200549 */
Jaeden Amerodfc7f4a2019-07-10 11:33:37 +0100550MBEDTLS_DEPRECATED
Manuel Pégourié-Gonnard32aa4372017-04-21 10:29:13 +0200551void mbedtls_ecdsa_restart_free( mbedtls_ecdsa_restart_ctx *ctx );
552#endif /* MBEDTLS_ECP_RESTARTABLE */
553
Manuel Pégourié-Gonnard2aea1412013-01-26 16:33:44 +0100554#ifdef __cplusplus
555}
556#endif
557
Paul Bakker9af723c2014-05-01 13:03:14 +0200558#endif /* ecdsa.h */