]>
Commit | Line | Data |
---|---|---|
700d8687 OM |
1 | /** |
2 | * \file ecdsa.h | |
3 | * | |
4 | * \brief This file contains ECDSA definitions and functions. | |
5 | * | |
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>. | |
11 | * | |
12 | */ | |
13 | /* | |
14 | * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved | |
15 | * SPDX-License-Identifier: GPL-2.0 | |
16 | * | |
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. | |
21 | * | |
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. | |
26 | * | |
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. | |
30 | * | |
31 | * This file is part of Mbed TLS (https://tls.mbed.org) | |
32 | */ | |
33 | ||
34 | #ifndef MBEDTLS_ECDSA_H | |
35 | #define MBEDTLS_ECDSA_H | |
36 | ||
37 | #include "ecp.h" | |
38 | #include "md.h" | |
39 | ||
40 | /* | |
41 | * RFC-4492 page 20: | |
42 | * | |
43 | * Ecdsa-Sig-Value ::= SEQUENCE { | |
44 | * r INTEGER, | |
45 | * s INTEGER | |
46 | * } | |
47 | * | |
48 | * Size is at most | |
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) | |
53 | */ | |
54 | #if MBEDTLS_ECP_MAX_BYTES > 124 | |
55 | #error "MBEDTLS_ECP_MAX_BYTES bigger than expected, please fix MBEDTLS_ECDSA_MAX_LEN" | |
56 | #endif | |
57 | /** The maximal size of an ECDSA signature in Bytes. */ | |
58 | #define MBEDTLS_ECDSA_MAX_LEN ( 3 + 2 * ( 3 + MBEDTLS_ECP_MAX_BYTES ) ) | |
59 | ||
60 | /** | |
61 | * \brief The ECDSA context structure. | |
62 | */ | |
63 | typedef mbedtls_ecp_keypair mbedtls_ecdsa_context; | |
64 | ||
65 | #ifdef __cplusplus | |
66 | extern "C" { | |
67 | #endif | |
68 | ||
69 | /** | |
70 | * \brief This function computes the ECDSA signature of a | |
71 | * previously-hashed message. | |
72 | * | |
73 | * \note The deterministic version is usually preferred. | |
74 | * | |
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 | |
79 | * 4.1.3, step 5. | |
80 | * | |
81 | * \see ecp.h | |
82 | * | |
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. | |
91 | * | |
92 | * \return \c 0 on success. | |
93 | * \return An \c MBEDTLS_ERR_ECP_XXX | |
94 | * or \c MBEDTLS_MPI_XXX error code on failure. | |
95 | */ | |
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 ); | |
99 | ||
100 | #if defined(MBEDTLS_ECDSA_DETERMINISTIC) | |
101 | /** | |
102 | * \brief This function computes the ECDSA signature of a | |
103 | * previously-hashed message, deterministic version. | |
104 | * | |
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>. | |
108 | * | |
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 | |
113 | * 4.1.3, step 5. | |
114 | * | |
115 | * \see ecp.h | |
116 | * | |
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. | |
124 | * | |
125 | * \return \c 0 on success. | |
126 | * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX | |
127 | * error code on failure. | |
128 | */ | |
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 */ | |
133 | ||
134 | /** | |
135 | * \brief This function verifies the ECDSA signature of a | |
136 | * previously-hashed message. | |
137 | * | |
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 | |
142 | * 4.1.4, step 3. | |
143 | * | |
144 | * \see ecp.h | |
145 | * | |
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. | |
152 | * | |
153 | * \return \c 0 on success. | |
154 | * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature | |
155 | * is invalid. | |
156 | * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX | |
157 | * error code on failure for any other reason. | |
158 | */ | |
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); | |
162 | ||
163 | /** | |
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>. | |
168 | * | |
169 | * \warning It is not thread-safe to use the same context in | |
170 | * multiple threads. | |
171 | * | |
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>. | |
177 | * | |
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. | |
182 | * | |
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 | |
187 | * 4.1.3, step 5. | |
188 | * | |
189 | * \see ecp.h | |
190 | * | |
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. | |
199 | * | |
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. | |
203 | */ | |
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), | |
208 | void *p_rng ); | |
209 | ||
210 | #if defined(MBEDTLS_ECDSA_DETERMINISTIC) | |
211 | #if ! defined(MBEDTLS_DEPRECATED_REMOVED) | |
212 | #if defined(MBEDTLS_DEPRECATED_WARNING) | |
213 | #define MBEDTLS_DEPRECATED __attribute__((deprecated)) | |
214 | #else | |
215 | #define MBEDTLS_DEPRECATED | |
216 | #endif | |
217 | /** | |
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>. | |
222 | * | |
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>. | |
226 | * | |
227 | * \warning It is not thread-safe to use the same context in | |
228 | * multiple threads. | |
229 | * | |
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. | |
234 | * | |
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 | |
239 | * 4.1.3, step 5. | |
240 | * | |
241 | * \see ecp.h | |
242 | * | |
243 | * \deprecated Superseded by mbedtls_ecdsa_write_signature() in | |
244 | * Mbed TLS version 2.0 and later. | |
245 | * | |
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. | |
252 | * | |
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. | |
256 | */ | |
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 */ | |
264 | ||
265 | /** | |
266 | * \brief This function reads and verifies an ECDSA signature. | |
267 | * | |
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 | |
272 | * 4.1.4, step 3. | |
273 | * | |
274 | * \see ecp.h | |
275 | * | |
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. | |
281 | * | |
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. | |
288 | */ | |
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 ); | |
292 | ||
293 | /** | |
294 | * \brief This function generates an ECDSA keypair on the given curve. | |
295 | * | |
296 | * \see ecp.h | |
297 | * | |
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. | |
303 | * | |
304 | * \return \c 0 on success. | |
305 | * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. | |
306 | */ | |
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 ); | |
309 | ||
310 | /** | |
311 | * \brief This function sets an ECDSA context from an EC key pair. | |
312 | * | |
313 | * \see ecp.h | |
314 | * | |
315 | * \param ctx The ECDSA context to set. | |
316 | * \param key The EC key to use. | |
317 | * | |
318 | * \return \c 0 on success. | |
319 | * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. | |
320 | */ | |
321 | int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, const mbedtls_ecp_keypair *key ); | |
322 | ||
323 | /** | |
324 | * \brief This function initializes an ECDSA context. | |
325 | * | |
326 | * \param ctx The ECDSA context to initialize. | |
327 | */ | |
328 | void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx ); | |
329 | ||
330 | /** | |
331 | * \brief This function frees an ECDSA context. | |
332 | * | |
333 | * \param ctx The ECDSA context to free. | |
334 | */ | |
335 | void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx ); | |
336 | ||
3a5ffba7 | 337 | int ecdsa_signature_to_asn1( const mbedtls_mpi *r, const mbedtls_mpi *s, unsigned char *sig, size_t *slen ); |
338 | ||
700d8687 OM |
339 | #ifdef __cplusplus |
340 | } | |
341 | #endif | |
342 | ||
343 | #endif /* ecdsa.h */ |