1 /** 2 * \file ecp_invasive.h 3 * 4 * \brief ECP module: interfaces for invasive testing only. 5 * 6 * The interfaces in this file are intended for testing purposes only. 7 * They SHOULD NOT be made available in library integrations except when 8 * building the library for testing. 9 */ 10 /* 11 * Copyright The Mbed TLS Contributors 12 * SPDX-License-Identifier: Apache-2.0 13 * 14 * Licensed under the Apache License, Version 2.0 (the "License"); you may 15 * not use this file except in compliance with the License. 16 * You may obtain a copy of the License at 17 * 18 * http://www.apache.org/licenses/LICENSE-2.0 19 * 20 * Unless required by applicable law or agreed to in writing, software 21 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 22 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 23 * See the License for the specific language governing permissions and 24 * limitations under the License. 25 */ 26 #ifndef MBEDTLS_ECP_INVASIVE_H 27 #define MBEDTLS_ECP_INVASIVE_H 28 29 #include "common.h" 30 #include "mbedtls/bignum.h" 31 #include "bignum_mod.h" 32 #include "mbedtls/ecp.h" 33 34 #if defined(MBEDTLS_TEST_HOOKS) && defined(MBEDTLS_ECP_C) 35 36 #if defined(MBEDTLS_ECP_DP_SECP384R1_ENABLED) 37 /* Preconditions: 38 * - bits is a multiple of 64 or is 224 39 * - c is -1 or -2 40 * - 0 <= N < 2^bits 41 * - N has room for bits plus one limb 42 * 43 * Behavior: 44 * Set N to c * 2^bits + old_value_of_N. 45 */ 46 void mbedtls_ecp_fix_negative(mbedtls_mpi *N, signed char c, size_t bits); 47 #endif 48 49 #if defined(MBEDTLS_ECP_MONTGOMERY_ENABLED) 50 /** Generate a private key on a Montgomery curve (Curve25519 or Curve448). 51 * 52 * This function implements key generation for the set of secret keys 53 * specified in [Curve25519] p. 5 and in [Curve448]. The resulting value 54 * has the lower bits masked but is not necessarily canonical. 55 * 56 * \note - [Curve25519] http://cr.yp.to/ecdh/curve25519-20060209.pdf 57 * - [RFC7748] https://tools.ietf.org/html/rfc7748 58 * 59 * \p high_bit The position of the high-order bit of the key to generate. 60 * This is the bit-size of the key minus 1: 61 * 254 for Curve25519 or 447 for Curve448. 62 * \param d The randomly generated key. This is a number of size 63 * exactly \p n_bits + 1 bits, with the least significant bits 64 * masked as specified in [Curve25519] and in [RFC7748] §5. 65 * \param f_rng The RNG function. 66 * \param p_rng The RNG context to be passed to \p f_rng. 67 * 68 * \return \c 0 on success. 69 * \return \c MBEDTLS_ERR_ECP_xxx or MBEDTLS_ERR_MPI_xxx on failure. 70 */ 71 int mbedtls_ecp_gen_privkey_mx(size_t n_bits, 72 mbedtls_mpi *d, 73 int (*f_rng)(void *, unsigned char *, size_t), 74 void *p_rng); 75 76 #endif /* MBEDTLS_ECP_MONTGOMERY_ENABLED */ 77 78 #if defined(MBEDTLS_ECP_DP_SECP192R1_ENABLED) 79 80 /** Fast quasi-reduction modulo p192 (FIPS 186-3 D.2.1) 81 * 82 * This operation expects a 384 bit MPI and the result of the reduction 83 * is a 192 bit MPI. 84 * 85 * \param[in,out] Np The address of the MPI to be converted. 86 * Must have twice as many limbs as the modulus. 87 * Upon return this holds the reduced value. The bitlength 88 * of the reduced value is the same as that of the modulus 89 * (192 bits). 90 * \param[in] Nn The length of \p Np in limbs. 91 */ 92 MBEDTLS_STATIC_TESTABLE 93 int mbedtls_ecp_mod_p192_raw(mbedtls_mpi_uint *Np, size_t Nn); 94 95 #endif /* MBEDTLS_ECP_DP_SECP192R1_ENABLED */ 96 97 #if defined(MBEDTLS_ECP_DP_SECP224R1_ENABLED) 98 99 /** Fast quasi-reduction modulo p224 (FIPS 186-3 D.2.2) 100 * 101 * \param[in,out] X The address of the MPI to be converted. 102 * Must have exact limb size that stores a 448-bit MPI 103 * (double the bitlength of the modulus). 104 * Upon return holds the reduced value which is 105 * in range `0 <= X < 2 * N` (where N is the modulus). 106 * The bitlength of the reduced value is the same as 107 * that of the modulus (224 bits). 108 * \param[in] X_limbs The length of \p X in limbs. 109 * 110 * \return \c 0 on success. 111 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if \p X_limbs is not the 112 * limb size that sores a 448-bit MPI. 113 */ 114 MBEDTLS_STATIC_TESTABLE 115 int mbedtls_ecp_mod_p224_raw(mbedtls_mpi_uint *X, size_t X_limbs); 116 117 #endif /* MBEDTLS_ECP_DP_SECP224R1_ENABLED */ 118 119 #if defined(MBEDTLS_ECP_DP_SECP256R1_ENABLED) 120 121 /** Fast quasi-reduction modulo p256 (FIPS 186-3 D.2.3) 122 * 123 * \param[in,out] X The address of the MPI to be converted. 124 * Must have exact limb size that stores a 512-bit MPI 125 * (double the bitlength of the modulus). 126 * Upon return holds the reduced value which is 127 * in range `0 <= X < 2 * N` (where N is the modulus). 128 * The bitlength of the reduced value is the same as 129 * that of the modulus (256 bits). 130 * \param[in] X_limbs The length of \p X in limbs. 131 * 132 * \return \c 0 on success. 133 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if \p X_limbs is not the 134 * limb size that sores a 512-bit MPI. 135 */ 136 MBEDTLS_STATIC_TESTABLE 137 int mbedtls_ecp_mod_p256_raw(mbedtls_mpi_uint *X, size_t X_limbs); 138 139 #endif 140 141 #if defined(MBEDTLS_ECP_DP_SECP521R1_ENABLED) 142 143 /** Fast quasi-reduction modulo p521 = 2^521 - 1 (FIPS 186-3 D.2.5) 144 * 145 * \param[in,out] X The address of the MPI to be converted. 146 * Must have twice as many limbs as the modulus 147 * (the modulus is 521 bits long). Upon return this 148 * holds the reduced value. The reduced value is 149 * in range `0 <= X < 2 * N` (where N is the modulus). 150 * and its the bitlength is one plus the bitlength 151 * of the modulus. 152 * \param[in] X_limbs The length of \p X in limbs. 153 * 154 * \return \c 0 on success. 155 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if \p X_limbs does not have 156 * twice as many limbs as the modulus. 157 */ 158 MBEDTLS_STATIC_TESTABLE 159 int mbedtls_ecp_mod_p521_raw(mbedtls_mpi_uint *X, size_t X_limbs); 160 161 #endif /* MBEDTLS_ECP_DP_SECP521R1_ENABLED */ 162 163 /** Initialise a modulus with hard-coded const curve data. 164 * 165 * \note The caller is responsible for the \p N modulus' memory. 166 * mbedtls_mpi_mod_modulus_free(&N) should be invoked at the 167 * end of its lifecycle. 168 * 169 * \param[in,out] N The address of the modulus structure to populate. 170 * Must be initialized. 171 * \param[in] id The mbedtls_ecp_group_id for which to initialise the modulus. 172 * \param[in] ctype The mbedtls_ecp_curve_type identifier for a coordinate modulus (P) 173 * or a scalar modulus (N). 174 * 175 * \return \c 0 if successful. 176 * \return #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if the given MPIs do not 177 * have the correct number of limbs. 178 * 179 */ 180 MBEDTLS_STATIC_TESTABLE 181 int mbedtls_ecp_modulus_setup(mbedtls_mpi_mod_modulus *N, 182 const mbedtls_ecp_group_id id, 183 const mbedtls_ecp_curve_type ctype); 184 185 #endif /* MBEDTLS_TEST_HOOKS && MBEDTLS_ECP_C */ 186 187 #endif /* MBEDTLS_ECP_INVASIVE_H */ 188
