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