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