1 /** 2 * Low-level modular bignum functions 3 * 4 * This interface should only be used by the higher-level modular bignum 5 * module (bignum_mod.c) and the ECP module (ecp.c, ecp_curves.c). All other 6 * modules should use the high-level modular bignum interface (bignum_mod.h) 7 * or the legacy bignum interface (bignum.h). 8 * 9 * This is a low-level interface to operations on integers modulo which 10 * has no protection against passing invalid arguments such as arrays of 11 * the wrong size. The functions in bignum_mod.h provide a higher-level 12 * interface that includes protections against accidental misuse, at the 13 * expense of code size and sometimes more cumbersome memory management. 14 */ 15 16 /* 17 * Copyright The Mbed TLS Contributors 18 * SPDX-License-Identifier: Apache-2.0 19 * 20 * Licensed under the Apache License, Version 2.0 (the "License"); you may 21 * not use this file except in compliance with the License. 22 * You may obtain a copy of the License at 23 * 24 * http://www.apache.org/licenses/LICENSE-2.0 25 * 26 * Unless required by applicable law or agreed to in writing, software 27 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 28 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 29 * See the License for the specific language governing permissions and 30 * limitations under the License. 31 */ 32 33 #ifndef MBEDTLS_BIGNUM_MOD_RAW_H 34 #define MBEDTLS_BIGNUM_MOD_RAW_H 35 36 #include "common.h" 37 38 #if defined(MBEDTLS_BIGNUM_C) 39 #include "mbedtls/bignum.h" 40 #endif 41 42 #include "bignum_mod.h" 43 44 /** 45 * \brief Perform a safe conditional copy of an MPI which doesn't reveal 46 * whether the assignment was done or not. 47 * 48 * The size to copy is determined by \p N. 49 * 50 * \param[out] X The address of the destination MPI. 51 * This must be initialized. Must have enough limbs to 52 * store the full value of \p A. 53 * \param[in] A The address of the source MPI. This must be initialized. 54 * \param[in] N The address of the modulus related to \p X and \p A. 55 * \param assign The condition deciding whether to perform the 56 * assignment or not. Must be either 0 or 1: 57 * * \c 1: Perform the assignment `X = A`. 58 * * \c 0: Keep the original value of \p X. 59 * 60 * \note This function avoids leaking any information about whether 61 * the assignment was done or not. 62 * 63 * \warning If \p assign is neither 0 nor 1, the result of this function 64 * is indeterminate, and the resulting value in \p X might be 65 * neither its original value nor the value in \p A. 66 */ 67 void mbedtls_mpi_mod_raw_cond_assign( mbedtls_mpi_uint *X, 68 const mbedtls_mpi_uint *A, 69 const mbedtls_mpi_mod_modulus *N, 70 unsigned char assign ); 71 72 /** 73 * \brief Perform a safe conditional swap of two MPIs which doesn't reveal 74 * whether the swap was done or not. 75 * 76 * The size to swap is determined by \p N. 77 * 78 * \param[in,out] X The address of the first MPI. This must be initialized. 79 * \param[in,out] Y The address of the second MPI. This must be initialized. 80 * \param[in] N The address of the modulus related to \p X and \p Y. 81 * \param swap The condition deciding whether to perform 82 * the swap or not. Must be either 0 or 1: 83 * * \c 1: Swap the values of \p X and \p Y. 84 * * \c 0: Keep the original values of \p X and \p Y. 85 * 86 * \note This function avoids leaking any information about whether 87 * the swap was done or not. 88 * 89 * \warning If \p swap is neither 0 nor 1, the result of this function 90 * is indeterminate, and both \p X and \p Y might end up with 91 * values different to either of the original ones. 92 */ 93 void mbedtls_mpi_mod_raw_cond_swap( mbedtls_mpi_uint *X, 94 mbedtls_mpi_uint *Y, 95 const mbedtls_mpi_mod_modulus *N, 96 unsigned char swap ); 97 98 /** Import X from unsigned binary data. 99 * 100 * The MPI needs to have enough limbs to store the full value (including any 101 * most significant zero bytes in the input). 102 * 103 * \param[out] X The address of the MPI. The size is determined by \p m. 104 * (In particular, it must have at least as many limbs as 105 * the modulus \p m.) 106 * \param[in] m The address of the modulus related to \p X. 107 * \param[in] input The input buffer to import from. 108 * \param input_length The length in bytes of \p input. 109 * \param ext_rep The endianness of the number in the input buffer. 110 * 111 * \return \c 0 if successful. 112 * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p X isn't 113 * large enough to hold the value in \p input. 114 * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if the external representation 115 * of \p m is invalid or \p X is not less than \p m. 116 */ 117 int mbedtls_mpi_mod_raw_read( mbedtls_mpi_uint *X, 118 const mbedtls_mpi_mod_modulus *m, 119 const unsigned char *input, 120 size_t input_length, 121 mbedtls_mpi_mod_ext_rep ext_rep ); 122 123 /** Export A into unsigned binary data. 124 * 125 * \param[in] A The address of the MPI. The size is determined by \p m. 126 * (In particular, it must have at least as many limbs as 127 * the modulus \p m.) 128 * \param[in] m The address of the modulus related to \p A. 129 * \param[out] output The output buffer to export to. 130 * \param output_length The length in bytes of \p output. 131 * \param ext_rep The endianness in which the number should be written into the output buffer. 132 * 133 * \return \c 0 if successful. 134 * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p output isn't 135 * large enough to hold the value of \p A. 136 * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if the external representation 137 * of \p m is invalid. 138 */ 139 int mbedtls_mpi_mod_raw_write( const mbedtls_mpi_uint *A, 140 const mbedtls_mpi_mod_modulus *m, 141 unsigned char *output, 142 size_t output_length, 143 mbedtls_mpi_mod_ext_rep ext_rep ); 144 145 /* BEGIN MERGE SLOT 1 */ 146 147 /* END MERGE SLOT 1 */ 148 149 /* BEGIN MERGE SLOT 2 */ 150 151 /** \brief Subtract two MPIs, returning the residue modulo the specified 152 * modulus. 153 * 154 * The size of the operation is determined by \p N. \p A and \p B must have 155 * the same number of limbs as \p N. 156 * 157 * \p X may be aliased to \p A or \p B, or even both, but may not overlap 158 * either otherwise. 159 * 160 * \param[out] X The address of the result MPI. 161 * This must be initialized. Must have enough limbs to 162 * store the full value of the result. 163 * \param[in] A The address of the first MPI. This must be initialized. 164 * \param[in] B The address of the second MPI. This must be initialized. 165 * \param[in] N The address of the modulus. Used to perform a modulo 166 * operation on the result of the subtraction. 167 */ 168 void mbedtls_mpi_mod_raw_sub( mbedtls_mpi_uint *X, 169 const mbedtls_mpi_uint *A, 170 const mbedtls_mpi_uint *B, 171 const mbedtls_mpi_mod_modulus *N ); 172 173 /* END MERGE SLOT 2 */ 174 175 /* BEGIN MERGE SLOT 3 */ 176 177 /* END MERGE SLOT 3 */ 178 179 /* BEGIN MERGE SLOT 4 */ 180 181 /* END MERGE SLOT 4 */ 182 183 /* BEGIN MERGE SLOT 5 */ 184 /** 185 * \brief Perform a known-size modular addition. 186 * 187 * Calculate `A + B modulo N`. 188 * 189 * The number of limbs in each operand, and the result, is given by the 190 * modulus \p N. 191 * 192 * \p X may be aliased to \p A or \p B, or even both, but may not overlap 193 * either otherwise. 194 * 195 * \param[out] X The result of the modular addition. 196 * \param[in] A Little-endian presentation of the left operand. This 197 * must be smaller than \p N. 198 * \param[in] B Little-endian presentation of the right operand. This 199 * must be smaller than \p N. 200 * \param[in] N The address of the modulus. 201 */ 202 void mbedtls_mpi_mod_raw_add( mbedtls_mpi_uint *X, 203 const mbedtls_mpi_uint *A, 204 const mbedtls_mpi_uint *B, 205 const mbedtls_mpi_mod_modulus *N ); 206 /* END MERGE SLOT 5 */ 207 208 /* BEGIN MERGE SLOT 6 */ 209 210 /* END MERGE SLOT 6 */ 211 212 /* BEGIN MERGE SLOT 7 */ 213 /** Convert an MPI into Montgomery form. 214 * 215 * \param X The address of the MPI. 216 * Must have the same number of limbs as \p m. 217 * \param m The address of the modulus, which gives the size of 218 * the base `R` = 2^(biL*m->limbs). 219 * 220 * \return \c 0 if successful. 221 */ 222 int mbedtls_mpi_mod_raw_to_mont_rep( mbedtls_mpi_uint *X, 223 const mbedtls_mpi_mod_modulus *m ); 224 225 /** Convert an MPI back from Montgomery representation. 226 * 227 * \param X The address of the MPI. 228 * Must have the same number of limbs as \p m. 229 * \param m The address of the modulus, which gives the size of 230 * the base `R`= 2^(biL*m->limbs). 231 * 232 * \return \c 0 if successful. 233 */ 234 int mbedtls_mpi_mod_raw_from_mont_rep( mbedtls_mpi_uint *X, 235 const mbedtls_mpi_mod_modulus *m ); 236 /* END MERGE SLOT 7 */ 237 238 /* BEGIN MERGE SLOT 8 */ 239 240 /* END MERGE SLOT 8 */ 241 242 /* BEGIN MERGE SLOT 9 */ 243 244 /* END MERGE SLOT 9 */ 245 246 /* BEGIN MERGE SLOT 10 */ 247 248 /* END MERGE SLOT 10 */ 249 250 #endif /* MBEDTLS_BIGNUM_MOD_RAW_H */ 251
