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