Implement Originality Signature Check in 'hf mfu info'
[proxmark3-svn] / common / mbedtls / ecdsa.h
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
337 int ecdsa_signature_to_asn1( const mbedtls_mpi *r, const mbedtls_mpi *s, unsigned char *sig, size_t *slen );
338
339 #ifdef __cplusplus
340 }
341 #endif
342
343 #endif /* ecdsa.h */
Impressum, Datenschutz