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