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 The Mbed TLS Contributors 15 * 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. 28 */ 29 30 #ifndef MBEDTLS_ECDSA_H 31 #define MBEDTLS_ECDSA_H 32 33 #if !defined(MBEDTLS_CONFIG_FILE) 34 #include "mbedtls/config.h" 35 #else 36 #include MBEDTLS_CONFIG_FILE 37 #endif 38 39 #include "mbedtls/ecp.h" 40 #include "mbedtls/md.h" 41 42 /** 43 * \brief Maximum ECDSA signature size for a given curve bit size 44 * 45 * \param bits Curve size in bits 46 * \return Maximum signature size in bytes 47 * 48 * \note This macro returns a compile-time constant if its argument 49 * is one. It may evaluate its argument multiple times. 50 */ 51 /* 52 * Ecdsa-Sig-Value ::= SEQUENCE { 53 * r INTEGER, 54 * s INTEGER 55 * } 56 * 57 * For each of r and s, the value (V) may include an extra initial "0" bit. 58 */ 59 #define MBEDTLS_ECDSA_MAX_SIG_LEN( bits ) \ 60 ( /*T,L of SEQUENCE*/ ( ( bits ) >= 61 * 8 ? 3 : 2 ) + \ 61 /*T,L of r,s*/ 2 * ( ( ( bits ) >= 127 * 8 ? 3 : 2 ) + \ 62 /*V of r,s*/ ( ( bits ) + 8 ) / 8 ) ) 63 64 /** The maximal size of an ECDSA signature in Bytes. */ 65 #define MBEDTLS_ECDSA_MAX_LEN MBEDTLS_ECDSA_MAX_SIG_LEN( MBEDTLS_ECP_MAX_BITS ) 66 67 #ifdef __cplusplus 68 extern "C" { 69 #endif 70 71 /** 72 * \brief The ECDSA context structure. 73 * 74 * \warning Performing multiple operations concurrently on the same 75 * ECDSA context is not supported; objects of this type 76 * should not be shared between multiple threads. 77 */ 78 typedef mbedtls_ecp_keypair mbedtls_ecdsa_context; 79 80 #if defined(MBEDTLS_ECP_RESTARTABLE) 81 82 /** 83 * \brief Internal restart context for ecdsa_verify() 84 * 85 * \note Opaque struct, defined in ecdsa.c 86 */ 87 typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx; 88 89 /** 90 * \brief Internal restart context for ecdsa_sign() 91 * 92 * \note Opaque struct, defined in ecdsa.c 93 */ 94 typedef struct mbedtls_ecdsa_restart_sig mbedtls_ecdsa_restart_sig_ctx; 95 96 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 97 /** 98 * \brief Internal restart context for ecdsa_sign_det() 99 * 100 * \note Opaque struct, defined in ecdsa.c 101 */ 102 typedef struct mbedtls_ecdsa_restart_det mbedtls_ecdsa_restart_det_ctx; 103 #endif 104 105 /** 106 * \brief General context for resuming ECDSA operations 107 */ 108 typedef struct 109 { 110 mbedtls_ecp_restart_ctx ecp; /*!< base context for ECP restart and 111 shared administrative info */ 112 mbedtls_ecdsa_restart_ver_ctx *ver; /*!< ecdsa_verify() sub-context */ 113 mbedtls_ecdsa_restart_sig_ctx *sig; /*!< ecdsa_sign() sub-context */ 114 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 115 mbedtls_ecdsa_restart_det_ctx *det; /*!< ecdsa_sign_det() sub-context */ 116 #endif 117 } mbedtls_ecdsa_restart_ctx; 118 119 #else /* MBEDTLS_ECP_RESTARTABLE */ 120 121 /* Now we can declare functions that take a pointer to that */ 122 typedef void mbedtls_ecdsa_restart_ctx; 123 124 #endif /* MBEDTLS_ECP_RESTARTABLE */ 125 126 /** 127 * \brief This function checks whether a given group can be used 128 * for ECDSA. 129 * 130 * \param gid The ECP group ID to check. 131 * 132 * \return \c 1 if the group can be used, \c 0 otherwise 133 */ 134 int mbedtls_ecdsa_can_do( mbedtls_ecp_group_id gid ); 135 136 /** 137 * \brief This function computes the ECDSA signature of a 138 * previously-hashed message. 139 * 140 * \note The deterministic version implemented in 141 * mbedtls_ecdsa_sign_det() is usually preferred. 142 * 143 * \note If the bitlength of the message hash is larger than the 144 * bitlength of the group order, then the hash is truncated 145 * as defined in <em>Standards for Efficient Cryptography Group 146 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 147 * 4.1.3, step 5. 148 * 149 * \see ecp.h 150 * 151 * \param grp The context for the elliptic curve to use. 152 * This must be initialized and have group parameters 153 * set, for example through mbedtls_ecp_group_load(). 154 * \param r The MPI context in which to store the first part 155 * the signature. This must be initialized. 156 * \param s The MPI context in which to store the second part 157 * the signature. This must be initialized. 158 * \param d The private signing key. This must be initialized. 159 * \param buf The content to be signed. This is usually the hash of 160 * the original data to be signed. This must be a readable 161 * buffer of length \p blen Bytes. It may be \c NULL if 162 * \p blen is zero. 163 * \param blen The length of \p buf in Bytes. 164 * \param f_rng The RNG function. This must not be \c NULL. 165 * \param p_rng The RNG context to be passed to \p f_rng. This may be 166 * \c NULL if \p f_rng doesn't need a context parameter. 167 * 168 * \return \c 0 on success. 169 * \return An \c MBEDTLS_ERR_ECP_XXX 170 * or \c MBEDTLS_MPI_XXX error code on failure. 171 */ 172 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, 173 const mbedtls_mpi *d, const unsigned char *buf, size_t blen, 174 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 175 176 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 177 #if ! defined(MBEDTLS_DEPRECATED_REMOVED) 178 #if defined(MBEDTLS_DEPRECATED_WARNING) 179 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 180 #else 181 #define MBEDTLS_DEPRECATED 182 #endif 183 /** 184 * \brief This function computes the ECDSA signature of a 185 * previously-hashed message, deterministic version. 186 * 187 * For more information, see <em>RFC-6979: Deterministic 188 * Usage of the Digital Signature Algorithm (DSA) and Elliptic 189 * Curve Digital Signature Algorithm (ECDSA)</em>. 190 * 191 * \note If the bitlength of the message hash is larger than the 192 * bitlength of the group order, then the hash is truncated as 193 * defined in <em>Standards for Efficient Cryptography Group 194 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 195 * 4.1.3, step 5. 196 * 197 * \warning Since the output of the internal RNG is always the same for 198 * the same key and message, this limits the efficiency of 199 * blinding and leaks information through side channels. For 200 * secure behavior use mbedtls_ecdsa_sign_det_ext() instead. 201 * 202 * (Optimally the blinding is a random value that is different 203 * on every execution. In this case the blinding is still 204 * random from the attackers perspective, but is the same on 205 * each execution. This means that this blinding does not 206 * prevent attackers from recovering secrets by combining 207 * several measurement traces, but may prevent some attacks 208 * that exploit relationships between secret data.) 209 * 210 * \see ecp.h 211 * 212 * \param grp The context for the elliptic curve to use. 213 * This must be initialized and have group parameters 214 * set, for example through mbedtls_ecp_group_load(). 215 * \param r The MPI context in which to store the first part 216 * the signature. This must be initialized. 217 * \param s The MPI context in which to store the second part 218 * the signature. This must be initialized. 219 * \param d The private signing key. This must be initialized 220 * and setup, for example through mbedtls_ecp_gen_privkey(). 221 * \param buf The hashed content to be signed. This must be a readable 222 * buffer of length \p blen Bytes. It may be \c NULL if 223 * \p blen is zero. 224 * \param blen The length of \p buf in Bytes. 225 * \param md_alg The hash algorithm used to hash the original data. 226 * 227 * \return \c 0 on success. 228 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 229 * error code on failure. 230 */ 231 int mbedtls_ecdsa_sign_det( mbedtls_ecp_group *grp, mbedtls_mpi *r, 232 mbedtls_mpi *s, const mbedtls_mpi *d, 233 const unsigned char *buf, size_t blen, 234 mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED; 235 #undef MBEDTLS_DEPRECATED 236 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 237 238 /** 239 * \brief This function computes the ECDSA signature of a 240 * previously-hashed message, deterministic version. 241 * 242 * For more information, see <em>RFC-6979: Deterministic 243 * Usage of the Digital Signature Algorithm (DSA) and Elliptic 244 * Curve Digital Signature Algorithm (ECDSA)</em>. 245 * 246 * \note If the bitlength of the message hash is larger than the 247 * bitlength of the group order, then the hash is truncated as 248 * defined in <em>Standards for Efficient Cryptography Group 249 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 250 * 4.1.3, step 5. 251 * 252 * \see ecp.h 253 * 254 * \param grp The context for the elliptic curve to use. 255 * This must be initialized and have group parameters 256 * set, for example through mbedtls_ecp_group_load(). 257 * \param r The MPI context in which to store the first part 258 * the signature. This must be initialized. 259 * \param s The MPI context in which to store the second part 260 * the signature. This must be initialized. 261 * \param d The private signing key. This must be initialized 262 * and setup, for example through mbedtls_ecp_gen_privkey(). 263 * \param buf The hashed content to be signed. This must be a readable 264 * buffer of length \p blen Bytes. It may be \c NULL if 265 * \p blen is zero. 266 * \param blen The length of \p buf in Bytes. 267 * \param md_alg The hash algorithm used to hash the original data. 268 * \param f_rng_blind The RNG function used for blinding. This must not be 269 * \c NULL. 270 * \param p_rng_blind The RNG context to be passed to \p f_rng. This may be 271 * \c NULL if \p f_rng doesn't need a context parameter. 272 * 273 * \return \c 0 on success. 274 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 275 * error code on failure. 276 */ 277 int mbedtls_ecdsa_sign_det_ext( mbedtls_ecp_group *grp, mbedtls_mpi *r, 278 mbedtls_mpi *s, const mbedtls_mpi *d, 279 const unsigned char *buf, size_t blen, 280 mbedtls_md_type_t md_alg, 281 int (*f_rng_blind)(void *, unsigned char *, size_t), 282 void *p_rng_blind ); 283 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ 284 285 /** 286 * \brief This function verifies the ECDSA signature of a 287 * previously-hashed message. 288 * 289 * \note If the bitlength of the message hash is larger than the 290 * bitlength of the group order, then the hash is truncated as 291 * defined in <em>Standards for Efficient Cryptography Group 292 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 293 * 4.1.4, step 3. 294 * 295 * \see ecp.h 296 * 297 * \param grp The ECP group to use. 298 * This must be initialized and have group parameters 299 * set, for example through mbedtls_ecp_group_load(). 300 * \param buf The hashed content that was signed. This must be a readable 301 * buffer of length \p blen Bytes. It may be \c NULL if 302 * \p blen is zero. 303 * \param blen The length of \p buf in Bytes. 304 * \param Q The public key to use for verification. This must be 305 * initialized and setup. 306 * \param r The first integer of the signature. 307 * This must be initialized. 308 * \param s The second integer of the signature. 309 * This must be initialized. 310 * 311 * \return \c 0 on success. 312 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature 313 * is invalid. 314 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 315 * error code on failure for any other reason. 316 */ 317 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp, 318 const unsigned char *buf, size_t blen, 319 const mbedtls_ecp_point *Q, const mbedtls_mpi *r, 320 const mbedtls_mpi *s); 321 322 /** 323 * \brief This function computes the ECDSA signature and writes it 324 * to a buffer, serialized as defined in <em>RFC-4492: 325 * Elliptic Curve Cryptography (ECC) Cipher Suites for 326 * Transport Layer Security (TLS)</em>. 327 * 328 * \warning It is not thread-safe to use the same context in 329 * multiple threads. 330 * 331 * \note The deterministic version is used if 332 * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more 333 * information, see <em>RFC-6979: Deterministic Usage 334 * of the Digital Signature Algorithm (DSA) and Elliptic 335 * Curve Digital Signature Algorithm (ECDSA)</em>. 336 * 337 * \note If the bitlength of the message hash is larger than the 338 * bitlength of the group order, then the hash is truncated as 339 * defined in <em>Standards for Efficient Cryptography Group 340 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 341 * 4.1.3, step 5. 342 * 343 * \see ecp.h 344 * 345 * \param ctx The ECDSA context to use. This must be initialized 346 * and have a group and private key bound to it, for example 347 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair(). 348 * \param md_alg The message digest that was used to hash the message. 349 * \param hash The message hash to be signed. This must be a readable 350 * buffer of length \p blen Bytes. 351 * \param hlen The length of the hash \p hash in Bytes. 352 * \param sig The buffer to which to write the signature. This must be a 353 * writable buffer of length at least twice as large as the 354 * size of the curve used, plus 9. For example, 73 Bytes if 355 * a 256-bit curve is used. A buffer length of 356 * #MBEDTLS_ECDSA_MAX_LEN is always safe. 357 * \param slen The address at which to store the actual length of 358 * the signature written. Must not be \c NULL. 359 * \param f_rng The RNG function. This must not be \c NULL if 360 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, 361 * it is used only for blinding and may be set to \c NULL, but 362 * doing so is DEPRECATED. 363 * \param p_rng The RNG context to be passed to \p f_rng. This may be 364 * \c NULL if \p f_rng is \c NULL or doesn't use a context. 365 * 366 * \return \c 0 on success. 367 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or 368 * \c MBEDTLS_ERR_ASN1_XXX error code on failure. 369 */ 370 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, 371 mbedtls_md_type_t md_alg, 372 const unsigned char *hash, size_t hlen, 373 unsigned char *sig, size_t *slen, 374 int (*f_rng)(void *, unsigned char *, size_t), 375 void *p_rng ); 376 377 /** 378 * \brief This function computes the ECDSA signature and writes it 379 * to a buffer, in a restartable way. 380 * 381 * \see \c mbedtls_ecdsa_write_signature() 382 * 383 * \note This function is like \c mbedtls_ecdsa_write_signature() 384 * but it can return early and restart according to the limit 385 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking. 386 * 387 * \param ctx The ECDSA context to use. This must be initialized 388 * and have a group and private key bound to it, for example 389 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair(). 390 * \param md_alg The message digest that was used to hash the message. 391 * \param hash The message hash to be signed. This must be a readable 392 * buffer of length \p blen Bytes. 393 * \param hlen The length of the hash \p hash in Bytes. 394 * \param sig The buffer to which to write the signature. This must be a 395 * writable buffer of length at least twice as large as the 396 * size of the curve used, plus 9. For example, 73 Bytes if 397 * a 256-bit curve is used. A buffer length of 398 * #MBEDTLS_ECDSA_MAX_LEN is always safe. 399 * \param slen The address at which to store the actual length of 400 * the signature written. Must not be \c NULL. 401 * \param f_rng The RNG function. This must not be \c NULL if 402 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, 403 * it is unused and may be set to \c NULL. 404 * \param p_rng The RNG context to be passed to \p f_rng. This may be 405 * \c NULL if \p f_rng is \c NULL or doesn't use a context. 406 * \param rs_ctx The restart context to use. This may be \c NULL to disable 407 * restarting. If it is not \c NULL, it must point to an 408 * initialized restart context. 409 * 410 * \return \c 0 on success. 411 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 412 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 413 * \return Another \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or 414 * \c MBEDTLS_ERR_ASN1_XXX error code on failure. 415 */ 416 int mbedtls_ecdsa_write_signature_restartable( mbedtls_ecdsa_context *ctx, 417 mbedtls_md_type_t md_alg, 418 const unsigned char *hash, size_t hlen, 419 unsigned char *sig, size_t *slen, 420 int (*f_rng)(void *, unsigned char *, size_t), 421 void *p_rng, 422 mbedtls_ecdsa_restart_ctx *rs_ctx ); 423 424 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 425 #if ! defined(MBEDTLS_DEPRECATED_REMOVED) 426 #if defined(MBEDTLS_DEPRECATED_WARNING) 427 #define MBEDTLS_DEPRECATED __attribute__((deprecated)) 428 #else 429 #define MBEDTLS_DEPRECATED 430 #endif 431 /** 432 * \brief This function computes an ECDSA signature and writes 433 * it to a buffer, serialized as defined in <em>RFC-4492: 434 * Elliptic Curve Cryptography (ECC) Cipher Suites for 435 * Transport Layer Security (TLS)</em>. 436 * 437 * The deterministic version is defined in <em>RFC-6979: 438 * Deterministic Usage of the Digital Signature Algorithm (DSA) 439 * and Elliptic Curve Digital Signature Algorithm (ECDSA)</em>. 440 * 441 * \warning It is not thread-safe to use the same context in 442 * multiple threads. 443 * 444 * \note If the bitlength of the message hash is larger than the 445 * bitlength of the group order, then the hash is truncated as 446 * defined in <em>Standards for Efficient Cryptography Group 447 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 448 * 4.1.3, step 5. 449 * 450 * \see ecp.h 451 * 452 * \deprecated Superseded by mbedtls_ecdsa_write_signature() in 453 * Mbed TLS version 2.0 and later. 454 * 455 * \param ctx The ECDSA context to use. This must be initialized 456 * and have a group and private key bound to it, for example 457 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair(). 458 * \param hash The message hash to be signed. This must be a readable 459 * buffer of length \p blen Bytes. 460 * \param hlen The length of the hash \p hash in Bytes. 461 * \param sig The buffer to which to write the signature. This must be a 462 * writable buffer of length at least twice as large as the 463 * size of the curve used, plus 9. For example, 73 Bytes if 464 * a 256-bit curve is used. A buffer length of 465 * #MBEDTLS_ECDSA_MAX_LEN is always safe. 466 * \param slen The address at which to store the actual length of 467 * the signature written. Must not be \c NULL. 468 * \param md_alg The message digest that was used to hash the message. 469 * 470 * \return \c 0 on success. 471 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or 472 * \c MBEDTLS_ERR_ASN1_XXX error code on failure. 473 */ 474 int mbedtls_ecdsa_write_signature_det( mbedtls_ecdsa_context *ctx, 475 const unsigned char *hash, size_t hlen, 476 unsigned char *sig, size_t *slen, 477 mbedtls_md_type_t md_alg ) MBEDTLS_DEPRECATED; 478 #undef MBEDTLS_DEPRECATED 479 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 480 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ 481 482 /** 483 * \brief This function reads and verifies an ECDSA signature. 484 * 485 * \note If the bitlength of the message hash is larger than the 486 * bitlength of the group order, then the hash is truncated as 487 * defined in <em>Standards for Efficient Cryptography Group 488 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 489 * 4.1.4, step 3. 490 * 491 * \see ecp.h 492 * 493 * \param ctx The ECDSA context to use. This must be initialized 494 * and have a group and public key bound to it. 495 * \param hash The message hash that was signed. This must be a readable 496 * buffer of length \p size Bytes. 497 * \param hlen The size of the hash \p hash. 498 * \param sig The signature to read and verify. This must be a readable 499 * buffer of length \p slen Bytes. 500 * \param slen The size of \p sig in Bytes. 501 * 502 * \return \c 0 on success. 503 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid. 504 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid 505 * signature in \p sig, but its length is less than \p siglen. 506 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX 507 * error code on failure for any other reason. 508 */ 509 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx, 510 const unsigned char *hash, size_t hlen, 511 const unsigned char *sig, size_t slen ); 512 513 /** 514 * \brief This function reads and verifies an ECDSA signature, 515 * in a restartable way. 516 * 517 * \see \c mbedtls_ecdsa_read_signature() 518 * 519 * \note This function is like \c mbedtls_ecdsa_read_signature() 520 * but it can return early and restart according to the limit 521 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking. 522 * 523 * \param ctx The ECDSA context to use. This must be initialized 524 * and have a group and public key bound to it. 525 * \param hash The message hash that was signed. This must be a readable 526 * buffer of length \p size Bytes. 527 * \param hlen The size of the hash \p hash. 528 * \param sig The signature to read and verify. This must be a readable 529 * buffer of length \p slen Bytes. 530 * \param slen The size of \p sig in Bytes. 531 * \param rs_ctx The restart context to use. This may be \c NULL to disable 532 * restarting. If it is not \c NULL, it must point to an 533 * initialized restart context. 534 * 535 * \return \c 0 on success. 536 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid. 537 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid 538 * signature in \p sig, but its length is less than \p siglen. 539 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 540 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 541 * \return Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX 542 * error code on failure for any other reason. 543 */ 544 int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx, 545 const unsigned char *hash, size_t hlen, 546 const unsigned char *sig, size_t slen, 547 mbedtls_ecdsa_restart_ctx *rs_ctx ); 548 549 /** 550 * \brief This function generates an ECDSA keypair on the given curve. 551 * 552 * \see ecp.h 553 * 554 * \param ctx The ECDSA context to store the keypair in. 555 * This must be initialized. 556 * \param gid The elliptic curve to use. One of the various 557 * \c MBEDTLS_ECP_DP_XXX macros depending on configuration. 558 * \param f_rng The RNG function to use. This must not be \c NULL. 559 * \param p_rng The RNG context to be passed to \p f_rng. This may be 560 * \c NULL if \p f_rng doesn't need a context argument. 561 * 562 * \return \c 0 on success. 563 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. 564 */ 565 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid, 566 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 567 568 /** 569 * \brief This function sets up an ECDSA context from an EC key pair. 570 * 571 * \see ecp.h 572 * 573 * \param ctx The ECDSA context to setup. This must be initialized. 574 * \param key The EC key to use. This must be initialized and hold 575 * a private-public key pair or a public key. In the former 576 * case, the ECDSA context may be used for signature creation 577 * and verification after this call. In the latter case, it 578 * may be used for signature verification. 579 * 580 * \return \c 0 on success. 581 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. 582 */ 583 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, 584 const mbedtls_ecp_keypair *key ); 585 586 /** 587 * \brief This function initializes an ECDSA context. 588 * 589 * \param ctx The ECDSA context to initialize. 590 * This must not be \c NULL. 591 */ 592 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx ); 593 594 /** 595 * \brief This function frees an ECDSA context. 596 * 597 * \param ctx The ECDSA context to free. This may be \c NULL, 598 * in which case this function does nothing. If it 599 * is not \c NULL, it must be initialized. 600 */ 601 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx ); 602 603 #if defined(MBEDTLS_ECP_RESTARTABLE) 604 /** 605 * \brief Initialize a restart context. 606 * 607 * \param ctx The restart context to initialize. 608 * This must not be \c NULL. 609 */ 610 void mbedtls_ecdsa_restart_init( mbedtls_ecdsa_restart_ctx *ctx ); 611 612 /** 613 * \brief Free the components of a restart context. 614 * 615 * \param ctx The restart context to free. This may be \c NULL, 616 * in which case this function does nothing. If it 617 * is not \c NULL, it must be initialized. 618 */ 619 void mbedtls_ecdsa_restart_free( mbedtls_ecdsa_restart_ctx *ctx ); 620 #endif /* MBEDTLS_ECP_RESTARTABLE */ 621 622 #ifdef __cplusplus 623 } 624 #endif 625 626 #endif /* ecdsa.h */ 627