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