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