Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1 | /** |
| 2 | * \file bignum.h |
Paul Bakker | e0ccd0a | 2009-01-04 16:27:10 +0000 | [diff] [blame] | 3 | * |
Darryl Green | a40a101 | 2018-01-05 15:33:17 +0000 | [diff] [blame] | 4 | * \brief Multi-precision integer library |
| 5 | */ |
| 6 | /* |
Bence Szépkúti | 1e14827 | 2020-08-07 13:07:28 +0200 | [diff] [blame] | 7 | * Copyright The Mbed TLS Contributors |
Dave Rodgman | 16799db | 2023-11-02 19:47:20 +0000 | [diff] [blame] | 8 | * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 9 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 10 | #ifndef MBEDTLS_BIGNUM_H |
| 11 | #define MBEDTLS_BIGNUM_H |
Mateusz Starzyk | 846f021 | 2021-05-19 19:44:07 +0200 | [diff] [blame] | 12 | #include "mbedtls/private_access.h" |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 13 | |
Bence Szépkúti | c662b36 | 2021-05-27 11:25:03 +0200 | [diff] [blame] | 14 | #include "mbedtls/build_info.h" |
Paul Bakker | cf0360a | 2012-01-20 10:08:14 +0000 | [diff] [blame] | 15 | |
Rich Evans | 00ab470 | 2015-02-06 13:43:58 +0000 | [diff] [blame] | 16 | #include <stddef.h> |
Manuel Pégourié-Gonnard | ab22910 | 2015-04-15 11:53:16 +0200 | [diff] [blame] | 17 | #include <stdint.h> |
Rich Evans | 00ab470 | 2015-02-06 13:43:58 +0000 | [diff] [blame] | 18 | |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 19 | #if defined(MBEDTLS_FS_IO) |
Manuel Pégourié-Gonnard | e94e6e5 | 2015-01-19 15:01:53 +0000 | [diff] [blame] | 20 | #include <stdio.h> |
| 21 | #endif |
| 22 | |
Gilles Peskine | d297157 | 2021-07-26 18:48:10 +0200 | [diff] [blame] | 23 | /** An error occurred while reading from or writing to a file. */ |
| 24 | #define MBEDTLS_ERR_MPI_FILE_IO_ERROR -0x0002 |
| 25 | /** Bad input parameters to function. */ |
| 26 | #define MBEDTLS_ERR_MPI_BAD_INPUT_DATA -0x0004 |
| 27 | /** There is an invalid character in the digit string. */ |
| 28 | #define MBEDTLS_ERR_MPI_INVALID_CHARACTER -0x0006 |
| 29 | /** The buffer is too small to write to. */ |
| 30 | #define MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL -0x0008 |
| 31 | /** The input arguments are negative or result in illegal output. */ |
| 32 | #define MBEDTLS_ERR_MPI_NEGATIVE_VALUE -0x000A |
| 33 | /** The input argument for division is zero, which is not allowed. */ |
| 34 | #define MBEDTLS_ERR_MPI_DIVISION_BY_ZERO -0x000C |
| 35 | /** The input arguments are not acceptable. */ |
| 36 | #define MBEDTLS_ERR_MPI_NOT_ACCEPTABLE -0x000E |
| 37 | /** Memory allocation failed. */ |
| 38 | #define MBEDTLS_ERR_MPI_ALLOC_FAILED -0x0010 |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 39 | |
Hanno Becker | 1eeca41 | 2018-10-15 12:01:35 +0100 | [diff] [blame] | 40 | #define MBEDTLS_MPI_CHK(f) \ |
| 41 | do \ |
| 42 | { \ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 43 | if ((ret = (f)) != 0) \ |
| 44 | goto cleanup; \ |
| 45 | } while (0) |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 46 | |
Janos Follath | e084964 | 2024-08-12 17:26:24 +0100 | [diff] [blame^] | 47 | /* Constants to identify whether a value is public or secret. If a parameter is marked as secret by |
| 48 | * this constant, the function must be constant time with respect to the parameter. |
| 49 | * |
| 50 | * This is only needed for functions with the _optionally_safe postfix. All other functions have |
| 51 | * fixed behavior that can't be changed at runtime and are constant time with respect to their |
| 52 | * parameters as prescribed by their documentation or by conventions in their module's documentation. |
Manuel Pégourié-Gonnard | 75ed587 | 2024-06-18 12:52:45 +0200 | [diff] [blame] | 53 | * |
| 54 | * Parameters should be named X_public where X is the name of the |
| 55 | * corresponding input parameter. |
| 56 | * |
| 57 | * Implementation should always check using |
| 58 | * if (X_public == MBEDTLS_MPI_IS_PUBLIC) { |
| 59 | * // unsafe path |
| 60 | * } else { |
| 61 | * // safe path |
| 62 | * } |
| 63 | * not the other way round, in order to prevent misuse. (This is, if a value |
| 64 | * other than the two below is passed, default to the safe path.) */ |
| 65 | #define MBEDTLS_MPI_IS_PUBLIC 0x2a2a |
| 66 | #define MBEDTLS_MPI_IS_SECRET 0 |
| 67 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 68 | /* |
Paul Bakker | f968857 | 2011-05-05 10:00:45 +0000 | [diff] [blame] | 69 | * Maximum size MPIs are allowed to grow to in number of limbs. |
| 70 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 71 | #define MBEDTLS_MPI_MAX_LIMBS 10000 |
Paul Bakker | f968857 | 2011-05-05 10:00:45 +0000 | [diff] [blame] | 72 | |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 73 | #if !defined(MBEDTLS_MPI_WINDOW_SIZE) |
Paul Bakker | f968857 | 2011-05-05 10:00:45 +0000 | [diff] [blame] | 74 | /* |
Janos Follath | 6bd5cae | 2024-02-21 11:27:31 +0000 | [diff] [blame] | 75 | * Maximum window size used for modular exponentiation. Default: 3 |
Paul Bakker | b6d5f08 | 2011-11-25 11:52:11 +0000 | [diff] [blame] | 76 | * Minimum value: 1. Maximum value: 6. |
| 77 | * |
Daniel Otte | 6086151 | 2020-09-07 13:07:14 +0200 | [diff] [blame] | 78 | * Result is an array of ( 2 ** MBEDTLS_MPI_WINDOW_SIZE ) MPIs used |
Janos Follath | 6bd5cae | 2024-02-21 11:27:31 +0000 | [diff] [blame] | 79 | * for the sliding window calculation. (So 8 by default) |
Paul Bakker | b6d5f08 | 2011-11-25 11:52:11 +0000 | [diff] [blame] | 80 | * |
| 81 | * Reduction in size, reduces speed. |
| 82 | */ |
Janos Follath | 1609d57 | 2024-02-14 14:58:39 +0000 | [diff] [blame] | 83 | #define MBEDTLS_MPI_WINDOW_SIZE 3 /**< Maximum window size used. */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 84 | #endif /* !MBEDTLS_MPI_WINDOW_SIZE */ |
Paul Bakker | b6d5f08 | 2011-11-25 11:52:11 +0000 | [diff] [blame] | 85 | |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 86 | #if !defined(MBEDTLS_MPI_MAX_SIZE) |
Paul Bakker | b6d5f08 | 2011-11-25 11:52:11 +0000 | [diff] [blame] | 87 | /* |
Paul Bakker | fe3256e | 2011-11-25 12:11:43 +0000 | [diff] [blame] | 88 | * Maximum size of MPIs allowed in bits and bytes for user-MPIs. |
Paul Bakker | f626e1d | 2013-01-21 12:10:00 +0100 | [diff] [blame] | 89 | * ( Default: 512 bytes => 4096 bits, Maximum tested: 2048 bytes => 16384 bits ) |
Paul Bakker | fe3256e | 2011-11-25 12:11:43 +0000 | [diff] [blame] | 90 | * |
Hanno Becker | efeef6c | 2018-01-05 08:07:47 +0000 | [diff] [blame] | 91 | * Note: Calculations can temporarily result in larger MPIs. So the number |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 92 | * of limbs required (MBEDTLS_MPI_MAX_LIMBS) is higher. |
Paul Bakker | fe3256e | 2011-11-25 12:11:43 +0000 | [diff] [blame] | 93 | */ |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 94 | #define MBEDTLS_MPI_MAX_SIZE 1024 /**< Maximum number of bytes for usable MPIs. */ |
| 95 | #endif /* !MBEDTLS_MPI_MAX_SIZE */ |
Paul Bakker | 9bcf16c | 2013-06-24 19:31:17 +0200 | [diff] [blame] | 96 | |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 97 | #define MBEDTLS_MPI_MAX_BITS (8 * MBEDTLS_MPI_MAX_SIZE) /**< Maximum number of bits for usable MPIs. */ |
Paul Bakker | fe3256e | 2011-11-25 12:11:43 +0000 | [diff] [blame] | 98 | |
| 99 | /* |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 100 | * When reading from files with mbedtls_mpi_read_file() and writing to files with |
| 101 | * mbedtls_mpi_write_file() the buffer should have space |
Paul Bakker | cb37aa5 | 2011-11-30 16:00:20 +0000 | [diff] [blame] | 102 | * for a (short) label, the MPI (in the provided radix), the newline |
| 103 | * characters and the '\0'. |
| 104 | * |
| 105 | * By default we assume at least a 10 char label, a minimum radix of 10 |
| 106 | * (decimal) and a maximum of 4096 bit numbers (1234 decimal chars). |
Paul Bakker | f918310 | 2012-09-27 20:42:35 +0000 | [diff] [blame] | 107 | * Autosized at compile time for at least a 10 char label, a minimum radix |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 108 | * of 10 (decimal) for a number of MBEDTLS_MPI_MAX_BITS size. |
Paul Bakker | f918310 | 2012-09-27 20:42:35 +0000 | [diff] [blame] | 109 | * |
| 110 | * This used to be statically sized to 1250 for a maximum of 4096 bit |
| 111 | * numbers (1234 decimal chars). |
| 112 | * |
| 113 | * Calculate using the formula: |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 114 | * MBEDTLS_MPI_RW_BUFFER_SIZE = ceil(MBEDTLS_MPI_MAX_BITS / ln(10) * ln(2)) + |
Paul Bakker | f918310 | 2012-09-27 20:42:35 +0000 | [diff] [blame] | 115 | * LabelSize + 6 |
Paul Bakker | cb37aa5 | 2011-11-30 16:00:20 +0000 | [diff] [blame] | 116 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 117 | #define MBEDTLS_MPI_MAX_BITS_SCALE100 (100 * MBEDTLS_MPI_MAX_BITS) |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 118 | #define MBEDTLS_LN_2_DIV_LN_10_SCALE100 332 |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 119 | #define MBEDTLS_MPI_RW_BUFFER_SIZE (((MBEDTLS_MPI_MAX_BITS_SCALE100 + \ |
| 120 | MBEDTLS_LN_2_DIV_LN_10_SCALE100 - 1) / \ |
| 121 | MBEDTLS_LN_2_DIV_LN_10_SCALE100) + 10 + 6) |
Paul Bakker | cb37aa5 | 2011-11-30 16:00:20 +0000 | [diff] [blame] | 122 | |
| 123 | /* |
Manuel Pégourié-Gonnard | 7b53889 | 2015-04-09 17:00:17 +0200 | [diff] [blame] | 124 | * Define the base integer type, architecture-wise. |
| 125 | * |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 126 | * 32 or 64-bit integer types can be forced regardless of the underlying |
| 127 | * architecture by defining MBEDTLS_HAVE_INT32 or MBEDTLS_HAVE_INT64 |
| 128 | * respectively and undefining MBEDTLS_HAVE_ASM. |
| 129 | * |
Andres Amaya Garcia | 93db11a | 2017-07-20 12:11:19 +0100 | [diff] [blame] | 130 | * Double-width integers (e.g. 128-bit in 64-bit architectures) can be |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 131 | * disabled by defining MBEDTLS_NO_UDBL_DIVISION. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 132 | */ |
Andres Amaya Garcia | aa27dfe | 2017-05-04 11:05:55 +0100 | [diff] [blame] | 133 | #if !defined(MBEDTLS_HAVE_INT32) |
| 134 | #if defined(_MSC_VER) && defined(_M_AMD64) |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 135 | /* Always choose 64-bit when using MSC */ |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 136 | #if !defined(MBEDTLS_HAVE_INT64) |
| 137 | #define MBEDTLS_HAVE_INT64 |
| 138 | #endif /* !MBEDTLS_HAVE_INT64 */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 139 | typedef int64_t mbedtls_mpi_sint; |
| 140 | typedef uint64_t mbedtls_mpi_uint; |
Agathiyan Bragadeesh | eed55c6 | 2023-07-19 11:08:02 +0100 | [diff] [blame] | 141 | #define MBEDTLS_MPI_UINT_MAX UINT64_MAX |
Andres Amaya Garcia | aa27dfe | 2017-05-04 11:05:55 +0100 | [diff] [blame] | 142 | #elif defined(__GNUC__) && ( \ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 143 | defined(__amd64__) || defined(__x86_64__) || \ |
| 144 | defined(__ppc64__) || defined(__powerpc64__) || \ |
| 145 | defined(__ia64__) || defined(__alpha__) || \ |
| 146 | (defined(__sparc__) && defined(__arch64__)) || \ |
| 147 | defined(__s390x__) || defined(__mips64) || \ |
| 148 | defined(__aarch64__)) |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 149 | #if !defined(MBEDTLS_HAVE_INT64) |
| 150 | #define MBEDTLS_HAVE_INT64 |
| 151 | #endif /* MBEDTLS_HAVE_INT64 */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 152 | typedef int64_t mbedtls_mpi_sint; |
| 153 | typedef uint64_t mbedtls_mpi_uint; |
Agathiyan Bragadeesh | eed55c6 | 2023-07-19 11:08:02 +0100 | [diff] [blame] | 154 | #define MBEDTLS_MPI_UINT_MAX UINT64_MAX |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 155 | #if !defined(MBEDTLS_NO_UDBL_DIVISION) |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 156 | /* mbedtls_t_udbl defined as 128-bit unsigned int */ |
| 157 | typedef unsigned int mbedtls_t_udbl __attribute__((mode(TI))); |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 158 | #define MBEDTLS_HAVE_UDBL |
| 159 | #endif /* !MBEDTLS_NO_UDBL_DIVISION */ |
Ko- | 05cff95 | 2018-08-20 12:59:57 +0100 | [diff] [blame] | 160 | #elif defined(__ARMCC_VERSION) && defined(__aarch64__) |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 161 | /* |
| 162 | * __ARMCC_VERSION is defined for both armcc and armclang and |
| 163 | * __aarch64__ is only defined by armclang when compiling 64-bit code |
| 164 | */ |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 165 | #if !defined(MBEDTLS_HAVE_INT64) |
| 166 | #define MBEDTLS_HAVE_INT64 |
| 167 | #endif /* !MBEDTLS_HAVE_INT64 */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 168 | typedef int64_t mbedtls_mpi_sint; |
| 169 | typedef uint64_t mbedtls_mpi_uint; |
Agathiyan Bragadeesh | eed55c6 | 2023-07-19 11:08:02 +0100 | [diff] [blame] | 170 | #define MBEDTLS_MPI_UINT_MAX UINT64_MAX |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 171 | #if !defined(MBEDTLS_NO_UDBL_DIVISION) |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 172 | /* mbedtls_t_udbl defined as 128-bit unsigned int */ |
| 173 | typedef __uint128_t mbedtls_t_udbl; |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 174 | #define MBEDTLS_HAVE_UDBL |
| 175 | #endif /* !MBEDTLS_NO_UDBL_DIVISION */ |
| 176 | #elif defined(MBEDTLS_HAVE_INT64) |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 177 | /* Force 64-bit integers with unknown compiler */ |
| 178 | typedef int64_t mbedtls_mpi_sint; |
| 179 | typedef uint64_t mbedtls_mpi_uint; |
Agathiyan Bragadeesh | eed55c6 | 2023-07-19 11:08:02 +0100 | [diff] [blame] | 180 | #define MBEDTLS_MPI_UINT_MAX UINT64_MAX |
Andres Amaya Garcia | aa27dfe | 2017-05-04 11:05:55 +0100 | [diff] [blame] | 181 | #endif |
| 182 | #endif /* !MBEDTLS_HAVE_INT32 */ |
| 183 | |
| 184 | #if !defined(MBEDTLS_HAVE_INT64) |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 185 | /* Default to 32-bit compilation */ |
Andres Amaya Garcia | aa27dfe | 2017-05-04 11:05:55 +0100 | [diff] [blame] | 186 | #if !defined(MBEDTLS_HAVE_INT32) |
| 187 | #define MBEDTLS_HAVE_INT32 |
| 188 | #endif /* !MBEDTLS_HAVE_INT32 */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 189 | typedef int32_t mbedtls_mpi_sint; |
| 190 | typedef uint32_t mbedtls_mpi_uint; |
Agathiyan Bragadeesh | eed55c6 | 2023-07-19 11:08:02 +0100 | [diff] [blame] | 191 | #define MBEDTLS_MPI_UINT_MAX UINT32_MAX |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 192 | #if !defined(MBEDTLS_NO_UDBL_DIVISION) |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 193 | typedef uint64_t mbedtls_t_udbl; |
Andres Amaya Garcia | df1486a | 2017-07-20 17:33:09 +0100 | [diff] [blame] | 194 | #define MBEDTLS_HAVE_UDBL |
Andres Amaya Garcia | d7fce00 | 2017-07-20 11:49:32 +0100 | [diff] [blame] | 195 | #endif /* !MBEDTLS_NO_UDBL_DIVISION */ |
Andres Amaya Garcia | aa27dfe | 2017-05-04 11:05:55 +0100 | [diff] [blame] | 196 | #endif /* !MBEDTLS_HAVE_INT64 */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 197 | |
Dave Rodgman | 85061b9 | 2023-09-06 08:41:05 +0100 | [diff] [blame] | 198 | /* |
| 199 | * Sanity check that exactly one of MBEDTLS_HAVE_INT32 or MBEDTLS_HAVE_INT64 is defined, |
| 200 | * so that code elsewhere doesn't have to check. |
| 201 | */ |
| 202 | #if (!(defined(MBEDTLS_HAVE_INT32) || defined(MBEDTLS_HAVE_INT64))) || \ |
| 203 | (defined(MBEDTLS_HAVE_INT32) && defined(MBEDTLS_HAVE_INT64)) |
| 204 | #error "Only 32-bit or 64-bit limbs are supported in bignum" |
| 205 | #endif |
| 206 | |
Gilles Peskine | 6110a16 | 2022-11-15 21:22:27 +0100 | [diff] [blame] | 207 | /** \typedef mbedtls_mpi_uint |
| 208 | * \brief The type of machine digits in a bignum, called _limbs_. |
| 209 | * |
| 210 | * This is always an unsigned integer type with no padding bits. The size |
| 211 | * is platform-dependent. |
| 212 | */ |
| 213 | |
| 214 | /** \typedef mbedtls_mpi_sint |
| 215 | * \brief The signed type corresponding to #mbedtls_mpi_uint. |
| 216 | * |
| 217 | * This is always an signed integer type with no padding bits. The size |
| 218 | * is platform-dependent. |
| 219 | */ |
| 220 | |
Paul Bakker | 407a0da | 2013-06-27 14:29:21 +0200 | [diff] [blame] | 221 | #ifdef __cplusplus |
| 222 | extern "C" { |
| 223 | #endif |
| 224 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 225 | /** |
| 226 | * \brief MPI structure |
| 227 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 228 | typedef struct mbedtls_mpi { |
Dave Rodgman | 98e632f | 2023-07-11 15:59:14 +0100 | [diff] [blame] | 229 | /** Pointer to limbs. |
| 230 | * |
| 231 | * This may be \c NULL if \c n is 0. |
| 232 | */ |
| 233 | mbedtls_mpi_uint *MBEDTLS_PRIVATE(p); |
| 234 | |
Gilles Peskine | 1288957 | 2022-11-09 21:55:33 +0100 | [diff] [blame] | 235 | /** Sign: -1 if the mpi is negative, 1 otherwise. |
| 236 | * |
| 237 | * The number 0 must be represented with `s = +1`. Although many library |
| 238 | * functions treat all-limbs-zero as equivalent to a valid representation |
| 239 | * of 0 regardless of the sign bit, there are exceptions, so bignum |
| 240 | * functions and external callers must always set \c s to +1 for the |
| 241 | * number zero. |
| 242 | * |
| 243 | * Note that this implies that calloc() or `... = {0}` does not create |
| 244 | * a valid MPI representation. You must call mbedtls_mpi_init(). |
| 245 | */ |
Gilles Peskine | 053022f | 2023-06-29 19:26:48 +0200 | [diff] [blame] | 246 | signed short MBEDTLS_PRIVATE(s); |
Gilles Peskine | 1288957 | 2022-11-09 21:55:33 +0100 | [diff] [blame] | 247 | |
| 248 | /** Total number of limbs in \c p. */ |
Gilles Peskine | 053022f | 2023-06-29 19:26:48 +0200 | [diff] [blame] | 249 | unsigned short MBEDTLS_PRIVATE(n); |
Gilles Peskine | 24a305e | 2023-07-18 13:41:22 +0200 | [diff] [blame] | 250 | /* Make sure that MBEDTLS_MPI_MAX_LIMBS fits in n. |
| 251 | * Use the same limit value on all platforms so that we don't have to |
| 252 | * think about different behavior on the rare platforms where |
| 253 | * unsigned short can store values larger than the minimum required by |
| 254 | * the C language, which is 65535. |
| 255 | */ |
Gilles Peskine | 053022f | 2023-06-29 19:26:48 +0200 | [diff] [blame] | 256 | #if MBEDTLS_MPI_MAX_LIMBS > 65535 |
| 257 | #error "MBEDTLS_MPI_MAX_LIMBS > 65535 is not supported" |
| 258 | #endif |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 259 | } |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 260 | mbedtls_mpi; |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 261 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 262 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 263 | * \brief Initialize an MPI context. |
| 264 | * |
| 265 | * This makes the MPI ready to be set or freed, |
Manuel Pégourié-Gonnard | da61ed3 | 2015-04-30 10:28:51 +0200 | [diff] [blame] | 266 | * but does not define a value for the MPI. |
Paul Bakker | 6c591fa | 2011-05-05 11:49:20 +0000 | [diff] [blame] | 267 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 268 | * \param X The MPI context to initialize. This must not be \c NULL. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 269 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 270 | void mbedtls_mpi_init(mbedtls_mpi *X); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 271 | |
| 272 | /** |
Hanno Becker | 8ce11a3 | 2018-12-19 16:18:52 +0000 | [diff] [blame] | 273 | * \brief This function frees the components of an MPI context. |
Paul Bakker | 6c591fa | 2011-05-05 11:49:20 +0000 | [diff] [blame] | 274 | * |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 275 | * \param X The MPI context to be cleared. This may be \c NULL, |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 276 | * in which case this function is a no-op. If it is |
| 277 | * not \c NULL, it must point to an initialized MPI. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 278 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 279 | void mbedtls_mpi_free(mbedtls_mpi *X); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 280 | |
| 281 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 282 | * \brief Enlarge an MPI to the specified number of limbs. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 283 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 284 | * \note This function does nothing if the MPI is |
| 285 | * already large enough. |
Gilles Peskine | 70ad839 | 2018-03-21 16:28:41 +0100 | [diff] [blame] | 286 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 287 | * \param X The MPI to grow. It must be initialized. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 288 | * \param nblimbs The target number of limbs. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 289 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 290 | * \return \c 0 if successful. |
| 291 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
| 292 | * \return Another negative error code on other kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 293 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 294 | int mbedtls_mpi_grow(mbedtls_mpi *X, size_t nblimbs); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 295 | |
| 296 | /** |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 297 | * \brief This function resizes an MPI downwards, keeping at least the |
| 298 | * specified number of limbs. |
Manuel Pégourié-Gonnard | 5868163 | 2013-11-21 10:39:37 +0100 | [diff] [blame] | 299 | * |
Gilles Peskine | 70ad839 | 2018-03-21 16:28:41 +0100 | [diff] [blame] | 300 | * If \c X is smaller than \c nblimbs, it is resized up |
| 301 | * instead. |
| 302 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 303 | * \param X The MPI to shrink. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 304 | * \param nblimbs The minimum number of limbs to keep. |
Manuel Pégourié-Gonnard | 5868163 | 2013-11-21 10:39:37 +0100 | [diff] [blame] | 305 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 306 | * \return \c 0 if successful. |
| 307 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed |
Gilles Peskine | 70ad839 | 2018-03-21 16:28:41 +0100 | [diff] [blame] | 308 | * (this can only happen when resizing up). |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 309 | * \return Another negative error code on other kinds of failure. |
Manuel Pégourié-Gonnard | 5868163 | 2013-11-21 10:39:37 +0100 | [diff] [blame] | 310 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 311 | int mbedtls_mpi_shrink(mbedtls_mpi *X, size_t nblimbs); |
Manuel Pégourié-Gonnard | 5868163 | 2013-11-21 10:39:37 +0100 | [diff] [blame] | 312 | |
| 313 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 314 | * \brief Make a copy of an MPI. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 315 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 316 | * \param X The destination MPI. This must point to an initialized MPI. |
| 317 | * \param Y The source MPI. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 318 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 319 | * \note The limb-buffer in the destination MPI is enlarged |
| 320 | * if necessary to hold the value in the source MPI. |
| 321 | * |
| 322 | * \return \c 0 if successful. |
| 323 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
| 324 | * \return Another negative error code on other kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 325 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 326 | int mbedtls_mpi_copy(mbedtls_mpi *X, const mbedtls_mpi *Y); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 327 | |
| 328 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 329 | * \brief Swap the contents of two MPIs. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 330 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 331 | * \param X The first MPI. It must be initialized. |
| 332 | * \param Y The second MPI. It must be initialized. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 333 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 334 | void mbedtls_mpi_swap(mbedtls_mpi *X, mbedtls_mpi *Y); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 335 | |
| 336 | /** |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 337 | * \brief Perform a safe conditional copy of MPI which doesn't |
| 338 | * reveal whether the condition was true or not. |
Manuel Pégourié-Gonnard | 71c2c21 | 2013-11-21 16:56:39 +0100 | [diff] [blame] | 339 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 340 | * \param X The MPI to conditionally assign to. This must point |
| 341 | * to an initialized MPI. |
| 342 | * \param Y The MPI to be assigned from. This must point to an |
| 343 | * initialized MPI. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 344 | * \param assign The condition deciding whether to perform the |
Tom Cosgrove | 583816c | 2022-08-18 14:09:18 +0100 | [diff] [blame] | 345 | * assignment or not. Must be either 0 or 1: |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 346 | * * \c 1: Perform the assignment `X = Y`. |
| 347 | * * \c 0: Keep the original value of \p X. |
Manuel Pégourié-Gonnard | 71c2c21 | 2013-11-21 16:56:39 +0100 | [diff] [blame] | 348 | * |
| 349 | * \note This function is equivalent to |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 350 | * `if( assign ) mbedtls_mpi_copy( X, Y );` |
Manuel Pégourié-Gonnard | 71c2c21 | 2013-11-21 16:56:39 +0100 | [diff] [blame] | 351 | * except that it avoids leaking any information about whether |
| 352 | * the assignment was done or not (the above code may leak |
Manuel Pégourié-Gonnard | d728350 | 2013-11-21 20:00:38 +0100 | [diff] [blame] | 353 | * information through branch prediction and/or memory access |
| 354 | * patterns analysis). |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 355 | * |
Tom Cosgrove | 583816c | 2022-08-18 14:09:18 +0100 | [diff] [blame] | 356 | * \warning If \p assign is neither 0 nor 1, the result of this function |
| 357 | * is indeterminate, and the resulting value in \p X might be |
| 358 | * neither its original value nor the value in \p Y. |
| 359 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 360 | * \return \c 0 if successful. |
| 361 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
| 362 | * \return Another negative error code on other kinds of failure. |
Manuel Pégourié-Gonnard | 71c2c21 | 2013-11-21 16:56:39 +0100 | [diff] [blame] | 363 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 364 | int mbedtls_mpi_safe_cond_assign(mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned char assign); |
Manuel Pégourié-Gonnard | 71c2c21 | 2013-11-21 16:56:39 +0100 | [diff] [blame] | 365 | |
| 366 | /** |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 367 | * \brief Perform a safe conditional swap which doesn't |
| 368 | * reveal whether the condition was true or not. |
Manuel Pégourié-Gonnard | a60fe89 | 2013-12-04 21:41:50 +0100 | [diff] [blame] | 369 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 370 | * \param X The first MPI. This must be initialized. |
| 371 | * \param Y The second MPI. This must be initialized. |
Tom Cosgrove | 583816c | 2022-08-18 14:09:18 +0100 | [diff] [blame] | 372 | * \param swap The condition deciding whether to perform |
| 373 | * the swap or not. Must be either 0 or 1: |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 374 | * * \c 1: Swap the values of \p X and \p Y. |
| 375 | * * \c 0: Keep the original values of \p X and \p Y. |
Manuel Pégourié-Gonnard | a60fe89 | 2013-12-04 21:41:50 +0100 | [diff] [blame] | 376 | * |
| 377 | * \note This function is equivalent to |
Tom Cosgrove | 583816c | 2022-08-18 14:09:18 +0100 | [diff] [blame] | 378 | * if( swap ) mbedtls_mpi_swap( X, Y ); |
Manuel Pégourié-Gonnard | a60fe89 | 2013-12-04 21:41:50 +0100 | [diff] [blame] | 379 | * except that it avoids leaking any information about whether |
Tom Cosgrove | 583816c | 2022-08-18 14:09:18 +0100 | [diff] [blame] | 380 | * the swap was done or not (the above code may leak |
Manuel Pégourié-Gonnard | a60fe89 | 2013-12-04 21:41:50 +0100 | [diff] [blame] | 381 | * information through branch prediction and/or memory access |
| 382 | * patterns analysis). |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 383 | * |
Tom Cosgrove | 583816c | 2022-08-18 14:09:18 +0100 | [diff] [blame] | 384 | * \warning If \p swap is neither 0 nor 1, the result of this function |
| 385 | * is indeterminate, and both \p X and \p Y might end up with |
| 386 | * values different to either of the original ones. |
| 387 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 388 | * \return \c 0 if successful. |
| 389 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
| 390 | * \return Another negative error code on other kinds of failure. |
| 391 | * |
Manuel Pégourié-Gonnard | a60fe89 | 2013-12-04 21:41:50 +0100 | [diff] [blame] | 392 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 393 | int mbedtls_mpi_safe_cond_swap(mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char swap); |
Manuel Pégourié-Gonnard | a60fe89 | 2013-12-04 21:41:50 +0100 | [diff] [blame] | 394 | |
| 395 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 396 | * \brief Store integer value in MPI. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 397 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 398 | * \param X The MPI to set. This must be initialized. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 399 | * \param z The value to use. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 400 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 401 | * \return \c 0 if successful. |
| 402 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
| 403 | * \return Another negative error code on other kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 404 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 405 | int mbedtls_mpi_lset(mbedtls_mpi *X, mbedtls_mpi_sint z); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 406 | |
Paul Bakker | 9a73632 | 2012-11-14 12:39:52 +0000 | [diff] [blame] | 407 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 408 | * \brief Get a specific bit from an MPI. |
Paul Bakker | 2f5947e | 2011-05-18 15:47:11 +0000 | [diff] [blame] | 409 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 410 | * \param X The MPI to query. This must be initialized. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 411 | * \param pos Zero-based index of the bit to query. |
Paul Bakker | 2f5947e | 2011-05-18 15:47:11 +0000 | [diff] [blame] | 412 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 413 | * \return \c 0 or \c 1 on success, depending on whether bit \c pos |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 414 | * of \c X is unset or set. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 415 | * \return A negative error code on failure. |
Paul Bakker | 2f5947e | 2011-05-18 15:47:11 +0000 | [diff] [blame] | 416 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 417 | int mbedtls_mpi_get_bit(const mbedtls_mpi *X, size_t pos); |
Paul Bakker | 2f5947e | 2011-05-18 15:47:11 +0000 | [diff] [blame] | 418 | |
Paul Bakker | 9a73632 | 2012-11-14 12:39:52 +0000 | [diff] [blame] | 419 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 420 | * \brief Modify a specific bit in an MPI. |
Paul Bakker | 2f5947e | 2011-05-18 15:47:11 +0000 | [diff] [blame] | 421 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 422 | * \note This function will grow the target MPI if necessary to set a |
| 423 | * bit to \c 1 in a not yet existing limb. It will not grow if |
| 424 | * the bit should be set to \c 0. |
Paul Bakker | 2f5947e | 2011-05-18 15:47:11 +0000 | [diff] [blame] | 425 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 426 | * \param X The MPI to modify. This must be initialized. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 427 | * \param pos Zero-based index of the bit to modify. |
| 428 | * \param val The desired value of bit \c pos: \c 0 or \c 1. |
Paul Bakker | 2f5947e | 2011-05-18 15:47:11 +0000 | [diff] [blame] | 429 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 430 | * \return \c 0 if successful. |
| 431 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
| 432 | * \return Another negative error code on other kinds of failure. |
Paul Bakker | 2f5947e | 2011-05-18 15:47:11 +0000 | [diff] [blame] | 433 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 434 | int mbedtls_mpi_set_bit(mbedtls_mpi *X, size_t pos, unsigned char val); |
Paul Bakker | 2f5947e | 2011-05-18 15:47:11 +0000 | [diff] [blame] | 435 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 436 | /** |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 437 | * \brief Return the number of bits of value \c 0 before the |
| 438 | * least significant bit of value \c 1. |
Paul Bakker | 6b906e5 | 2012-05-08 12:01:43 +0000 | [diff] [blame] | 439 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 440 | * \note This is the same as the zero-based index of |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 441 | * the least significant bit of value \c 1. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 442 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 443 | * \param X The MPI to query. |
| 444 | * |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 445 | * \return The number of bits of value \c 0 before the least significant |
| 446 | * bit of value \c 1 in \p X. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 447 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 448 | size_t mbedtls_mpi_lsb(const mbedtls_mpi *X); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 449 | |
| 450 | /** |
Paul Bakker | 6b906e5 | 2012-05-08 12:01:43 +0000 | [diff] [blame] | 451 | * \brief Return the number of bits up to and including the most |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 452 | * significant bit of value \c 1. |
Paul Bakker | 6b906e5 | 2012-05-08 12:01:43 +0000 | [diff] [blame] | 453 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 454 | * * \note This is same as the one-based index of the most |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 455 | * significant bit of value \c 1. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 456 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 457 | * \param X The MPI to query. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 458 | * |
| 459 | * \return The number of bits up to and including the most |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 460 | * significant bit of value \c 1. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 461 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 462 | size_t mbedtls_mpi_bitlen(const mbedtls_mpi *X); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 463 | |
| 464 | /** |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 465 | * \brief Return the total size of an MPI value in bytes. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 466 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 467 | * \param X The MPI to use. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 468 | * |
| 469 | * \note The value returned by this function may be less than |
| 470 | * the number of bytes used to store \p X internally. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 471 | * This happens if and only if there are trailing bytes |
| 472 | * of value zero. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 473 | * |
| 474 | * \return The least number of bytes capable of storing |
| 475 | * the absolute value of \p X. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 476 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 477 | size_t mbedtls_mpi_size(const mbedtls_mpi *X); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 478 | |
| 479 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 480 | * \brief Import an MPI from an ASCII string. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 481 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 482 | * \param X The destination MPI. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 483 | * \param radix The numeric base of the input string. |
| 484 | * \param s Null-terminated string buffer. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 485 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 486 | * \return \c 0 if successful. |
| 487 | * \return A negative error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 488 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 489 | int mbedtls_mpi_read_string(mbedtls_mpi *X, int radix, const char *s); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 490 | |
| 491 | /** |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 492 | * \brief Export an MPI to an ASCII string. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 493 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 494 | * \param X The source MPI. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 495 | * \param radix The numeric base of the output string. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 496 | * \param buf The buffer to write the string to. This must be writable |
Hanno Becker | d731012 | 2018-12-18 18:11:42 +0000 | [diff] [blame] | 497 | * buffer of length \p buflen Bytes. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 498 | * \param buflen The available size in Bytes of \p buf. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 499 | * \param olen The address at which to store the length of the string |
| 500 | * written, including the final \c NULL byte. This must |
| 501 | * not be \c NULL. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 502 | * |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 503 | * \note You can call this function with `buflen == 0` to obtain the |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 504 | * minimum required buffer size in `*olen`. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 505 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 506 | * \return \c 0 if successful. |
| 507 | * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the target buffer \p buf |
| 508 | * is too small to hold the value of \p X in the desired base. |
| 509 | * In this case, `*olen` is nonetheless updated to contain the |
| 510 | * size of \p buf required for a successful call. |
| 511 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 512 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 513 | int mbedtls_mpi_write_string(const mbedtls_mpi *X, int radix, |
| 514 | char *buf, size_t buflen, size_t *olen); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 515 | |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 516 | #if defined(MBEDTLS_FS_IO) |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 517 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 518 | * \brief Read an MPI from a line in an opened file. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 519 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 520 | * \param X The destination MPI. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 521 | * \param radix The numeric base of the string representation used |
| 522 | * in the source line. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 523 | * \param fin The input file handle to use. This must not be \c NULL. |
Hanno Becker | b2034b7 | 2017-04-26 11:46:46 +0100 | [diff] [blame] | 524 | * |
| 525 | * \note On success, this function advances the file stream |
| 526 | * to the end of the current line or to EOF. |
| 527 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 528 | * The function returns \c 0 on an empty line. |
Hanno Becker | b2034b7 | 2017-04-26 11:46:46 +0100 | [diff] [blame] | 529 | * |
| 530 | * Leading whitespaces are ignored, as is a |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 531 | * '0x' prefix for radix \c 16. |
Hanno Becker | b2034b7 | 2017-04-26 11:46:46 +0100 | [diff] [blame] | 532 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 533 | * \return \c 0 if successful. |
| 534 | * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the file read buffer |
| 535 | * is too small. |
| 536 | * \return Another negative error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 537 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 538 | int mbedtls_mpi_read_file(mbedtls_mpi *X, int radix, FILE *fin); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 539 | |
| 540 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 541 | * \brief Export an MPI into an opened file. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 542 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 543 | * \param p A string prefix to emit prior to the MPI data. |
| 544 | * For example, this might be a label, or "0x" when |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 545 | * printing in base \c 16. This may be \c NULL if no prefix |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 546 | * is needed. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 547 | * \param X The source MPI. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 548 | * \param radix The numeric base to be used in the emitted string. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 549 | * \param fout The output file handle. This may be \c NULL, in which case |
| 550 | * the output is written to \c stdout. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 551 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 552 | * \return \c 0 if successful. |
| 553 | * \return A negative error code on failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 554 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 555 | int mbedtls_mpi_write_file(const char *p, const mbedtls_mpi *X, |
| 556 | int radix, FILE *fout); |
Manuel Pégourié-Gonnard | 2cf5a7c | 2015-04-08 12:49:31 +0200 | [diff] [blame] | 557 | #endif /* MBEDTLS_FS_IO */ |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 558 | |
| 559 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 560 | * \brief Import an MPI from unsigned big endian binary data. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 561 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 562 | * \param X The destination MPI. This must point to an initialized MPI. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 563 | * \param buf The input buffer. This must be a readable buffer of length |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 564 | * \p buflen Bytes. |
Andrzej Kurek | 69ed8c4 | 2022-02-17 10:06:44 -0500 | [diff] [blame] | 565 | * \param buflen The length of the input buffer \p buf in Bytes. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 566 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 567 | * \return \c 0 if successful. |
| 568 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
| 569 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 570 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 571 | int mbedtls_mpi_read_binary(mbedtls_mpi *X, const unsigned char *buf, |
| 572 | size_t buflen); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 573 | |
| 574 | /** |
Janos Follath | a778a94 | 2019-02-13 10:28:28 +0000 | [diff] [blame] | 575 | * \brief Import X from unsigned binary data, little endian |
| 576 | * |
| 577 | * \param X The destination MPI. This must point to an initialized MPI. |
| 578 | * \param buf The input buffer. This must be a readable buffer of length |
| 579 | * \p buflen Bytes. |
Andrzej Kurek | 69ed8c4 | 2022-02-17 10:06:44 -0500 | [diff] [blame] | 580 | * \param buflen The length of the input buffer \p buf in Bytes. |
Janos Follath | a778a94 | 2019-02-13 10:28:28 +0000 | [diff] [blame] | 581 | * |
| 582 | * \return \c 0 if successful. |
| 583 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
| 584 | * \return Another negative error code on different kinds of failure. |
| 585 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 586 | int mbedtls_mpi_read_binary_le(mbedtls_mpi *X, |
| 587 | const unsigned char *buf, size_t buflen); |
Janos Follath | a778a94 | 2019-02-13 10:28:28 +0000 | [diff] [blame] | 588 | |
| 589 | /** |
| 590 | * \brief Export X into unsigned binary data, big endian. |
| 591 | * Always fills the whole buffer, which will start with zeros |
| 592 | * if the number is smaller. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 593 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 594 | * \param X The source MPI. This must point to an initialized MPI. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 595 | * \param buf The output buffer. This must be a writable buffer of length |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 596 | * \p buflen Bytes. |
| 597 | * \param buflen The size of the output buffer \p buf in Bytes. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 598 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 599 | * \return \c 0 if successful. |
| 600 | * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 601 | * large enough to hold the value of \p X. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 602 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 603 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 604 | int mbedtls_mpi_write_binary(const mbedtls_mpi *X, unsigned char *buf, |
| 605 | size_t buflen); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 606 | |
| 607 | /** |
Janos Follath | e344d0f | 2019-02-19 16:17:40 +0000 | [diff] [blame] | 608 | * \brief Export X into unsigned binary data, little endian. |
| 609 | * Always fills the whole buffer, which will end with zeros |
| 610 | * if the number is smaller. |
| 611 | * |
| 612 | * \param X The source MPI. This must point to an initialized MPI. |
| 613 | * \param buf The output buffer. This must be a writable buffer of length |
| 614 | * \p buflen Bytes. |
| 615 | * \param buflen The size of the output buffer \p buf in Bytes. |
| 616 | * |
| 617 | * \return \c 0 if successful. |
| 618 | * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't |
| 619 | * large enough to hold the value of \p X. |
| 620 | * \return Another negative error code on different kinds of failure. |
| 621 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 622 | int mbedtls_mpi_write_binary_le(const mbedtls_mpi *X, |
| 623 | unsigned char *buf, size_t buflen); |
Janos Follath | e344d0f | 2019-02-19 16:17:40 +0000 | [diff] [blame] | 624 | |
| 625 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 626 | * \brief Perform a left-shift on an MPI: X <<= count |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 627 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 628 | * \param X The MPI to shift. This must point to an initialized MPI. |
Minos Galanakis | 2056d09 | 2023-05-02 14:53:58 +0100 | [diff] [blame] | 629 | * The MPI pointed by \p X may be resized to fit |
| 630 | * the resulting number. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 631 | * \param count The number of bits to shift by. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 632 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 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. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 636 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 637 | int mbedtls_mpi_shift_l(mbedtls_mpi *X, size_t count); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 638 | |
| 639 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 640 | * \brief Perform a right-shift on an MPI: X >>= count |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 641 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 642 | * \param X The MPI to shift. This must point to an initialized MPI. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 643 | * \param count The number of bits to shift by. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 644 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 645 | * \return \c 0 if successful. |
| 646 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 647 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 648 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 649 | int mbedtls_mpi_shift_r(mbedtls_mpi *X, size_t count); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 650 | |
| 651 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 652 | * \brief Compare the absolute values of two MPIs. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 653 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 654 | * \param X The left-hand MPI. This must point to an initialized MPI. |
| 655 | * \param Y The right-hand MPI. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 656 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 657 | * \return \c 1 if `|X|` is greater than `|Y|`. |
| 658 | * \return \c -1 if `|X|` is lesser than `|Y|`. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 659 | * \return \c 0 if `|X|` is equal to `|Y|`. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 660 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 661 | int mbedtls_mpi_cmp_abs(const mbedtls_mpi *X, const mbedtls_mpi *Y); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 662 | |
| 663 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 664 | * \brief Compare two MPIs. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 665 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 666 | * \param X The left-hand MPI. This must point to an initialized MPI. |
| 667 | * \param Y The right-hand MPI. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 668 | * |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 669 | * \return \c 1 if \p X is greater than \p Y. |
| 670 | * \return \c -1 if \p X is lesser than \p Y. |
| 671 | * \return \c 0 if \p X is equal to \p Y. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 672 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 673 | int mbedtls_mpi_cmp_mpi(const mbedtls_mpi *X, const mbedtls_mpi *Y); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 674 | |
| 675 | /** |
Janos Follath | 0e5532d | 2019-10-11 14:21:53 +0100 | [diff] [blame] | 676 | * \brief Check if an MPI is less than the other in constant time. |
Janos Follath | ee6abce | 2019-09-05 14:47:19 +0100 | [diff] [blame] | 677 | * |
| 678 | * \param X The left-hand MPI. This must point to an initialized MPI |
| 679 | * with the same allocated length as Y. |
| 680 | * \param Y The right-hand MPI. This must point to an initialized MPI |
| 681 | * with the same allocated length as X. |
| 682 | * \param ret The result of the comparison: |
Janos Follath | 0e5532d | 2019-10-11 14:21:53 +0100 | [diff] [blame] | 683 | * \c 1 if \p X is less than \p Y. |
| 684 | * \c 0 if \p X is greater than or equal to \p Y. |
Janos Follath | ee6abce | 2019-09-05 14:47:19 +0100 | [diff] [blame] | 685 | * |
| 686 | * \return 0 on success. |
| 687 | * \return MBEDTLS_ERR_MPI_BAD_INPUT_DATA if the allocated length of |
| 688 | * the two input MPIs is not the same. |
| 689 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 690 | int mbedtls_mpi_lt_mpi_ct(const mbedtls_mpi *X, const mbedtls_mpi *Y, |
| 691 | unsigned *ret); |
Janos Follath | ee6abce | 2019-09-05 14:47:19 +0100 | [diff] [blame] | 692 | |
| 693 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 694 | * \brief Compare an MPI with an integer. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 695 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 696 | * \param X The left-hand MPI. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 697 | * \param z The integer value to compare \p X to. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 698 | * |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 699 | * \return \c 1 if \p X is greater than \p z. |
| 700 | * \return \c -1 if \p X is lesser than \p z. |
| 701 | * \return \c 0 if \p X is equal to \p z. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 702 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 703 | int mbedtls_mpi_cmp_int(const mbedtls_mpi *X, mbedtls_mpi_sint z); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 704 | |
| 705 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 706 | * \brief Perform an unsigned addition of MPIs: X = |A| + |B| |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 707 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 708 | * \param X The destination MPI. This must point to an initialized MPI. |
| 709 | * \param A The first summand. This must point to an initialized MPI. |
| 710 | * \param B The second summand. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 711 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 712 | * \return \c 0 if successful. |
| 713 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 714 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 715 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 716 | int mbedtls_mpi_add_abs(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 717 | const mbedtls_mpi *B); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 718 | |
| 719 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 720 | * \brief Perform an unsigned subtraction of MPIs: X = |A| - |B| |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 721 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 722 | * \param X The destination MPI. This must point to an initialized MPI. |
| 723 | * \param A The minuend. This must point to an initialized MPI. |
| 724 | * \param B The subtrahend. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 725 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 726 | * \return \c 0 if successful. |
| 727 | * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is greater than \p A. |
| 728 | * \return Another negative error code on different kinds of failure. |
| 729 | * |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 730 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 731 | int mbedtls_mpi_sub_abs(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 732 | const mbedtls_mpi *B); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 733 | |
| 734 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 735 | * \brief Perform a signed addition of MPIs: X = A + B |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 736 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 737 | * \param X The destination MPI. This must point to an initialized MPI. |
| 738 | * \param A The first summand. This must point to an initialized MPI. |
| 739 | * \param B The second summand. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 740 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 741 | * \return \c 0 if successful. |
| 742 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 743 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 744 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 745 | int mbedtls_mpi_add_mpi(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 746 | const mbedtls_mpi *B); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 747 | |
| 748 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 749 | * \brief Perform a signed subtraction of MPIs: X = A - B |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 750 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 751 | * \param X The destination MPI. This must point to an initialized MPI. |
| 752 | * \param A The minuend. This must point to an initialized MPI. |
| 753 | * \param B The subtrahend. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 754 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 755 | * \return \c 0 if successful. |
| 756 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 757 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 758 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 759 | int mbedtls_mpi_sub_mpi(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 760 | const mbedtls_mpi *B); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 761 | |
| 762 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 763 | * \brief Perform a signed addition of an MPI and an integer: X = A + b |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 764 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 765 | * \param X The destination MPI. This must point to an initialized MPI. |
| 766 | * \param A The first summand. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 767 | * \param b The second summand. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 768 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 769 | * \return \c 0 if successful. |
| 770 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 771 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 772 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 773 | int mbedtls_mpi_add_int(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 774 | mbedtls_mpi_sint b); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 775 | |
| 776 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 777 | * \brief Perform a signed subtraction of an MPI and an integer: |
| 778 | * X = A - b |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 779 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 780 | * \param X The destination MPI. This must point to an initialized MPI. |
| 781 | * \param A The minuend. This must point to an initialized MPI. |
Hanno Becker | 01c3c10 | 2018-12-17 23:04:51 +0000 | [diff] [blame] | 782 | * \param b The subtrahend. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 783 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 784 | * \return \c 0 if successful. |
| 785 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 786 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 787 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 788 | int mbedtls_mpi_sub_int(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 789 | mbedtls_mpi_sint b); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 790 | |
| 791 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 792 | * \brief Perform a multiplication of two MPIs: X = A * B |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 793 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 794 | * \param X The destination MPI. This must point to an initialized MPI. |
| 795 | * \param A The first factor. This must point to an initialized MPI. |
| 796 | * \param B The second factor. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 797 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 798 | * \return \c 0 if successful. |
| 799 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 800 | * \return Another negative error code on different kinds of failure. |
| 801 | * |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 802 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 803 | int mbedtls_mpi_mul_mpi(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 804 | const mbedtls_mpi *B); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 805 | |
| 806 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 807 | * \brief Perform a multiplication of an MPI with an unsigned integer: |
| 808 | * X = A * b |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 809 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 810 | * \param X The destination MPI. This must point to an initialized MPI. |
| 811 | * \param A The first factor. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 812 | * \param b The second factor. |
Manuel Pégourié-Gonnard | 35f1d7f | 2015-03-19 12:42:40 +0000 | [diff] [blame] | 813 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 814 | * \return \c 0 if successful. |
| 815 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 816 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 817 | * |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 818 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 819 | int mbedtls_mpi_mul_int(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 820 | mbedtls_mpi_uint b); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 821 | |
| 822 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 823 | * \brief Perform a division with remainder of two MPIs: |
| 824 | * A = Q * B + R |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 825 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 826 | * \param Q The destination MPI for the quotient. |
Hanno Becker | d01ff49 | 2018-12-18 23:10:28 +0000 | [diff] [blame] | 827 | * This may be \c NULL if the value of the |
Glenn Strauss | 0750d08 | 2022-11-08 02:25:01 -0500 | [diff] [blame] | 828 | * quotient is not needed. This must not alias A or B. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 829 | * \param R The destination MPI for the remainder value. |
Hanno Becker | d01ff49 | 2018-12-18 23:10:28 +0000 | [diff] [blame] | 830 | * This may be \c NULL if the value of the |
Glenn Strauss | 0750d08 | 2022-11-08 02:25:01 -0500 | [diff] [blame] | 831 | * remainder is not needed. This must not alias A or B. |
| 832 | * \param A The dividend. This must point to an initialized MPI. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 833 | * \param B The divisor. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 834 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 835 | * \return \c 0 if successful. |
| 836 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 837 | * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 838 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 839 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 840 | int mbedtls_mpi_div_mpi(mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, |
| 841 | const mbedtls_mpi *B); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 842 | |
| 843 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 844 | * \brief Perform a division with remainder of an MPI by an integer: |
| 845 | * A = Q * b + R |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 846 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 847 | * \param Q The destination MPI for the quotient. |
Hanno Becker | d01ff49 | 2018-12-18 23:10:28 +0000 | [diff] [blame] | 848 | * This may be \c NULL if the value of the |
Glenn Strauss | 0750d08 | 2022-11-08 02:25:01 -0500 | [diff] [blame] | 849 | * quotient is not needed. This must not alias A. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 850 | * \param R The destination MPI for the remainder value. |
Hanno Becker | d01ff49 | 2018-12-18 23:10:28 +0000 | [diff] [blame] | 851 | * This may be \c NULL if the value of the |
Glenn Strauss | 0750d08 | 2022-11-08 02:25:01 -0500 | [diff] [blame] | 852 | * remainder is not needed. This must not alias A. |
Hanno Becker | 8ce11a3 | 2018-12-19 16:18:52 +0000 | [diff] [blame] | 853 | * \param A The dividend. This must point to an initialized MPi. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 854 | * \param b The divisor. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 855 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 856 | * \return \c 0 if successful. |
| 857 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 858 | * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 859 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 860 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 861 | int mbedtls_mpi_div_int(mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, |
| 862 | mbedtls_mpi_sint b); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 863 | |
| 864 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 865 | * \brief Perform a modular reduction. R = A mod B |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 866 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 867 | * \param R The destination MPI for the residue value. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 868 | * This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 869 | * \param A The MPI to compute the residue of. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 870 | * This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 871 | * \param B The base of the modular reduction. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 872 | * This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 873 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 874 | * \return \c 0 if successful. |
| 875 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 876 | * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero. |
| 877 | * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is negative. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 878 | * \return Another negative error code on different kinds of failure. |
| 879 | * |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 880 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 881 | int mbedtls_mpi_mod_mpi(mbedtls_mpi *R, const mbedtls_mpi *A, |
| 882 | const mbedtls_mpi *B); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 883 | |
| 884 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 885 | * \brief Perform a modular reduction with respect to an integer. |
| 886 | * r = A mod b |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 887 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 888 | * \param r The address at which to store the residue. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 889 | * This must not be \c NULL. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 890 | * \param A The MPI to compute the residue of. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 891 | * This must point to an initialized MPi. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 892 | * \param b The integer base of the modular reduction. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 893 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 894 | * \return \c 0 if successful. |
| 895 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 896 | * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero. |
| 897 | * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p b is negative. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 898 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 899 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 900 | int mbedtls_mpi_mod_int(mbedtls_mpi_uint *r, const mbedtls_mpi *A, |
| 901 | mbedtls_mpi_sint b); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 902 | |
| 903 | /** |
Manuel Pégourié-Gonnard | 75ed587 | 2024-06-18 12:52:45 +0200 | [diff] [blame] | 904 | * \brief Perform a modular exponentiation: X = A^E mod N |
| 905 | * |
| 906 | * \param X The destination MPI. This must point to an initialized MPI. |
| 907 | * This must not alias E or N. |
| 908 | * \param A The base of the exponentiation. |
| 909 | * This must point to an initialized MPI. |
| 910 | * \param E The exponent MPI. This must point to an initialized MPI. |
| 911 | * \param N The base for the modular reduction. This must point to an |
| 912 | * initialized MPI. |
| 913 | * \param prec_RR A helper MPI depending solely on \p N which can be used to |
| 914 | * speed-up multiple modular exponentiations for the same value |
| 915 | * of \p N. This may be \c NULL. If it is not \c NULL, it must |
| 916 | * point to an initialized MPI. If it hasn't been used after |
| 917 | * the call to mbedtls_mpi_init(), this function will compute |
| 918 | * the helper value and store it in \p prec_RR for reuse on |
| 919 | * subsequent calls to this function. Otherwise, the function |
| 920 | * will assume that \p prec_RR holds the helper value set by a |
| 921 | * previous call to mbedtls_mpi_exp_mod(), and reuse it. |
| 922 | * |
| 923 | * \return \c 0 if successful. |
| 924 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 925 | * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \c N is negative or |
| 926 | * even, or if \c E is negative. |
| 927 | * \return Another negative error code on different kinds of failures. |
| 928 | * |
| 929 | */ |
| 930 | int mbedtls_mpi_exp_mod_optionally_safe(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 931 | const mbedtls_mpi *E, const mbedtls_mpi *N, |
| 932 | mbedtls_mpi *prec_RR, int E_public); |
| 933 | |
| 934 | /** |
| 935 | * \brief Perform a modular exponentiation: X = A^E mod N |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 936 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 937 | * \param X The destination MPI. This must point to an initialized MPI. |
Glenn Strauss | 0750d08 | 2022-11-08 02:25:01 -0500 | [diff] [blame] | 938 | * This must not alias E or N. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 939 | * \param A The base of the exponentiation. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 940 | * This must point to an initialized MPI. |
| 941 | * \param E The exponent MPI. This must point to an initialized MPI. |
| 942 | * \param N The base for the modular reduction. This must point to an |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 943 | * initialized MPI. |
Yuto Takano | 538a0cb | 2021-07-14 10:20:09 +0100 | [diff] [blame] | 944 | * \param prec_RR A helper MPI depending solely on \p N which can be used to |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 945 | * speed-up multiple modular exponentiations for the same value |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 946 | * of \p N. This may be \c NULL. If it is not \c NULL, it must |
Hanno Becker | 8ce11a3 | 2018-12-19 16:18:52 +0000 | [diff] [blame] | 947 | * point to an initialized MPI. If it hasn't been used after |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 948 | * the call to mbedtls_mpi_init(), this function will compute |
Yuto Takano | 538a0cb | 2021-07-14 10:20:09 +0100 | [diff] [blame] | 949 | * the helper value and store it in \p prec_RR for reuse on |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 950 | * subsequent calls to this function. Otherwise, the function |
Yuto Takano | 538a0cb | 2021-07-14 10:20:09 +0100 | [diff] [blame] | 951 | * will assume that \p prec_RR holds the helper value set by a |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 952 | * previous call to mbedtls_mpi_exp_mod(), and reuse it. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 953 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 954 | * \return \c 0 if successful. |
| 955 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 956 | * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \c N is negative or |
| 957 | * even, or if \c E is negative. |
| 958 | * \return Another negative error code on different kinds of failures. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 959 | * |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 960 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 961 | int mbedtls_mpi_exp_mod(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 962 | const mbedtls_mpi *E, const mbedtls_mpi *N, |
| 963 | mbedtls_mpi *prec_RR); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 964 | |
| 965 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 966 | * \brief Fill an MPI with a number of random bytes. |
Paul Bakker | 287781a | 2011-03-26 13:18:49 +0000 | [diff] [blame] | 967 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 968 | * \param X The destination MPI. This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 969 | * \param size The number of random bytes to generate. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 970 | * \param f_rng The RNG function to use. This must not be \c NULL. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 971 | * \param p_rng The RNG parameter to be passed to \p f_rng. This may be |
| 972 | * \c NULL if \p f_rng doesn't need a context argument. |
Paul Bakker | 287781a | 2011-03-26 13:18:49 +0000 | [diff] [blame] | 973 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 974 | * \return \c 0 if successful. |
| 975 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 976 | * \return Another negative error code on failure. |
Hanno Becker | 15f2b3e | 2017-10-17 15:17:05 +0100 | [diff] [blame] | 977 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 978 | * \note The bytes obtained from the RNG are interpreted |
Hanno Becker | 15f2b3e | 2017-10-17 15:17:05 +0100 | [diff] [blame] | 979 | * as a big-endian representation of an MPI; this can |
| 980 | * be relevant in applications like deterministic ECDSA. |
Paul Bakker | 287781a | 2011-03-26 13:18:49 +0000 | [diff] [blame] | 981 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 982 | int mbedtls_mpi_fill_random(mbedtls_mpi *X, size_t size, |
| 983 | int (*f_rng)(void *, unsigned char *, size_t), |
| 984 | void *p_rng); |
Paul Bakker | 287781a | 2011-03-26 13:18:49 +0000 | [diff] [blame] | 985 | |
Gilles Peskine | 02ac93a | 2021-03-29 22:02:55 +0200 | [diff] [blame] | 986 | /** Generate a random number uniformly in a range. |
| 987 | * |
| 988 | * This function generates a random number between \p min inclusive and |
| 989 | * \p N exclusive. |
| 990 | * |
| 991 | * The procedure complies with RFC 6979 §3.3 (deterministic ECDSA) |
| 992 | * when the RNG is a suitably parametrized instance of HMAC_DRBG |
| 993 | * and \p min is \c 1. |
| 994 | * |
| 995 | * \note There are `N - min` possible outputs. The lower bound |
| 996 | * \p min can be reached, but the upper bound \p N cannot. |
| 997 | * |
| 998 | * \param X The destination MPI. This must point to an initialized MPI. |
| 999 | * \param min The minimum value to return. |
| 1000 | * It must be nonnegative. |
| 1001 | * \param N The upper bound of the range, exclusive. |
| 1002 | * In other words, this is one plus the maximum value to return. |
| 1003 | * \p N must be strictly larger than \p min. |
| 1004 | * \param f_rng The RNG function to use. This must not be \c NULL. |
| 1005 | * \param p_rng The RNG parameter to be passed to \p f_rng. |
| 1006 | * |
| 1007 | * \return \c 0 if successful. |
| 1008 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
Gilles Peskine | 1e918f4 | 2021-03-29 22:14:51 +0200 | [diff] [blame] | 1009 | * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p min or \p N is invalid |
| 1010 | * or if they are incompatible. |
Gilles Peskine | 7ed7c5a | 2021-04-13 21:28:38 +0200 | [diff] [blame] | 1011 | * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if the implementation was |
| 1012 | * unable to find a suitable value within a limited number |
| 1013 | * of attempts. This has a negligible probability if \p N |
| 1014 | * is significantly larger than \p min, which is the case |
| 1015 | * for all usual cryptographic applications. |
Gilles Peskine | 02ac93a | 2021-03-29 22:02:55 +0200 | [diff] [blame] | 1016 | * \return Another negative error code on failure. |
| 1017 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 1018 | int mbedtls_mpi_random(mbedtls_mpi *X, |
| 1019 | mbedtls_mpi_sint min, |
| 1020 | const mbedtls_mpi *N, |
| 1021 | int (*f_rng)(void *, unsigned char *, size_t), |
| 1022 | void *p_rng); |
Gilles Peskine | 02ac93a | 2021-03-29 22:02:55 +0200 | [diff] [blame] | 1023 | |
Paul Bakker | 287781a | 2011-03-26 13:18:49 +0000 | [diff] [blame] | 1024 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1025 | * \brief Compute the greatest common divisor: G = gcd(A, B) |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1026 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 1027 | * \param G The destination MPI. This must point to an initialized MPI. |
| 1028 | * \param A The first operand. This must point to an initialized MPI. |
Hanno Becker | 01c3c10 | 2018-12-17 23:04:51 +0000 | [diff] [blame] | 1029 | * \param B The second operand. This must point to an initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 1030 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1031 | * \return \c 0 if successful. |
| 1032 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 1033 | * \return Another negative error code on different kinds of failure. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1034 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 1035 | int mbedtls_mpi_gcd(mbedtls_mpi *G, const mbedtls_mpi *A, |
| 1036 | const mbedtls_mpi *B); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1037 | |
| 1038 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1039 | * \brief Compute the modular inverse: X = A^-1 mod N |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1040 | * |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 1041 | * \param X The destination MPI. This must point to an initialized MPI. |
| 1042 | * \param A The MPI to calculate the modular inverse of. This must point |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1043 | * to an initialized MPI. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 1044 | * \param N The base of the modular inversion. This must point to an |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1045 | * initialized MPI. |
Paul Bakker | 13e2dfe | 2009-07-28 07:18:38 +0000 | [diff] [blame] | 1046 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1047 | * \return \c 0 if successful. |
| 1048 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 1049 | * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p N is less than |
| 1050 | * or equal to one. |
Andrzej Kurek | 69ed8c4 | 2022-02-17 10:06:44 -0500 | [diff] [blame] | 1051 | * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p A has no modular |
| 1052 | * inverse with respect to \p N. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1053 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 1054 | int mbedtls_mpi_inv_mod(mbedtls_mpi *X, const mbedtls_mpi *A, |
| 1055 | const mbedtls_mpi *N); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1056 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1057 | /** |
Janos Follath | a0b67c2 | 2018-09-18 14:48:23 +0100 | [diff] [blame] | 1058 | * \brief Miller-Rabin primality test. |
| 1059 | * |
| 1060 | * \warning If \p X is potentially generated by an adversary, for example |
| 1061 | * when validating cryptographic parameters that you didn't |
| 1062 | * generate yourself and that are supposed to be prime, then |
| 1063 | * \p rounds should be at least the half of the security |
| 1064 | * strength of the cryptographic algorithm. On the other hand, |
Tom Cosgrove | 1e21144 | 2022-05-26 11:51:00 +0100 | [diff] [blame] | 1065 | * if \p X is chosen uniformly or non-adversarially (as is the |
Janos Follath | a0b67c2 | 2018-09-18 14:48:23 +0100 | [diff] [blame] | 1066 | * case when mbedtls_mpi_gen_prime calls this function), then |
| 1067 | * \p rounds can be much lower. |
| 1068 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1069 | * \param X The MPI to check for primality. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 1070 | * This must point to an initialized MPI. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1071 | * \param rounds The number of bases to perform the Miller-Rabin primality |
| 1072 | * test for. The probability of returning 0 on a composite is |
David Horstmann | d855b46 | 2023-02-23 18:39:16 +0000 | [diff] [blame] | 1073 | * at most 2<sup>-2*\p rounds </sup>. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 1074 | * \param f_rng The RNG function to use. This must not be \c NULL. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1075 | * \param p_rng The RNG parameter to be passed to \p f_rng. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 1076 | * This may be \c NULL if \p f_rng doesn't use |
| 1077 | * a context parameter. |
Janos Follath | a0b67c2 | 2018-09-18 14:48:23 +0100 | [diff] [blame] | 1078 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1079 | * \return \c 0 if successful, i.e. \p X is probably prime. |
| 1080 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 1081 | * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p X is not prime. |
| 1082 | * \return Another negative error code on other kinds of failure. |
Janos Follath | a0b67c2 | 2018-09-18 14:48:23 +0100 | [diff] [blame] | 1083 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 1084 | int mbedtls_mpi_is_prime_ext(const mbedtls_mpi *X, int rounds, |
| 1085 | int (*f_rng)(void *, unsigned char *, size_t), |
| 1086 | void *p_rng); |
Janos Follath | a0b67c2 | 2018-09-18 14:48:23 +0100 | [diff] [blame] | 1087 | /** |
Janos Follath | 7c025a9 | 2018-08-14 11:08:41 +0100 | [diff] [blame] | 1088 | * \brief Flags for mbedtls_mpi_gen_prime() |
| 1089 | * |
| 1090 | * Each of these flags is a constraint on the result X returned by |
| 1091 | * mbedtls_mpi_gen_prime(). |
| 1092 | */ |
| 1093 | typedef enum { |
Janos Follath | f301d23 | 2018-08-14 13:34:01 +0100 | [diff] [blame] | 1094 | MBEDTLS_MPI_GEN_PRIME_FLAG_DH = 0x0001, /**< (X-1)/2 is prime too */ |
| 1095 | MBEDTLS_MPI_GEN_PRIME_FLAG_LOW_ERR = 0x0002, /**< lower error rate from 2<sup>-80</sup> to 2<sup>-128</sup> */ |
Janos Follath | 7c025a9 | 2018-08-14 11:08:41 +0100 | [diff] [blame] | 1096 | } mbedtls_mpi_gen_prime_flag_t; |
| 1097 | |
| 1098 | /** |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1099 | * \brief Generate a prime number. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1100 | * |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1101 | * \param X The destination MPI to store the generated prime in. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 1102 | * This must point to an initialized MPi. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1103 | * \param nbits The required size of the destination MPI in bits. |
Hanno Becker | d01ff49 | 2018-12-18 23:10:28 +0000 | [diff] [blame] | 1104 | * This must be between \c 3 and #MBEDTLS_MPI_MAX_BITS. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1105 | * \param flags A mask of flags of type #mbedtls_mpi_gen_prime_flag_t. |
Hanno Becker | 8282c2f | 2018-12-12 13:36:46 +0000 | [diff] [blame] | 1106 | * \param f_rng The RNG function to use. This must not be \c NULL. |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1107 | * \param p_rng The RNG parameter to be passed to \p f_rng. |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 1108 | * This may be \c NULL if \p f_rng doesn't use |
| 1109 | * a context parameter. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1110 | * |
Hanno Becker | e118504 | 2018-12-13 14:31:46 +0000 | [diff] [blame] | 1111 | * \return \c 0 if successful, in which case \p X holds a |
Hanno Becker | c23483e | 2018-12-10 17:21:19 +0000 | [diff] [blame] | 1112 | * probably prime number. |
| 1113 | * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. |
| 1114 | * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if `nbits` is not between |
| 1115 | * \c 3 and #MBEDTLS_MPI_MAX_BITS. |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1116 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 1117 | int mbedtls_mpi_gen_prime(mbedtls_mpi *X, size_t nbits, int flags, |
| 1118 | int (*f_rng)(void *, unsigned char *, size_t), |
| 1119 | void *p_rng); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1120 | |
Ron Eldor | fa8f635 | 2017-06-20 15:48:46 +0300 | [diff] [blame] | 1121 | #if defined(MBEDTLS_SELF_TEST) |
| 1122 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1123 | /** |
| 1124 | * \brief Checkup routine |
| 1125 | * |
| 1126 | * \return 0 if successful, or 1 if the test failed |
| 1127 | */ |
Gilles Peskine | 449bd83 | 2023-01-11 14:50:10 +0100 | [diff] [blame] | 1128 | int mbedtls_mpi_self_test(int verbose); |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1129 | |
Ron Eldor | fa8f635 | 2017-06-20 15:48:46 +0300 | [diff] [blame] | 1130 | #endif /* MBEDTLS_SELF_TEST */ |
| 1131 | |
Paul Bakker | 5121ce5 | 2009-01-03 21:22:43 +0000 | [diff] [blame] | 1132 | #ifdef __cplusplus |
| 1133 | } |
| 1134 | #endif |
| 1135 | |
| 1136 | #endif /* bignum.h */ |