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: Apache-2.0 20 * 21 * Licensed under the Apache License, Version 2.0 (the "License"); you may 22 * not use this file except in compliance with the License. 23 * You may obtain a copy of the License at 24 * 25 * http://www.apache.org/licenses/LICENSE-2.0 26 * 27 * Unless required by applicable law or agreed to in writing, software 28 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 29 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 30 * See the License for the specific language governing permissions and 31 * limitations under the License. 32 * 33 * This file is part of Mbed TLS (https://tls.mbed.org) 34 */ 35 36 #ifndef MBEDTLS_ECP_ALT_H 37 #define MBEDTLS_ECP_ALT_H 38 39 #if defined(MBEDTLS_ECP_ALT) 40 /* 41 * default mbed TLS elliptic curve arithmetic implementation 42 * 43 * (in case MBEDTLS_ECP_ALT is defined then the developer has to provide an 44 * alternative implementation for the whole module and it will replace this 45 * one.) 46 */ 47 48 /** 49 * \brief The ECP group structure. 50 * 51 * We consider two types of curve equations: 52 * <ul><li>Short Weierstrass: <code>y^2 = x^3 + A x + B mod P</code> 53 * (SEC1 + RFC-4492)</li> 54 * <li>Montgomery: <code>y^2 = x^3 + A x^2 + x mod P</code> (Curve25519, 55 * Curve448)</li></ul> 56 * In both cases, the generator (\p G) for a prime-order subgroup is fixed. 57 * 58 * For Short Weierstrass, this subgroup is the whole curve, and its 59 * cardinality is denoted by \p N. Our code requires that \p N is an 60 * odd prime as mbedtls_ecp_mul() requires an odd number, and 61 * mbedtls_ecdsa_sign() requires that it is prime for blinding purposes. 62 * 63 * For Montgomery curves, we do not store \p A, but <code>(A + 2) / 4</code>, 64 * which is the quantity used in the formulas. Additionally, \p nbits is 65 * not the size of \p N but the required size for private keys. 66 * 67 * If \p modp is NULL, reduction modulo \p P is done using a generic algorithm. 68 * Otherwise, \p modp must point to a function that takes an \p mbedtls_mpi in the 69 * range of <code>0..2^(2*pbits)-1</code>, and transforms it in-place to an integer 70 * which is congruent mod \p P to the given MPI, and is close enough to \p pbits 71 * in size, so that it may be efficiently brought in the 0..P-1 range by a few 72 * additions or subtractions. Therefore, it is only an approximative modular 73 * reduction. It must return 0 on success and non-zero on failure. 74 * 75 * \note Alternative implementations must keep the group IDs distinct. If 76 * two group structures have the same ID, then they must be 77 * identical. 78 * 79 */ 80 typedef struct mbedtls_ecp_group 81 { 82 mbedtls_ecp_group_id id; /*!< An internal group identifier. */ 83 mbedtls_mpi P; /*!< The prime modulus of the base field. */ 84 mbedtls_mpi A; /*!< For Short Weierstrass: \p A in the equation. For 85 Montgomery curves: <code>(A + 2) / 4</code>. */ 86 mbedtls_mpi B; /*!< For Short Weierstrass: \p B in the equation. 87 For Montgomery curves: unused. */ 88 mbedtls_ecp_point G; /*!< The generator of the subgroup used. */ 89 mbedtls_mpi N; /*!< The order of \p G. */ 90 size_t pbits; /*!< The number of bits in \p P.*/ 91 size_t nbits; /*!< For Short Weierstrass: The number of bits in \p P. 92 For Montgomery curves: the number of bits in the 93 private keys. */ 94 unsigned int h; /*!< \internal 1 if the constants are static. */ 95 int (*modp)(mbedtls_mpi *); /*!< The function for fast pseudo-reduction 96 mod \p P (see above).*/ 97 int (*t_pre)(mbedtls_ecp_point *, void *); /*!< Unused. */ 98 int (*t_post)(mbedtls_ecp_point *, void *); /*!< Unused. */ 99 void *t_data; /*!< Unused. */ 100 mbedtls_ecp_point *T; /*!< Pre-computed points for ecp_mul_comb(). */ 101 size_t T_size; /*!< The number of pre-computed points. */ 102 } 103 mbedtls_ecp_group; 104 105 /** 106 * \name SECTION: Module settings 107 * 108 * The configuration options you can set for this module are in this section. 109 * Either change them in config.h, or define them using the compiler command line. 110 * \{ 111 */ 112 113 #if !defined(MBEDTLS_ECP_MAX_BITS) 114 /** 115 * The maximum size of the groups, that is, of \c N and \c P. 116 */ 117 #define MBEDTLS_ECP_MAX_BITS 521 /**< The maximum size of groups, in bits. */ 118 #endif 119 120 #define MBEDTLS_ECP_MAX_BYTES ( ( MBEDTLS_ECP_MAX_BITS + 7 ) / 8 ) 121 #define MBEDTLS_ECP_MAX_PT_LEN ( 2 * MBEDTLS_ECP_MAX_BYTES + 1 ) 122 123 #if !defined(MBEDTLS_ECP_WINDOW_SIZE) 124 /* 125 * Maximum "window" size used for point multiplication. 126 * Default: 6. 127 * Minimum value: 2. Maximum value: 7. 128 * 129 * Result is an array of at most ( 1 << ( MBEDTLS_ECP_WINDOW_SIZE - 1 ) ) 130 * points used for point multiplication. This value is directly tied to EC 131 * peak memory usage, so decreasing it by one should roughly cut memory usage 132 * by two (if large curves are in use). 133 * 134 * Reduction in size may reduce speed, but larger curves are impacted first. 135 * Sample performances (in ECDHE handshakes/s, with FIXED_POINT_OPTIM = 1): 136 * w-size: 6 5 4 3 2 137 * 521 145 141 135 120 97 138 * 384 214 209 198 177 146 139 * 256 320 320 303 262 226 140 * 224 475 475 453 398 342 141 * 192 640 640 633 587 476 142 */ 143 #define MBEDTLS_ECP_WINDOW_SIZE 6 /**< The maximum window size used. */ 144 #endif /* MBEDTLS_ECP_WINDOW_SIZE */ 145 146 #if !defined(MBEDTLS_ECP_FIXED_POINT_OPTIM) 147 /* 148 * Trade memory for speed on fixed-point multiplication. 149 * 150 * This speeds up repeated multiplication of the generator (that is, the 151 * multiplication in ECDSA signatures, and half of the multiplications in 152 * ECDSA verification and ECDHE) by a factor roughly 3 to 4. 153 * 154 * The cost is increasing EC peak memory usage by a factor roughly 2. 155 * 156 * Change this value to 0 to reduce peak memory usage. 157 */ 158 #define MBEDTLS_ECP_FIXED_POINT_OPTIM 1 /**< Enable fixed-point speed-up. */ 159 #endif /* MBEDTLS_ECP_FIXED_POINT_OPTIM */ 160 161 /* \} name SECTION: Module settings */ 162 163 #endif /* MBEDTLS_ECP_ALT */ 164 165 #endif /* ecp_alt.h */ 166