1 /** 2 * \file ecp.h 3 * 4 * \brief Elliptic curves over GF(p) 5 */ 6 /* 7 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved 8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 9 * 10 * This file is provided under the Apache License 2.0, or the 11 * GNU General Public License v2.0 or later. 12 * 13 * ********** 14 * Apache License 2.0: 15 * 16 * Licensed under the Apache License, Version 2.0 (the "License"); you may 17 * not use this file except in compliance with the License. 18 * You may obtain a copy of the License at 19 * 20 * http://www.apache.org/licenses/LICENSE-2.0 21 * 22 * Unless required by applicable law or agreed to in writing, software 23 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 24 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 * See the License for the specific language governing permissions and 26 * limitations under the License. 27 * 28 * ********** 29 * 30 * ********** 31 * GNU General Public License v2.0 or later: 32 * 33 * This program is free software; you can redistribute it and/or modify 34 * it under the terms of the GNU General Public License as published by 35 * the Free Software Foundation; either version 2 of the License, or 36 * (at your option) any later version. 37 * 38 * This program is distributed in the hope that it will be useful, 39 * but WITHOUT ANY WARRANTY; without even the implied warranty of 40 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 41 * GNU General Public License for more details. 42 * 43 * You should have received a copy of the GNU General Public License along 44 * with this program; if not, write to the Free Software Foundation, Inc., 45 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 46 * 47 * ********** 48 * 49 * This file is part of mbed TLS (https://tls.mbed.org) 50 */ 51 #ifndef MBEDTLS_ECP_H 52 #define MBEDTLS_ECP_H 53 54 #if !defined(MBEDTLS_CONFIG_FILE) 55 #include "config.h" 56 #else 57 #include MBEDTLS_CONFIG_FILE 58 #endif 59 60 #include "bignum.h" 61 62 /* 63 * ECP error codes 64 */ 65 #define MBEDTLS_ERR_ECP_BAD_INPUT_DATA -0x4F80 /**< Bad input parameters to function. */ 66 #define MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL -0x4F00 /**< The buffer is too small to write to. */ 67 #define MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE -0x4E80 /**< Requested curve not available. */ 68 #define MBEDTLS_ERR_ECP_VERIFY_FAILED -0x4E00 /**< The signature is not valid. */ 69 #define MBEDTLS_ERR_ECP_ALLOC_FAILED -0x4D80 /**< Memory allocation failed. */ 70 #define MBEDTLS_ERR_ECP_RANDOM_FAILED -0x4D00 /**< Generation of random value, such as (ephemeral) key, failed. */ 71 #define MBEDTLS_ERR_ECP_INVALID_KEY -0x4C80 /**< Invalid private or public key. */ 72 #define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH -0x4C00 /**< The buffer contains a valid signature followed by more data. */ 73 #define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED -0x4B80 /**< ECP hardware accelerator failed. */ 74 75 #if !defined(MBEDTLS_ECP_ALT) 76 /* 77 * default mbed TLS elliptic curve arithmetic implementation 78 * 79 * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an 80 * alternative implementation for the whole module and it will replace this 81 * one.) 82 */ 83 84 #ifdef __cplusplus 85 extern "C" { 86 #endif 87 88 /** 89 * Domain parameters (curve, subgroup and generator) identifiers. 90 * 91 * Only curves over prime fields are supported. 92 * 93 * \warning This library does not support validation of arbitrary domain 94 * parameters. Therefore, only well-known domain parameters from trusted 95 * sources should be used. See mbedtls_ecp_group_load(). 96 */ 97 typedef enum 98 { 99 MBEDTLS_ECP_DP_NONE = 0, 100 MBEDTLS_ECP_DP_SECP192R1, /*!< 192-bits NIST curve */ 101 MBEDTLS_ECP_DP_SECP224R1, /*!< 224-bits NIST curve */ 102 MBEDTLS_ECP_DP_SECP256R1, /*!< 256-bits NIST curve */ 103 MBEDTLS_ECP_DP_SECP384R1, /*!< 384-bits NIST curve */ 104 MBEDTLS_ECP_DP_SECP521R1, /*!< 521-bits NIST curve */ 105 MBEDTLS_ECP_DP_BP256R1, /*!< 256-bits Brainpool curve */ 106 MBEDTLS_ECP_DP_BP384R1, /*!< 384-bits Brainpool curve */ 107 MBEDTLS_ECP_DP_BP512R1, /*!< 512-bits Brainpool curve */ 108 MBEDTLS_ECP_DP_CURVE25519, /*!< Curve25519 */ 109 MBEDTLS_ECP_DP_SECP192K1, /*!< 192-bits "Koblitz" curve */ 110 MBEDTLS_ECP_DP_SECP224K1, /*!< 224-bits "Koblitz" curve */ 111 MBEDTLS_ECP_DP_SECP256K1, /*!< 256-bits "Koblitz" curve */ 112 } mbedtls_ecp_group_id; 113 114 /** 115 * Number of supported curves (plus one for NONE). 116 * 117 * (Montgomery curves excluded for now.) 118 */ 119 #define MBEDTLS_ECP_DP_MAX 12 120 121 /** 122 * Curve information for use by other modules 123 */ 124 typedef struct 125 { 126 mbedtls_ecp_group_id grp_id; /*!< Internal identifier */ 127 uint16_t tls_id; /*!< TLS NamedCurve identifier */ 128 uint16_t bit_size; /*!< Curve size in bits */ 129 const char *name; /*!< Human-friendly name */ 130 } mbedtls_ecp_curve_info; 131 132 /** 133 * \brief ECP point structure (jacobian coordinates) 134 * 135 * \note All functions expect and return points satisfying 136 * the following condition: Z == 0 or Z == 1. (Other 137 * values of Z are used by internal functions only.) 138 * The point is zero, or "at infinity", if Z == 0. 139 * Otherwise, X and Y are its standard (affine) coordinates. 140 */ 141 typedef struct 142 { 143 mbedtls_mpi X; /*!< the point's X coordinate */ 144 mbedtls_mpi Y; /*!< the point's Y coordinate */ 145 mbedtls_mpi Z; /*!< the point's Z coordinate */ 146 } 147 mbedtls_ecp_point; 148 149 /** 150 * \brief ECP group structure 151 * 152 * We consider two types of curves equations: 153 * 1. Short Weierstrass y^2 = x^3 + A x + B mod P (SEC1 + RFC 4492) 154 * 2. Montgomery, y^2 = x^3 + A x^2 + x mod P (Curve25519 + draft) 155 * In both cases, a generator G for a prime-order subgroup is fixed. In the 156 * short weierstrass, this subgroup is actually the whole curve, and its 157 * cardinal is denoted by N. 158 * 159 * In the case of Short Weierstrass curves, our code requires that N is an odd 160 * prime. (Use odd in mbedtls_ecp_mul() and prime in mbedtls_ecdsa_sign() for blinding.) 161 * 162 * In the case of Montgomery curves, we don't store A but (A + 2) / 4 which is 163 * the quantity actually used in the formulas. Also, nbits is not the size of N 164 * but the required size for private keys. 165 * 166 * If modp is NULL, reduction modulo P is done using a generic algorithm. 167 * Otherwise, it must point to a function that takes an mbedtls_mpi in the range 168 * 0..2^(2*pbits)-1 and transforms it in-place in an integer of little more 169 * than pbits, so that the integer may be efficiently brought in the 0..P-1 170 * range by a few additions or substractions. It must return 0 on success and 171 * non-zero on failure. 172 */ 173 typedef struct 174 { 175 mbedtls_ecp_group_id id; /*!< internal group identifier */ 176 mbedtls_mpi P; /*!< prime modulus of the base field */ 177 mbedtls_mpi A; /*!< 1. A in the equation, or 2. (A + 2) / 4 */ 178 mbedtls_mpi B; /*!< 1. B in the equation, or 2. unused */ 179 mbedtls_ecp_point G; /*!< generator of the (sub)group used */ 180 mbedtls_mpi N; /*!< 1. the order of G, or 2. unused */ 181 size_t pbits; /*!< number of bits in P */ 182 size_t nbits; /*!< number of bits in 1. P, or 2. private keys */ 183 unsigned int h; /*!< internal: 1 if the constants are static */ 184 int (*modp)(mbedtls_mpi *); /*!< function for fast reduction mod P */ 185 int (*t_pre)(mbedtls_ecp_point *, void *); /*!< unused */ 186 int (*t_post)(mbedtls_ecp_point *, void *); /*!< unused */ 187 void *t_data; /*!< unused */ 188 mbedtls_ecp_point *T; /*!< pre-computed points for ecp_mul_comb() */ 189 size_t T_size; /*!< number for pre-computed points */ 190 } 191 mbedtls_ecp_group; 192 193 /** 194 * \brief ECP key pair structure 195 * 196 * A generic key pair that could be used for ECDSA, fixed ECDH, etc. 197 * 198 * \note Members purposefully in the same order as struc mbedtls_ecdsa_context. 199 */ 200 typedef struct 201 { 202 mbedtls_ecp_group grp; /*!< Elliptic curve and base point */ 203 mbedtls_mpi d; /*!< our secret value */ 204 mbedtls_ecp_point Q; /*!< our public value */ 205 } 206 mbedtls_ecp_keypair; 207 208 /** 209 * \name SECTION: Module settings 210 * 211 * The configuration options you can set for this module are in this section. 212 * Either change them in config.h or define them on the compiler command line. 213 * \{ 214 */ 215 216 #if !defined(MBEDTLS_ECP_MAX_BITS) 217 /** 218 * Maximum size of the groups (that is, of N and P) 219 */ 220 #define MBEDTLS_ECP_MAX_BITS 521 /**< Maximum bit size of groups */ 221 #endif 222 223 #define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 ) 224 #define MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 ) 225 226 #if !defined(MBEDTLS_ECP_WINDOW_SIZE) 227 /* 228 * Maximum "window" size used for point multiplication. 229 * Default: 6. 230 * Minimum value: 2. Maximum value: 7. 231 * 232 * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) ) 233 * points used for point multiplication. This value is directly tied to EC 234 * peak memory usage, so decreasing it by one should roughly cut memory usage 235 * by two (if large curves are in use). 236 * 237 * Reduction in size may reduce speed, but larger curves are impacted first. 238 * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1): 239 * w-size: 6 5 4 3 2 240 * 521 145 141 135 120 97 241 * 384 214 209 198 177 146 242 * 256 320 320 303 262 226 243 244 * 224 475 475 453 398 342 245 * 192 640 640 633 587 476 246 */ 247 #define MBEDTLS_ECP_WINDOW_SIZE 6 /**< Maximum window size used */ 248 #endif /* MBEDTLS_ECP_WINDOW_SIZE */ 249 250 #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM) 251 /* 252 * Trade memory for speed on fixed-point multiplication. 253 * 254 * This speeds up repeated multiplication of the generator (that is, the 255 * multiplication in ECDSA signatures, and half of the multiplications in 256 * ECDSA verification and ECDHE) by a factor roughly 3 to 4. 257 * 258 * The cost is increasing EC peak memory usage by a factor roughly 2. 259 * 260 * Change this value to 0 to reduce peak memory usage. 261 */ 262 #define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up */ 263 #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */ 264 265 /* \} name SECTION: Module settings */ 266 267 /* 268 * Point formats, from RFC 4492's enum ECPointFormat 269 */ 270 #define MBEDTLS_ECP_PF_UNCOMPRESSED 0 /**< Uncompressed point format */ 271 #define MBEDTLS_ECP_PF_COMPRESSED 1 /**< Compressed point format */ 272 273 /* 274 * Some other constants from RFC 4492 275 */ 276 #define MBEDTLS_ECP_TLS_NAMED_CURVE 3 /**< ECCurveType's named_curve */ 277 278 /** 279 * \brief Get the list of supported curves in order of preferrence 280 * (full information) 281 * 282 * \return A statically allocated array, the last entry is 0. 283 */ 284 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_list( void ); 285 286 /** 287 * \brief Get the list of supported curves in order of preferrence 288 * (grp_id only) 289 * 290 * \return A statically allocated array, 291 * terminated with MBEDTLS_ECP_DP_NONE. 292 */ 293 const mbedtls_ecp_group_id *mbedtls_ecp_grp_id_list( void ); 294 295 /** 296 * \brief Get curve information from an internal group identifier 297 * 298 * \param grp_id A MBEDTLS_ECP_DP_XXX value 299 * 300 * \return The associated curve information or NULL 301 */ 302 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_grp_id( mbedtls_ecp_group_id grp_id ); 303 304 /** 305 * \brief Get curve information from a TLS NamedCurve value 306 * 307 * \param tls_id A MBEDTLS_ECP_DP_XXX value 308 * 309 * \return The associated curve information or NULL 310 */ 311 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_tls_id( uint16_t tls_id ); 312 313 /** 314 * \brief Get curve information from a human-readable name 315 * 316 * \param name The name 317 * 318 * \return The associated curve information or NULL 319 */ 320 const mbedtls_ecp_curve_info *mbedtls_ecp_curve_info_from_name( const char *name ); 321 322 /** 323 * \brief Initialize a point (as zero) 324 */ 325 void mbedtls_ecp_point_init( mbedtls_ecp_point *pt ); 326 327 /** 328 * \brief Initialize a group (to something meaningless) 329 */ 330 void mbedtls_ecp_group_init( mbedtls_ecp_group *grp ); 331 332 /** 333 * \brief Initialize a key pair (as an invalid one) 334 */ 335 void mbedtls_ecp_keypair_init( mbedtls_ecp_keypair *key ); 336 337 /** 338 * \brief Free the components of a point 339 */ 340 void mbedtls_ecp_point_free( mbedtls_ecp_point *pt ); 341 342 /** 343 * \brief Free the components of an ECP group 344 */ 345 void mbedtls_ecp_group_free( mbedtls_ecp_group *grp ); 346 347 /** 348 * \brief Free the components of a key pair 349 */ 350 void mbedtls_ecp_keypair_free( mbedtls_ecp_keypair *key ); 351 352 /** 353 * \brief Copy the contents of point Q into P 354 * 355 * \param P Destination point 356 * \param Q Source point 357 * 358 * \return 0 if successful, 359 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed 360 */ 361 int mbedtls_ecp_copy( mbedtls_ecp_point *P, const mbedtls_ecp_point *Q ); 362 363 /** 364 * \brief Copy the contents of a group object 365 * 366 * \param dst Destination group 367 * \param src Source group 368 * 369 * \return 0 if successful, 370 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed 371 */ 372 int mbedtls_ecp_group_copy( mbedtls_ecp_group *dst, const mbedtls_ecp_group *src ); 373 374 /** 375 * \brief Set a point to zero 376 * 377 * \param pt Destination point 378 * 379 * \return 0 if successful, 380 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed 381 */ 382 int mbedtls_ecp_set_zero( mbedtls_ecp_point *pt ); 383 384 /** 385 * \brief Tell if a point is zero 386 * 387 * \param pt Point to test 388 * 389 * \return 1 if point is zero, 0 otherwise 390 */ 391 int mbedtls_ecp_is_zero( mbedtls_ecp_point *pt ); 392 393 /** 394 * \brief Compare two points 395 * 396 * \note This assumes the points are normalized. Otherwise, 397 * they may compare as "not equal" even if they are. 398 * 399 * \param P First point to compare 400 * \param Q Second point to compare 401 * 402 * \return 0 if the points are equal, 403 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA otherwise 404 */ 405 int mbedtls_ecp_point_cmp( const mbedtls_ecp_point *P, 406 const mbedtls_ecp_point *Q ); 407 408 /** 409 * \brief Import a non-zero point from two ASCII strings 410 * 411 * \param P Destination point 412 * \param radix Input numeric base 413 * \param x First affine coordinate as a null-terminated string 414 * \param y Second affine coordinate as a null-terminated string 415 * 416 * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code 417 */ 418 int mbedtls_ecp_point_read_string( mbedtls_ecp_point *P, int radix, 419 const char *x, const char *y ); 420 421 /** 422 * \brief Export a point into unsigned binary data 423 * 424 * \param grp Group to which the point should belong 425 * \param P Point to export 426 * \param format Point format, should be a MBEDTLS_ECP_PF_XXX macro 427 * \param olen Length of the actual output 428 * \param buf Output buffer 429 * \param buflen Length of the output buffer 430 * 431 * \return 0 if successful, 432 * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA 433 * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL 434 */ 435 int mbedtls_ecp_point_write_binary( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *P, 436 int format, size_t *olen, 437 unsigned char *buf, size_t buflen ); 438 439 /** 440 * \brief Import a point from unsigned binary data 441 * 442 * \param grp Group to which the point should belong 443 * \param P Point to import 444 * \param buf Input buffer 445 * \param ilen Actual length of input 446 * 447 * \return 0 if successful, 448 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid, 449 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, 450 * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE if the point format 451 * is not implemented. 452 * 453 * \note This function does NOT check that the point actually 454 * belongs to the given group, see mbedtls_ecp_check_pubkey() for 455 * that. 456 */ 457 int mbedtls_ecp_point_read_binary( const mbedtls_ecp_group *grp, mbedtls_ecp_point *P, 458 const unsigned char *buf, size_t ilen ); 459 460 /** 461 * \brief Import a point from a TLS ECPoint record 462 * 463 * \param grp ECP group used 464 * \param pt Destination point 465 * \param buf $(Start of input buffer) 466 * \param len Buffer length 467 * 468 * \note buf is updated to point right after the ECPoint on exit 469 * 470 * \return 0 if successful, 471 * MBEDTLS_ERR_MPI_XXX if initialization failed 472 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid 473 */ 474 int mbedtls_ecp_tls_read_point( const mbedtls_ecp_group *grp, mbedtls_ecp_point *pt, 475 const unsigned char **buf, size_t len ); 476 477 /** 478 * \brief Export a point as a TLS ECPoint record 479 * 480 * \param grp ECP group used 481 * \param pt Point to export 482 * \param format Export format 483 * \param olen length of data written 484 * \param buf Buffer to write to 485 * \param blen Buffer length 486 * 487 * \return 0 if successful, 488 * or MBEDTLS_ERR_ECP_BAD_INPUT_DATA 489 * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL 490 */ 491 int mbedtls_ecp_tls_write_point( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt, 492 int format, size_t *olen, 493 unsigned char *buf, size_t blen ); 494 495 /** 496 * \brief Set a group using well-known domain parameters 497 * 498 * \param grp Destination group 499 * \param id Index in the list of well-known domain parameters 500 * 501 * \return 0 if successful, 502 * MBEDTLS_ERR_MPI_XXX if initialization failed 503 * MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE for unkownn groups 504 * 505 * \note Index should be a value of RFC 4492's enum NamedCurve, 506 * usually in the form of a MBEDTLS_ECP_DP_XXX macro. 507 */ 508 int mbedtls_ecp_group_load( mbedtls_ecp_group *grp, mbedtls_ecp_group_id id ); 509 510 /** 511 * \brief Set a group from a TLS ECParameters record 512 * 513 * \param grp Destination group 514 * \param buf &(Start of input buffer) 515 * \param len Buffer length 516 * 517 * \note buf is updated to point right after ECParameters on exit 518 * 519 * \return 0 if successful, 520 * MBEDTLS_ERR_MPI_XXX if initialization failed 521 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA if input is invalid 522 */ 523 int mbedtls_ecp_tls_read_group( mbedtls_ecp_group *grp, const unsigned char **buf, size_t len ); 524 525 /** 526 * \brief Write the TLS ECParameters record for a group 527 * 528 * \param grp ECP group used 529 * \param olen Number of bytes actually written 530 * \param buf Buffer to write to 531 * \param blen Buffer length 532 * 533 * \return 0 if successful, 534 * or MBEDTLS_ERR_ECP_BUFFER_TOO_SMALL 535 */ 536 int mbedtls_ecp_tls_write_group( const mbedtls_ecp_group *grp, size_t *olen, 537 unsigned char *buf, size_t blen ); 538 539 /** 540 * \brief Multiplication by an integer: R = m * P 541 * (Not thread-safe to use same group in multiple threads) 542 * 543 * \note In order to prevent timing attacks, this function 544 * executes the exact same sequence of (base field) 545 * operations for any valid m. It avoids any if-branch or 546 * array index depending on the value of m. 547 * 548 * \note If \p f_rng is not NULL, it is used to randomize 549 * intermediate results to prevent potential timing attacks 550 * targeting these results. We recommend always providing 551 * a non-NULL \p f_rng. The overhead is negligible. 552 * Note: unless #MBEDTLS_ECP_NO_INTERNAL_RNG is defined, when 553 * \p f_rng is NULL, an internal RNG (seeded from the value 554 * of \p m) will be used instead. 555 * 556 * \param grp ECP group 557 * \param R Destination point 558 * \param m Integer by which to multiply 559 * \param P Point to multiply 560 * \param f_rng RNG function (see notes) 561 * \param p_rng RNG parameter 562 * 563 * \return 0 if successful, 564 * MBEDTLS_ERR_ECP_INVALID_KEY if m is not a valid privkey 565 * or P is not a valid pubkey, 566 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed 567 */ 568 int mbedtls_ecp_mul( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, 569 const mbedtls_mpi *m, const mbedtls_ecp_point *P, 570 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 571 572 /** 573 * \brief Multiplication and addition of two points by integers: 574 * R = m * P + n * Q 575 * (Not thread-safe to use same group in multiple threads) 576 * 577 * \note In contrast to mbedtls_ecp_mul(), this function does not guarantee 578 * a constant execution flow and timing. 579 * 580 * \param grp ECP group 581 * \param R Destination point 582 * \param m Integer by which to multiply P 583 * \param P Point to multiply by m 584 * \param n Integer by which to multiply Q 585 * \param Q Point to be multiplied by n 586 * 587 * \return 0 if successful, 588 * MBEDTLS_ERR_ECP_INVALID_KEY if m or n is not a valid privkey 589 * or P or Q is not a valid pubkey, 590 * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed 591 */ 592 int mbedtls_ecp_muladd( mbedtls_ecp_group *grp, mbedtls_ecp_point *R, 593 const mbedtls_mpi *m, const mbedtls_ecp_point *P, 594 const mbedtls_mpi *n, const mbedtls_ecp_point *Q ); 595 596 /** 597 * \brief Check that a point is a valid public key on this curve 598 * 599 * \param grp Curve/group the point should belong to 600 * \param pt Point to check 601 * 602 * \return 0 if point is a valid public key, 603 * MBEDTLS_ERR_ECP_INVALID_KEY otherwise. 604 * 605 * \note This function only checks the point is non-zero, has valid 606 * coordinates and lies on the curve, but not that it is 607 * indeed a multiple of G. This is additional check is more 608 * expensive, isn't required by standards, and shouldn't be 609 * necessary if the group used has a small cofactor. In 610 * particular, it is useless for the NIST groups which all 611 * have a cofactor of 1. 612 * 613 * \note Uses bare components rather than an mbedtls_ecp_keypair structure 614 * in order to ease use with other structures such as 615 * mbedtls_ecdh_context of mbedtls_ecdsa_context. 616 */ 617 int mbedtls_ecp_check_pubkey( const mbedtls_ecp_group *grp, const mbedtls_ecp_point *pt ); 618 619 /** 620 * \brief Check that an mbedtls_mpi is a valid private key for this curve 621 * 622 * \param grp Group used 623 * \param d Integer to check 624 * 625 * \return 0 if point is a valid private key, 626 * MBEDTLS_ERR_ECP_INVALID_KEY otherwise. 627 * 628 * \note Uses bare components rather than an mbedtls_ecp_keypair structure 629 * in order to ease use with other structures such as 630 * mbedtls_ecdh_context of mbedtls_ecdsa_context. 631 */ 632 int mbedtls_ecp_check_privkey( const mbedtls_ecp_group *grp, const mbedtls_mpi *d ); 633 634 /** 635 * \brief Generate a private key 636 * 637 * \param grp ECP group 638 * \param d Destination MPI (secret part) 639 * \param f_rng RNG function 640 * \param p_rng RNG parameter 641 * 642 * \return 0 if successful, 643 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code 644 */ 645 int mbedtls_ecp_gen_privkey( const mbedtls_ecp_group *grp, 646 mbedtls_mpi *d, 647 int (*f_rng)(void *, unsigned char *, size_t), 648 void *p_rng ); 649 650 /** 651 * \brief Generate a keypair with configurable base point 652 * 653 * \param grp ECP group 654 * \param G Chosen base point 655 * \param d Destination MPI (secret part) 656 * \param Q Destination point (public part) 657 * \param f_rng RNG function 658 * \param p_rng RNG parameter 659 * 660 * \return 0 if successful, 661 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code 662 * 663 * \note Uses bare components rather than an mbedtls_ecp_keypair structure 664 * in order to ease use with other structures such as 665 * mbedtls_ecdh_context of mbedtls_ecdsa_context. 666 */ 667 int mbedtls_ecp_gen_keypair_base( mbedtls_ecp_group *grp, 668 const mbedtls_ecp_point *G, 669 mbedtls_mpi *d, mbedtls_ecp_point *Q, 670 int (*f_rng)(void *, unsigned char *, size_t), 671 void *p_rng ); 672 673 /** 674 * \brief Generate a keypair 675 * 676 * \param grp ECP group 677 * \param d Destination MPI (secret part) 678 * \param Q Destination point (public part) 679 * \param f_rng RNG function 680 * \param p_rng RNG parameter 681 * 682 * \return 0 if successful, 683 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code 684 * 685 * \note Uses bare components rather than an mbedtls_ecp_keypair structure 686 * in order to ease use with other structures such as 687 * mbedtls_ecdh_context of mbedtls_ecdsa_context. 688 */ 689 int mbedtls_ecp_gen_keypair( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, 690 int (*f_rng)(void *, unsigned char *, size_t), 691 void *p_rng ); 692 693 /** 694 * \brief Generate a keypair 695 * 696 * \param grp_id ECP group identifier 697 * \param key Destination keypair 698 * \param f_rng RNG function 699 * \param p_rng RNG parameter 700 * 701 * \return 0 if successful, 702 * or a MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code 703 */ 704 int mbedtls_ecp_gen_key( mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key, 705 int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ); 706 707 /** 708 * \brief Check a public-private key pair 709 * 710 * \param pub Keypair structure holding a public key 711 * \param prv Keypair structure holding a private (plus public) key 712 * 713 * \return 0 if successful (keys are valid and match), or 714 * MBEDTLS_ERR_ECP_BAD_INPUT_DATA, or 715 * a MBEDTLS_ERR_ECP_XXX or MBEDTLS_ERR_MPI_XXX code. 716 */ 717 int mbedtls_ecp_check_pub_priv( const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv ); 718 719 #if defined(MBEDTLS_SELF_TEST) 720 721 /** 722 * \brief Checkup routine 723 * 724 * \return 0 if successful, or 1 if a test failed 725 */ 726 int mbedtls_ecp_self_test( int verbose ); 727 728 #endif /* MBEDTLS_SELF_TEST */ 729 730 #ifdef __cplusplus 731 } 732 #endif 733 734 #else /* MBEDTLS_ECP_ALT */ 735 #include "ecp_alt.h" 736 #endif /* MBEDTLS_ECP_ALT */ 737 738 #endif /* ecp.h */ 739