4 * \brief This file contains ECDSA definitions and functions.
6 * The Elliptic Curve Digital Signature Algorithm (ECDSA) is defined in
7 * <em>Standards for Efficient Cryptography Group (SECG):
8 * 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>.
14 * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
15 * SPDX-License-Identifier: GPL-2.0
17 * This program is free software; you can redistribute it and/or modify
18 * it under the terms of the GNU General Public License as published by
19 * the Free Software Foundation; either version 2 of the License, or
20 * (at your option) any later version.
22 * This program is distributed in the hope that it will be useful,
23 * but WITHOUT ANY WARRANTY; without even the implied warranty of
24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 * GNU General Public License for more details.
27 * You should have received a copy of the GNU General Public License along
28 * with this program; if not, write to the Free Software Foundation, Inc.,
29 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
31 * This file is part of Mbed TLS (https://tls.mbed.org)
34 #ifndef MBEDTLS_ECDSA_H
35 #define MBEDTLS_ECDSA_H
43 * Ecdsa-Sig-Value ::= SEQUENCE {
49 * 1 (tag) + 1 (len) + 1 (initial 0) + ECP_MAX_BYTES for each of r and s,
50 * twice that + 1 (tag) + 2 (len) for the sequence
51 * (assuming ECP_MAX_BYTES is less than 126 for r and s,
52 * and less than 124 (total len <= 255) for the sequence)
54 #if MBEDTLS_ECP_MAX_BYTES > 124
55 #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN"
57 /** The maximal size of an ECDSA signature in Bytes. */
58 #define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) )
61 * \brief The ECDSA context structure.
63 typedef mbedtls_ecp_keypair mbedtls_ecdsa_context
;
70 * \brief This function computes the ECDSA signature of a
71 * previously-hashed message.
73 * \note The deterministic version is usually preferred.
75 * \note If the bitlength of the message hash is larger than the
76 * bitlength of the group order, then the hash is truncated
77 * as defined in <em>Standards for Efficient Cryptography Group
78 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
83 * \param grp The ECP group.
84 * \param r The first output integer.
85 * \param s The second output integer.
86 * \param d The private signing key.
87 * \param buf The message hash.
88 * \param blen The length of \p buf.
89 * \param f_rng The RNG function.
90 * \param p_rng The RNG context.
92 * \return \c 0 on success.
93 * \return An \c MBEDTLS_ERR_ECP_XXX
94 * or \c MBEDTLS_MPI_XXX error code on failure.
96 int mbedtls_ecdsa_sign( mbedtls_ecp_group
*grp
, mbedtls_mpi
*r
, mbedtls_mpi
*s
,
97 const mbedtls_mpi
*d
, const unsigned char *buf
, size_t blen
,
98 int (*f_rng
)(void *, unsigned char *, size_t), void *p_rng
);
100 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
102 * \brief This function computes the ECDSA signature of a
103 * previously-hashed message, deterministic version.
105 * For more information, see <em>RFC-6979: Deterministic
106 * Usage of the Digital Signature Algorithm (DSA) and Elliptic
107 * Curve Digital Signature Algorithm (ECDSA)</em>.
109 * \note If the bitlength of the message hash is larger than the
110 * bitlength of the group order, then the hash is truncated as
111 * defined in <em>Standards for Efficient Cryptography Group
112 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
117 * \param grp The ECP group.
118 * \param r The first output integer.
119 * \param s The second output integer.
120 * \param d The private signing key.
121 * \param buf The message hash.
122 * \param blen The length of \p buf.
123 * \param md_alg The MD algorithm used to hash the message.
125 * \return \c 0 on success.
126 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
127 * error code on failure.
129 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group
*grp
, mbedtls_mpi
*r
, mbedtls_mpi
*s
,
130 const mbedtls_mpi
*d
, const unsigned char *buf
, size_t blen
,
131 mbedtls_md_type_t md_alg
);
132 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
135 * \brief This function verifies the ECDSA signature of a
136 * previously-hashed message.
138 * \note If the bitlength of the message hash is larger than the
139 * bitlength of the group order, then the hash is truncated as
140 * defined in <em>Standards for Efficient Cryptography Group
141 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
146 * \param grp The ECP group.
147 * \param buf The message hash.
148 * \param blen The length of \p buf.
149 * \param Q The public key to use for verification.
150 * \param r The first integer of the signature.
151 * \param s The second integer of the signature.
153 * \return \c 0 on success.
154 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature
156 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX
157 * error code on failure for any other reason.
159 int mbedtls_ecdsa_verify( mbedtls_ecp_group
*grp
,
160 const unsigned char *buf
, size_t blen
,
161 const mbedtls_ecp_point
*Q
, const mbedtls_mpi
*r
, const mbedtls_mpi
*s
);
164 * \brief This function computes the ECDSA signature and writes it
165 * to a buffer, serialized as defined in <em>RFC-4492:
166 * Elliptic Curve Cryptography (ECC) Cipher Suites for
167 * Transport Layer Security (TLS)</em>.
169 * \warning It is not thread-safe to use the same context in
172 * \note The deterministic version is used if
173 * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more
174 * information, see <em>RFC-6979: Deterministic Usage
175 * of the Digital Signature Algorithm (DSA) and Elliptic
176 * Curve Digital Signature Algorithm (ECDSA)</em>.
178 * \note The \p sig buffer must be at least twice as large as the
179 * size of the curve used, plus 9. For example, 73 Bytes if
180 * a 256-bit curve is used. A buffer length of
181 * #MBEDTLS_ECDSA_MAX_LEN is always safe.
183 * \note If the bitlength of the message hash is larger than the
184 * bitlength of the group order, then the hash is truncated as
185 * defined in <em>Standards for Efficient Cryptography Group
186 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
191 * \param ctx The ECDSA context.
192 * \param md_alg The message digest that was used to hash the message.
193 * \param hash The message hash.
194 * \param hlen The length of the hash.
195 * \param sig The buffer that holds the signature.
196 * \param slen The length of the signature written.
197 * \param f_rng The RNG function.
198 * \param p_rng The RNG context.
200 * \return \c 0 on success.
201 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
202 * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
204 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context
*ctx
, mbedtls_md_type_t md_alg
,
205 const unsigned char *hash
, size_t hlen
,
206 unsigned char *sig
, size_t *slen
,
207 int (*f_rng
)(void *, unsigned char *, size_t),
210 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
211 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
212 #if defined(MBEDTLS_DEPRECATED_WARNING)
213 #define MBEDTLS_DEPRECATED __attribute__((deprecated))
215 #define MBEDTLS_DEPRECATED
218 * \brief This function computes an ECDSA signature and writes
219 * it to a buffer, serialized as defined in <em>RFC-4492:
220 * Elliptic Curve Cryptography (ECC) Cipher Suites for
221 * Transport Layer Security (TLS)</em>.
223 * The deterministic version is defined in <em>RFC-6979:
224 * Deterministic Usage of the Digital Signature Algorithm (DSA)
225 * and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>.
227 * \warning It is not thread-safe to use the same context in
230 * \note The \p sig buffer must be at least twice as large as the
231 * size of the curve used, plus 9. For example, 73 Bytes if a
232 * 256-bit curve is used. A buffer length of
233 * #MBEDTLS_ECDSA_MAX_LEN is always safe.
235 * \note If the bitlength of the message hash is larger than the
236 * bitlength of the group order, then the hash is truncated as
237 * defined in <em>Standards for Efficient Cryptography Group
238 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
243 * \deprecated Superseded by mbedtls_ecdsa_write_signature() in
244 * Mbed TLS version 2.0 and later.
246 * \param ctx The ECDSA context.
247 * \param hash The message hash.
248 * \param hlen The length of the hash.
249 * \param sig The buffer that holds the signature.
250 * \param slen The length of the signature written.
251 * \param md_alg The MD algorithm used to hash the message.
253 * \return \c 0 on success.
254 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
255 * \c MBEDTLS_ERR_ASN1_XXX error code on failure.
257 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context
*ctx
,
258 const unsigned char *hash
, size_t hlen
,
259 unsigned char *sig
, size_t *slen
,
260 mbedtls_md_type_t md_alg
) MBEDTLS_DEPRECATED
;
261 #undef MBEDTLS_DEPRECATED
262 #endif /* MBEDTLS_DEPRECATED_REMOVED */
263 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
266 * \brief This function reads and verifies an ECDSA signature.
268 * \note If the bitlength of the message hash is larger than the
269 * bitlength of the group order, then the hash is truncated as
270 * defined in <em>Standards for Efficient Cryptography Group
271 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section
276 * \param ctx The ECDSA context.
277 * \param hash The message hash.
278 * \param hlen The size of the hash.
279 * \param sig The signature to read and verify.
280 * \param slen The size of \p sig.
282 * \return \c 0 on success.
283 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
284 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
285 * signature in \p sig, but its length is less than \p siglen.
286 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
287 * error code on failure for any other reason.
289 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context
*ctx
,
290 const unsigned char *hash
, size_t hlen
,
291 const unsigned char *sig
, size_t slen
);
294 * \brief This function generates an ECDSA keypair on the given curve.
298 * \param ctx The ECDSA context to store the keypair in.
299 * \param gid The elliptic curve to use. One of the various
300 * \c MBEDTLS_ECP_DP_XXX macros depending on configuration.
301 * \param f_rng The RNG function.
302 * \param p_rng The RNG context.
304 * \return \c 0 on success.
305 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
307 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context
*ctx
, mbedtls_ecp_group_id gid
,
308 int (*f_rng
)(void *, unsigned char *, size_t), void *p_rng
);
311 * \brief This function sets an ECDSA context from an EC key pair.
315 * \param ctx The ECDSA context to set.
316 * \param key The EC key to use.
318 * \return \c 0 on success.
319 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure.
321 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context
*ctx
, const mbedtls_ecp_keypair
*key
);
324 * \brief This function initializes an ECDSA context.
326 * \param ctx The ECDSA context to initialize.
328 void mbedtls_ecdsa_init( mbedtls_ecdsa_context
*ctx
);
331 * \brief This function frees an ECDSA context.
333 * \param ctx The ECDSA context to free.
335 void mbedtls_ecdsa_free( mbedtls_ecdsa_context
*ctx
);
337 int ecdsa_signature_to_asn1( const mbedtls_mpi
*r
, const mbedtls_mpi
*s
, unsigned char *sig
, size_t *slen
);