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. This must not be \c NULL. 154 * \param p_rng The RNG context to be passed to \p f_rng. This may be 155 * \c NULL if \p f_rng doesn't need a context parameter. 156 * 157 * \return \c 0 on success. 158 * \return An \c MBEDTLS_ERR_ECP_XXX 159 * or \c MBEDTLS_MPI_XXX error code on failure. 160 */ 161 int mbedtls_ecdsa_sign(mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, 162 const mbedtls_mpi *d, const unsigned char *buf, size_t blen, 163 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng); 164 165 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 166 /** 167 * \brief This function computes the ECDSA signature of a 168 * previously-hashed message, deterministic version. 169 * 170 * For more information, see <em>RFC-6979: Deterministic 171 * Usage of the Digital Signature Algorithm (DSA) and Elliptic 172 * Curve Digital Signature Algorithm (ECDSA)</em>. 173 * 174 * \note If the bitlength of the message hash is larger than the 175 * bitlength of the group order, then the hash is truncated as 176 * defined in <em>Standards for Efficient Cryptography Group 177 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 178 * 4.1.3, step 5. 179 * 180 * \see ecp.h 181 * 182 * \param grp The context for the elliptic curve to use. 183 * This must be initialized and have group parameters 184 * set, for example through mbedtls_ecp_group_load(). 185 * \param r The MPI context in which to store the first part 186 * the signature. This must be initialized. 187 * \param s The MPI context in which to store the second part 188 * the signature. This must be initialized. 189 * \param d The private signing key. This must be initialized 190 * and setup, for example through mbedtls_ecp_gen_privkey(). 191 * \param buf The hashed content to be signed. This must be a readable 192 * buffer of length \p blen Bytes. It may be \c NULL if 193 * \p blen is zero. 194 * \param blen The length of \p buf in Bytes. 195 * \param md_alg The hash algorithm used to hash the original data. 196 * \param f_rng_blind The RNG function used for blinding. This must not be 197 * \c NULL. 198 * \param p_rng_blind The RNG context to be passed to \p f_rng_blind. This 199 * may be \c NULL if \p f_rng_blind doesn't need a context 200 * parameter. 201 * 202 * \return \c 0 on success. 203 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 204 * error code on failure. 205 */ 206 int mbedtls_ecdsa_sign_det_ext(mbedtls_ecp_group *grp, mbedtls_mpi *r, 207 mbedtls_mpi *s, const mbedtls_mpi *d, 208 const unsigned char *buf, size_t blen, 209 mbedtls_md_type_t md_alg, 210 int (*f_rng_blind)(void *, unsigned char *, size_t), 211 void *p_rng_blind); 212 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ 213 214 #if !defined(MBEDTLS_ECDSA_SIGN_ALT) 215 /** 216 * \brief This function computes the ECDSA signature of a 217 * previously-hashed message, in a restartable way. 218 * 219 * \note The deterministic version implemented in 220 * mbedtls_ecdsa_sign_det_restartable() is usually 221 * preferred. 222 * 223 * \note This function is like \c mbedtls_ecdsa_sign() but 224 * it can return early and restart according to the 225 * limit set with \c mbedtls_ecp_set_max_ops() to 226 * reduce blocking. 227 * 228 * \note If the bitlength of the message hash is larger 229 * than the bitlength of the group order, then the 230 * hash is truncated as defined in <em>Standards for 231 * Efficient Cryptography Group (SECG): SEC1 Elliptic 232 * Curve Cryptography</em>, section 4.1.3, step 5. 233 * 234 * \see ecp.h 235 * 236 * \param grp The context for the elliptic curve to use. 237 * This must be initialized and have group parameters 238 * set, for example through mbedtls_ecp_group_load(). 239 * \param r The MPI context in which to store the first part 240 * the signature. This must be initialized. 241 * \param s The MPI context in which to store the second part 242 * the signature. This must be initialized. 243 * \param d The private signing key. This must be initialized 244 * and setup, for example through 245 * mbedtls_ecp_gen_privkey(). 246 * \param buf The hashed content to be signed. This must be a readable 247 * buffer of length \p blen Bytes. It may be \c NULL if 248 * \p blen is zero. 249 * \param blen The length of \p buf in Bytes. 250 * \param f_rng The RNG function. This must not be \c NULL. 251 * \param p_rng The RNG context to be passed to \p f_rng. This may be 252 * \c NULL if \p f_rng doesn't need a context parameter. 253 * \param f_rng_blind The RNG function used for blinding. This must not be 254 * \c NULL. 255 * \param p_rng_blind The RNG context to be passed to \p f_rng. This may be 256 * \c NULL if \p f_rng doesn't need a context parameter. 257 * \param rs_ctx The restart context to use. This may be \c NULL 258 * to disable restarting. If it is not \c NULL, it 259 * must point to an initialized restart context. 260 * 261 * \return \c 0 on success. 262 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 263 * operations was reached: see \c 264 * mbedtls_ecp_set_max_ops(). 265 * \return Another \c MBEDTLS_ERR_ECP_XXX, \c 266 * MBEDTLS_ERR_MPI_XXX or \c MBEDTLS_ERR_ASN1_XXX 267 * error code on failure. 268 */ 269 int mbedtls_ecdsa_sign_restartable( 270 mbedtls_ecp_group *grp, 271 mbedtls_mpi *r, mbedtls_mpi *s, 272 const mbedtls_mpi *d, 273 const unsigned char *buf, size_t blen, 274 int (*f_rng)(void *, unsigned char *, size_t), 275 void *p_rng, 276 int (*f_rng_blind)(void *, unsigned char *, size_t), 277 void *p_rng_blind, 278 mbedtls_ecdsa_restart_ctx *rs_ctx); 279 280 #endif /* !MBEDTLS_ECDSA_SIGN_ALT */ 281 282 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 283 284 /** 285 * \brief This function computes the ECDSA signature of a 286 * previously-hashed message, in a restartable way. 287 * 288 * \note This function is like \c 289 * mbedtls_ecdsa_sign_det_ext() but it can return 290 * early and restart according to the limit set with 291 * \c mbedtls_ecp_set_max_ops() to reduce blocking. 292 * 293 * \note If the bitlength of the message hash is larger 294 * than the bitlength of the group order, then the 295 * hash is truncated as defined in <em>Standards for 296 * Efficient Cryptography Group (SECG): SEC1 Elliptic 297 * Curve Cryptography</em>, section 4.1.3, step 5. 298 * 299 * \see ecp.h 300 * 301 * \param grp The context for the elliptic curve to use. 302 * This must be initialized and have group parameters 303 * set, for example through mbedtls_ecp_group_load(). 304 * \param r The MPI context in which to store the first part 305 * the signature. This must be initialized. 306 * \param s The MPI context in which to store the second part 307 * the signature. This must be initialized. 308 * \param d The private signing key. This must be initialized 309 * and setup, for example through 310 * mbedtls_ecp_gen_privkey(). 311 * \param buf The hashed content to be signed. This must be a readable 312 * buffer of length \p blen Bytes. It may be \c NULL if 313 * \p blen is zero. 314 * \param blen The length of \p buf in Bytes. 315 * \param md_alg The hash algorithm used to hash the original data. 316 * \param f_rng_blind The RNG function used for blinding. This must not be 317 * \c NULL. 318 * \param p_rng_blind The RNG context to be passed to \p f_rng_blind. This may be 319 * \c NULL if \p f_rng_blind doesn't need a context parameter. 320 * \param rs_ctx The restart context to use. This may be \c NULL 321 * to disable restarting. If it is not \c NULL, it 322 * must point to an initialized restart context. 323 * 324 * \return \c 0 on success. 325 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 326 * operations was reached: see \c 327 * mbedtls_ecp_set_max_ops(). 328 * \return Another \c MBEDTLS_ERR_ECP_XXX, \c 329 * MBEDTLS_ERR_MPI_XXX or \c MBEDTLS_ERR_ASN1_XXX 330 * error code on failure. 331 */ 332 int mbedtls_ecdsa_sign_det_restartable( 333 mbedtls_ecp_group *grp, 334 mbedtls_mpi *r, mbedtls_mpi *s, 335 const mbedtls_mpi *d, const unsigned char *buf, size_t blen, 336 mbedtls_md_type_t md_alg, 337 int (*f_rng_blind)(void *, unsigned char *, size_t), 338 void *p_rng_blind, 339 mbedtls_ecdsa_restart_ctx *rs_ctx); 340 341 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ 342 343 /** 344 * \brief This function verifies the ECDSA signature of a 345 * previously-hashed message. 346 * 347 * \note If the bitlength of the message hash is larger than the 348 * bitlength of the group order, then the hash is truncated as 349 * defined in <em>Standards for Efficient Cryptography Group 350 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 351 * 4.1.4, step 3. 352 * 353 * \see ecp.h 354 * 355 * \param grp The ECP group to use. 356 * This must be initialized and have group parameters 357 * set, for example through mbedtls_ecp_group_load(). 358 * \param buf The hashed content that was signed. This must be a readable 359 * buffer of length \p blen Bytes. It may be \c NULL if 360 * \p blen is zero. 361 * \param blen The length of \p buf in Bytes. 362 * \param Q The public key to use for verification. This must be 363 * initialized and setup. 364 * \param r The first integer of the signature. 365 * This must be initialized. 366 * \param s The second integer of the signature. 367 * This must be initialized. 368 * 369 * \return \c 0 on success. 370 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 371 * error code on failure. 372 */ 373 int mbedtls_ecdsa_verify(mbedtls_ecp_group *grp, 374 const unsigned char *buf, size_t blen, 375 const mbedtls_ecp_point *Q, const mbedtls_mpi *r, 376 const mbedtls_mpi *s); 377 378 #if !defined(MBEDTLS_ECDSA_VERIFY_ALT) 379 /** 380 * \brief This function verifies the ECDSA signature of a 381 * previously-hashed message, in a restartable manner 382 * 383 * \note If the bitlength of the message hash is larger than the 384 * bitlength of the group order, then the hash is truncated as 385 * defined in <em>Standards for Efficient Cryptography Group 386 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 387 * 4.1.4, step 3. 388 * 389 * \see ecp.h 390 * 391 * \param grp The ECP group to use. 392 * This must be initialized and have group parameters 393 * set, for example through mbedtls_ecp_group_load(). 394 * \param buf The hashed content that was signed. This must be a readable 395 * buffer of length \p blen Bytes. It may be \c NULL if 396 * \p blen is zero. 397 * \param blen The length of \p buf in Bytes. 398 * \param Q The public key to use for verification. This must be 399 * initialized and setup. 400 * \param r The first integer of the signature. 401 * This must be initialized. 402 * \param s The second integer of the signature. 403 * This must be initialized. 404 * \param rs_ctx The restart context to use. This may be \c NULL to disable 405 * restarting. If it is not \c NULL, it must point to an 406 * initialized restart context. 407 * 408 * \return \c 0 on success. 409 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 410 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 411 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 412 * error code on failure. 413 */ 414 int mbedtls_ecdsa_verify_restartable(mbedtls_ecp_group *grp, 415 const unsigned char *buf, size_t blen, 416 const mbedtls_ecp_point *Q, 417 const mbedtls_mpi *r, 418 const mbedtls_mpi *s, 419 mbedtls_ecdsa_restart_ctx *rs_ctx); 420 421 #endif /* !MBEDTLS_ECDSA_VERIFY_ALT */ 422 423 /** 424 * \brief This function computes the ECDSA signature and writes it 425 * to a buffer, serialized as defined in <em>RFC-4492: 426 * Elliptic Curve Cryptography (ECC) Cipher Suites for 427 * Transport Layer Security (TLS)</em>. 428 * 429 * \warning It is not thread-safe to use the same context in 430 * multiple threads. 431 * 432 * \note The deterministic version is used if 433 * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more 434 * information, see <em>RFC-6979: Deterministic Usage 435 * of the Digital Signature Algorithm (DSA) and Elliptic 436 * Curve Digital Signature Algorithm (ECDSA)</em>. 437 * 438 * \note If the bitlength of the message hash is larger than the 439 * bitlength of the group order, then the hash is truncated as 440 * defined in <em>Standards for Efficient Cryptography Group 441 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 442 * 4.1.3, step 5. 443 * 444 * \see ecp.h 445 * 446 * \param ctx The ECDSA context to use. This must be initialized 447 * and have a group and private key bound to it, for example 448 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair(). 449 * \param md_alg The message digest that was used to hash the message. 450 * \param hash The message hash to be signed. This must be a readable 451 * buffer of length \p hlen Bytes. 452 * \param hlen The length of the hash \p hash in Bytes. 453 * \param sig The buffer to which to write the signature. This must be a 454 * writable buffer of length at least twice as large as the 455 * size of the curve used, plus 9. For example, 73 Bytes if 456 * a 256-bit curve is used. A buffer length of 457 * #MBEDTLS_ECDSA_MAX_LEN is always safe. 458 * \param sig_size The size of the \p sig buffer in bytes. 459 * \param slen The address at which to store the actual length of 460 * the signature written. Must not be \c NULL. 461 * \param f_rng The RNG function. This must not be \c NULL if 462 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, 463 * it is used only for blinding and may be set to \c NULL, but 464 * doing so is DEPRECATED. 465 * \param p_rng The RNG context to be passed to \p f_rng. This may be 466 * \c NULL if \p f_rng is \c NULL or doesn't use a context. 467 * 468 * \return \c 0 on success. 469 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or 470 * \c MBEDTLS_ERR_ASN1_XXX error code on failure. 471 */ 472 int mbedtls_ecdsa_write_signature(mbedtls_ecdsa_context *ctx, 473 mbedtls_md_type_t md_alg, 474 const unsigned char *hash, size_t hlen, 475 unsigned char *sig, size_t sig_size, size_t *slen, 476 int (*f_rng)(void *, unsigned char *, size_t), 477 void *p_rng); 478 479 /** 480 * \brief This function computes the ECDSA signature and writes it 481 * to a buffer, in a restartable way. 482 * 483 * \see \c mbedtls_ecdsa_write_signature() 484 * 485 * \note This function is like \c mbedtls_ecdsa_write_signature() 486 * but it can return early and restart according to the limit 487 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking. 488 * 489 * \param ctx The ECDSA context to use. This must be initialized 490 * and have a group and private key bound to it, for example 491 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair(). 492 * \param md_alg The message digest that was used to hash the message. 493 * \param hash The message hash to be signed. This must be a readable 494 * buffer of length \p hlen Bytes. 495 * \param hlen The length of the hash \p hash in Bytes. 496 * \param sig The buffer to which to write the signature. This must be a 497 * writable buffer of length at least twice as large as the 498 * size of the curve used, plus 9. For example, 73 Bytes if 499 * a 256-bit curve is used. A buffer length of 500 * #MBEDTLS_ECDSA_MAX_LEN is always safe. 501 * \param sig_size The size of the \p sig buffer in bytes. 502 * \param slen The address at which to store the actual length of 503 * the signature written. Must not be \c NULL. 504 * \param f_rng The RNG function. This must not be \c NULL if 505 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, 506 * it is unused and may be set to \c NULL. 507 * \param p_rng The RNG context to be passed to \p f_rng. This may be 508 * \c NULL if \p f_rng is \c NULL or doesn't use a context. 509 * \param rs_ctx The restart context to use. This may be \c NULL to disable 510 * restarting. If it is not \c NULL, it must point to an 511 * initialized restart context. 512 * 513 * \return \c 0 on success. 514 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 515 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 516 * \return Another \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or 517 * \c MBEDTLS_ERR_ASN1_XXX error code on failure. 518 */ 519 int mbedtls_ecdsa_write_signature_restartable(mbedtls_ecdsa_context *ctx, 520 mbedtls_md_type_t md_alg, 521 const unsigned char *hash, size_t hlen, 522 unsigned char *sig, size_t sig_size, size_t *slen, 523 int (*f_rng)(void *, unsigned char *, size_t), 524 void *p_rng, 525 mbedtls_ecdsa_restart_ctx *rs_ctx); 526 527 /** 528 * \brief This function reads and verifies an ECDSA signature. 529 * 530 * \note If the bitlength of the message hash is larger than the 531 * bitlength of the group order, then the hash is truncated as 532 * defined in <em>Standards for Efficient Cryptography Group 533 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 534 * 4.1.4, step 3. 535 * 536 * \see ecp.h 537 * 538 * \param ctx The ECDSA context to use. This must be initialized 539 * and have a group and public key bound to it. 540 * \param hash The message hash that was signed. This must be a readable 541 * buffer of length \p hlen Bytes. 542 * \param hlen The size of the hash \p hash. 543 * \param sig The signature to read and verify. This must be a readable 544 * buffer of length \p slen Bytes. 545 * \param slen The size of \p sig in Bytes. 546 * 547 * \return \c 0 on success. 548 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid. 549 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid 550 * signature in \p sig, but its length is less than \p siglen. 551 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX 552 * error code on failure for any other reason. 553 */ 554 int mbedtls_ecdsa_read_signature(mbedtls_ecdsa_context *ctx, 555 const unsigned char *hash, size_t hlen, 556 const unsigned char *sig, size_t slen); 557 558 /** 559 * \brief This function reads and verifies an ECDSA signature, 560 * in a restartable way. 561 * 562 * \see \c mbedtls_ecdsa_read_signature() 563 * 564 * \note This function is like \c mbedtls_ecdsa_read_signature() 565 * but it can return early and restart according to the limit 566 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking. 567 * 568 * \param ctx The ECDSA context to use. This must be initialized 569 * and have a group and public key bound to it. 570 * \param hash The message hash that was signed. This must be a readable 571 * buffer of length \p hlen Bytes. 572 * \param hlen The size of the hash \p hash. 573 * \param sig The signature to read and verify. This must be a readable 574 * buffer of length \p slen Bytes. 575 * \param slen The size of \p sig in Bytes. 576 * \param rs_ctx The restart context to use. This may be \c NULL to disable 577 * restarting. If it is not \c NULL, it must point to an 578 * initialized restart context. 579 * 580 * \return \c 0 on success. 581 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid. 582 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid 583 * signature in \p sig, but its length is less than \p siglen. 584 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 585 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 586 * \return Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX 587 * error code on failure for any other reason. 588 */ 589 int mbedtls_ecdsa_read_signature_restartable(mbedtls_ecdsa_context *ctx, 590 const unsigned char *hash, size_t hlen, 591 const unsigned char *sig, size_t slen, 592 mbedtls_ecdsa_restart_ctx *rs_ctx); 593 594 /** 595 * \brief This function generates an ECDSA keypair on the given curve. 596 * 597 * \see ecp.h 598 * 599 * \param ctx The ECDSA context to store the keypair in. 600 * This must be initialized. 601 * \param gid The elliptic curve to use. One of the various 602 * \c MBEDTLS_ECP_DP_XXX macros depending on configuration. 603 * \param f_rng The RNG function to use. This must not be \c NULL. 604 * \param p_rng The RNG context to be passed to \p f_rng. This may be 605 * \c NULL if \p f_rng doesn't need a context argument. 606 * 607 * \return \c 0 on success. 608 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. 609 */ 610 int mbedtls_ecdsa_genkey(mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid, 611 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng); 612 613 /** 614 * \brief This function sets up an ECDSA context from an EC key pair. 615 * 616 * \see ecp.h 617 * 618 * \param ctx The ECDSA context to setup. This must be initialized. 619 * \param key The EC key to use. This must be initialized and hold 620 * a private-public key pair or a public key. In the former 621 * case, the ECDSA context may be used for signature creation 622 * and verification after this call. In the latter case, it 623 * may be used for signature verification. 624 * 625 * \return \c 0 on success. 626 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. 627 */ 628 int mbedtls_ecdsa_from_keypair(mbedtls_ecdsa_context *ctx, 629 const mbedtls_ecp_keypair *key); 630 631 /** 632 * \brief This function initializes an ECDSA context. 633 * 634 * \param ctx The ECDSA context to initialize. 635 * This must not be \c NULL. 636 */ 637 void mbedtls_ecdsa_init(mbedtls_ecdsa_context *ctx); 638 639 /** 640 * \brief This function frees an ECDSA context. 641 * 642 * \param ctx The ECDSA context to free. This may be \c NULL, 643 * in which case this function does nothing. If it 644 * is not \c NULL, it must be initialized. 645 */ 646 void mbedtls_ecdsa_free(mbedtls_ecdsa_context *ctx); 647 648 #if defined(MBEDTLS_ECP_RESTARTABLE) 649 /** 650 * \brief Initialize a restart context. 651 * 652 * \param ctx The restart context to initialize. 653 * This must not be \c NULL. 654 */ 655 void mbedtls_ecdsa_restart_init(mbedtls_ecdsa_restart_ctx *ctx); 656 657 /** 658 * \brief Free the components of a restart context. 659 * 660 * \param ctx The restart context to free. This may be \c NULL, 661 * in which case this function does nothing. If it 662 * is not \c NULL, it must be initialized. 663 */ 664 void mbedtls_ecdsa_restart_free(mbedtls_ecdsa_restart_ctx *ctx); 665 #endif /* MBEDTLS_ECP_RESTARTABLE */ 666 667 #ifdef __cplusplus 668 } 669 #endif 670 671 #endif /* ecdsa.h */ 672
