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 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 MBEDTLS_PRIVATE(ecp); /*!< base context for ECP restart and 108 shared administrative info */ 109 mbedtls_ecdsa_restart_ver_ctx *MBEDTLS_PRIVATE(ver); /*!< ecdsa_verify() sub-context */ 110 mbedtls_ecdsa_restart_sig_ctx *MBEDTLS_PRIVATE(sig); /*!< ecdsa_sign() sub-context */ 111 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 112 mbedtls_ecdsa_restart_det_ctx *MBEDTLS_PRIVATE(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 checks whether a given group can be used 125 * for ECDSA. 126 * 127 * \param gid The ECP group ID to check. 128 * 129 * \return \c 1 if the group can be used, \c 0 otherwise 130 */ 131 int mbedtls_ecdsa_can_do( mbedtls_ecp_group_id gid ); 132 133 /** 134 * \brief This function computes the ECDSA signature of a 135 * previously-hashed message. 136 * 137 * \note The deterministic version implemented in 138 * mbedtls_ecdsa_sign_det_ext() is usually preferred. 139 * 140 * \note If the bitlength of the message hash is larger than the 141 * bitlength of the group order, then the hash is truncated 142 * as defined in <em>Standards for Efficient Cryptography Group 143 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 144 * 4.1.3, step 5. 145 * 146 * \see ecp.h 147 * 148 * \param grp The context for the elliptic curve to use. 149 * This must be initialized and have group parameters 150 * set, for example through mbedtls_ecp_group_load(). 151 * \param r The MPI context in which to store the first part 152 * the signature. This must be initialized. 153 * \param s The MPI context in which to store the second part 154 * the signature. This must be initialized. 155 * \param d The private signing key. This must be initialized. 156 * \param buf The content to be signed. This is usually the hash of 157 * the original data to be signed. This must be a readable 158 * buffer of length \p blen Bytes. It may be \c NULL if 159 * \p blen is zero. 160 * \param blen The length of \p buf in Bytes. 161 * \param f_rng The RNG function. This must not be \c NULL. 162 * \param p_rng The RNG context to be passed to \p f_rng. This may be 163 * \c NULL if \p f_rng doesn't need a context parameter. 164 * 165 * \return \c 0 on success. 166 * \return An \c MBEDTLS_ERR_ECP_XXX 167 * or \c MBEDTLS_MPI_XXX error code on failure. 168 */ 169 int mbedtls_ecdsa_sign( mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, 170 const mbedtls_mpi *d, const unsigned char *buf, size_t blen, 171 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 172 173 #if defined(MBEDTLS_ECDSA_DETERMINISTIC) 174 /** 175 * \brief This function computes the ECDSA signature of a 176 * previously-hashed message, deterministic version. 177 * 178 * For more information, see <em>RFC-6979: Deterministic 179 * Usage of the Digital Signature Algorithm (DSA) and Elliptic 180 * Curve Digital Signature Algorithm (ECDSA)</em>. 181 * 182 * \note If the bitlength of the message hash is larger than the 183 * bitlength of the group order, then the hash is truncated as 184 * defined in <em>Standards for Efficient Cryptography Group 185 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 186 * 4.1.3, step 5. 187 * 188 * \see ecp.h 189 * 190 * \param grp The context for the elliptic curve to use. 191 * This must be initialized and have group parameters 192 * set, for example through mbedtls_ecp_group_load(). 193 * \param r The MPI context in which to store the first part 194 * the signature. This must be initialized. 195 * \param s The MPI context in which to store the second part 196 * the signature. This must be initialized. 197 * \param d The private signing key. This must be initialized 198 * and setup, for example through mbedtls_ecp_gen_privkey(). 199 * \param buf The hashed content to be signed. This must be a readable 200 * buffer of length \p blen Bytes. It may be \c NULL if 201 * \p blen is zero. 202 * \param blen The length of \p buf in Bytes. 203 * \param md_alg The hash algorithm used to hash the original data. 204 * \param f_rng_blind The RNG function used for blinding. This must not be 205 * \c NULL. 206 * \param p_rng_blind The RNG context to be passed to \p f_rng. This may be 207 * \c NULL if \p f_rng doesn't need a context parameter. 208 * 209 * \return \c 0 on success. 210 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 211 * error code on failure. 212 */ 213 int mbedtls_ecdsa_sign_det_ext( mbedtls_ecp_group *grp, mbedtls_mpi *r, 214 mbedtls_mpi *s, const mbedtls_mpi *d, 215 const unsigned char *buf, size_t blen, 216 mbedtls_md_type_t md_alg, 217 int (*f_rng_blind)(void *, unsigned char *, size_t), 218 void *p_rng_blind ); 219 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */ 220 221 /** 222 * \brief This function verifies the ECDSA signature of a 223 * previously-hashed message. 224 * 225 * \note If the bitlength of the message hash is larger than the 226 * bitlength of the group order, then the hash is truncated as 227 * defined in <em>Standards for Efficient Cryptography Group 228 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 229 * 4.1.4, step 3. 230 * 231 * \see ecp.h 232 * 233 * \param grp The ECP group to use. 234 * This must be initialized and have group parameters 235 * set, for example through mbedtls_ecp_group_load(). 236 * \param buf The hashed content that was signed. This must be a readable 237 * buffer of length \p blen Bytes. It may be \c NULL if 238 * \p blen is zero. 239 * \param blen The length of \p buf in Bytes. 240 * \param Q The public key to use for verification. This must be 241 * initialized and setup. 242 * \param r The first integer of the signature. 243 * This must be initialized. 244 * \param s The second integer of the signature. 245 * This must be initialized. 246 * 247 * \return \c 0 on success. 248 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the signature 249 * is invalid. 250 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_MPI_XXX 251 * error code on failure for any other reason. 252 */ 253 int mbedtls_ecdsa_verify( mbedtls_ecp_group *grp, 254 const unsigned char *buf, size_t blen, 255 const mbedtls_ecp_point *Q, const mbedtls_mpi *r, 256 const mbedtls_mpi *s); 257 258 /** 259 * \brief This function computes the ECDSA signature and writes it 260 * to a buffer, serialized as defined in <em>RFC-4492: 261 * Elliptic Curve Cryptography (ECC) Cipher Suites for 262 * Transport Layer Security (TLS)</em>. 263 * 264 * \warning It is not thread-safe to use the same context in 265 * multiple threads. 266 * 267 * \note The deterministic version is used if 268 * #MBEDTLS_ECDSA_DETERMINISTIC is defined. For more 269 * information, see <em>RFC-6979: Deterministic Usage 270 * of the Digital Signature Algorithm (DSA) and Elliptic 271 * Curve Digital Signature Algorithm (ECDSA)</em>. 272 * 273 * \note If the bitlength of the message hash is larger than the 274 * bitlength of the group order, then the hash is truncated as 275 * defined in <em>Standards for Efficient Cryptography Group 276 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 277 * 4.1.3, step 5. 278 * 279 * \see ecp.h 280 * 281 * \param ctx The ECDSA context to use. This must be initialized 282 * and have a group and private key bound to it, for example 283 * via mbedtls_ecdsa_genkey() or mbedtls_ecdsa_from_keypair(). 284 * \param md_alg The message digest that was used to hash the message. 285 * \param hash The message hash to be signed. This must be a readable 286 * buffer of length \p blen Bytes. 287 * \param hlen The length of the hash \p hash in Bytes. 288 * \param sig The buffer to which to write the signature. This must be a 289 * writable buffer of length at least twice as large as the 290 * size of the curve used, plus 9. For example, 73 Bytes if 291 * a 256-bit curve is used. A buffer length of 292 * #MBEDTLS_ECDSA_MAX_LEN is always safe. 293 * \param sig_size The size of the \p sig buffer in bytes. 294 * \param slen The address at which to store the actual length of 295 * the signature written. Must not be \c NULL. 296 * \param f_rng The RNG function. This must not be \c NULL if 297 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, 298 * it is used only for blinding and may be set to \c NULL, but 299 * doing so is DEPRECATED. 300 * \param p_rng The RNG context to be passed to \p f_rng. This may be 301 * \c NULL if \p f_rng is \c NULL or doesn't use a context. 302 * 303 * \return \c 0 on success. 304 * \return An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or 305 * \c MBEDTLS_ERR_ASN1_XXX error code on failure. 306 */ 307 int mbedtls_ecdsa_write_signature( mbedtls_ecdsa_context *ctx, 308 mbedtls_md_type_t md_alg, 309 const unsigned char *hash, size_t hlen, 310 unsigned char *sig, size_t sig_size, size_t *slen, 311 int (*f_rng)(void *, unsigned char *, size_t), 312 void *p_rng ); 313 314 /** 315 * \brief This function computes the ECDSA signature and writes it 316 * to a buffer, in a restartable way. 317 * 318 * \see \c mbedtls_ecdsa_write_signature() 319 * 320 * \note This function is like \c mbedtls_ecdsa_write_signature() 321 * but it can return early and restart according to the limit 322 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking. 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 sig_size The size of the \p sig buffer in bytes. 337 * \param slen The address at which to store the actual length of 338 * the signature written. Must not be \c NULL. 339 * \param f_rng The RNG function. This must not be \c NULL if 340 * #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise, 341 * it is unused and may be set to \c NULL. 342 * \param p_rng The RNG context to be passed to \p f_rng. This may be 343 * \c NULL if \p f_rng is \c NULL or doesn't use a context. 344 * \param rs_ctx The restart context to use. This may be \c NULL to disable 345 * restarting. If it is not \c NULL, it must point to an 346 * initialized restart context. 347 * 348 * \return \c 0 on success. 349 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 350 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 351 * \return Another \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or 352 * \c MBEDTLS_ERR_ASN1_XXX error code on failure. 353 */ 354 int mbedtls_ecdsa_write_signature_restartable( mbedtls_ecdsa_context *ctx, 355 mbedtls_md_type_t md_alg, 356 const unsigned char *hash, size_t hlen, 357 unsigned char *sig, size_t sig_size, size_t *slen, 358 int (*f_rng)(void *, unsigned char *, size_t), 359 void *p_rng, 360 mbedtls_ecdsa_restart_ctx *rs_ctx ); 361 362 /** 363 * \brief This function reads and verifies an ECDSA signature. 364 * 365 * \note If the bitlength of the message hash is larger than the 366 * bitlength of the group order, then the hash is truncated as 367 * defined in <em>Standards for Efficient Cryptography Group 368 * (SECG): SEC1 Elliptic Curve Cryptography</em>, section 369 * 4.1.4, step 3. 370 * 371 * \see ecp.h 372 * 373 * \param ctx The ECDSA context to use. This must be initialized 374 * and have a group and public key bound to it. 375 * \param hash The message hash that was signed. This must be a readable 376 * buffer of length \p size Bytes. 377 * \param hlen The size of the hash \p hash. 378 * \param sig The signature to read and verify. This must be a readable 379 * buffer of length \p slen Bytes. 380 * \param slen The size of \p sig in Bytes. 381 * 382 * \return \c 0 on success. 383 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid. 384 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid 385 * signature in \p sig, but its length is less than \p siglen. 386 * \return An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX 387 * error code on failure for any other reason. 388 */ 389 int mbedtls_ecdsa_read_signature( mbedtls_ecdsa_context *ctx, 390 const unsigned char *hash, size_t hlen, 391 const unsigned char *sig, size_t slen ); 392 393 /** 394 * \brief This function reads and verifies an ECDSA signature, 395 * in a restartable way. 396 * 397 * \see \c mbedtls_ecdsa_read_signature() 398 * 399 * \note This function is like \c mbedtls_ecdsa_read_signature() 400 * but it can return early and restart according to the limit 401 * set with \c mbedtls_ecp_set_max_ops() to reduce blocking. 402 * 403 * \param ctx The ECDSA context to use. This must be initialized 404 * and have a group and public key bound to it. 405 * \param hash The message hash that was signed. This must be a readable 406 * buffer of length \p size Bytes. 407 * \param hlen The size of the hash \p hash. 408 * \param sig The signature to read and verify. This must be a readable 409 * buffer of length \p slen Bytes. 410 * \param slen The size of \p sig in Bytes. 411 * \param rs_ctx The restart context to use. This may be \c NULL to disable 412 * restarting. If it is not \c NULL, it must point to an 413 * initialized restart context. 414 * 415 * \return \c 0 on success. 416 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid. 417 * \return #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid 418 * signature in \p sig, but its length is less than \p siglen. 419 * \return #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of 420 * operations was reached: see \c mbedtls_ecp_set_max_ops(). 421 * \return Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX 422 * error code on failure for any other reason. 423 */ 424 int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx, 425 const unsigned char *hash, size_t hlen, 426 const unsigned char *sig, size_t slen, 427 mbedtls_ecdsa_restart_ctx *rs_ctx ); 428 429 /** 430 * \brief This function generates an ECDSA keypair on the given curve. 431 * 432 * \see ecp.h 433 * 434 * \param ctx The ECDSA context to store the keypair in. 435 * This must be initialized. 436 * \param gid The elliptic curve to use. One of the various 437 * \c MBEDTLS_ECP_DP_XXX macros depending on configuration. 438 * \param f_rng The RNG function to use. This must not be \c NULL. 439 * \param p_rng The RNG context to be passed to \p f_rng. This may be 440 * \c NULL if \p f_rng doesn't need a context argument. 441 * 442 * \return \c 0 on success. 443 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. 444 */ 445 int mbedtls_ecdsa_genkey( mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid, 446 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 447 448 /** 449 * \brief This function sets up an ECDSA context from an EC key pair. 450 * 451 * \see ecp.h 452 * 453 * \param ctx The ECDSA context to setup. This must be initialized. 454 * \param key The EC key to use. This must be initialized and hold 455 * a private-public key pair or a public key. In the former 456 * case, the ECDSA context may be used for signature creation 457 * and verification after this call. In the latter case, it 458 * may be used for signature verification. 459 * 460 * \return \c 0 on success. 461 * \return An \c MBEDTLS_ERR_ECP_XXX code on failure. 462 */ 463 int mbedtls_ecdsa_from_keypair( mbedtls_ecdsa_context *ctx, 464 const mbedtls_ecp_keypair *key ); 465 466 /** 467 * \brief This function initializes an ECDSA context. 468 * 469 * \param ctx The ECDSA context to initialize. 470 * This must not be \c NULL. 471 */ 472 void mbedtls_ecdsa_init( mbedtls_ecdsa_context *ctx ); 473 474 /** 475 * \brief This function frees an ECDSA context. 476 * 477 * \param ctx The ECDSA context to free. This may be \c NULL, 478 * in which case this function does nothing. If it 479 * is not \c NULL, it must be initialized. 480 */ 481 void mbedtls_ecdsa_free( mbedtls_ecdsa_context *ctx ); 482 483 #if defined(MBEDTLS_ECP_RESTARTABLE) 484 /** 485 * \brief Initialize a restart context. 486 * 487 * \param ctx The restart context to initialize. 488 * This must not be \c NULL. 489 */ 490 void mbedtls_ecdsa_restart_init( mbedtls_ecdsa_restart_ctx *ctx ); 491 492 /** 493 * \brief Free the components of a restart context. 494 * 495 * \param ctx The restart context to free. This may be \c NULL, 496 * in which case this function does nothing. If it 497 * is not \c NULL, it must be initialized. 498 */ 499 void mbedtls_ecdsa_restart_free( mbedtls_ecdsa_restart_ctx *ctx ); 500 #endif /* MBEDTLS_ECP_RESTARTABLE */ 501 502 #ifdef __cplusplus 503 } 504 #endif 505 506 #endif /* ecdsa.h */ 507