git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/bignum.h

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