From c23483ed8c8d4523c4b225aec505974891503a79 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Mon, 10 Dec 2018 17:21:19 +0000 Subject: [PATCH 01/14] Document preconditions on parameters in public bignum API --- include/mbedtls/bignum.h | 736 +++++++++++++++++++++++---------------- 1 file changed, 429 insertions(+), 307 deletions(-) diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index 40cfab49af..d8de4a3759 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -186,96 +186,111 @@ typedef struct mbedtls_mpi mbedtls_mpi; /** - * \brief Initialize one MPI (make internal references valid) - * This just makes it ready to be set or freed, + * \brief Initialize an MPI context. + * + * This makes the MPI ready to be set or freed, * but does not define a value for the MPI. * - * \param X One MPI to initialize. + * \param X The MPI context to initialize. Must not be \c NULL. */ void mbedtls_mpi_init( mbedtls_mpi *X ); /** - * \brief Unallocate one MPI + * \brief Clear an MPI context. * - * \param X One MPI to unallocate. + * \param X The MPI context to be cleared. May be \c NULL, + * in which case this function is a no-op. */ void mbedtls_mpi_free( mbedtls_mpi *X ); /** - * \brief Enlarge to the specified number of limbs + * \brief Enlarge an MPI to the specified number of limbs. * - * This function does nothing if the MPI is already large enough. + * \note This function does nothing if the MPI is + * already large enough. * - * \param X MPI to grow - * \param nblimbs The target number of limbs + * \param X The MPI to grow. Must point to an initialized MPI. + * \param nblimbs The target number of limbs. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return Another negative error code on other kinds of failure. */ int mbedtls_mpi_grow( mbedtls_mpi *X, size_t nblimbs ); /** - * \brief Resize down, keeping at least the specified number of limbs + * \brief Resize down, keeping at least the specified number of limbs. * * If \c X is smaller than \c nblimbs, it is resized up * instead. * - * \param X MPI to shrink - * \param nblimbs The minimum number of limbs to keep + * \param X The MPI to shrink. Must point to an initialized MPI. + * \param nblimbs The minimum number of limbs to keep. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed * (this can only happen when resizing up). + * \return Another negative error code on other kinds of failure. */ int mbedtls_mpi_shrink( mbedtls_mpi *X, size_t nblimbs ); /** - * \brief Copy the contents of Y into X + * \brief Make a copy of an MPI. * - * \param X Destination MPI. It is enlarged if necessary. - * \param Y Source MPI. + * \param X The destination MPI. Must point to an initialized MPI. + * \param Y The source MPI. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \note The limb-buffer in the destination MPI is enlarged + * if necessary to hold the value in the source MPI. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return Another negative error code on other kinds of failure. */ int mbedtls_mpi_copy( mbedtls_mpi *X, const mbedtls_mpi *Y ); /** - * \brief Swap the contents of X and Y + * \brief Swap the contents of two MPIs. * - * \param X First MPI value - * \param Y Second MPI value + * \param X The first MPI. Must not be \c NULL. + * \param Y The second MPI. Must not be \c NULL. */ void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y ); /** - * \brief Safe conditional assignement X = Y if assign is 1 + * \brief Safe conditional copy of MPI which doesn't + * reveal whether the conditional was true or not. * - * \param X MPI to conditionally assign to - * \param Y Value to be assigned - * \param assign 1: perform the assignment, 0: keep X's original value - * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, + * \param X The MPI to conditionally assign to. + * \param Y The MPI to be assigned from. + * \param assign The conditional deciding whether to perform the + * assignment or not. Possible values: + * * \c 1: Perform the assignment `X = Y`. + * * \c 0: Keep the original value of \p X. * * \note This function is equivalent to - * if( assign ) mbedtls_mpi_copy( X, Y ); + * `if( assign ) mbedtls_mpi_copy( X, Y );` * except that it avoids leaking any information about whether * the assignment was done or not (the above code may leak * information through branch prediction and/or memory access * patterns analysis). + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return Another negative error code on other kinds of failure. */ int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned char assign ); /** - * \brief Safe conditional swap X <-> Y if swap is 1 + * \brief Safe conditional swap which doesn't + * reveal whether the conditional was true or not. * - * \param X First mbedtls_mpi value - * \param Y Second mbedtls_mpi value - * \param assign 1: perform the swap, 0: keep X and Y's original values - * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, + * \param X The first MPI. + * \param Y The second MPI. + * \param assign The conditional deciding whether to perform + * the swap or not Possible values: + * * \c 1: Swap the values of \p X and \p Y. + * * \c 0: Keep the original values of \p X and \p Y. * * \note This function is equivalent to * if( assign ) mbedtls_mpi_swap( X, Y ); @@ -283,415 +298,506 @@ int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned * the assignment was done or not (the above code may leak * information through branch prediction and/or memory access * patterns analysis). + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return Another negative error code on other kinds of failure. + * */ int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char assign ); /** - * \brief Set value from integer + * \brief Store integer value in MPI. * - * \param X MPI to set - * \param z Value to use + * \param X The MPI to set. + * \param z The value to use. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return Another negative error code on other kinds of failure. */ int mbedtls_mpi_lset( mbedtls_mpi *X, mbedtls_mpi_sint z ); /** - * \brief Get a specific bit from X + * \brief Get a specific bit from an MPI. * - * \param X MPI to use - * \param pos Zero-based index of the bit in X + * \param X The MPI to query. + * \param pos Zero-based index of the bit to query. * - * \return Either a 0 or a 1 + * \return \c 0 or \c 1 on success, depending on whether bit \c pos + * of \c X is unset resp. set. + * \return A negative error code on failure. */ int mbedtls_mpi_get_bit( const mbedtls_mpi *X, size_t pos ); /** - * \brief Set a bit of X to a specific value of 0 or 1 + * \brief Modify a specific bit in an MPI. * - * \note Will grow X if necessary to set a bit to 1 in a not yet - * existing limb. Will not grow if bit should be set to 0 + * \note This function will grow the target MPI if necessary to set a + * bit to \c 1 in a not yet existing limb. It will not grow if + * the bit should be set to \c 0. * - * \param X MPI to use - * \param pos Zero-based index of the bit in X - * \param val The value to set the bit to (0 or 1) + * \param X The MPI to modify. + * \param pos Zero-based index of the bit to modify. + * \param val The desired value of bit \c pos: \c 0 or \c 1. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_BAD_INPUT_DATA if val is not 0 or 1 + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return Another negative error code on other kinds of failure. */ int mbedtls_mpi_set_bit( mbedtls_mpi *X, size_t pos, unsigned char val ); /** - * \brief Return the number of zero-bits before the least significant - * '1' bit + * \brief Return the number of zero-bits before the + * least significant 1-bit * - * Note: Thus also the zero-based index of the least significant '1' bit + * \note This is the same as the zero-based index of + * the least significant '1' bit. * - * \param X MPI to use + * \param X The MPI to query. + * + * \return The number of zero-bits before the least significant + * 1-bit in \p X. */ size_t mbedtls_mpi_lsb( const mbedtls_mpi *X ); /** * \brief Return the number of bits up to and including the most - * significant '1' bit' + * significant 1-bit. * - * Note: Thus also the one-based index of the most significant '1' bit + * * \note This is same as the one-based index of the most + * significant 1-bit. * - * \param X MPI to use + * \param X The MPI to query. Must point to an initialized MPI. + * + * \return The number of bits up to and including the most + * significant 1-bit. */ size_t mbedtls_mpi_bitlen( const mbedtls_mpi *X ); /** - * \brief Return the total size in bytes + * \brief Return the total size an MPI value in bytes. * - * \param X MPI to use + * \param X The MPI to use. Must point to an initialized MPI. + * + * \note The value returned by this function may be less than + * the number of bytes used to store \p X internally. + * This happens if and only if there are trailing zero-bytes. + * + * \return The least number of bytes capable of storing + * the absolute value of \p X. */ size_t mbedtls_mpi_size( const mbedtls_mpi *X ); /** - * \brief Import from an ASCII string + * \brief Import an MPI from an ASCII string. * - * \param X Destination MPI - * \param radix Input numeric base - * \param s Null-terminated string buffer + * \param X The destination MPI. Must point to an initialized MPI. + * \param radix The numeric base of the input string. + * \param s Null-terminated string buffer. * - * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code + * \return \c 0 if successful. + * \return A negative error code on failure. */ int mbedtls_mpi_read_string( mbedtls_mpi *X, int radix, const char *s ); /** - * \brief Export into an ASCII string + * \brief Export an MPI into an ASCII string. * - * \param X Source MPI - * \param radix Output numeric base - * \param buf Buffer to write the string to - * \param buflen Length of buf - * \param olen Length of the string written, including final NUL byte + * \param X The source MPI. Must point to an initialized MPI. + * \param radix The numeric base of the output string. + * \param buf Buffer to write the string to. Must be writable of + * length \p buflen Bytes. May be \c NULL if `buflen == 0`. + * \param buflen The available size in Bytes of \p buf. + * \param olen Address at which to store the length of the string written, + * including final \c NULL byte. Must not be \c NULL. * - * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code. - * *olen is always updated to reflect the amount - * of data that has (or would have) been written. + * \note Call this function with `buflen == 0` to obtain the + * minimum required buffer size in `*olen`. * - * \note Call this function with buflen = 0 to obtain the - * minimum required buffer size in *olen. + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the target buffer \p buf + * is too small to hold the value of \p X in the desired base. + * In this case, `*olen` is nonetheless updated to contain the + * size of \p buf required for a successful call. + * \return Another negative error code on different kinds of failure. */ int mbedtls_mpi_write_string( const mbedtls_mpi *X, int radix, char *buf, size_t buflen, size_t *olen ); #if defined(MBEDTLS_FS_IO) /** - * \brief Read MPI from a line in an opened file + * \brief Read an MPI from a line in an opened file. * - * \param X Destination MPI - * \param radix Input numeric base - * \param fin Input file handle - * - * \return 0 if successful, MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if - * the file read buffer is too small or a - * MBEDTLS_ERR_MPI_XXX error code + * \param X The destination MPI. Must point to an initialized MPI. + * \param radix The numeric base of the string representation used + * in the source line. + * \param fin The input file handle to use. Must not be \c NULL. * * \note On success, this function advances the file stream * to the end of the current line or to EOF. * - * The function returns 0 on an empty line. + * The function returns \c 0 on an empty line. * * Leading whitespaces are ignored, as is a - * '0x' prefix for radix 16. + * '0x' prefix for radix \c 16. * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if the file read buffer + * is too small. + * \return Another negative error code on failure. */ int mbedtls_mpi_read_file( mbedtls_mpi *X, int radix, FILE *fin ); /** - * \brief Write X into an opened file, or stdout if fout is NULL + * \brief Export an MPI into an opened file. * - * \param p Prefix, can be NULL - * \param X Source MPI - * \param radix Output numeric base - * \param fout Output file handle (can be NULL) + * \param p A string prefix to emit prior to the MPI data. + * For example, this might be a label, or "0x" when + * printing in base 16. May be \c NULL if no prefix + * is needed. + * \param X The source MPI. Must point to an initialized MPI. + * \param radix The numeric base to be used in the emitted string. + * \param fout The output file handle. May be \c NULL, in which case + * the output is written to `stdout`. * - * \return 0 if successful, or a MBEDTLS_ERR_MPI_XXX error code - * - * \note Set fout == NULL to print X on the console. + * \return \c 0 if successful. + * \return A negative error code on failure. */ -int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X, int radix, FILE *fout ); +int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X, + int radix, FILE *fout ); #endif /* MBEDTLS_FS_IO */ /** - * \brief Import X from unsigned binary data, big endian + * \brief Import an MPI from unsigned big endian binary data. * - * \param X Destination MPI - * \param buf Input buffer - * \param buflen Input buffer size + * \param X The destination MPI. Must point to an initialized MPI. + * \param buf The input buffer. Must be a readable buffer of length + * \p buflen Bytes. + * \param buflen The length of the input buffer \p p in Bytes. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf, size_t buflen ); +int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf, + size_t buflen ); /** - * \brief Export X into unsigned binary data, big endian. - * Always fills the whole buffer, which will start with zeros - * if the number is smaller. + * \brief Export an MPI into unsigned big endian binary data + * of fixed size. * - * \param X Source MPI - * \param buf Output buffer - * \param buflen Output buffer size + * \param X The source MPI. Must point to an initialized MPI. + * \param buf The output buffer. Must be a writable buffer of length + * \p buflen Bytes. + * \param buflen The size of the output buffer \p buf in Bytes. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if buf isn't large enough + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't + * large enoguh to hold the value of \p X. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf, size_t buflen ); +int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf, + size_t buflen ); /** - * \brief Left-shift: X <<= count + * \brief Perform a left-shift on an MPI: X <<= count * - * \param X MPI to shift - * \param count Amount to shift + * \param X The MPI to shift. Must point to an initialized MPI. + * \param count The amount to shift, in bits. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. */ int mbedtls_mpi_shift_l( mbedtls_mpi *X, size_t count ); /** - * \brief Right-shift: X >>= count + * \brief Perform a right-shift on an MPI: X >>= count * - * \param X MPI to shift - * \param count Amount to shift + * \param X The MPI to shift. Must point to an initialized MPI. + * \param count The amount to shift, in bits. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. */ int mbedtls_mpi_shift_r( mbedtls_mpi *X, size_t count ); /** - * \brief Compare unsigned values + * \brief Compare the absolute values of two MPIs. * - * \param X Left-hand MPI - * \param Y Right-hand MPI + * \param X The left-hand MPI. Must point to an initialized MPI. + * \param Y The right-hand MPI. Must point to an initialized MPI. * - * \return 1 if |X| is greater than |Y|, - * -1 if |X| is lesser than |Y| or - * 0 if |X| is equal to |Y| + * \return \c 1 if `|X|` is greater than `|Y|`. + * \return \c -1 if `|X|` is lesser than `|Y|`. + * \return \c 0 if `|X|` is equal than `|Y|`. */ int mbedtls_mpi_cmp_abs( const mbedtls_mpi *X, const mbedtls_mpi *Y ); /** - * \brief Compare signed values + * \brief Compare two MPIs. * - * \param X Left-hand MPI - * \param Y Right-hand MPI + * \param X The left-hand MPI. Must point to an initialized MPI. + * \param Y The right-hand MPI. Must point to an initialized MPI. * - * \return 1 if X is greater than Y, - * -1 if X is lesser than Y or - * 0 if X is equal to Y + * \return \c 1 if `X` is greater than `Y`. + * \return \c -1 if `X` is lesser than `Y`. + * \return \c 0 if `X` is equal than `Y`. */ int mbedtls_mpi_cmp_mpi( const mbedtls_mpi *X, const mbedtls_mpi *Y ); /** - * \brief Compare signed values + * \brief Compare an MPI with an integer. * - * \param X Left-hand MPI - * \param z The integer value to compare to + * \param X The left-hand MPI. Must point to an initialized MPI. + * \param z The integer value to compare \p X to. * - * \return 1 if X is greater than z, - * -1 if X is lesser than z or - * 0 if X is equal to z + * \return \c 1 if `X` is greater than `z`. + * \return \c -1 if `X` is lesser than `z`. + * \return \c 0 if `X` is equal than `z`. */ int mbedtls_mpi_cmp_int( const mbedtls_mpi *X, mbedtls_mpi_sint z ); /** - * \brief Unsigned addition: X = |A| + |B| + * \brief Perform an unsigned addition of MPIs: X = |A| + |B| * - * \param X Destination MPI - * \param A Left-hand MPI - * \param B Right-hand MPI + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The first summand. Must point to an initialized MPI. + * \param B The second summand. Must point to an initialized MPI. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_add_abs( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B ); +int mbedtls_mpi_add_abs( mbedtls_mpi *X, const mbedtls_mpi *A, + const mbedtls_mpi *B ); /** - * \brief Unsigned subtraction: X = |A| - |B| + * \brief Perform an unsigned subtraction of MPIs: X = |A| - |B| * - * \param X Destination MPI - * \param A Left-hand MPI - * \param B Right-hand MPI + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The minuend. Must point to an initialized MPI. + * \param B The subtrahend. Must point to an initialized MPI. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is greater than \p A. + * \return Another negative error code on different kinds of failure. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_NEGATIVE_VALUE if B is greater than A */ -int mbedtls_mpi_sub_abs( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B ); +int mbedtls_mpi_sub_abs( mbedtls_mpi *X, const mbedtls_mpi *A, + const mbedtls_mpi *B ); /** - * \brief Signed addition: X = A + B + * \brief Perform a signed addition of MPIs: X = A + B * - * \param X Destination MPI - * \param A Left-hand MPI - * \param B Right-hand MPI + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The first summand. Must point to an initialized MPI. + * \param B The second summand. Must point to an initialized MPI. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_add_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B ); +int mbedtls_mpi_add_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, + const mbedtls_mpi *B ); /** - * \brief Signed subtraction: X = A - B + * \brief Perform a signed subtraction of MPIs: X = A - B * - * \param X Destination MPI - * \param A Left-hand MPI - * \param B Right-hand MPI + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The minuend. Must point to an initialized MPI. + * \param B The subtrahend. Must point to an initialized MPI. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_sub_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B ); +int mbedtls_mpi_sub_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, + const mbedtls_mpi *B ); /** - * \brief Signed addition: X = A + b + * \brief Perform a signed addition of an MPI and an integer: X = A + b * - * \param X Destination MPI - * \param A Left-hand MPI - * \param b The integer value to add + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The first summand. Must point to an initialized MPI. + * \param b The second summand. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint b ); +int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A, + mbedtls_mpi_sint b ); /** - * \brief Signed subtraction: X = A - b + * \brief Perform a signed subtraction of an MPI and an integer: + * X = A - b * - * \param X Destination MPI - * \param A Left-hand MPI - * \param b The integer value to subtract + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The minuend. Must point to an initialized MPI. + * \param B The subtrahend. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_sub_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint b ); +int mbedtls_mpi_sub_int( mbedtls_mpi *X, const mbedtls_mpi *A, + mbedtls_mpi_sint b ); /** - * \brief Baseline multiplication: X = A * B + * \brief Perform a multiplication of two MPIs: X = A * B * - * \param X Destination MPI - * \param A Left-hand MPI - * \param B Right-hand MPI + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The first factor. Must point to an initialized MPI. + * \param B The second factor. Must point to an initialized MPI. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed */ -int mbedtls_mpi_mul_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B ); +int mbedtls_mpi_mul_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, + const mbedtls_mpi *B ); /** - * \brief Baseline multiplication: X = A * b + * \brief Perform a multiplication of an MPI with an unsigned integer: + * X = A * b * - * \param X Destination MPI - * \param A Left-hand MPI - * \param b The unsigned integer value to multiply with + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The first factor. Must point to an initialized MPI. + * \param b The second factor. * - * \note b is unsigned + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed */ -int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_uint b ); +int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A, + mbedtls_mpi_uint b ); /** - * \brief Division by mbedtls_mpi: A = Q * B + R + * \brief Perform a division with remainder of two MPIs: + * A = Q * B + R * - * \param Q Destination MPI for the quotient - * \param R Destination MPI for the rest value - * \param A Left-hand MPI - * \param B Right-hand MPI + * \param Q The destination MPI for the quotient. + * May be \c NULL is the value of the quotient is not needed. + * \param R The destination MPI for the remainder value. + * May be \c NULL if the value of the remainder is not needed. + * \param A The divident. Must point to an initialized MPi. + * \param B The divisor. Must point to an initialized MPI. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if B == 0 - * - * \note Either Q or R can be NULL. + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if `B == 0`. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B ); +int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, + const mbedtls_mpi *B ); /** - * \brief Division by int: A = Q * b + R + * \brief Perform a division with remainder of an MPI by an integer: + * A = Q * b + R * - * \param Q Destination MPI for the quotient - * \param R Destination MPI for the rest value - * \param A Left-hand MPI - * \param b Integer to divide by + * \param Q The destination MPI for the quotient. + * May be \c NULL is the value of the quotient is not needed. + * \param R The destination MPI for the remainder value. + * May be \c NULL if the value of the remainder is not needed. + * \param A The divident. Must point to an initialized MPi. + * \param b The divisor. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if b == 0 - * - * \note Either Q or R can be NULL. + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. + * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if `b == 0`. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, mbedtls_mpi_sint b ); +int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, + mbedtls_mpi_sint b ); /** - * \brief Modulo: R = A mod B + * \brief Perform a modular reduction. R = A mod B * - * \param R Destination MPI for the rest value - * \param A Left-hand MPI - * \param B Right-hand MPI + * \param R The destination MPI for the residue value. + * Must point to an initialized MPI. + * \param A The MPI to compute the residue of. + * Must point to an initialized MPI. + * \param B The base of the modular reduction. + * Must point to an initialized MPI. + * + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if `B == 0`. + * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if `B < 0`. + * \return Another negative error code on different kinds of failure. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if B == 0, - * MBEDTLS_ERR_MPI_NEGATIVE_VALUE if B < 0 */ -int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B ); +int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A, + const mbedtls_mpi *B ); /** - * \brief Modulo: r = A mod b + * \brief Perform a modular reduction with respect to an integer. + * r = A mod b * - * \param r Destination mbedtls_mpi_uint - * \param A Left-hand MPI - * \param b Integer to divide by + * \param r The address at which to store the residue. + * Must not be \c NULL. + * \param A The MPI to compute the residue of. + * Must point to an initialized MPi. + * \param b The integer base of the modular reduction. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if b == 0, - * MBEDTLS_ERR_MPI_NEGATIVE_VALUE if b < 0 + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if `b == 0`. + * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if `b < 0`. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A, mbedtls_mpi_sint b ); +int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A, + mbedtls_mpi_sint b ); /** - * \brief Sliding-window exponentiation: X = A^E mod N + * \brief Perform a sliding-window exponentiation: X = A^E mod N * - * \param X Destination MPI - * \param A Left-hand MPI - * \param E Exponent MPI - * \param N Modular MPI - * \param _RR Speed-up MPI used for recalculations + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The base of the exponentiation. + * Must point to an initialized MPI. + * \param E The exponent MPI. Must point to an initialized MPI. + * \param N The base for the modular reduction. Must point to an + * initialized MPI. + * \param _RR A helper MPI depending solely on \p N which can be used to + * speed-up multiple modular exponentiations for the same value + * of \p N. May be \c NULL. If it is not \c NULL, it must point + * an initialized MPI. If it is freshly initialized, i.e. not + * used after the call to mbedtls_mpi_init(), this function + * will compute the helper value and store it in \p _RR for + * reuse on subsequent calls to this function. Otherwise, the + * function will assume that \p _RR holds the helper value set + * by a previous call to mbedtls_mpi_exp_mod(), and reuse it. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_BAD_INPUT_DATA if N is negative or even or - * if E is negative + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \c N is negative or + * even, or if \c E is negative. + * \return Another negative error code on different kinds of failures. * - * \note _RR is used to avoid re-computing R*R mod N across - * multiple calls, which speeds up things a bit. It can - * be set to NULL if the extra performance is unneeded. */ -int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *E, const mbedtls_mpi *N, mbedtls_mpi *_RR ); +int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, + const mbedtls_mpi *E, const mbedtls_mpi *N, + mbedtls_mpi *_RR ); /** - * \brief Fill an MPI X with size bytes of random + * \brief Fill an MPI with a number of random bytes. * - * \param X Destination MPI - * \param size Size in bytes - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param X The destination MPI. Must point to an initialized MPI. + * \param size The number of random bytes to generate. + * \param f_rng The RNG function to use. Must not be \c NULL. + * \param p_rng The RNG parameter to be passed to \p f_rng. May be \c NULL + * if \p f_rng doesn't need a context argument. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on failure. * - * \note The bytes obtained from the PRNG are interpreted + * \note The bytes obtained from the RNG are interpreted * as a big-endian representation of an MPI; this can * be relevant in applications like deterministic ECDSA. */ @@ -700,30 +806,36 @@ int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size, void *p_rng ); /** - * \brief Greatest common divisor: G = gcd(A, B) + * \brief Compute the greatest common divisor: G = gcd(A, B) * - * \param G Destination MPI - * \param A Left-hand MPI - * \param B Right-hand MPI + * \param G The destination MPI. Must point to an initialized MPI. + * \param A The first operand. Must point to an initialized MPI. + * \param A The second operand. Must point to an initialized MPI. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return Another negative error code on different kinds of failure. */ -int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A, const mbedtls_mpi *B ); +int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A, + const mbedtls_mpi *B ); /** - * \brief Modular inverse: X = A^-1 mod N + * \brief Compute the modular inverse: X = A^-1 mod N * - * \param X Destination MPI - * \param A Left-hand MPI - * \param N Right-hand MPI + * \param X The destination MPI. Must point to an initialized MPI. + * \param A The MPI to calculate the modular inverse of. Must point + * to an initialized MPI. + * \param N The base of the modular inversion. Must point to an + * initialized MPI. * - * \return 0 if successful, - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_BAD_INPUT_DATA if N is <= 1, - MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if A has no inverse mod N. + * \return \c 0 if successful. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if `N <= 1`. + * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p has no modular inverse + * with respect to \p N. */ -int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *N ); +int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A, + const mbedtls_mpi *N ); #if !defined(MBEDTLS_DEPRECATED_REMOVED) #if defined(MBEDTLS_DEPRECATED_WARNING) @@ -732,19 +844,22 @@ int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi #define MBEDTLS_DEPRECATED #endif /** - * \brief Miller-Rabin primality test with error probability of - * 2-80 + * \brief Perform a Miller-Rabin primality test with error + * probability of 2-80. * * \deprecated Superseded by mbedtls_mpi_is_prime_ext() which allows * specifying the number of Miller-Rabin rounds. * - * \param X MPI to check - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param X The MPI to check for primality. + * Must point to an initialized MPI. + * \param f_rng The RNG function to use. Must not be \c NULL. + * \param p_rng The RNG parameter to be passed to \p f_rng. + * May be \c NULL if \p f_rng doesn't use a context parameter. * - * \return 0 if successful (probably prime), - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime + * \return \c 0 if successful, i.e. \p X is probably prime. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p X is not prime. + * \return Another negative error code on other kinds of failure. */ MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime( const mbedtls_mpi *X, int (*f_rng)(void *, unsigned char *, size_t), @@ -764,16 +879,19 @@ MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime( const mbedtls_mpi *X, * case when mbedtls_mpi_gen_prime calls this function), then * \p rounds can be much lower. * - * \param X MPI to check - * \param rounds Number of bases to perform Miller-Rabin primality test for. - * The probability of returning 0 on a composite is at most - * 2-2*\p rounds. - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param X The MPI to check for primality. + * Must point to an initialized MPI. + * \param rounds The number of bases to perform the Miller-Rabin primality + * test for. The probability of returning 0 on a composite is + * at most 2-2*\p rounds. + * \param f_rng The RNG function to use. Must not be \c NULL. + * \param p_rng The RNG parameter to be passed to \p f_rng. + * May be \c NULL if \p f_rng doesn't use a context parameter. * - * \return 0 if successful (probably prime), - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if X is not prime + * \return \c 0 if successful, i.e. \p X is probably prime. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p X is not prime. + * \return Another negative error code on other kinds of failure. */ int mbedtls_mpi_is_prime_ext( const mbedtls_mpi *X, int rounds, int (*f_rng)(void *, unsigned char *, size_t), @@ -790,18 +908,22 @@ typedef enum { } mbedtls_mpi_gen_prime_flag_t; /** - * \brief Prime number generation + * \brief Generate a prime number. * - * \param X Destination MPI - * \param nbits Required size of X in bits - * ( 3 <= nbits <= MBEDTLS_MPI_MAX_BITS ) - * \param flags Mask of flags of type #mbedtls_mpi_gen_prime_flag_t - * \param f_rng RNG function - * \param p_rng RNG parameter + * \param X The destination MPI to store the generated prime in. + * Must point to an initialized MPi. + * \param nbits The required size of the destination MPI in bits. + * Must be between \c 3 and #MBEDTLS_MPI_MAX_BITS. + * \param flags A mask of flags of type #mbedtls_mpi_gen_prime_flag_t. + * \param f_rng The RNG function to use. Must not be \c NULL. + * \param p_rng The RNG parameter to be passed to \p f_rng. + * May be \c NULL if \p f_rng doesn't use a context parameter. * - * \return 0 if successful (probably prime), - * MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed, - * MBEDTLS_ERR_MPI_BAD_INPUT_DATA if nbits is < 3 + * \return \c 0 if successful, in which case \p X holds a probably + * probably prime number. + * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. + * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if `nbits` is not between + * \c 3 and #MBEDTLS_MPI_MAX_BITS. */ int mbedtls_mpi_gen_prime( mbedtls_mpi *X, size_t nbits, int flags, int (*f_rng)(void *, unsigned char *, size_t), From 73d7d79bc1789a0a5608094eea6dffbc656d5237 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 11 Dec 2018 10:35:51 +0000 Subject: [PATCH 02/14] Implement parameter validation for MPI module --- library/bignum.c | 144 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 130 insertions(+), 14 deletions(-) diff --git a/library/bignum.c b/library/bignum.c index be4df2fe78..90af7e4953 100644 --- a/library/bignum.c +++ b/library/bignum.c @@ -59,6 +59,11 @@ #define mbedtls_free free #endif +#define MPI_VALIDATE_RET( cond ) \ + MBEDTLS_INTERNAL_VALIDATE_RET( cond, MBEDTLS_ERR_MPI_BAD_INPUT_DATA ) +#define MPI_VALIDATE( cond ) \ + MBEDTLS_INTERNAL_VALIDATE( cond ) + #define ciL (sizeof(mbedtls_mpi_uint)) /* chars in limb */ #define biL (ciL << 3) /* bits in limb */ #define biH (ciL << 2) /* half limb size */ @@ -83,8 +88,7 @@ static void mbedtls_mpi_zeroize( mbedtls_mpi_uint *v, size_t n ) */ void mbedtls_mpi_init( mbedtls_mpi *X ) { - if( X == NULL ) - return; + MPI_VALIDATE( X != NULL ); X->s = 1; X->n = 0; @@ -116,6 +120,7 @@ void mbedtls_mpi_free( mbedtls_mpi *X ) int mbedtls_mpi_grow( mbedtls_mpi *X, size_t nblimbs ) { mbedtls_mpi_uint *p; + MPI_VALIDATE_RET( X != NULL ); if( nblimbs > MBEDTLS_MPI_MAX_LIMBS ) return( MBEDTLS_ERR_MPI_ALLOC_FAILED ); @@ -147,6 +152,10 @@ int mbedtls_mpi_shrink( mbedtls_mpi *X, size_t nblimbs ) { mbedtls_mpi_uint *p; size_t i; + MPI_VALIDATE_RET( X != NULL ); + + if( nblimbs > MBEDTLS_MPI_MAX_LIMBS ) + return( MBEDTLS_ERR_MPI_ALLOC_FAILED ); /* Actually resize up in this case */ if( X->n <= nblimbs ) @@ -183,6 +192,8 @@ int mbedtls_mpi_copy( mbedtls_mpi *X, const mbedtls_mpi *Y ) { int ret = 0; size_t i; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( Y != NULL ); if( X == Y ) return( 0 ); @@ -222,6 +233,8 @@ cleanup: void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y ) { mbedtls_mpi T; + MPI_VALIDATE( X != NULL ); + MPI_VALIDATE( Y != NULL ); memcpy( &T, X, sizeof( mbedtls_mpi ) ); memcpy( X, Y, sizeof( mbedtls_mpi ) ); @@ -237,6 +250,8 @@ int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned { int ret = 0; size_t i; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( Y != NULL ); /* make sure assign is 0 or 1 in a time-constant manner */ assign = (assign | (unsigned char)-assign) >> 7; @@ -266,6 +281,8 @@ int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char sw int ret, s; size_t i; mbedtls_mpi_uint tmp; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( Y != NULL ); if( X == Y ) return( 0 ); @@ -298,6 +315,7 @@ cleanup: int mbedtls_mpi_lset( mbedtls_mpi *X, mbedtls_mpi_sint z ) { int ret; + MPI_VALIDATE_RET( X != NULL ); MBEDTLS_MPI_CHK( mbedtls_mpi_grow( X, 1 ) ); memset( X->p, 0, X->n * ciL ); @@ -315,6 +333,8 @@ cleanup: */ int mbedtls_mpi_get_bit( const mbedtls_mpi *X, size_t pos ) { + MPI_VALIDATE_RET( X != NULL ); + if( X->n * biL <= pos ) return( 0 ); @@ -333,6 +353,7 @@ int mbedtls_mpi_set_bit( mbedtls_mpi *X, size_t pos, unsigned char val ) int ret = 0; size_t off = pos / biL; size_t idx = pos % biL; + MPI_VALIDATE_RET( X != NULL ); if( val != 0 && val != 1 ) return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); @@ -359,6 +380,7 @@ cleanup: size_t mbedtls_mpi_lsb( const mbedtls_mpi *X ) { size_t i, j, count = 0; + MPI_VALIDATE_RET( X != NULL ); for( i = 0; i < X->n; i++ ) for( j = 0; j < biL; j++, count++ ) @@ -439,9 +461,11 @@ int mbedtls_mpi_read_string( mbedtls_mpi *X, int radix, const char *s ) size_t i, j, slen, n; mbedtls_mpi_uint d; mbedtls_mpi T; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( s != NULL ); if( radix < 2 || radix > 16 ) - return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); + return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA );; mbedtls_mpi_init( &T ); @@ -539,9 +563,12 @@ int mbedtls_mpi_write_string( const mbedtls_mpi *X, int radix, size_t n; char *p; mbedtls_mpi T; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( olen != NULL ); + MPI_VALIDATE_RET( buflen == 0 || buf != NULL ); if( radix < 2 || radix > 16 ) - return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); + return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA );; n = mbedtls_mpi_bitlen( X ); if( radix >= 4 ) n >>= 1; @@ -620,6 +647,12 @@ int mbedtls_mpi_read_file( mbedtls_mpi *X, int radix, FILE *fin ) */ char s[ MBEDTLS_MPI_RW_BUFFER_SIZE ]; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( fin != NULL ); + + if( radix < 2 || radix > 16 ) + return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); + memset( s, 0, sizeof( s ) ); if( fgets( s, sizeof( s ) - 1, fin ) == NULL ) return( MBEDTLS_ERR_MPI_FILE_IO_ERROR ); @@ -651,6 +684,10 @@ int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X, int radix, FILE * newline characters and '\0' */ char s[ MBEDTLS_MPI_RW_BUFFER_SIZE ]; + MPI_VALIDATE_RET( X != NULL ); + + if( radix < 2 || radix > 16 ) + return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); memset( s, 0, sizeof( s ) ); @@ -687,6 +724,9 @@ int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf, size_t bu size_t i, j; size_t const limbs = CHARS_TO_LIMBS( buflen ); + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( buflen == 0 || buf != NULL ); + /* Ensure that target MPI has exactly the necessary number of limbs */ if( X->n != limbs ) { @@ -711,11 +751,16 @@ cleanup: int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf, size_t buflen ) { - size_t stored_bytes = X->n * ciL; + size_t stored_bytes; size_t bytes_to_copy; unsigned char *p; size_t i; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( buflen == 0 || buf != NULL ); + + stored_bytes = X->n * ciL; + if( stored_bytes < buflen ) { /* There is enough space in the output buffer. Write initial @@ -754,6 +799,7 @@ int mbedtls_mpi_shift_l( mbedtls_mpi *X, size_t count ) int ret; size_t i, v0, t1; mbedtls_mpi_uint r0 = 0, r1; + MPI_VALIDATE_RET( X != NULL ); v0 = count / (biL ); t1 = count & (biL - 1); @@ -803,6 +849,7 @@ int mbedtls_mpi_shift_r( mbedtls_mpi *X, size_t count ) { size_t i, v0, v1; mbedtls_mpi_uint r0 = 0, r1; + MPI_VALIDATE_RET( X != NULL ); v0 = count / biL; v1 = count & (biL - 1); @@ -845,6 +892,8 @@ int mbedtls_mpi_shift_r( mbedtls_mpi *X, size_t count ) int mbedtls_mpi_cmp_abs( const mbedtls_mpi *X, const mbedtls_mpi *Y ) { size_t i, j; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( Y != NULL ); for( i = X->n; i > 0; i-- ) if( X->p[i - 1] != 0 ) @@ -875,6 +924,8 @@ int mbedtls_mpi_cmp_abs( const mbedtls_mpi *X, const mbedtls_mpi *Y ) int mbedtls_mpi_cmp_mpi( const mbedtls_mpi *X, const mbedtls_mpi *Y ) { size_t i, j; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( Y != NULL ); for( i = X->n; i > 0; i-- ) if( X->p[i - 1] != 0 ) @@ -909,6 +960,7 @@ int mbedtls_mpi_cmp_int( const mbedtls_mpi *X, mbedtls_mpi_sint z ) { mbedtls_mpi Y; mbedtls_mpi_uint p[1]; + MPI_VALIDATE_RET( X != NULL ); *p = ( z < 0 ) ? -z : z; Y.s = ( z < 0 ) ? -1 : 1; @@ -926,6 +978,9 @@ int mbedtls_mpi_add_abs( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi int ret; size_t i, j; mbedtls_mpi_uint *o, *p, c, tmp; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( B != NULL ); if( X == B ) { @@ -1003,6 +1058,9 @@ int mbedtls_mpi_sub_abs( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi mbedtls_mpi TB; int ret; size_t n; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( B != NULL ); if( mbedtls_mpi_cmp_abs( A, B ) < 0 ) return( MBEDTLS_ERR_MPI_NEGATIVE_VALUE ); @@ -1043,8 +1101,12 @@ cleanup: */ int mbedtls_mpi_add_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B ) { - int ret, s = A->s; + int ret, s; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( B != NULL ); + s = A->s; if( A->s * B->s < 0 ) { if( mbedtls_mpi_cmp_abs( A, B ) >= 0 ) @@ -1074,8 +1136,12 @@ cleanup: */ int mbedtls_mpi_sub_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *B ) { - int ret, s = A->s; + int ret, s; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( B != NULL ); + s = A->s; if( A->s * B->s > 0 ) { if( mbedtls_mpi_cmp_abs( A, B ) >= 0 ) @@ -1107,6 +1173,8 @@ int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint { mbedtls_mpi _B; mbedtls_mpi_uint p[1]; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); p[0] = ( b < 0 ) ? -b : b; _B.s = ( b < 0 ) ? -1 : 1; @@ -1123,6 +1191,8 @@ int mbedtls_mpi_sub_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_sint { mbedtls_mpi _B; mbedtls_mpi_uint p[1]; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); p[0] = ( b < 0 ) ? -b : b; _B.s = ( b < 0 ) ? -1 : 1; @@ -1212,6 +1282,9 @@ int mbedtls_mpi_mul_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi int ret; size_t i, j; mbedtls_mpi TA, TB; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( B != NULL ); mbedtls_mpi_init( &TA ); mbedtls_mpi_init( &TB ); @@ -1248,6 +1321,8 @@ int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A, mbedtls_mpi_uint { mbedtls_mpi _B; mbedtls_mpi_uint p[1]; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); _B.s = 1; _B.n = 1; @@ -1356,11 +1431,14 @@ static mbedtls_mpi_uint mbedtls_int_div_int( mbedtls_mpi_uint u1, /* * Division by mbedtls_mpi: A = Q * B + R (HAC 14.20) */ -int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B ) +int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, + const mbedtls_mpi *B ) { int ret; size_t i, n, t, k; mbedtls_mpi X, Y, Z, T1, T2; + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( B != NULL ); if( mbedtls_mpi_cmp_int( B, 0 ) == 0 ) return( MBEDTLS_ERR_MPI_DIVISION_BY_ZERO ); @@ -1471,10 +1549,13 @@ cleanup: /* * Division by int: A = Q * b + R */ -int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, mbedtls_mpi_sint b ) +int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, + const mbedtls_mpi *A, + mbedtls_mpi_sint b ) { mbedtls_mpi _B; mbedtls_mpi_uint p[1]; + MPI_VALIDATE_RET( A != NULL ); p[0] = ( b < 0 ) ? -b : b; _B.s = ( b < 0 ) ? -1 : 1; @@ -1490,6 +1571,9 @@ int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, m int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A, const mbedtls_mpi *B ) { int ret; + MPI_VALIDATE_RET( R != NULL ); + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( B != NULL ); if( mbedtls_mpi_cmp_int( B, 0 ) < 0 ) return( MBEDTLS_ERR_MPI_NEGATIVE_VALUE ); @@ -1514,6 +1598,8 @@ int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A, mbedtls_mpi_ { size_t i; mbedtls_mpi_uint x, y, z; + MPI_VALIDATE_RET( r != NULL ); + MPI_VALIDATE_RET( A != NULL ); if( b == 0 ) return( MBEDTLS_ERR_MPI_DIVISION_BY_ZERO ); @@ -1627,7 +1713,8 @@ static int mpi_montmul( mbedtls_mpi *A, const mbedtls_mpi *B, const mbedtls_mpi /* * Montgomery reduction: A = A * R^-1 mod N */ -static int mpi_montred( mbedtls_mpi *A, const mbedtls_mpi *N, mbedtls_mpi_uint mm, const mbedtls_mpi *T ) +static int mpi_montred( mbedtls_mpi *A, const mbedtls_mpi *N, + mbedtls_mpi_uint mm, const mbedtls_mpi *T ) { mbedtls_mpi_uint z = 1; mbedtls_mpi U; @@ -1641,7 +1728,9 @@ static int mpi_montred( mbedtls_mpi *A, const mbedtls_mpi *N, mbedtls_mpi_uint m /* * Sliding-window exponentiation: X = A^E mod N (HAC 14.85) */ -int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi *E, const mbedtls_mpi *N, mbedtls_mpi *_RR ) +int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, + const mbedtls_mpi *E, const mbedtls_mpi *N, + mbedtls_mpi *_RR ) { int ret; size_t wbits, wsize, one = 1; @@ -1651,6 +1740,11 @@ int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi mbedtls_mpi RR, T, W[ 2 << MBEDTLS_MPI_WINDOW_SIZE ], Apos; int neg; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( E != NULL ); + MPI_VALIDATE_RET( N != NULL ); + if( mbedtls_mpi_cmp_int( N, 0 ) <= 0 || ( N->p[0] & 1 ) == 0 ) return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); @@ -1855,6 +1949,10 @@ int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A, const mbedtls_mpi *B size_t lz, lzt; mbedtls_mpi TG, TA, TB; + MPI_VALIDATE_RET( G != NULL ); + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( B != NULL ); + mbedtls_mpi_init( &TG ); mbedtls_mpi_init( &TA ); mbedtls_mpi_init( &TB ); MBEDTLS_MPI_CHK( mbedtls_mpi_copy( &TA, A ) ); @@ -1911,6 +2009,8 @@ int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size, { int ret; unsigned char buf[MBEDTLS_MPI_MAX_SIZE]; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( f_rng != NULL ); if( size > MBEDTLS_MPI_MAX_SIZE ) return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); @@ -1930,6 +2030,9 @@ int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A, const mbedtls_mpi { int ret; mbedtls_mpi G, TA, TU, U1, U2, TB, TV, V1, V2; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( A != NULL ); + MPI_VALIDATE_RET( N != NULL ); if( mbedtls_mpi_cmp_int( N, 1 ) <= 0 ) return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); @@ -2089,7 +2192,11 @@ static int mpi_miller_rabin( const mbedtls_mpi *X, size_t rounds, size_t i, j, k, s; mbedtls_mpi W, R, T, A, RR; - mbedtls_mpi_init( &W ); mbedtls_mpi_init( &R ); mbedtls_mpi_init( &T ); mbedtls_mpi_init( &A ); + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( f_rng != NULL ); + + mbedtls_mpi_init( &W ); mbedtls_mpi_init( &R ); + mbedtls_mpi_init( &T ); mbedtls_mpi_init( &A ); mbedtls_mpi_init( &RR ); /* @@ -2161,7 +2268,8 @@ static int mpi_miller_rabin( const mbedtls_mpi *X, size_t rounds, } cleanup: - mbedtls_mpi_free( &W ); mbedtls_mpi_free( &R ); mbedtls_mpi_free( &T ); mbedtls_mpi_free( &A ); + mbedtls_mpi_free( &W ); mbedtls_mpi_free( &R ); + mbedtls_mpi_free( &T ); mbedtls_mpi_free( &A ); mbedtls_mpi_free( &RR ); return( ret ); @@ -2176,6 +2284,8 @@ int mbedtls_mpi_is_prime_ext( const mbedtls_mpi *X, int rounds, { int ret; mbedtls_mpi XX; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( f_rng != NULL ); XX.s = 1; XX.n = X->n; @@ -2207,12 +2317,15 @@ int mbedtls_mpi_is_prime( const mbedtls_mpi *X, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ) { + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( f_rng != NULL ); + /* * In the past our key generation aimed for an error rate of at most * 2^-80. Since this function is deprecated, aim for the same certainty * here as well. */ - return mbedtls_mpi_is_prime_ext( X, 40, f_rng, p_rng ); + return( mbedtls_mpi_is_prime_ext( X, 40, f_rng, p_rng ) ); } #endif @@ -2240,6 +2353,9 @@ int mbedtls_mpi_gen_prime( mbedtls_mpi *X, size_t nbits, int flags, mbedtls_mpi_uint r; mbedtls_mpi Y; + MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( f_rng != NULL ); + if( nbits < 3 || nbits > MBEDTLS_MPI_MAX_BITS ) return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); From afb607b9db3c88c95be47bb27477cb0500037121 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 11 Dec 2018 14:27:08 +0000 Subject: [PATCH 03/14] Add tests for parameter validation in MPI module --- tests/suites/test_suite_mpi.data | 3 + tests/suites/test_suite_mpi.function | 175 +++++++++++++++++++++++++++ 2 files changed, 178 insertions(+) diff --git a/tests/suites/test_suite_mpi.data b/tests/suites/test_suite_mpi.data index 6ea3b2943d..ff25a6fcc7 100644 --- a/tests/suites/test_suite_mpi.data +++ b/tests/suites/test_suite_mpi.data @@ -1,3 +1,6 @@ +Parameter validation +mpi_invalid_param: + Arguments with no value mpi_null: diff --git a/tests/suites/test_suite_mpi.function b/tests/suites/test_suite_mpi.function index 9c1d78f7fd..a82bf8181a 100644 --- a/tests/suites/test_suite_mpi.function +++ b/tests/suites/test_suite_mpi.function @@ -50,6 +50,181 @@ int mbedtls_test_mpi_miller_rabin_determinizer( void* state, * END_DEPENDENCIES */ +/* BEGIN_CASE depends_on:MBEDTLS_CHECK_PARAMS:!MBEDTLS_PARAM_FAILED_ALT */ +void mpi_invalid_param( ) +{ + mbedtls_mpi X; + const char *s_in = "00101000101010"; + char s_out[16] = { 0 }; + unsigned char u_out[16] = { 0 }; + unsigned char u_in[16] = { 0 }; + size_t olen; + mbedtls_mpi_uint mpi_uint; + + TEST_INVALID_PARAM( mbedtls_mpi_init( NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_grow( NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_copy( NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_copy( &X, NULL ) ); + TEST_INVALID_PARAM( mbedtls_mpi_swap( NULL, &X ) ); + TEST_INVALID_PARAM( mbedtls_mpi_swap( &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_safe_cond_assign( NULL, &X, 0 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_safe_cond_assign( &X, NULL, 0 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_safe_cond_swap( NULL, &X, 0 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_safe_cond_swap( &X, NULL, 0 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_lset( NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_get_bit( NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_set_bit( NULL, 42, 0 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_read_string( NULL, 2, s_in ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_read_string( &X, 2, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_write_string( NULL, 2, + s_out, sizeof( s_out ), + &olen ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_write_string( &X, 2, + NULL, sizeof( s_out ), + &olen ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_write_string( &X, 2, + s_out, sizeof( s_out ), + NULL ) ); +#if defined(MBEDTLS_FS_IO) + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_read_file( NULL, 2, stdin ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_read_file( &X, 2, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_write_file( "", NULL, 2, NULL ) ); +#endif /* MBEDTLS_FS_IO */ + + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_read_binary( NULL, u_in, + sizeof( u_in ) ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_read_binary( &X, NULL, + sizeof( u_in ) ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_write_binary( NULL, u_out, + sizeof( u_out ) ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_write_binary( &X, NULL, + sizeof( u_out ) ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_shift_l( NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_shift_r( NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_cmp_abs( NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_cmp_abs( &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_cmp_mpi( NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_cmp_mpi( &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_cmp_int( NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_add_abs( NULL, &X, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_add_abs( &X, NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_add_abs( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_sub_abs( NULL, &X, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_sub_abs( &X, NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_sub_abs( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_add_mpi( NULL, &X, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_add_mpi( &X, NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_add_mpi( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_sub_mpi( NULL, &X, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_sub_mpi( &X, NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_sub_mpi( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_add_int( NULL, &X, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_add_int( &X, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_sub_int( NULL, &X, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_sub_int( &X, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mul_mpi( NULL, &X, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mul_mpi( &X, NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mul_mpi( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mul_int( NULL, &X, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mul_int( &X, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_div_mpi( &X, &X, NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_div_mpi( &X, &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_div_int( &X, &X, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mod_mpi( NULL, &X, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mod_mpi( &X, NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mod_mpi( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mod_int( NULL, &X, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_mod_int( &mpi_uint, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_exp_mod( NULL, &X, &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_exp_mod( &X, NULL, &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_exp_mod( &X, &X, NULL, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_exp_mod( &X, &X, &X, NULL, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_fill_random( NULL, 42, rnd_std_rand, + NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_fill_random( &X, 42, NULL, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_gcd( NULL, &X, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_gcd( &X, NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_gcd( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_inv_mod( NULL, &X, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_inv_mod( &X, NULL, &X ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, + mbedtls_mpi_inv_mod( NULL, &X, &X ) ); + +exit: + return; + +} +/* END_CASE */ + /* BEGIN_CASE */ void mpi_null( ) { From 8282c2f0704d4f980a806080f4381eb5cee9a953 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Wed, 12 Dec 2018 13:36:46 +0000 Subject: [PATCH 04/14] Minor improvements to bignum documentation --- include/mbedtls/bignum.h | 175 ++++++++++++++++++++------------------- 1 file changed, 89 insertions(+), 86 deletions(-) diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index d8de4a3759..4f835b4e24 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -191,7 +191,7 @@ mbedtls_mpi; * This makes the MPI ready to be set or freed, * but does not define a value for the MPI. * - * \param X The MPI context to initialize. Must not be \c NULL. + * \param X The MPI context to initialize. This must not be \c NULL. */ void mbedtls_mpi_init( mbedtls_mpi *X ); @@ -199,7 +199,8 @@ void mbedtls_mpi_init( mbedtls_mpi *X ); * \brief Clear an MPI context. * * \param X The MPI context to be cleared. May be \c NULL, - * in which case this function is a no-op. + * in which case this function is a no-op. If it is + * not \c NULL, it must point to an initialized MPI. */ void mbedtls_mpi_free( mbedtls_mpi *X ); @@ -209,7 +210,7 @@ void mbedtls_mpi_free( mbedtls_mpi *X ); * \note This function does nothing if the MPI is * already large enough. * - * \param X The MPI to grow. Must point to an initialized MPI. + * \param X The MPI to grow. It must be initialized. * \param nblimbs The target number of limbs. * * \return \c 0 if successful. @@ -224,7 +225,7 @@ int mbedtls_mpi_grow( mbedtls_mpi *X, size_t nblimbs ); * If \c X is smaller than \c nblimbs, it is resized up * instead. * - * \param X The MPI to shrink. Must point to an initialized MPI. + * \param X The MPI to shrink. This must point to an initialized MPI. * \param nblimbs The minimum number of limbs to keep. * * \return \c 0 if successful. @@ -237,8 +238,8 @@ int mbedtls_mpi_shrink( mbedtls_mpi *X, size_t nblimbs ); /** * \brief Make a copy of an MPI. * - * \param X The destination MPI. Must point to an initialized MPI. - * \param Y The source MPI. + * \param X The destination MPI. This must point to an initialized MPI. + * \param Y The source MPI. This must point to an initialized MPI. * * \note The limb-buffer in the destination MPI is enlarged * if necessary to hold the value in the source MPI. @@ -252,8 +253,8 @@ int mbedtls_mpi_copy( mbedtls_mpi *X, const mbedtls_mpi *Y ); /** * \brief Swap the contents of two MPIs. * - * \param X The first MPI. Must not be \c NULL. - * \param Y The second MPI. Must not be \c NULL. + * \param X The first MPI. It must be initialized. + * \param Y The second MPI. It must be initialized. */ void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y ); @@ -261,8 +262,10 @@ void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y ); * \brief Safe conditional copy of MPI which doesn't * reveal whether the conditional was true or not. * - * \param X The MPI to conditionally assign to. - * \param Y The MPI to be assigned from. + * \param X The MPI to conditionally assign to. This must point + * to an initialized MPI. + * \param Y The MPI to be assigned from. This must point to an + * initialized MPI. * \param assign The conditional deciding whether to perform the * assignment or not. Possible values: * * \c 1: Perform the assignment `X = Y`. @@ -285,10 +288,10 @@ int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned * \brief Safe conditional swap which doesn't * reveal whether the conditional was true or not. * - * \param X The first MPI. - * \param Y The second MPI. + * \param X The first MPI. This must be initialized. + * \param Y The second MPI. This must be initialized. * \param assign The conditional deciding whether to perform - * the swap or not Possible values: + * the swap or not. Possible values: * * \c 1: Swap the values of \p X and \p Y. * * \c 0: Keep the original values of \p X and \p Y. * @@ -309,7 +312,7 @@ int mbedtls_mpi_safe_cond_swap( mbedtls_mpi *X, mbedtls_mpi *Y, unsigned char as /** * \brief Store integer value in MPI. * - * \param X The MPI to set. + * \param X The MPI to set. This must be initialized. * \param z The value to use. * * \return \c 0 if successful. @@ -321,11 +324,11 @@ int mbedtls_mpi_lset( mbedtls_mpi *X, mbedtls_mpi_sint z ); /** * \brief Get a specific bit from an MPI. * - * \param X The MPI to query. + * \param X The MPI to query. This must be initialized. * \param pos Zero-based index of the bit to query. * * \return \c 0 or \c 1 on success, depending on whether bit \c pos - * of \c X is unset resp. set. + * of \c X is unset or set. * \return A negative error code on failure. */ int mbedtls_mpi_get_bit( const mbedtls_mpi *X, size_t pos ); @@ -337,7 +340,7 @@ int mbedtls_mpi_get_bit( const mbedtls_mpi *X, size_t pos ); * bit to \c 1 in a not yet existing limb. It will not grow if * the bit should be set to \c 0. * - * \param X The MPI to modify. + * \param X The MPI to modify. This must be initialized. * \param pos Zero-based index of the bit to modify. * \param val The desired value of bit \c pos: \c 0 or \c 1. * @@ -349,7 +352,7 @@ int mbedtls_mpi_set_bit( mbedtls_mpi *X, size_t pos, unsigned char val ); /** * \brief Return the number of zero-bits before the - * least significant 1-bit + * least significant '1' bit * * \note This is the same as the zero-based index of * the least significant '1' bit. @@ -357,28 +360,28 @@ int mbedtls_mpi_set_bit( mbedtls_mpi *X, size_t pos, unsigned char val ); * \param X The MPI to query. * * \return The number of zero-bits before the least significant - * 1-bit in \p X. + * '1' bit in \p X. */ size_t mbedtls_mpi_lsb( const mbedtls_mpi *X ); /** * \brief Return the number of bits up to and including the most - * significant 1-bit. + * significant '1' bit. * * * \note This is same as the one-based index of the most - * significant 1-bit. + * significant '1' bit. * - * \param X The MPI to query. Must point to an initialized MPI. + * \param X The MPI to query. This must point to an initialized MPI. * * \return The number of bits up to and including the most - * significant 1-bit. + * significant '1' bit. */ size_t mbedtls_mpi_bitlen( const mbedtls_mpi *X ); /** * \brief Return the total size an MPI value in bytes. * - * \param X The MPI to use. Must point to an initialized MPI. + * \param X The MPI to use. This must point to an initialized MPI. * * \note The value returned by this function may be less than * the number of bytes used to store \p X internally. @@ -392,7 +395,7 @@ size_t mbedtls_mpi_size( const mbedtls_mpi *X ); /** * \brief Import an MPI from an ASCII string. * - * \param X The destination MPI. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. * \param radix The numeric base of the input string. * \param s Null-terminated string buffer. * @@ -404,13 +407,13 @@ int mbedtls_mpi_read_string( mbedtls_mpi *X, int radix, const char *s ); /** * \brief Export an MPI into an ASCII string. * - * \param X The source MPI. Must point to an initialized MPI. + * \param X The source MPI. This must point to an initialized MPI. * \param radix The numeric base of the output string. * \param buf Buffer to write the string to. Must be writable of * length \p buflen Bytes. May be \c NULL if `buflen == 0`. * \param buflen The available size in Bytes of \p buf. * \param olen Address at which to store the length of the string written, - * including final \c NULL byte. Must not be \c NULL. + * including final \c NULL byte. This must not be \c NULL. * * \note Call this function with `buflen == 0` to obtain the * minimum required buffer size in `*olen`. @@ -429,10 +432,10 @@ int mbedtls_mpi_write_string( const mbedtls_mpi *X, int radix, /** * \brief Read an MPI from a line in an opened file. * - * \param X The destination MPI. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. * \param radix The numeric base of the string representation used * in the source line. - * \param fin The input file handle to use. Must not be \c NULL. + * \param fin The input file handle to use. This must not be \c NULL. * * \note On success, this function advances the file stream * to the end of the current line or to EOF. @@ -456,7 +459,7 @@ int mbedtls_mpi_read_file( mbedtls_mpi *X, int radix, FILE *fin ); * For example, this might be a label, or "0x" when * printing in base 16. May be \c NULL if no prefix * is needed. - * \param X The source MPI. Must point to an initialized MPI. + * \param X The source MPI. This must point to an initialized MPI. * \param radix The numeric base to be used in the emitted string. * \param fout The output file handle. May be \c NULL, in which case * the output is written to `stdout`. @@ -471,7 +474,7 @@ int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X, /** * \brief Import an MPI from unsigned big endian binary data. * - * \param X The destination MPI. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. * \param buf The input buffer. Must be a readable buffer of length * \p buflen Bytes. * \param buflen The length of the input buffer \p p in Bytes. @@ -487,7 +490,7 @@ int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf, * \brief Export an MPI into unsigned big endian binary data * of fixed size. * - * \param X The source MPI. Must point to an initialized MPI. + * \param X The source MPI. This must point to an initialized MPI. * \param buf The output buffer. Must be a writable buffer of length * \p buflen Bytes. * \param buflen The size of the output buffer \p buf in Bytes. @@ -503,7 +506,7 @@ int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf, /** * \brief Perform a left-shift on an MPI: X <<= count * - * \param X The MPI to shift. Must point to an initialized MPI. + * \param X The MPI to shift. This must point to an initialized MPI. * \param count The amount to shift, in bits. * * \return \c 0 if successful. @@ -515,7 +518,7 @@ int mbedtls_mpi_shift_l( mbedtls_mpi *X, size_t count ); /** * \brief Perform a right-shift on an MPI: X >>= count * - * \param X The MPI to shift. Must point to an initialized MPI. + * \param X The MPI to shift. This must point to an initialized MPI. * \param count The amount to shift, in bits. * * \return \c 0 if successful. @@ -527,8 +530,8 @@ int mbedtls_mpi_shift_r( mbedtls_mpi *X, size_t count ); /** * \brief Compare the absolute values of two MPIs. * - * \param X The left-hand MPI. Must point to an initialized MPI. - * \param Y The right-hand MPI. Must point to an initialized MPI. + * \param X The left-hand MPI. This must point to an initialized MPI. + * \param Y The right-hand MPI. This must point to an initialized MPI. * * \return \c 1 if `|X|` is greater than `|Y|`. * \return \c -1 if `|X|` is lesser than `|Y|`. @@ -539,8 +542,8 @@ int mbedtls_mpi_cmp_abs( const mbedtls_mpi *X, const mbedtls_mpi *Y ); /** * \brief Compare two MPIs. * - * \param X The left-hand MPI. Must point to an initialized MPI. - * \param Y The right-hand MPI. Must point to an initialized MPI. + * \param X The left-hand MPI. This must point to an initialized MPI. + * \param Y The right-hand MPI. This must point to an initialized MPI. * * \return \c 1 if `X` is greater than `Y`. * \return \c -1 if `X` is lesser than `Y`. @@ -551,7 +554,7 @@ int mbedtls_mpi_cmp_mpi( const mbedtls_mpi *X, const mbedtls_mpi *Y ); /** * \brief Compare an MPI with an integer. * - * \param X The left-hand MPI. Must point to an initialized MPI. + * \param X The left-hand MPI. This must point to an initialized MPI. * \param z The integer value to compare \p X to. * * \return \c 1 if `X` is greater than `z`. @@ -563,9 +566,9 @@ int mbedtls_mpi_cmp_int( const mbedtls_mpi *X, mbedtls_mpi_sint z ); /** * \brief Perform an unsigned addition of MPIs: X = |A| + |B| * - * \param X The destination MPI. Must point to an initialized MPI. - * \param A The first summand. Must point to an initialized MPI. - * \param B The second summand. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. + * \param A The first summand. This must point to an initialized MPI. + * \param B The second summand. This must point to an initialized MPI. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -577,9 +580,9 @@ int mbedtls_mpi_add_abs( mbedtls_mpi *X, const mbedtls_mpi *A, /** * \brief Perform an unsigned subtraction of MPIs: X = |A| - |B| * - * \param X The destination MPI. Must point to an initialized MPI. - * \param A The minuend. Must point to an initialized MPI. - * \param B The subtrahend. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. + * \param A The minuend. This must point to an initialized MPI. + * \param B The subtrahend. This must point to an initialized MPI. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is greater than \p A. @@ -592,9 +595,9 @@ int mbedtls_mpi_sub_abs( mbedtls_mpi *X, const mbedtls_mpi *A, /** * \brief Perform a signed addition of MPIs: X = A + B * - * \param X The destination MPI. Must point to an initialized MPI. - * \param A The first summand. Must point to an initialized MPI. - * \param B The second summand. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. + * \param A The first summand. This must point to an initialized MPI. + * \param B The second summand. This must point to an initialized MPI. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -606,9 +609,9 @@ int mbedtls_mpi_add_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, /** * \brief Perform a signed subtraction of MPIs: X = A - B * - * \param X The destination MPI. Must point to an initialized MPI. - * \param A The minuend. Must point to an initialized MPI. - * \param B The subtrahend. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. + * \param A The minuend. This must point to an initialized MPI. + * \param B The subtrahend. This must point to an initialized MPI. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -620,8 +623,8 @@ int mbedtls_mpi_sub_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, /** * \brief Perform a signed addition of an MPI and an integer: X = A + b * - * \param X The destination MPI. Must point to an initialized MPI. - * \param A The first summand. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. + * \param A The first summand. This must point to an initialized MPI. * \param b The second summand. * * \return \c 0 if successful. @@ -635,8 +638,8 @@ int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A, * \brief Perform a signed subtraction of an MPI and an integer: * X = A - b * - * \param X The destination MPI. Must point to an initialized MPI. - * \param A The minuend. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. + * \param A The minuend. This must point to an initialized MPI. * \param B The subtrahend. * * \return \c 0 if successful. @@ -649,9 +652,9 @@ int mbedtls_mpi_sub_int( mbedtls_mpi *X, const mbedtls_mpi *A, /** * \brief Perform a multiplication of two MPIs: X = A * B * - * \param X The destination MPI. Must point to an initialized MPI. - * \param A The first factor. Must point to an initialized MPI. - * \param B The second factor. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. + * \param A The first factor. This must point to an initialized MPI. + * \param B The second factor. This must point to an initialized MPI. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -665,8 +668,8 @@ int mbedtls_mpi_mul_mpi( mbedtls_mpi *X, const mbedtls_mpi *A, * \brief Perform a multiplication of an MPI with an unsigned integer: * X = A * b * - * \param X The destination MPI. Must point to an initialized MPI. - * \param A The first factor. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. + * \param A The first factor. This must point to an initialized MPI. * \param b The second factor. * * \return \c 0 if successful. @@ -685,8 +688,8 @@ int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A, * May be \c NULL is the value of the quotient is not needed. * \param R The destination MPI for the remainder value. * May be \c NULL if the value of the remainder is not needed. - * \param A The divident. Must point to an initialized MPi. - * \param B The divisor. Must point to an initialized MPI. + * \param A The divident. This must point to an initialized MPi. + * \param B The divisor. This must point to an initialized MPI. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. @@ -704,7 +707,7 @@ int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, * May be \c NULL is the value of the quotient is not needed. * \param R The destination MPI for the remainder value. * May be \c NULL if the value of the remainder is not needed. - * \param A The divident. Must point to an initialized MPi. + * \param A The divident. This must point to an initialized MPi. * \param b The divisor. * * \return \c 0 if successful. @@ -719,11 +722,11 @@ int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, * \brief Perform a modular reduction. R = A mod B * * \param R The destination MPI for the residue value. - * Must point to an initialized MPI. + * This must point to an initialized MPI. * \param A The MPI to compute the residue of. - * Must point to an initialized MPI. + * This must point to an initialized MPI. * \param B The base of the modular reduction. - * Must point to an initialized MPI. + * This must point to an initialized MPI. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -740,9 +743,9 @@ int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A, * r = A mod b * * \param r The address at which to store the residue. - * Must not be \c NULL. + * This must not be \c NULL. * \param A The MPI to compute the residue of. - * Must point to an initialized MPi. + * This must point to an initialized MPi. * \param b The integer base of the modular reduction. * * \return \c 0 if successful. @@ -757,11 +760,11 @@ int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A, /** * \brief Perform a sliding-window exponentiation: X = A^E mod N * - * \param X The destination MPI. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. * \param A The base of the exponentiation. - * Must point to an initialized MPI. - * \param E The exponent MPI. Must point to an initialized MPI. - * \param N The base for the modular reduction. Must point to an + * This must point to an initialized MPI. + * \param E The exponent MPI. This must point to an initialized MPI. + * \param N The base for the modular reduction. This must point to an * initialized MPI. * \param _RR A helper MPI depending solely on \p N which can be used to * speed-up multiple modular exponentiations for the same value @@ -787,9 +790,9 @@ int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, /** * \brief Fill an MPI with a number of random bytes. * - * \param X The destination MPI. Must point to an initialized MPI. + * \param X The destination MPI. This must point to an initialized MPI. * \param size The number of random bytes to generate. - * \param f_rng The RNG function to use. Must not be \c NULL. + * \param f_rng The RNG function to use. This must not be \c NULL. * \param p_rng The RNG parameter to be passed to \p f_rng. May be \c NULL * if \p f_rng doesn't need a context argument. * @@ -808,9 +811,9 @@ int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size, /** * \brief Compute the greatest common divisor: G = gcd(A, B) * - * \param G The destination MPI. Must point to an initialized MPI. - * \param A The first operand. Must point to an initialized MPI. - * \param A The second operand. Must point to an initialized MPI. + * \param G The destination MPI. This must point to an initialized MPI. + * \param A The first operand. This must point to an initialized MPI. + * \param A The second operand. This must point to an initialized MPI. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -822,10 +825,10 @@ int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A, /** * \brief Compute the modular inverse: X = A^-1 mod N * - * \param X The destination MPI. Must point to an initialized MPI. - * \param A The MPI to calculate the modular inverse of. Must point + * \param X The destination MPI. This must point to an initialized MPI. + * \param A The MPI to calculate the modular inverse of. This must point * to an initialized MPI. - * \param N The base of the modular inversion. Must point to an + * \param N The base of the modular inversion. This must point to an * initialized MPI. * * \return \c 0 if successful. @@ -851,8 +854,8 @@ int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A, * specifying the number of Miller-Rabin rounds. * * \param X The MPI to check for primality. - * Must point to an initialized MPI. - * \param f_rng The RNG function to use. Must not be \c NULL. + * This must point to an initialized MPI. + * \param f_rng The RNG function to use. This must not be \c NULL. * \param p_rng The RNG parameter to be passed to \p f_rng. * May be \c NULL if \p f_rng doesn't use a context parameter. * @@ -880,11 +883,11 @@ MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime( const mbedtls_mpi *X, * \p rounds can be much lower. * * \param X The MPI to check for primality. - * Must point to an initialized MPI. + * This must point to an initialized MPI. * \param rounds The number of bases to perform the Miller-Rabin primality * test for. The probability of returning 0 on a composite is * at most 2-2*\p rounds. - * \param f_rng The RNG function to use. Must not be \c NULL. + * \param f_rng The RNG function to use. This must not be \c NULL. * \param p_rng The RNG parameter to be passed to \p f_rng. * May be \c NULL if \p f_rng doesn't use a context parameter. * @@ -911,11 +914,11 @@ typedef enum { * \brief Generate a prime number. * * \param X The destination MPI to store the generated prime in. - * Must point to an initialized MPi. + * This must point to an initialized MPi. * \param nbits The required size of the destination MPI in bits. * Must be between \c 3 and #MBEDTLS_MPI_MAX_BITS. * \param flags A mask of flags of type #mbedtls_mpi_gen_prime_flag_t. - * \param f_rng The RNG function to use. Must not be \c NULL. + * \param f_rng The RNG function to use. This must not be \c NULL. * \param p_rng The RNG parameter to be passed to \p f_rng. * May be \c NULL if \p f_rng doesn't use a context parameter. * From 54c91dd2358b74777f059c551a19d930861377b7 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Wed, 12 Dec 2018 13:37:06 +0000 Subject: [PATCH 05/14] Remove double semicolon from bignum.c --- library/bignum.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/bignum.c b/library/bignum.c index 90af7e4953..8b01bad6cb 100644 --- a/library/bignum.c +++ b/library/bignum.c @@ -465,7 +465,7 @@ int mbedtls_mpi_read_string( mbedtls_mpi *X, int radix, const char *s ) MPI_VALIDATE_RET( s != NULL ); if( radix < 2 || radix > 16 ) - return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA );; + return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); mbedtls_mpi_init( &T ); @@ -568,7 +568,7 @@ int mbedtls_mpi_write_string( const mbedtls_mpi *X, int radix, MPI_VALIDATE_RET( buflen == 0 || buf != NULL ); if( radix < 2 || radix > 16 ) - return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA );; + return( MBEDTLS_ERR_MPI_BAD_INPUT_DATA ); n = mbedtls_mpi_bitlen( X ); if( radix >= 4 ) n >>= 1; From 56b661cbf890a0d8f8324efeb24ed70e03dcb5e5 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Wed, 12 Dec 2018 13:37:25 +0000 Subject: [PATCH 06/14] Add test that mbedtls_mpi_free() accepts NULL parameter --- tests/suites/test_suite_mpi.function | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/suites/test_suite_mpi.function b/tests/suites/test_suite_mpi.function index a82bf8181a..ddab63e079 100644 --- a/tests/suites/test_suite_mpi.function +++ b/tests/suites/test_suite_mpi.function @@ -219,9 +219,10 @@ void mpi_invalid_param( ) TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_inv_mod( NULL, &X, &X ) ); + mbedtls_mpi_free( NULL ); + exit: return; - } /* END_CASE */ From e118504a5f22893c3e80c1ad17fc45e7d5cc82d4 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Thu, 13 Dec 2018 14:31:46 +0000 Subject: [PATCH 07/14] Numerous minor improvements to bignum documentation --- include/mbedtls/bignum.h | 128 ++++++++++++++------------- tests/suites/test_suite_mpi.function | 34 ++++++- 2 files changed, 101 insertions(+), 61 deletions(-) diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index 4f835b4e24..ba747d09bf 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -196,9 +196,9 @@ mbedtls_mpi; void mbedtls_mpi_init( mbedtls_mpi *X ); /** - * \brief Clear an MPI context. + * \brief This function frees the components an MPI context. * - * \param X The MPI context to be cleared. May be \c NULL, + * \param X The MPI context to be cleared. This may be \c NULL, * in which case this function is a no-op. If it is * not \c NULL, it must point to an initialized MPI. */ @@ -220,7 +220,8 @@ void mbedtls_mpi_free( mbedtls_mpi *X ); int mbedtls_mpi_grow( mbedtls_mpi *X, size_t nblimbs ); /** - * \brief Resize down, keeping at least the specified number of limbs. + * \brief This function resizes an MPI downwards, keeping at least the + * specified number of limbs. * * If \c X is smaller than \c nblimbs, it is resized up * instead. @@ -259,14 +260,14 @@ int mbedtls_mpi_copy( mbedtls_mpi *X, const mbedtls_mpi *Y ); void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y ); /** - * \brief Safe conditional copy of MPI which doesn't - * reveal whether the conditional was true or not. + * \brief Perform a safe conditional copy of MPI which doesn't + * reveal whether the condition was true or not. * * \param X The MPI to conditionally assign to. This must point * to an initialized MPI. * \param Y The MPI to be assigned from. This must point to an * initialized MPI. - * \param assign The conditional deciding whether to perform the + * \param assign The condition deciding whether to perform the * assignment or not. Possible values: * * \c 1: Perform the assignment `X = Y`. * * \c 0: Keep the original value of \p X. @@ -285,12 +286,12 @@ void mbedtls_mpi_swap( mbedtls_mpi *X, mbedtls_mpi *Y ); int mbedtls_mpi_safe_cond_assign( mbedtls_mpi *X, const mbedtls_mpi *Y, unsigned char assign ); /** - * \brief Safe conditional swap which doesn't - * reveal whether the conditional was true or not. + * \brief Perform a safe conditional swap which doesn't + * reveal whether the condition was true or not. * * \param X The first MPI. This must be initialized. * \param Y The second MPI. This must be initialized. - * \param assign The conditional deciding whether to perform + * \param assign The condition deciding whether to perform * the swap or not. Possible values: * * \c 1: Swap the values of \p X and \p Y. * * \c 0: Keep the original values of \p X and \p Y. @@ -351,41 +352,42 @@ int mbedtls_mpi_get_bit( const mbedtls_mpi *X, size_t pos ); int mbedtls_mpi_set_bit( mbedtls_mpi *X, size_t pos, unsigned char val ); /** - * \brief Return the number of zero-bits before the - * least significant '1' bit + * \brief Return the number of bits of value \c 0 before the + * least significant bit of value \c 1. * * \note This is the same as the zero-based index of - * the least significant '1' bit. + * the least significant bit of value \c 1. * * \param X The MPI to query. * - * \return The number of zero-bits before the least significant - * '1' bit in \p X. + * \return The number of bits of value \c 0 before the least significant + * bit of value \c 1 in \p X. */ size_t mbedtls_mpi_lsb( const mbedtls_mpi *X ); /** * \brief Return the number of bits up to and including the most - * significant '1' bit. + * significant bit of value \c 1. * * * \note This is same as the one-based index of the most - * significant '1' bit. + * significant bit of value \c 1. * * \param X The MPI to query. This must point to an initialized MPI. * * \return The number of bits up to and including the most - * significant '1' bit. + * significant bit of value \c 1. */ size_t mbedtls_mpi_bitlen( const mbedtls_mpi *X ); /** - * \brief Return the total size an MPI value in bytes. + * \brief Return the total size of an MPI value in bytes. * * \param X The MPI to use. This must point to an initialized MPI. * * \note The value returned by this function may be less than * the number of bytes used to store \p X internally. - * This happens if and only if there are trailing zero-bytes. + * This happens if and only if there are trailing bytes + * of value zero. * * \return The least number of bytes capable of storing * the absolute value of \p X. @@ -405,17 +407,19 @@ size_t mbedtls_mpi_size( const mbedtls_mpi *X ); int mbedtls_mpi_read_string( mbedtls_mpi *X, int radix, const char *s ); /** - * \brief Export an MPI into an ASCII string. + * \brief Export an MPI to an ASCII string. * * \param X The source MPI. This must point to an initialized MPI. * \param radix The numeric base of the output string. - * \param buf Buffer to write the string to. Must be writable of - * length \p buflen Bytes. May be \c NULL if `buflen == 0`. + * \param buf The buffer to write the string to. This must be writable + * buffer of length \p buflen Bytes. It May be \c NULL if + * `buflen == 0`. * \param buflen The available size in Bytes of \p buf. - * \param olen Address at which to store the length of the string written, - * including final \c NULL byte. This must not be \c NULL. + * \param olen The address at which to store the length of the string + * written, including the final \c NULL byte. This must + * not be \c NULL. * - * \note Call this function with `buflen == 0` to obtain the + * \note You can call this function with `buflen == 0` to obtain the * minimum required buffer size in `*olen`. * * \return \c 0 if successful. @@ -457,12 +461,12 @@ int mbedtls_mpi_read_file( mbedtls_mpi *X, int radix, FILE *fin ); * * \param p A string prefix to emit prior to the MPI data. * For example, this might be a label, or "0x" when - * printing in base 16. May be \c NULL if no prefix + * printing in base \c 16. This may be \c NULL if no prefix * is needed. * \param X The source MPI. This must point to an initialized MPI. * \param radix The numeric base to be used in the emitted string. - * \param fout The output file handle. May be \c NULL, in which case - * the output is written to `stdout`. + * \param fout The output file handle. This may be \c NULL, in which case + * the output is written to \c stdout. * * \return \c 0 if successful. * \return A negative error code on failure. @@ -475,7 +479,7 @@ int mbedtls_mpi_write_file( const char *p, const mbedtls_mpi *X, * \brief Import an MPI from unsigned big endian binary data. * * \param X The destination MPI. This must point to an initialized MPI. - * \param buf The input buffer. Must be a readable buffer of length + * \param buf The input buffer. This must be a readable buffer of length * \p buflen Bytes. * \param buflen The length of the input buffer \p p in Bytes. * @@ -491,13 +495,13 @@ int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf, * of fixed size. * * \param X The source MPI. This must point to an initialized MPI. - * \param buf The output buffer. Must be a writable buffer of length + * \param buf The output buffer. This must be a writable buffer of length * \p buflen Bytes. * \param buflen The size of the output buffer \p buf in Bytes. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_BUFFER_TOO_SMALL if \p buf isn't - * large enoguh to hold the value of \p X. + * large enough to hold the value of \p X. * \return Another negative error code on different kinds of failure. */ int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf, @@ -507,7 +511,7 @@ int mbedtls_mpi_write_binary( const mbedtls_mpi *X, unsigned char *buf, * \brief Perform a left-shift on an MPI: X <<= count * * \param X The MPI to shift. This must point to an initialized MPI. - * \param count The amount to shift, in bits. + * \param count The number of bits to shift by. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -519,7 +523,7 @@ int mbedtls_mpi_shift_l( mbedtls_mpi *X, size_t count ); * \brief Perform a right-shift on an MPI: X >>= count * * \param X The MPI to shift. This must point to an initialized MPI. - * \param count The amount to shift, in bits. + * \param count The number of bits to shift by. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -535,7 +539,7 @@ int mbedtls_mpi_shift_r( mbedtls_mpi *X, size_t count ); * * \return \c 1 if `|X|` is greater than `|Y|`. * \return \c -1 if `|X|` is lesser than `|Y|`. - * \return \c 0 if `|X|` is equal than `|Y|`. + * \return \c 0 if `|X|` is equal to `|Y|`. */ int mbedtls_mpi_cmp_abs( const mbedtls_mpi *X, const mbedtls_mpi *Y ); @@ -545,9 +549,9 @@ int mbedtls_mpi_cmp_abs( const mbedtls_mpi *X, const mbedtls_mpi *Y ); * \param X The left-hand MPI. This must point to an initialized MPI. * \param Y The right-hand MPI. This must point to an initialized MPI. * - * \return \c 1 if `X` is greater than `Y`. - * \return \c -1 if `X` is lesser than `Y`. - * \return \c 0 if `X` is equal than `Y`. + * \return \c 1 if \p X is greater than \p Y. + * \return \c -1 if \p X is lesser than \p Y. + * \return \c 0 if \p X is equal to \p Y. */ int mbedtls_mpi_cmp_mpi( const mbedtls_mpi *X, const mbedtls_mpi *Y ); @@ -557,9 +561,9 @@ int mbedtls_mpi_cmp_mpi( const mbedtls_mpi *X, const mbedtls_mpi *Y ); * \param X The left-hand MPI. This must point to an initialized MPI. * \param z The integer value to compare \p X to. * - * \return \c 1 if `X` is greater than `z`. - * \return \c -1 if `X` is lesser than `z`. - * \return \c 0 if `X` is equal than `z`. + * \return \c 1 if \p X is greater than \p z. + * \return \c -1 if \p X is lesser than \p z. + * \return \c 0 if \p X is equal to \p z. */ int mbedtls_mpi_cmp_int( const mbedtls_mpi *X, mbedtls_mpi_sint z ); @@ -693,7 +697,7 @@ int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A, * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. - * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if `B == 0`. + * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero. * \return Another negative error code on different kinds of failure. */ int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, @@ -712,7 +716,7 @@ int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if memory allocation failed. - * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if `b == 0`. + * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero. * \return Another negative error code on different kinds of failure. */ int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, @@ -730,8 +734,8 @@ int mbedtls_mpi_div_int( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. - * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if `B == 0`. - * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if `B < 0`. + * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p B equals zero. + * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p B is negative. * \return Another negative error code on different kinds of failure. * */ @@ -750,8 +754,8 @@ int mbedtls_mpi_mod_mpi( mbedtls_mpi *R, const mbedtls_mpi *A, * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. - * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if `b == 0`. - * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if `b < 0`. + * \return #MBEDTLS_ERR_MPI_DIVISION_BY_ZERO if \p b equals zero. + * \return #MBEDTLS_ERR_MPI_NEGATIVE_VALUE if \p b is negative. * \return Another negative error code on different kinds of failure. */ int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A, @@ -768,13 +772,13 @@ int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A, * initialized MPI. * \param _RR A helper MPI depending solely on \p N which can be used to * speed-up multiple modular exponentiations for the same value - * of \p N. May be \c NULL. If it is not \c NULL, it must point - * an initialized MPI. If it is freshly initialized, i.e. not - * used after the call to mbedtls_mpi_init(), this function - * will compute the helper value and store it in \p _RR for - * reuse on subsequent calls to this function. Otherwise, the - * function will assume that \p _RR holds the helper value set - * by a previous call to mbedtls_mpi_exp_mod(), and reuse it. + * of \p N. This may be \c NULL. If it is not \c NULL, it must + * point an initialized MPI. If it hasn't been used after + * the call to mbedtls_mpi_init(), this function will compute + * the helper value and store it in \p _RR for reuse on + * subsequent calls to this function. Otherwise, the function + * will assume that \p _RR holds the helper value set by a + * previous call to mbedtls_mpi_exp_mod(), and reuse it. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -793,8 +797,8 @@ int mbedtls_mpi_exp_mod( mbedtls_mpi *X, const mbedtls_mpi *A, * \param X The destination MPI. This must point to an initialized MPI. * \param size The number of random bytes to generate. * \param f_rng The RNG function to use. This must not be \c NULL. - * \param p_rng The RNG parameter to be passed to \p f_rng. May be \c NULL - * if \p f_rng doesn't need a context argument. + * \param p_rng The RNG parameter to be passed to \p f_rng. This may be + * \c NULL if \p f_rng doesn't need a context argument. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -833,7 +837,8 @@ int mbedtls_mpi_gcd( mbedtls_mpi *G, const mbedtls_mpi *A, * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. - * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if `N <= 1`. + * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if \p N is less than + * or equal to one. * \return #MBEDTLS_ERR_MPI_NOT_ACCEPTABLE if \p has no modular inverse * with respect to \p N. */ @@ -857,7 +862,8 @@ int mbedtls_mpi_inv_mod( mbedtls_mpi *X, const mbedtls_mpi *A, * This must point to an initialized MPI. * \param f_rng The RNG function to use. This must not be \c NULL. * \param p_rng The RNG parameter to be passed to \p f_rng. - * May be \c NULL if \p f_rng doesn't use a context parameter. + * This may be \c NULL if \p f_rng doesn't use a + * context parameter. * * \return \c 0 if successful, i.e. \p X is probably prime. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -889,7 +895,8 @@ MBEDTLS_DEPRECATED int mbedtls_mpi_is_prime( const mbedtls_mpi *X, * at most 2-2*\p rounds. * \param f_rng The RNG function to use. This must not be \c NULL. * \param p_rng The RNG parameter to be passed to \p f_rng. - * May be \c NULL if \p f_rng doesn't use a context parameter. + * This may be \c NULL if \p f_rng doesn't use + * a context parameter. * * \return \c 0 if successful, i.e. \p X is probably prime. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -920,9 +927,10 @@ typedef enum { * \param flags A mask of flags of type #mbedtls_mpi_gen_prime_flag_t. * \param f_rng The RNG function to use. This must not be \c NULL. * \param p_rng The RNG parameter to be passed to \p f_rng. - * May be \c NULL if \p f_rng doesn't use a context parameter. + * This may be \c NULL if \p f_rng doesn't use + * a context parameter. * - * \return \c 0 if successful, in which case \p X holds a probably + * \return \c 0 if successful, in which case \p X holds a * probably prime number. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. * \return #MBEDTLS_ERR_MPI_BAD_INPUT_DATA if `nbits` is not between diff --git a/tests/suites/test_suite_mpi.function b/tests/suites/test_suite_mpi.function index ddab63e079..d5bb6a7b9c 100644 --- a/tests/suites/test_suite_mpi.function +++ b/tests/suites/test_suite_mpi.function @@ -62,32 +62,41 @@ void mpi_invalid_param( ) mbedtls_mpi_uint mpi_uint; TEST_INVALID_PARAM( mbedtls_mpi_init( NULL ) ); + TEST_VALID_PARAM( mbedtls_mpi_free( NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_grow( NULL, 42 ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_copy( NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_copy( &X, NULL ) ); + TEST_INVALID_PARAM( mbedtls_mpi_swap( NULL, &X ) ); TEST_INVALID_PARAM( mbedtls_mpi_swap( &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_safe_cond_assign( NULL, &X, 0 ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_safe_cond_assign( &X, NULL, 0 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_safe_cond_swap( NULL, &X, 0 ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_safe_cond_swap( &X, NULL, 0 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_lset( NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_get_bit( NULL, 42 ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_set_bit( NULL, 42, 0 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_read_string( NULL, 2, s_in ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_read_string( &X, 2, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_write_string( NULL, 2, s_out, sizeof( s_out ), @@ -100,11 +109,13 @@ void mpi_invalid_param( ) mbedtls_mpi_write_string( &X, 2, s_out, sizeof( s_out ), NULL ) ); + #if defined(MBEDTLS_FS_IO) TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_read_file( NULL, 2, stdin ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_read_file( &X, 2, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_write_file( "", NULL, 2, NULL ) ); #endif /* MBEDTLS_FS_IO */ @@ -115,84 +126,102 @@ void mpi_invalid_param( ) TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_read_binary( &X, NULL, sizeof( u_in ) ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_write_binary( NULL, u_out, sizeof( u_out ) ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_write_binary( &X, NULL, sizeof( u_out ) ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_shift_l( NULL, 42 ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_shift_r( NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_cmp_abs( NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_cmp_abs( &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_cmp_mpi( NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_cmp_mpi( &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_cmp_int( NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_add_abs( NULL, &X, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_add_abs( &X, NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_add_abs( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_sub_abs( NULL, &X, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_sub_abs( &X, NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_sub_abs( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_add_mpi( NULL, &X, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_add_mpi( &X, NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_add_mpi( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_sub_mpi( NULL, &X, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_sub_mpi( &X, NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_sub_mpi( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_add_int( NULL, &X, 42 ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_add_int( &X, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_sub_int( NULL, &X, 42 ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_sub_int( &X, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mul_mpi( NULL, &X, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mul_mpi( &X, NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mul_mpi( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mul_int( NULL, &X, 42 ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mul_int( &X, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_div_mpi( &X, &X, NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_div_mpi( &X, &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_div_int( &X, &X, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mod_mpi( NULL, &X, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mod_mpi( &X, NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mod_mpi( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mod_int( NULL, &X, 42 ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mod_int( &mpi_uint, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_exp_mod( NULL, &X, &X, &X, NULL ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, @@ -201,23 +230,26 @@ void mpi_invalid_param( ) mbedtls_mpi_exp_mod( &X, &X, NULL, &X, NULL ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_exp_mod( &X, &X, &X, NULL, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_fill_random( NULL, 42, rnd_std_rand, NULL ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_fill_random( &X, 42, NULL, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_gcd( NULL, &X, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_gcd( &X, NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_gcd( &X, &X, NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_inv_mod( NULL, &X, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_inv_mod( &X, NULL, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, - mbedtls_mpi_inv_mod( NULL, &X, &X ) ); + mbedtls_mpi_inv_mod( &X, &X, NULL ) ); mbedtls_mpi_free( NULL ); From 01c3c1064052512b4a386be56ac33c5eac924a30 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Mon, 17 Dec 2018 23:04:51 +0000 Subject: [PATCH 08/14] Fix typos in documentation of bignum module Found by doxygen.sh --- include/mbedtls/bignum.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index ba747d09bf..e0c863f7b2 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -644,7 +644,7 @@ int mbedtls_mpi_add_int( mbedtls_mpi *X, const mbedtls_mpi *A, * * \param X The destination MPI. This must point to an initialized MPI. * \param A The minuend. This must point to an initialized MPI. - * \param B The subtrahend. + * \param b The subtrahend. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. @@ -817,7 +817,7 @@ int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size, * * \param G The destination MPI. This must point to an initialized MPI. * \param A The first operand. This must point to an initialized MPI. - * \param A The second operand. This must point to an initialized MPI. + * \param B The second operand. This must point to an initialized MPI. * * \return \c 0 if successful. * \return #MBEDTLS_ERR_MPI_ALLOC_FAILED if a memory allocation failed. From d73101266d78a879c30071bb3b744820b5a42485 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 18 Dec 2018 18:11:42 +0000 Subject: [PATCH 09/14] Don't promise that passing a NULL to mbedtls_mpi_read_string works --- include/mbedtls/bignum.h | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index e0c863f7b2..d3337d2fbf 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -412,8 +412,7 @@ int mbedtls_mpi_read_string( mbedtls_mpi *X, int radix, const char *s ); * \param X The source MPI. This must point to an initialized MPI. * \param radix The numeric base of the output string. * \param buf The buffer to write the string to. This must be writable - * buffer of length \p buflen Bytes. It May be \c NULL if - * `buflen == 0`. + * buffer of length \p buflen Bytes. * \param buflen The available size in Bytes of \p buf. * \param olen The address at which to store the length of the string * written, including the final \c NULL byte. This must From d01ff493e54cd9179420b35fdaf726611f4dcc83 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 18 Dec 2018 23:10:28 +0000 Subject: [PATCH 10/14] Minor improvements in bignum documentation --- include/mbedtls/bignum.h | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index d3337d2fbf..7b808381ef 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -688,9 +688,11 @@ int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A, * A = Q * B + R * * \param Q The destination MPI for the quotient. - * May be \c NULL is the value of the quotient is not needed. + * This may be \c NULL if the value of the + * quotient is not needed. * \param R The destination MPI for the remainder value. - * May be \c NULL if the value of the remainder is not needed. + * This may be \c NULL if the value of the + * remainder is not needed. * \param A The divident. This must point to an initialized MPi. * \param B The divisor. This must point to an initialized MPI. * @@ -707,9 +709,11 @@ int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, * A = Q * b + R * * \param Q The destination MPI for the quotient. - * May be \c NULL is the value of the quotient is not needed. + * This may be \c NULL if the value of the + * quotient is not needed. * \param R The destination MPI for the remainder value. - * May be \c NULL if the value of the remainder is not needed. + * This may be \c NULL if the value of the + * remainder is not needed. * \param A The divident. This must point to an initialized MPi. * \param b The divisor. * @@ -922,7 +926,7 @@ typedef enum { * \param X The destination MPI to store the generated prime in. * This must point to an initialized MPi. * \param nbits The required size of the destination MPI in bits. - * Must be between \c 3 and #MBEDTLS_MPI_MAX_BITS. + * This must be between \c 3 and #MBEDTLS_MPI_MAX_BITS. * \param flags A mask of flags of type #mbedtls_mpi_gen_prime_flag_t. * \param f_rng The RNG function to use. This must not be \c NULL. * \param p_rng The RNG parameter to be passed to \p f_rng. From b48e1aa846d58fbef94ddd65775af28e0d31bfae Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 18 Dec 2018 23:25:01 +0000 Subject: [PATCH 11/14] Add separate test for mbedtls_mpi_free() accepting NULL --- tests/suites/test_suite_mpi.data | 5 ++++- tests/suites/test_suite_mpi.function | 8 +++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/tests/suites/test_suite_mpi.data b/tests/suites/test_suite_mpi.data index ff25a6fcc7..8b5f97d389 100644 --- a/tests/suites/test_suite_mpi.data +++ b/tests/suites/test_suite_mpi.data @@ -1,4 +1,7 @@ -Parameter validation +MPI - Valid parameters +mpi_valid_param: + +MPI - Invalid parameters mpi_invalid_param: Arguments with no value diff --git a/tests/suites/test_suite_mpi.function b/tests/suites/test_suite_mpi.function index d5bb6a7b9c..63e0e9715b 100644 --- a/tests/suites/test_suite_mpi.function +++ b/tests/suites/test_suite_mpi.function @@ -50,6 +50,13 @@ int mbedtls_test_mpi_miller_rabin_determinizer( void* state, * END_DEPENDENCIES */ +/* BEGIN_CASE */ +void mpi_valid_param( ) +{ + TEST_VALID_PARAM( mbedtls_mpi_free( NULL ) ); +} +/* END_CASE */ + /* BEGIN_CASE depends_on:MBEDTLS_CHECK_PARAMS:!MBEDTLS_PARAM_FAILED_ALT */ void mpi_invalid_param( ) { @@ -62,7 +69,6 @@ void mpi_invalid_param( ) mbedtls_mpi_uint mpi_uint; TEST_INVALID_PARAM( mbedtls_mpi_init( NULL ) ); - TEST_VALID_PARAM( mbedtls_mpi_free( NULL ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_grow( NULL, 42 ) ); From 59274d43cb628d49f02bd8414833802fa3fd1181 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Tue, 18 Dec 2018 23:27:03 +0000 Subject: [PATCH 12/14] Remove unnecessary call to mbedtls_mpi_free() in MPI tests --- tests/suites/test_suite_mpi.function | 2 -- 1 file changed, 2 deletions(-) diff --git a/tests/suites/test_suite_mpi.function b/tests/suites/test_suite_mpi.function index 63e0e9715b..3379a999d1 100644 --- a/tests/suites/test_suite_mpi.function +++ b/tests/suites/test_suite_mpi.function @@ -257,8 +257,6 @@ void mpi_invalid_param( ) TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_inv_mod( &X, &X, NULL ) ); - mbedtls_mpi_free( NULL ); - exit: return; } From 8ce11a323e9e7b5297a296e32fc738c6ecaa3756 Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Wed, 19 Dec 2018 16:18:52 +0000 Subject: [PATCH 13/14] Minor improvements to bignum module --- include/mbedtls/bignum.h | 8 ++++---- library/bignum.c | 12 ++++++------ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/include/mbedtls/bignum.h b/include/mbedtls/bignum.h index 7b808381ef..141a8e9adf 100644 --- a/include/mbedtls/bignum.h +++ b/include/mbedtls/bignum.h @@ -196,7 +196,7 @@ mbedtls_mpi; void mbedtls_mpi_init( mbedtls_mpi *X ); /** - * \brief This function frees the components an MPI context. + * \brief This function frees the components of an MPI context. * * \param X The MPI context to be cleared. This may be \c NULL, * in which case this function is a no-op. If it is @@ -693,7 +693,7 @@ int mbedtls_mpi_mul_int( mbedtls_mpi *X, const mbedtls_mpi *A, * \param R The destination MPI for the remainder value. * This may be \c NULL if the value of the * remainder is not needed. - * \param A The divident. This must point to an initialized MPi. + * \param A The dividend. This must point to an initialized MPi. * \param B The divisor. This must point to an initialized MPI. * * \return \c 0 if successful. @@ -714,7 +714,7 @@ int mbedtls_mpi_div_mpi( mbedtls_mpi *Q, mbedtls_mpi *R, const mbedtls_mpi *A, * \param R The destination MPI for the remainder value. * This may be \c NULL if the value of the * remainder is not needed. - * \param A The divident. This must point to an initialized MPi. + * \param A The dividend. This must point to an initialized MPi. * \param b The divisor. * * \return \c 0 if successful. @@ -776,7 +776,7 @@ int mbedtls_mpi_mod_int( mbedtls_mpi_uint *r, const mbedtls_mpi *A, * \param _RR A helper MPI depending solely on \p N which can be used to * speed-up multiple modular exponentiations for the same value * of \p N. This may be \c NULL. If it is not \c NULL, it must - * point an initialized MPI. If it hasn't been used after + * point to an initialized MPI. If it hasn't been used after * the call to mbedtls_mpi_init(), this function will compute * the helper value and store it in \p _RR for reuse on * subsequent calls to this function. Otherwise, the function diff --git a/library/bignum.c b/library/bignum.c index 8b01bad6cb..0d0d922c13 100644 --- a/library/bignum.c +++ b/library/bignum.c @@ -724,7 +724,7 @@ int mbedtls_mpi_read_binary( mbedtls_mpi *X, const unsigned char *buf, size_t bu size_t i, j; size_t const limbs = CHARS_TO_LIMBS( buflen ); - MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( X != NULL ); MPI_VALIDATE_RET( buflen == 0 || buf != NULL ); /* Ensure that target MPI has exactly the necessary number of limbs */ @@ -2009,7 +2009,7 @@ int mbedtls_mpi_fill_random( mbedtls_mpi *X, size_t size, { int ret; unsigned char buf[MBEDTLS_MPI_MAX_SIZE]; - MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( X != NULL ); MPI_VALIDATE_RET( f_rng != NULL ); if( size > MBEDTLS_MPI_MAX_SIZE ) @@ -2192,7 +2192,7 @@ static int mpi_miller_rabin( const mbedtls_mpi *X, size_t rounds, size_t i, j, k, s; mbedtls_mpi W, R, T, A, RR; - MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( X != NULL ); MPI_VALIDATE_RET( f_rng != NULL ); mbedtls_mpi_init( &W ); mbedtls_mpi_init( &R ); @@ -2284,7 +2284,7 @@ int mbedtls_mpi_is_prime_ext( const mbedtls_mpi *X, int rounds, { int ret; mbedtls_mpi XX; - MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( X != NULL ); MPI_VALIDATE_RET( f_rng != NULL ); XX.s = 1; @@ -2317,7 +2317,7 @@ int mbedtls_mpi_is_prime( const mbedtls_mpi *X, int (*f_rng)(void *, unsigned char *, size_t), void *p_rng ) { - MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( X != NULL ); MPI_VALIDATE_RET( f_rng != NULL ); /* @@ -2353,7 +2353,7 @@ int mbedtls_mpi_gen_prime( mbedtls_mpi *X, size_t nbits, int flags, mbedtls_mpi_uint r; mbedtls_mpi Y; - MPI_VALIDATE_RET( X != NULL ); + MPI_VALIDATE_RET( X != NULL ); MPI_VALIDATE_RET( f_rng != NULL ); if( nbits < 3 || nbits > MBEDTLS_MPI_MAX_BITS ) From f25ee7f79d79e1104329d493a66df069e387b23c Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Wed, 19 Dec 2018 16:51:02 +0000 Subject: [PATCH 14/14] Fix parameter validation for mbedtls_mpi_lsb() The MPI_VALIDATE_RET() macro cannot be used for parameter validation of mbedtls_mpi_lsb() because this function returns a size_t. Use the underlying MBEDTLS_INTERNAL_VALIDATE_RET() insteaed, returning 0 on failure. Also, add a test for this behaviour. --- library/bignum.c | 2 +- tests/suites/test_suite_mpi.function | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/library/bignum.c b/library/bignum.c index 0d0d922c13..f968a0ad7d 100644 --- a/library/bignum.c +++ b/library/bignum.c @@ -380,7 +380,7 @@ cleanup: size_t mbedtls_mpi_lsb( const mbedtls_mpi *X ) { size_t i, j, count = 0; - MPI_VALIDATE_RET( X != NULL ); + MBEDTLS_INTERNAL_VALIDATE_RET( X != NULL, 0 ); for( i = 0; i < X->n; i++ ) for( j = 0; j < biL; j++, count++ ) diff --git a/tests/suites/test_suite_mpi.function b/tests/suites/test_suite_mpi.function index 3379a999d1..d1fa5a46cf 100644 --- a/tests/suites/test_suite_mpi.function +++ b/tests/suites/test_suite_mpi.function @@ -216,6 +216,8 @@ void mpi_invalid_param( ) TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_div_int( &X, &X, NULL, 42 ) ); + TEST_INVALID_PARAM_RET( 0, mbedtls_mpi_lsb( NULL ) ); + TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA, mbedtls_mpi_mod_mpi( NULL, &X, &X ) ); TEST_INVALID_PARAM_RET( MBEDTLS_ERR_MPI_BAD_INPUT_DATA,