1 | /**
|
---|
2 | * \file bignum.h
|
---|
3 | *
|
---|
4 | * \brief Multi-precision integer library
|
---|
5 | */
|
---|
6 | /*
|
---|
7 | * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
|
---|
8 | * SPDX-License-Identifier: Apache-2.0
|
---|
9 | *
|
---|
10 | * Licensed under the Apache License, Version 2.0 (the "License"); you may
|
---|
11 | * not use this file except in compliance with the License.
|
---|
12 | * You may obtain a copy of the License at
|
---|
13 | *
|
---|
14 | * http://www.apache.org/licenses/LICENSE-2.0
|
---|
15 | *
|
---|
16 | * Unless required by applicable law or agreed to in writing, software
|
---|
17 | * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
---|
18 | * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
19 | * See the License for the specific language governing permissions and
|
---|
20 | * limitations under the License.
|
---|
21 | *
|
---|
22 | * This file is part of mbed TLS (https://tls.mbed.org)
|
---|
23 | */
|
---|
24 | #ifndef MBEDTLS_BIGNUM_H
|
---|
25 | #define MBEDTLS_BIGNUM_H
|
---|
26 |
|
---|
27 | #if !defined(MBEDTLS_CONFIG_FILE)
|
---|
28 | #include "config.h"
|
---|
29 | #else
|
---|
30 | #include MBEDTLS_CONFIG_FILE
|
---|
31 | #endif
|
---|
32 |
|
---|
33 | #include <stddef.h>
|
---|
34 | #include <stdint.h>
|
---|
35 |
|
---|
36 | #if defined(MBEDTLS_FS_IO)
|
---|
37 | #include <stdio.h>
|
---|
38 | #endif
|
---|
39 |
|
---|
40 | #define MBEDTLS_ERR_MPI_FILE_IO_ERROR -0x0002 /**< An error occurred while reading from or writing to a file. */
|
---|
41 | #define MBEDTLS_ERR_MPI_BAD_INPUT_DATA -0x0004 /**< Bad input parameters to function. */
|
---|
42 | #define MBEDTLS_ERR_MPI_INVALID_CHARACTER -0x0006 /**< There is an invalid character in the digit string. */
|
---|
43 | #define MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL -0x0008 /**< The buffer is too small to write to. */
|
---|
44 | #define MBEDTLS_ERR_MPI_NEGATIVE_VALUE -0x000A /**< The input arguments are negative or result in illegal output. */
|
---|
45 | #define MBEDTLS_ERR_MPI_DIVISION_BY_ZERO -0x000C /**< The input argument for division is zero, which is not allowed. */
|
---|
46 | #define MBEDTLS_ERR_MPI_NOT_ACCEPTABLE -0x000E /**< The input arguments are not acceptable. */
|
---|
47 | #define MBEDTLS_ERR_MPI_ALLOC_FAILED -0x0010 /**< Memory allocation failed. */
|
---|
48 |
|
---|
49 | #define MBEDTLS_MPI_CHK(f) do { if( ( ret = f ) != 0 ) goto cleanup; } while( 0 )
|
---|
50 |
|
---|
51 | /*
|
---|
52 | * Maximum size MPIs are allowed to grow to in number of limbs.
|
---|
53 | */
|
---|
54 | #define MBEDTLS_MPI_MAX_LIMBS 10000
|
---|
55 |
|
---|
56 | #if !defined(MBEDTLS_MPI_WINDOW_SIZE)
|
---|
57 | /*
|
---|
58 | * Maximum window size used for modular exponentiation. Default: 6
|
---|
59 | * Minimum value: 1. Maximum value: 6.
|
---|
60 | *
|
---|
61 | * Result is an array of ( 2 << MBEDTLS_MPI_WINDOW_SIZE ) MPIs used
|
---|
62 | * for the sliding window calculation. (So 64 by default)
|
---|
63 | *
|
---|
64 | * Reduction in size, reduces speed.
|
---|
65 | */
|
---|
66 | #define MBEDTLS_MPI_WINDOW_SIZE 6 /**< Maximum windows size used. */
|
---|
67 | #endif /* !MBEDTLS_MPI_WINDOW_SIZE */
|
---|
68 |
|
---|
69 | #if !defined(MBEDTLS_MPI_MAX_SIZE)
|
---|
70 | /*
|
---|
71 | * Maximum size of MPIs allowed in bits and bytes for user-MPIs.
|
---|
72 | * ( Default: 512 bytes => 4096 bits, Maximum tested: 2048 bytes => 16384 bits )
|
---|
73 | *
|
---|
74 | * Note: Calculations can temporarily result in larger MPIs. So the number
|
---|
75 | * of limbs required (MBEDTLS_MPI_MAX_LIMBS) is higher.
|
---|
76 | */
|
---|
77 | #define MBEDTLS_MPI_MAX_SIZE 1024 /**< Maximum number of bytes for usable MPIs. */
|
---|
78 | #endif /* !MBEDTLS_MPI_MAX_SIZE */
|
---|
79 |
|
---|
80 | #define MBEDTLS_MPI_MAX_BITS ( 8 * MBEDTLS_MPI_MAX_SIZE ) /**< Maximum number of bits for usable MPIs. */
|
---|
81 |
|
---|
82 | /*
|
---|
83 | * When reading from files with mbedtls_mpi_read_file() and writing to files with
|
---|
84 | * mbedtls_mpi_write_file() the buffer should have space
|
---|
85 | * for a (short) label, the MPI (in the provided radix), the newline
|
---|
86 | * characters and the '\0'.
|
---|
87 | *
|
---|
88 | * By default we assume at least a 10 char label, a minimum radix of 10
|
---|
89 | * (decimal) and a maximum of 4096 bit numbers (1234 decimal chars).
|
---|
90 | * Autosized at compile time for at least a 10 char label, a minimum radix
|
---|
91 | * of 10 (decimal) for a number of MBEDTLS_MPI_MAX_BITS size.
|
---|
92 | *
|
---|
93 | * This used to be statically sized to 1250 for a maximum of 4096 bit
|
---|
94 | * numbers (1234 decimal chars).
|
---|
95 | *
|
---|
96 | * Calculate using the formula:
|
---|
97 | * MBEDTLS_MPI_RW_BUFFER_SIZE = ceil(MBEDTLS_MPI_MAX_BITS / ln(10) * ln(2)) +
|
---|
98 | * LabelSize + 6
|
---|
99 | */
|
---|
100 | #define MBEDTLS_MPI_MAX_BITS_SCALE100 ( 100 * MBEDTLS_MPI_MAX_BITS )
|
---|
101 | #define MBEDTLS_LN_2_DIV_LN_10_SCALE100 332
|
---|
102 | #define MBEDTLS_MPI_RW_BUFFER_SIZE ( ((MBEDTLS_MPI_MAX_BITS_SCALE100 + MBEDTLS_LN_2_DIV_LN_10_SCALE100 - 1) / MBEDTLS_LN_2_DIV_LN_10_SCALE100) + 10 + 6 )
|
---|
103 |
|
---|
104 | /*
|
---|
105 | * Define the base integer type, architecture-wise.
|
---|
106 | *
|
---|
107 | * 32 or 64-bit integer types can be forced regardless of the underlying
|
---|
108 | * architecture by defining MBEDTLS_HAVE_INT32 or MBEDTLS_HAVE_INT64
|
---|
109 | * respectively and undefining MBEDTLS_HAVE_ASM.
|
---|
110 | *
|
---|
111 | * Double-width integers (e.g. 128-bit in 64-bit architectures) can be
|
---|
112 | * disabled by defining MBEDTLS_NO_UDBL_DIVISION.
|
---|
113 | */
|
---|
114 | #if !defined(MBEDTLS_HAVE_INT32)
|
---|
115 | #if defined(_MSC_VER) && defined(_M_AMD64)
|
---|
116 | /* Always choose 64-bit when using MSC */
|
---|
117 | #if !defined(MBEDTLS_HAVE_INT64)
|
---|
118 | #define MBEDTLS_HAVE_INT64
|
---|
119 | #endif /* !MBEDTLS_HAVE_INT64 */
|
---|
120 | typedef int64_t mbedtls_mpi_sint;
|
---|
121 | typedef uint64_t mbedtls_mpi_uint;
|
---|
122 | #elif defined(__GNUC__) && ( \
|
---|
123 | defined(__amd64__) || defined(__x86_64__) || \
|
---|
124 | defined(__ppc64__) || defined(__powerpc64__) || \
|
---|
125 | defined(__ia64__) || defined(__alpha__) || \
|
---|
126 | ( defined(__sparc__) && defined(__arch64__) ) || \
|
---|
127 | defined(__s390x__) || defined(__mips64) )
|
---|
128 | #if !defined(MBEDTLS_HAVE_INT64)
|
---|
129 | #define MBEDTLS_HAVE_INT64
|
---|
130 | #endif /* MBEDTLS_HAVE_INT64 */
|
---|
131 | typedef int64_t mbedtls_mpi_sint;
|
---|
132 | typedef uint64_t mbedtls_mpi_uint;
|
---|
133 | #if !defined(MBEDTLS_NO_UDBL_DIVISION)
|
---|
134 | /* mbedtls_t_udbl defined as 128-bit unsigned int */
|
---|
135 | typedef unsigned int mbedtls_t_udbl __attribute__((mode(TI)));
|
---|
136 | #define MBEDTLS_HAVE_UDBL
|
---|
137 | #endif /* !MBEDTLS_NO_UDBL_DIVISION */
|
---|
138 | #elif defined(__ARMCC_VERSION) && defined(__aarch64__)
|
---|
139 | /*
|
---|
140 | * __ARMCC_VERSION is defined for both armcc and armclang and
|
---|
141 | * __aarch64__ is only defined by armclang when compiling 64-bit code
|
---|
142 | */
|
---|
143 | #if !defined(MBEDTLS_HAVE_INT64)
|
---|
144 | #define MBEDTLS_HAVE_INT64
|
---|
145 | #endif /* !MBEDTLS_HAVE_INT64 */
|
---|
146 | typedef int64_t mbedtls_mpi_sint;
|
---|
147 | typedef uint64_t mbedtls_mpi_uint;
|
---|
148 | #if !defined(MBEDTLS_NO_UDBL_DIVISION)
|
---|
149 | /* mbedtls_t_udbl defined as 128-bit unsigned int */
|
---|
150 | typedef __uint128_t mbedtls_t_udbl;
|
---|
151 | #define MBEDTLS_HAVE_UDBL
|
---|
152 | #endif /* !MBEDTLS_NO_UDBL_DIVISION */
|
---|
153 | #elif defined(MBEDTLS_HAVE_INT64)
|
---|
154 | /* Force 64-bit integers with unknown compiler */
|
---|
155 | typedef int64_t mbedtls_mpi_sint;
|
---|
156 | typedef uint64_t mbedtls_mpi_uint;
|
---|
157 | #endif
|
---|
158 | #endif /* !MBEDTLS_HAVE_INT32 */
|
---|
159 |
|
---|
160 | #if !defined(MBEDTLS_HAVE_INT64)
|
---|
161 | /* Default to 32-bit compilation */
|
---|
162 | #if !defined(MBEDTLS_HAVE_INT32)
|
---|
163 | #define MBEDTLS_HAVE_INT32
|
---|
164 | #endif /* !MBEDTLS_HAVE_INT32 */
|
---|
165 | typedef int32_t mbedtls_mpi_sint;
|
---|
166 | typedef uint32_t mbedtls_mpi_uint;
|
---|
167 | #if !defined(MBEDTLS_NO_UDBL_DIVISION)
|
---|
168 | typedef uint64_t mbedtls_t_udbl;
|
---|
169 | #define MBEDTLS_HAVE_UDBL
|
---|
170 | #endif /* !MBEDTLS_NO_UDBL_DIVISION */
|
---|
171 | #endif /* !MBEDTLS_HAVE_INT64 */
|
---|
172 |
|
---|
173 | #ifdef __cplusplus
|
---|
174 | extern "C" {
|
---|
175 | #endif
|
---|
176 |
|
---|
177 | /**
|
---|
178 | * \brief MPI structure
|
---|
179 | */
|
---|
180 | typedef struct mbedtls_mpi
|
---|
181 | {
|
---|
182 | int s; /*!< integer sign */
|
---|
183 | size_t n; /*!< total # of limbs */
|
---|
184 | mbedtls_mpi_uint *p; /*!< pointer to limbs */
|
---|
185 | }
|
---|
186 | mbedtls_mpi;
|
---|
187 |
|
---|
188 | /**
|
---|
189 | * \brief Initialize an MPI context.
|
---|
190 | *
|
---|
191 | * This makes the MPI ready to be set or freed,
|
---|
192 | * but does not define a value for the MPI.
|
---|
193 | *
|
---|
194 | * \param X The MPI context to initialize. This must not be \c NULL.
|
---|
195 | */
|
---|
196 | void mbedtls_mpi_init( mbedtls_mpi *X );
|
---|
197 |
|
---|
198 | /**
|
---|
199 | * \brief This function frees the components of an MPI context.
|
---|
200 | *
|
---|
201 | * \param X The MPI context to be cleared. This may be \c NULL,
|
---|
202 | * in which case this function is a no-op. If it is
|
---|
203 | * not \c NULL, it must point to an initialized MPI.
|
---|
204 | */
|
---|
205 | void mbedtls_mpi_free( mbedtls_mpi *X );
|
---|
206 |
|
---|
207 | /**
|
---|
208 | * \brief Enlarge an MPI to the specified number of limbs.
|
---|
209 | *
|
---|
210 | * \note This function does nothing if the MPI is
|
---|
211 | * already large enough.
|
---|
212 | *
|
---|
213 | * \param X The MPI to grow. It must be initialized.
|
---|
214 | * \param nblimbs The target number of limbs.
|
---|
215 | *
|
---|
216 | * \return \c 0 if successful.
|
---|
217 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
|
---|
218 | * \return Another negative error code on other kinds of failure.
|
---|
219 | */
|
---|
220 | int mbedtls_mpi_grow( mbedtls_mpi *X, size_t nblimbs );
|
---|
221 |
|
---|
222 | /**
|
---|
223 | * \brief This function resizes an MPI downwards, keeping at least the
|
---|
224 | * specified number of limbs.
|
---|
225 | *
|
---|
226 | * If \c X is smaller than \c nblimbs, it is resized up
|
---|
227 | * instead.
|
---|
228 | *
|
---|
229 | * \param X The MPI to shrink. This must point to an initialized MPI.
|
---|
230 | * \param nblimbs The minimum number of limbs to keep.
|
---|
231 | *
|
---|
232 | * \return \c 0 if successful.
|
---|
233 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed
|
---|
234 | * (this can only happen when resizing up).
|
---|
235 | * \return Another negative error code on other kinds of failure.
|
---|
236 | */
|
---|
237 | int mbedtls_mpi_shrink( mbedtls_mpi *X, size_t nblimbs );
|
---|
238 |
|
---|
239 | /**
|
---|
240 | * \brief Make a copy of an MPI.
|
---|
241 | *
|
---|
242 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
243 | * \param Y The source MPI. This must point to an initialized MPI.
|
---|
244 | *
|
---|
245 | * \note The limb-buffer in the destination MPI is enlarged
|
---|
246 | * if necessary to hold the value in the source MPI.
|
---|
247 | *
|
---|
248 | * \return \c 0 if successful.
|
---|
249 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
|
---|
250 | * \return Another negative error code on other kinds of failure.
|
---|
251 | */
|
---|
252 | int mbedtls_mpi_copy( mbedtls_mpi *X, const mbedtls_mpi *Y );
|
---|
253 |
|
---|
254 | /**
|
---|
255 | * \brief Swap the contents of two MPIs.
|
---|
256 | *
|
---|
257 | * \param X The first MPI. It must be initialized.
|
---|
258 | * \param Y The second MPI. It must be initialized.
|
---|
259 | */
|
---|
260 | void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y );
|
---|
261 |
|
---|
262 | /**
|
---|
263 | * \brief Perform a safe conditional copy of MPI which doesn't
|
---|
264 | * reveal whether the condition was true or not.
|
---|
265 | *
|
---|
266 | * \param X The MPI to conditionally assign to. This must point
|
---|
267 | * to an initialized MPI.
|
---|
268 | * \param Y The MPI to be assigned from. This must point to an
|
---|
269 | * initialized MPI.
|
---|
270 | * \param assign The condition deciding whether to perform the
|
---|
271 | * assignment or not. Possible values:
|
---|
272 | * * \c 1: Perform the assignment `X = Y`.
|
---|
273 | * * \c 0: Keep the original value of \p X.
|
---|
274 | *
|
---|
275 | * \note This function is equivalent to
|
---|
276 | * `if( assign ) mbedtls_mpi_copy( X, Y );`
|
---|
277 | * except that it avoids leaking any information about whether
|
---|
278 | * the assignment was done or not (the above code may leak
|
---|
279 | * information through branch prediction and/or memory access
|
---|
280 | * patterns analysis).
|
---|
281 | *
|
---|
282 | * \return \c 0 if successful.
|
---|
283 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
|
---|
284 | * \return Another negative error code on other kinds of failure.
|
---|
285 | */
|
---|
286 | int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned char assign );
|
---|
287 |
|
---|
288 | /**
|
---|
289 | * \brief Perform a safe conditional swap which doesn't
|
---|
290 | * reveal whether the condition was true or not.
|
---|
291 | *
|
---|
292 | * \param X The first MPI. This must be initialized.
|
---|
293 | * \param Y The second MPI. This must be initialized.
|
---|
294 | * \param assign The condition deciding whether to perform
|
---|
295 | * the swap or not. Possible values:
|
---|
296 | * * \c 1: Swap the values of \p X and \p Y.
|
---|
297 | * * \c 0: Keep the original values of \p X and \p Y.
|
---|
298 | *
|
---|
299 | * \note This function is equivalent to
|
---|
300 | * if( assign ) mbedtls_mpi_swap( X, Y );
|
---|
301 | * except that it avoids leaking any information about whether
|
---|
302 | * the assignment was done or not (the above code may leak
|
---|
303 | * information through branch prediction and/or memory access
|
---|
304 | * patterns analysis).
|
---|
305 | *
|
---|
306 | * \return \c 0 if successful.
|
---|
307 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
|
---|
308 | * \return Another negative error code on other kinds of failure.
|
---|
309 | *
|
---|
310 | */
|
---|
311 | int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char assign );
|
---|
312 |
|
---|
313 | /**
|
---|
314 | * \brief Store integer value in MPI.
|
---|
315 | *
|
---|
316 | * \param X The MPI to set. This must be initialized.
|
---|
317 | * \param z The value to use.
|
---|
318 | *
|
---|
319 | * \return \c 0 if successful.
|
---|
320 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
|
---|
321 | * \return Another negative error code on other kinds of failure.
|
---|
322 | */
|
---|
323 | int mbedtls_mpi_lset( mbedtls_mpi *X, mbedtls_mpi_sint z );
|
---|
324 |
|
---|
325 | /**
|
---|
326 | * \brief Get a specific bit from an MPI.
|
---|
327 | *
|
---|
328 | * \param X The MPI to query. This must be initialized.
|
---|
329 | * \param pos Zero-based index of the bit to query.
|
---|
330 | *
|
---|
331 | * \return \c 0 or \c 1 on success, depending on whether bit \c pos
|
---|
332 | * of \c X is unset or set.
|
---|
333 | * \return A negative error code on failure.
|
---|
334 | */
|
---|
335 | int mbedtls_mpi_get_bit( const mbedtls_mpi *X, size_t pos );
|
---|
336 |
|
---|
337 | /**
|
---|
338 | * \brief Modify a specific bit in an MPI.
|
---|
339 | *
|
---|
340 | * \note This function will grow the target MPI if necessary to set a
|
---|
341 | * bit to \c 1 in a not yet existing limb. It will not grow if
|
---|
342 | * the bit should be set to \c 0.
|
---|
343 | *
|
---|
344 | * \param X The MPI to modify. This must be initialized.
|
---|
345 | * \param pos Zero-based index of the bit to modify.
|
---|
346 | * \param val The desired value of bit \c pos: \c 0 or \c 1.
|
---|
347 | *
|
---|
348 | * \return \c 0 if successful.
|
---|
349 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
|
---|
350 | * \return Another negative error code on other kinds of failure.
|
---|
351 | */
|
---|
352 | int mbedtls_mpi_set_bit( mbedtls_mpi *X, size_t pos, unsigned char val );
|
---|
353 |
|
---|
354 | /**
|
---|
355 | * \brief Return the number of bits of value \c 0 before the
|
---|
356 | * least significant bit of value \c 1.
|
---|
357 | *
|
---|
358 | * \note This is the same as the zero-based index of
|
---|
359 | * the least significant bit of value \c 1.
|
---|
360 | *
|
---|
361 | * \param X The MPI to query.
|
---|
362 | *
|
---|
363 | * \return The number of bits of value \c 0 before the least significant
|
---|
364 | * bit of value \c 1 in \p X.
|
---|
365 | */
|
---|
366 | size_t mbedtls_mpi_lsb( const mbedtls_mpi *X );
|
---|
367 |
|
---|
368 | /**
|
---|
369 | * \brief Return the number of bits up to and including the most
|
---|
370 | * significant bit of value \c 1.
|
---|
371 | *
|
---|
372 | * * \note This is same as the one-based index of the most
|
---|
373 | * significant bit of value \c 1.
|
---|
374 | *
|
---|
375 | * \param X The MPI to query. This must point to an initialized MPI.
|
---|
376 | *
|
---|
377 | * \return The number of bits up to and including the most
|
---|
378 | * significant bit of value \c 1.
|
---|
379 | */
|
---|
380 | size_t mbedtls_mpi_bitlen( const mbedtls_mpi *X );
|
---|
381 |
|
---|
382 | /**
|
---|
383 | * \brief Return the total size of an MPI value in bytes.
|
---|
384 | *
|
---|
385 | * \param X The MPI to use. This must point to an initialized MPI.
|
---|
386 | *
|
---|
387 | * \note The value returned by this function may be less than
|
---|
388 | * the number of bytes used to store \p X internally.
|
---|
389 | * This happens if and only if there are trailing bytes
|
---|
390 | * of value zero.
|
---|
391 | *
|
---|
392 | * \return The least number of bytes capable of storing
|
---|
393 | * the absolute value of \p X.
|
---|
394 | */
|
---|
395 | size_t mbedtls_mpi_size( const mbedtls_mpi *X );
|
---|
396 |
|
---|
397 | /**
|
---|
398 | * \brief Import an MPI from an ASCII string.
|
---|
399 | *
|
---|
400 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
401 | * \param radix The numeric base of the input string.
|
---|
402 | * \param s Null-terminated string buffer.
|
---|
403 | *
|
---|
404 | * \return \c 0 if successful.
|
---|
405 | * \return A negative error code on failure.
|
---|
406 | */
|
---|
407 | int mbedtls_mpi_read_string( mbedtls_mpi *X, int radix, const char *s );
|
---|
408 |
|
---|
409 | /**
|
---|
410 | * \brief Export an MPI to an ASCII string.
|
---|
411 | *
|
---|
412 | * \param X The source MPI. This must point to an initialized MPI.
|
---|
413 | * \param radix The numeric base of the output string.
|
---|
414 | * \param buf The buffer to write the string to. This must be writable
|
---|
415 | * buffer of length \p buflen Bytes.
|
---|
416 | * \param buflen The available size in Bytes of \p buf.
|
---|
417 | * \param olen The address at which to store the length of the string
|
---|
418 | * written, including the final \c NULL byte. This must
|
---|
419 | * not be \c NULL.
|
---|
420 | *
|
---|
421 | * \note You can call this function with `buflen == 0` to obtain the
|
---|
422 | * minimum required buffer size in `*olen`.
|
---|
423 | *
|
---|
424 | * \return \c 0 if successful.
|
---|
425 | * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the target buffer \p buf
|
---|
426 | * is too small to hold the value of \p X in the desired base.
|
---|
427 | * In this case, `*olen` is nonetheless updated to contain the
|
---|
428 | * size of \p buf required for a successful call.
|
---|
429 | * \return Another negative error code on different kinds of failure.
|
---|
430 | */
|
---|
431 | int mbedtls_mpi_write_string( const mbedtls_mpi *X, int radix,
|
---|
432 | char *buf, size_t buflen, size_t *olen );
|
---|
433 |
|
---|
434 | #if defined(MBEDTLS_FS_IO)
|
---|
435 | /**
|
---|
436 | * \brief Read an MPI from a line in an opened file.
|
---|
437 | *
|
---|
438 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
439 | * \param radix The numeric base of the string representation used
|
---|
440 | * in the source line.
|
---|
441 | * \param fin The input file handle to use. This must not be \c NULL.
|
---|
442 | *
|
---|
443 | * \note On success, this function advances the file stream
|
---|
444 | * to the end of the current line or to EOF.
|
---|
445 | *
|
---|
446 | * The function returns \c 0 on an empty line.
|
---|
447 | *
|
---|
448 | * Leading whitespaces are ignored, as is a
|
---|
449 | * '0x' prefix for radix \c 16.
|
---|
450 | *
|
---|
451 | * \return \c 0 if successful.
|
---|
452 | * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the file read buffer
|
---|
453 | * is too small.
|
---|
454 | * \return Another negative error code on failure.
|
---|
455 | */
|
---|
456 | int mbedtls_mpi_read_file( mbedtls_mpi *X, int radix, FILE *fin );
|
---|
457 |
|
---|
458 | /**
|
---|
459 | * \brief Export an MPI into an opened file.
|
---|
460 | *
|
---|
461 | * \param p A string prefix to emit prior to the MPI data.
|
---|
462 | * For example, this might be a label, or "0x" when
|
---|
463 | * printing in base \c 16. This may be \c NULL if no prefix
|
---|
464 | * is needed.
|
---|
465 | * \param X The source MPI. This must point to an initialized MPI.
|
---|
466 | * \param radix The numeric base to be used in the emitted string.
|
---|
467 | * \param fout The output file handle. This may be \c NULL, in which case
|
---|
468 | * the output is written to \c stdout.
|
---|
469 | *
|
---|
470 | * \return \c 0 if successful.
|
---|
471 | * \return A negative error code on failure.
|
---|
472 | */
|
---|
473 | int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X,
|
---|
474 | int radix, FILE *fout );
|
---|
475 | #endif /* MBEDTLS_FS_IO */
|
---|
476 |
|
---|
477 | /**
|
---|
478 | * \brief Import an MPI from unsigned big endian binary data.
|
---|
479 | *
|
---|
480 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
481 | * \param buf The input buffer. This must be a readable buffer of length
|
---|
482 | * \p buflen Bytes.
|
---|
483 | * \param buflen The length of the input buffer \p p in Bytes.
|
---|
484 | *
|
---|
485 | * \return \c 0 if successful.
|
---|
486 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
|
---|
487 | * \return Another negative error code on different kinds of failure.
|
---|
488 | */
|
---|
489 | int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf,
|
---|
490 | size_t buflen );
|
---|
491 |
|
---|
492 | /**
|
---|
493 | * \brief Export an MPI into unsigned big endian binary data
|
---|
494 | * of fixed size.
|
---|
495 | *
|
---|
496 | * \param X The source MPI. This must point to an initialized MPI.
|
---|
497 | * \param buf The output buffer. This must be a writable buffer of length
|
---|
498 | * \p buflen Bytes.
|
---|
499 | * \param buflen The size of the output buffer \p buf in Bytes.
|
---|
500 | *
|
---|
501 | * \return \c 0 if successful.
|
---|
502 | * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't
|
---|
503 | * large enough to hold the value of \p X.
|
---|
504 | * \return Another negative error code on different kinds of failure.
|
---|
505 | */
|
---|
506 | int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf,
|
---|
507 | size_t buflen );
|
---|
508 |
|
---|
509 | /**
|
---|
510 | * \brief Perform a left-shift on an MPI: X <<= count
|
---|
511 | *
|
---|
512 | * \param X The MPI to shift. This must point to an initialized MPI.
|
---|
513 | * \param count The number of bits to shift by.
|
---|
514 | *
|
---|
515 | * \return \c 0 if successful.
|
---|
516 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
517 | * \return Another negative error code on different kinds of failure.
|
---|
518 | */
|
---|
519 | int mbedtls_mpi_shift_l( mbedtls_mpi *X, size_t count );
|
---|
520 |
|
---|
521 | /**
|
---|
522 | * \brief Perform a right-shift on an MPI: X >>= count
|
---|
523 | *
|
---|
524 | * \param X The MPI to shift. This must point to an initialized MPI.
|
---|
525 | * \param count The number of bits to shift by.
|
---|
526 | *
|
---|
527 | * \return \c 0 if successful.
|
---|
528 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
529 | * \return Another negative error code on different kinds of failure.
|
---|
530 | */
|
---|
531 | int mbedtls_mpi_shift_r( mbedtls_mpi *X, size_t count );
|
---|
532 |
|
---|
533 | /**
|
---|
534 | * \brief Compare the absolute values of two MPIs.
|
---|
535 | *
|
---|
536 | * \param X The left-hand MPI. This must point to an initialized MPI.
|
---|
537 | * \param Y The right-hand MPI. This must point to an initialized MPI.
|
---|
538 | *
|
---|
539 | * \return \c 1 if `|X|` is greater than `|Y|`.
|
---|
540 | * \return \c -1 if `|X|` is lesser than `|Y|`.
|
---|
541 | * \return \c 0 if `|X|` is equal to `|Y|`.
|
---|
542 | */
|
---|
543 | int mbedtls_mpi_cmp_abs( const mbedtls_mpi *X, const mbedtls_mpi *Y );
|
---|
544 |
|
---|
545 | /**
|
---|
546 | * \brief Compare two MPIs.
|
---|
547 | *
|
---|
548 | * \param X The left-hand MPI. This must point to an initialized MPI.
|
---|
549 | * \param Y The right-hand MPI. This must point to an initialized MPI.
|
---|
550 | *
|
---|
551 | * \return \c 1 if \p X is greater than \p Y.
|
---|
552 | * \return \c -1 if \p X is lesser than \p Y.
|
---|
553 | * \return \c 0 if \p X is equal to \p Y.
|
---|
554 | */
|
---|
555 | int mbedtls_mpi_cmp_mpi( const mbedtls_mpi *X, const mbedtls_mpi *Y );
|
---|
556 |
|
---|
557 | /**
|
---|
558 | * \brief Compare an MPI with an integer.
|
---|
559 | *
|
---|
560 | * \param X The left-hand MPI. This must point to an initialized MPI.
|
---|
561 | * \param z The integer value to compare \p X to.
|
---|
562 | *
|
---|
563 | * \return \c 1 if \p X is greater than \p z.
|
---|
564 | * \return \c -1 if \p X is lesser than \p z.
|
---|
565 | * \return \c 0 if \p X is equal to \p z.
|
---|
566 | */
|
---|
567 | int mbedtls_mpi_cmp_int( const mbedtls_mpi *X, mbedtls_mpi_sint z );
|
---|
568 |
|
---|
569 | /**
|
---|
570 | * \brief Perform an unsigned addition of MPIs: X = |A| + |B|
|
---|
571 | *
|
---|
572 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
573 | * \param A The first summand. This must point to an initialized MPI.
|
---|
574 | * \param B The second summand. This must point to an initialized MPI.
|
---|
575 | *
|
---|
576 | * \return \c 0 if successful.
|
---|
577 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
578 | * \return Another negative error code on different kinds of failure.
|
---|
579 | */
|
---|
580 | int mbedtls_mpi_add_abs( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
581 | const mbedtls_mpi *B );
|
---|
582 |
|
---|
583 | /**
|
---|
584 | * \brief Perform an unsigned subtraction of MPIs: X = |A| - |B|
|
---|
585 | *
|
---|
586 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
587 | * \param A The minuend. This must point to an initialized MPI.
|
---|
588 | * \param B The subtrahend. This must point to an initialized MPI.
|
---|
589 | *
|
---|
590 | * \return \c 0 if successful.
|
---|
591 | * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is greater than \p A.
|
---|
592 | * \return Another negative error code on different kinds of failure.
|
---|
593 | *
|
---|
594 | */
|
---|
595 | int mbedtls_mpi_sub_abs( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
596 | const mbedtls_mpi *B );
|
---|
597 |
|
---|
598 | /**
|
---|
599 | * \brief Perform a signed addition of MPIs: X = A + B
|
---|
600 | *
|
---|
601 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
602 | * \param A The first summand. This must point to an initialized MPI.
|
---|
603 | * \param B The second summand. This must point to an initialized MPI.
|
---|
604 | *
|
---|
605 | * \return \c 0 if successful.
|
---|
606 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
607 | * \return Another negative error code on different kinds of failure.
|
---|
608 | */
|
---|
609 | int mbedtls_mpi_add_mpi( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
610 | const mbedtls_mpi *B );
|
---|
611 |
|
---|
612 | /**
|
---|
613 | * \brief Perform a signed subtraction of MPIs: X = A - B
|
---|
614 | *
|
---|
615 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
616 | * \param A The minuend. This must point to an initialized MPI.
|
---|
617 | * \param B The subtrahend. This must point to an initialized MPI.
|
---|
618 | *
|
---|
619 | * \return \c 0 if successful.
|
---|
620 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
621 | * \return Another negative error code on different kinds of failure.
|
---|
622 | */
|
---|
623 | int mbedtls_mpi_sub_mpi( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
624 | const mbedtls_mpi *B );
|
---|
625 |
|
---|
626 | /**
|
---|
627 | * \brief Perform a signed addition of an MPI and an integer: X = A + b
|
---|
628 | *
|
---|
629 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
630 | * \param A The first summand. This must point to an initialized MPI.
|
---|
631 | * \param b The second summand.
|
---|
632 | *
|
---|
633 | * \return \c 0 if successful.
|
---|
634 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
635 | * \return Another negative error code on different kinds of failure.
|
---|
636 | */
|
---|
637 | int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
638 | mbedtls_mpi_sint b );
|
---|
639 |
|
---|
640 | /**
|
---|
641 | * \brief Perform a signed subtraction of an MPI and an integer:
|
---|
642 | * X = A - b
|
---|
643 | *
|
---|
644 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
645 | * \param A The minuend. This must point to an initialized MPI.
|
---|
646 | * \param b The subtrahend.
|
---|
647 | *
|
---|
648 | * \return \c 0 if successful.
|
---|
649 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
650 | * \return Another negative error code on different kinds of failure.
|
---|
651 | */
|
---|
652 | int mbedtls_mpi_sub_int( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
653 | mbedtls_mpi_sint b );
|
---|
654 |
|
---|
655 | /**
|
---|
656 | * \brief Perform a multiplication of two MPIs: X = A * B
|
---|
657 | *
|
---|
658 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
659 | * \param A The first factor. This must point to an initialized MPI.
|
---|
660 | * \param B The second factor. This must point to an initialized MPI.
|
---|
661 | *
|
---|
662 | * \return \c 0 if successful.
|
---|
663 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
664 | * \return Another negative error code on different kinds of failure.
|
---|
665 | *
|
---|
666 | */
|
---|
667 | int mbedtls_mpi_mul_mpi( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
668 | const mbedtls_mpi *B );
|
---|
669 |
|
---|
670 | /**
|
---|
671 | * \brief Perform a multiplication of an MPI with an unsigned integer:
|
---|
672 | * X = A * b
|
---|
673 | *
|
---|
674 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
675 | * \param A The first factor. This must point to an initialized MPI.
|
---|
676 | * \param b The second factor.
|
---|
677 | *
|
---|
678 | * \return \c 0 if successful.
|
---|
679 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
680 | * \return Another negative error code on different kinds of failure.
|
---|
681 | *
|
---|
682 | */
|
---|
683 | int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
684 | mbedtls_mpi_uint b );
|
---|
685 |
|
---|
686 | /**
|
---|
687 | * \brief Perform a division with remainder of two MPIs:
|
---|
688 | * A = Q * B + R
|
---|
689 | *
|
---|
690 | * \param Q The destination MPI for the quotient.
|
---|
691 | * This may be \c NULL if the value of the
|
---|
692 | * quotient is not needed.
|
---|
693 | * \param R The destination MPI for the remainder value.
|
---|
694 | * This may be \c NULL if the value of the
|
---|
695 | * remainder is not needed.
|
---|
696 | * \param A The dividend. This must point to an initialized MPi.
|
---|
697 | * \param B The divisor. This must point to an initialized MPI.
|
---|
698 | *
|
---|
699 | * \return \c 0 if successful.
|
---|
700 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
|
---|
701 | * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero.
|
---|
702 | * \return Another negative error code on different kinds of failure.
|
---|
703 | */
|
---|
704 | int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A,
|
---|
705 | const mbedtls_mpi *B );
|
---|
706 |
|
---|
707 | /**
|
---|
708 | * \brief Perform a division with remainder of an MPI by an integer:
|
---|
709 | * A = Q * b + R
|
---|
710 | *
|
---|
711 | * \param Q The destination MPI for the quotient.
|
---|
712 | * This may be \c NULL if the value of the
|
---|
713 | * quotient is not needed.
|
---|
714 | * \param R The destination MPI for the remainder value.
|
---|
715 | * This may be \c NULL if the value of the
|
---|
716 | * remainder is not needed.
|
---|
717 | * \param A The dividend. This must point to an initialized MPi.
|
---|
718 | * \param b The divisor.
|
---|
719 | *
|
---|
720 | * \return \c 0 if successful.
|
---|
721 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed.
|
---|
722 | * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero.
|
---|
723 | * \return Another negative error code on different kinds of failure.
|
---|
724 | */
|
---|
725 | int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A,
|
---|
726 | mbedtls_mpi_sint b );
|
---|
727 |
|
---|
728 | /**
|
---|
729 | * \brief Perform a modular reduction. R = A mod B
|
---|
730 | *
|
---|
731 | * \param R The destination MPI for the residue value.
|
---|
732 | * This must point to an initialized MPI.
|
---|
733 | * \param A The MPI to compute the residue of.
|
---|
734 | * This must point to an initialized MPI.
|
---|
735 | * \param B The base of the modular reduction.
|
---|
736 | * This must point to an initialized MPI.
|
---|
737 | *
|
---|
738 | * \return \c 0 if successful.
|
---|
739 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
740 | * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero.
|
---|
741 | * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is negative.
|
---|
742 | * \return Another negative error code on different kinds of failure.
|
---|
743 | *
|
---|
744 | */
|
---|
745 | int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A,
|
---|
746 | const mbedtls_mpi *B );
|
---|
747 |
|
---|
748 | /**
|
---|
749 | * \brief Perform a modular reduction with respect to an integer.
|
---|
750 | * r = A mod b
|
---|
751 | *
|
---|
752 | * \param r The address at which to store the residue.
|
---|
753 | * This must not be \c NULL.
|
---|
754 | * \param A The MPI to compute the residue of.
|
---|
755 | * This must point to an initialized MPi.
|
---|
756 | * \param b The integer base of the modular reduction.
|
---|
757 | *
|
---|
758 | * \return \c 0 if successful.
|
---|
759 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
760 | * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero.
|
---|
761 | * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p b is negative.
|
---|
762 | * \return Another negative error code on different kinds of failure.
|
---|
763 | */
|
---|
764 | int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A,
|
---|
765 | mbedtls_mpi_sint b );
|
---|
766 |
|
---|
767 | /**
|
---|
768 | * \brief Perform a sliding-window exponentiation: X = A^E mod N
|
---|
769 | *
|
---|
770 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
771 | * \param A The base of the exponentiation.
|
---|
772 | * This must point to an initialized MPI.
|
---|
773 | * \param E The exponent MPI. This must point to an initialized MPI.
|
---|
774 | * \param N The base for the modular reduction. This must point to an
|
---|
775 | * initialized MPI.
|
---|
776 | * \param _RR A helper MPI depending solely on \p N which can be used to
|
---|
777 | * speed-up multiple modular exponentiations for the same value
|
---|
778 | * of \p N. This may be \c NULL. If it is not \c NULL, it must
|
---|
779 | * point to an initialized MPI. If it hasn't been used after
|
---|
780 | * the call to mbedtls_mpi_init(), this function will compute
|
---|
781 | * the helper value and store it in \p _RR for reuse on
|
---|
782 | * subsequent calls to this function. Otherwise, the function
|
---|
783 | * will assume that \p _RR holds the helper value set by a
|
---|
784 | * previous call to mbedtls_mpi_exp_mod(), and reuse it.
|
---|
785 | *
|
---|
786 | * \return \c 0 if successful.
|
---|
787 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
788 | * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \c N is negative or
|
---|
789 | * even, or if \c E is negative.
|
---|
790 | * \return Another negative error code on different kinds of failures.
|
---|
791 | *
|
---|
792 | */
|
---|
793 | int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
794 | const mbedtls_mpi *E, const mbedtls_mpi *N,
|
---|
795 | mbedtls_mpi *_RR );
|
---|
796 |
|
---|
797 | /**
|
---|
798 | * \brief Fill an MPI with a number of random bytes.
|
---|
799 | *
|
---|
800 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
801 | * \param size The number of random bytes to generate.
|
---|
802 | * \param f_rng The RNG function to use. This must not be \c NULL.
|
---|
803 | * \param p_rng The RNG parameter to be passed to \p f_rng. This may be
|
---|
804 | * \c NULL if \p f_rng doesn't need a context argument.
|
---|
805 | *
|
---|
806 | * \return \c 0 if successful.
|
---|
807 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
808 | * \return Another negative error code on failure.
|
---|
809 | *
|
---|
810 | * \note The bytes obtained from the RNG are interpreted
|
---|
811 | * as a big-endian representation of an MPI; this can
|
---|
812 | * be relevant in applications like deterministic ECDSA.
|
---|
813 | */
|
---|
814 | int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size,
|
---|
815 | int (*f_rng)(void *, unsigned char *, size_t),
|
---|
816 | void *p_rng );
|
---|
817 |
|
---|
818 | /**
|
---|
819 | * \brief Compute the greatest common divisor: G = gcd(A, B)
|
---|
820 | *
|
---|
821 | * \param G The destination MPI. This must point to an initialized MPI.
|
---|
822 | * \param A The first operand. This must point to an initialized MPI.
|
---|
823 | * \param B The second operand. This must point to an initialized MPI.
|
---|
824 | *
|
---|
825 | * \return \c 0 if successful.
|
---|
826 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
827 | * \return Another negative error code on different kinds of failure.
|
---|
828 | */
|
---|
829 | int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A,
|
---|
830 | const mbedtls_mpi *B );
|
---|
831 |
|
---|
832 | /**
|
---|
833 | * \brief Compute the modular inverse: X = A^-1 mod N
|
---|
834 | *
|
---|
835 | * \param X The destination MPI. This must point to an initialized MPI.
|
---|
836 | * \param A The MPI to calculate the modular inverse of. This must point
|
---|
837 | * to an initialized MPI.
|
---|
838 | * \param N The base of the modular inversion. This must point to an
|
---|
839 | * initialized MPI.
|
---|
840 | *
|
---|
841 | * \return \c 0 if successful.
|
---|
842 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
843 | * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p N is less than
|
---|
844 | * or equal to one.
|
---|
845 | * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p has no modular inverse
|
---|
846 | * with respect to \p N.
|
---|
847 | */
|
---|
848 | int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A,
|
---|
849 | const mbedtls_mpi *N );
|
---|
850 |
|
---|
851 | #if !defined(MBEDTLS_DEPRECATED_REMOVED)
|
---|
852 | #if defined(MBEDTLS_DEPRECATED_WARNING)
|
---|
853 | #define MBEDTLS_DEPRECATED __attribute__((deprecated))
|
---|
854 | #else
|
---|
855 | #define MBEDTLS_DEPRECATED
|
---|
856 | #endif
|
---|
857 | /**
|
---|
858 | * \brief Perform a Miller-Rabin primality test with error
|
---|
859 | * probability of 2<sup>-80</sup>.
|
---|
860 | *
|
---|
861 | * \deprecated Superseded by mbedtls_mpi_is_prime_ext() which allows
|
---|
862 | * specifying the number of Miller-Rabin rounds.
|
---|
863 | *
|
---|
864 | * \param X The MPI to check for primality.
|
---|
865 | * This must point to an initialized MPI.
|
---|
866 | * \param f_rng The RNG function to use. This must not be \c NULL.
|
---|
867 | * \param p_rng The RNG parameter to be passed to \p f_rng.
|
---|
868 | * This may be \c NULL if \p f_rng doesn't use a
|
---|
869 | * context parameter.
|
---|
870 | *
|
---|
871 | * \return \c 0 if successful, i.e. \p X is probably prime.
|
---|
872 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
873 | * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p X is not prime.
|
---|
874 | * \return Another negative error code on other kinds of failure.
|
---|
875 | */
|
---|
876 | MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime( const mbedtls_mpi *X,
|
---|
877 | int (*f_rng)(void *, unsigned char *, size_t),
|
---|
878 | void *p_rng );
|
---|
879 | #undef MBEDTLS_DEPRECATED
|
---|
880 | #endif /* !MBEDTLS_DEPRECATED_REMOVED */
|
---|
881 |
|
---|
882 | /**
|
---|
883 | * \brief Miller-Rabin primality test.
|
---|
884 | *
|
---|
885 | * \warning If \p X is potentially generated by an adversary, for example
|
---|
886 | * when validating cryptographic parameters that you didn't
|
---|
887 | * generate yourself and that are supposed to be prime, then
|
---|
888 | * \p rounds should be at least the half of the security
|
---|
889 | * strength of the cryptographic algorithm. On the other hand,
|
---|
890 | * if \p X is chosen uniformly or non-adversially (as is the
|
---|
891 | * case when mbedtls_mpi_gen_prime calls this function), then
|
---|
892 | * \p rounds can be much lower.
|
---|
893 | *
|
---|
894 | * \param X The MPI to check for primality.
|
---|
895 | * This must point to an initialized MPI.
|
---|
896 | * \param rounds The number of bases to perform the Miller-Rabin primality
|
---|
897 | * test for. The probability of returning 0 on a composite is
|
---|
898 | * at most 2<sup>-2*\p rounds</sup>.
|
---|
899 | * \param f_rng The RNG function to use. This must not be \c NULL.
|
---|
900 | * \param p_rng The RNG parameter to be passed to \p f_rng.
|
---|
901 | * This may be \c NULL if \p f_rng doesn't use
|
---|
902 | * a context parameter.
|
---|
903 | *
|
---|
904 | * \return \c 0 if successful, i.e. \p X is probably prime.
|
---|
905 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
906 | * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p X is not prime.
|
---|
907 | * \return Another negative error code on other kinds of failure.
|
---|
908 | */
|
---|
909 | int mbedtls_mpi_is_prime_ext( const mbedtls_mpi *X, int rounds,
|
---|
910 | int (*f_rng)(void *, unsigned char *, size_t),
|
---|
911 | void *p_rng );
|
---|
912 | /**
|
---|
913 | * \brief Flags for mbedtls_mpi_gen_prime()
|
---|
914 | *
|
---|
915 | * Each of these flags is a constraint on the result X returned by
|
---|
916 | * mbedtls_mpi_gen_prime().
|
---|
917 | */
|
---|
918 | typedef enum {
|
---|
919 | MBEDTLS_MPI_GEN_PRIME_FLAG_DH = 0x0001, /**< (X-1)/2 is prime too */
|
---|
920 | MBEDTLS_MPI_GEN_PRIME_FLAG_LOW_ERR = 0x0002, /**< lower error rate from 2<sup>-80</sup> to 2<sup>-128</sup> */
|
---|
921 | } mbedtls_mpi_gen_prime_flag_t;
|
---|
922 |
|
---|
923 | /**
|
---|
924 | * \brief Generate a prime number.
|
---|
925 | *
|
---|
926 | * \param X The destination MPI to store the generated prime in.
|
---|
927 | * This must point to an initialized MPi.
|
---|
928 | * \param nbits The required size of the destination MPI in bits.
|
---|
929 | * This must be between \c 3 and #MBEDTLS_MPI_MAX_BITS.
|
---|
930 | * \param flags A mask of flags of type #mbedtls_mpi_gen_prime_flag_t.
|
---|
931 | * \param f_rng The RNG function to use. This must not be \c NULL.
|
---|
932 | * \param p_rng The RNG parameter to be passed to \p f_rng.
|
---|
933 | * This may be \c NULL if \p f_rng doesn't use
|
---|
934 | * a context parameter.
|
---|
935 | *
|
---|
936 | * \return \c 0 if successful, in which case \p X holds a
|
---|
937 | * probably prime number.
|
---|
938 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed.
|
---|
939 | * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if `nbits` is not between
|
---|
940 | * \c 3 and #MBEDTLS_MPI_MAX_BITS.
|
---|
941 | */
|
---|
942 | int mbedtls_mpi_gen_prime( mbedtls_mpi *X, size_t nbits, int flags,
|
---|
943 | int (*f_rng)(void *, unsigned char *, size_t),
|
---|
944 | void *p_rng );
|
---|
945 |
|
---|
946 | #if defined(MBEDTLS_SELF_TEST)
|
---|
947 |
|
---|
948 | /**
|
---|
949 | * \brief Checkup routine
|
---|
950 | *
|
---|
951 | * \return 0 if successful, or 1 if the test failed
|
---|
952 | */
|
---|
953 | int mbedtls_mpi_self_test( int verbose );
|
---|
954 |
|
---|
955 | #endif /* MBEDTLS_SELF_TEST */
|
---|
956 |
|
---|
957 | #ifdef __cplusplus
|
---|
958 | }
|
---|
959 | #endif
|
---|
960 |
|
---|
961 | #endif /* bignum.h */
|
---|