Merge remote-tracking branch 'public/pr/2283' into development

include/mbedtls/dhm.h

@@ -127,9 +127,15 @@ mbedtls_dhm_context;
 void mbedtls_dhm_init( mbedtls_dhm_context *ctx );
 
 /**
- * \brief          This function parses the ServerKeyExchange parameters.
+ * \brief          This function parses the DHM parameters in a
+ *                 TLS ServerKeyExchange handshake message
+ *                 (DHM modulus, generator, and public key).
  *
- * \param ctx      The DHM context.
+ * \note           In a TLS handshake, this is the how the client
+ *                 sets up its DHM context from the server's public
+ *                 DHM key material.
+ *
+ * \param ctx      The DHM context to use. This must be initialized.
  * \param p        On input, *p must be the start of the input buffer.
  *                 On output, *p is updated to point to the end of the data
  *                 that has been read. On success, this is the first byte
@@ -147,27 +153,33 @@ int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
                              const unsigned char *end );
 
 /**
- * \brief          This function sets up and writes the ServerKeyExchange
+ * \brief          This function generates a DHM key pair and exports its
- *                 parameters.
+ *                 public part together with the DHM parameters in the format
+ *                 used in a TLS ServerKeyExchange handshake message.
  *
- * \note           The destination buffer must be large enough to hold
+ * \note           This function assumes that the DHM parameters \c ctx->P
- *                 the reduced binary presentation of the modulus, the generator
+ *                 and \c ctx->G have already been properly set. For that, use
- *                 and the public key, each wrapped with a 2-byte length field.
- *                 It is the responsibility of the caller to ensure that enough
- *                 space is available. Refer to \c mbedtls_mpi_size to computing
- *                 the byte-size of an MPI.
- *
- * \note           This function assumes that \c ctx->P and \c ctx->G
- *                 have already been properly set. For that, use
  *                 mbedtls_dhm_set_group() below in conjunction with
  *                 mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
  *
- * \param ctx      The DHM context.
+ * \note           In a TLS handshake, this is the how the server generates
+ *                 and exports its DHM key material.
+ *
+ * \param ctx      The DHM context to use. This must be initialized
+ *                 and have the DHM parameters set. It may or may not
+ *                 already have imported the peer's public key.
  * \param x_size   The private key size in Bytes.
- * \param olen     The number of characters written.
+ * \param olen     The address at which to store the number of Bytes
- * \param output   The destination buffer.
+ *                 written on success. This must not be \c NULL.
- * \param f_rng    The RNG function.
+ * \param output   The destination buffer. This must be a writable buffer of
- * \param p_rng    The RNG context.
+ *                 sufficient size to hold the reduced binary presentation of
+ *                 the modulus, the generator and the public key, each wrapped
+ *                 with a 2-byte length field. It is the responsibility of the
+ *                 caller to ensure that enough space is available. Refer to
+ *                 mbedtls_mpi_size() to computing the byte-size of an MPI.
+ * \param f_rng    The RNG function. Must not be \c NULL.
+ * \param p_rng    The RNG context to be passed to \p f_rng. This may be
+ *                 \c NULL if \p f_rng doesn't need a context parameter.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -180,12 +192,14 @@ int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
 /**
  * \brief          This function sets the prime modulus and generator.
  *
- * \note           This function can be used to set \p P, \p G
+ * \note           This function can be used to set \c ctx->P, \c ctx->G
  *                 in preparation for mbedtls_dhm_make_params().
  *
- * \param ctx      The DHM context.
+ * \param ctx      The DHM context to configure. This must be initialized.
- * \param P        The MPI holding the DHM prime modulus.
+ * \param P        The MPI holding the DHM prime modulus. This must be
- * \param G        The MPI holding the DHM generator.
+ *                 an initialized MPI.
+ * \param G        The MPI holding the DHM generator. This must be an
+ *                 initialized MPI.
  *
  * \return         \c 0 if successful.
  * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -195,11 +209,17 @@ int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
                            const mbedtls_mpi *G );
 
 /**
- * \brief          This function imports the public value of the peer, G^Y.
+ * \brief          This function imports the raw public value of the peer.
  *
- * \param ctx      The DHM context.
+ * \note           In a TLS handshake, this is the how the server imports
- * \param input    The input buffer containing the G^Y value of the peer.
+ *                 the Client's public DHM key.
- * \param ilen     The size of the input buffer.
+ *
+ * \param ctx      The DHM context to use. This must be initialized and have
+ *                 its DHM parameters set, e.g. via mbedtls_dhm_set_group().
+ *                 It may or may not already have generated its own private key.
+ * \param input    The input buffer containing the \c G^Y value of the peer.
+ *                 This must be a readable buffer of size \p ilen Bytes.
+ * \param ilen     The size of the input buffer \p input in Bytes.
  *
  * \return         \c 0 on success.
  * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -208,21 +228,25 @@ int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
                      const unsigned char *input, size_t ilen );
 
 /**
- * \brief          This function creates its own private key, \c X, and
+ * \brief          This function creates a DHM key pair and exports
- *                 exports \c G^X.
+ *                 the raw public key in big-endian format.
  *
  * \note           The destination buffer is always fully written
  *                 so as to contain a big-endian representation of G^X mod P.
- *                 If it is larger than ctx->len, it is padded accordingly
+ *                 If it is larger than \c ctx->len, it is padded accordingly
  *                 with zero-bytes at the beginning.
  *
- * \param ctx      The DHM context.
+ * \param ctx      The DHM context to use. This must be initialized and
+ *                 have the DHM parameters set. It may or may not already
+ *                 have imported the peer's public key.
  * \param x_size   The private key size in Bytes.
- * \param output   The destination buffer.
+ * \param output   The destination buffer. This must be a writable buffer of
- * \param olen     The length of the destination buffer. Must be at least
+ *                 size \p olen Bytes.
- *                  equal to ctx->len (the size of \c P).
+ * \param olen     The length of the destination buffer. This must be at least
- * \param f_rng    The RNG function.
+ *                 equal to `ctx->len` (the size of \c P).
- * \param p_rng    The RNG context.
+ * \param f_rng    The RNG function. This must not be \c NULL.
+ * \param p_rng    The RNG context 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 on success.
  * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -236,19 +260,24 @@ int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
  * \brief          This function derives and exports the shared secret
  *                 \c (G^Y)^X mod \c P.
  *
- * \note                If \p f_rng is not NULL, it is used to blind the input as
+ * \note           If \p f_rng is not \c NULL, it is used to blind the input as
  *                 a countermeasure against timing attacks. Blinding is used
  *                 only if our private key \c X is re-used, and not used
  *                 otherwise. We recommend always passing a non-NULL
  *                 \p f_rng argument.
  *
- * \param ctx           The DHM context.
+ * \param ctx           The DHM context to use. This must be initialized
- * \param output        The destination buffer.
+ *                      and have its own private key generated and the peer's
- * \param output_size   The size of the destination buffer. Must be at least
+ *                      public key imported.
- *                      the size of ctx->len (the size of \c P).
+ * \param output        The buffer to write the generated shared key to. This
+ *                      must be a writable buffer of size \p output_size Bytes.
+ * \param output_size   The size of the destination buffer. This must be at
+ *                      least the size of \c ctx->len (the size of \c P).
  * \param olen          On exit, holds the actual number of Bytes written.
- * \param f_rng         The RNG function, for blinding purposes.
+ * \param f_rng         The RNG function, for blinding purposes. This may
- * \param p_rng         The RNG context.
+ *                      b \c NULL if blinding isn't needed.
+ * \param p_rng         The RNG context. This may be \c NULL if \p f_rng
+ *                      doesn't need a context argument.
  *
  * \return              \c 0 on success.
  * \return              An \c MBEDTLS_ERR_DHM_XXX error code on failure.
@@ -259,9 +288,12 @@ int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
                      void *p_rng );
 
 /**
- * \brief          This function frees and clears the components of a DHM context.
+ * \brief          This function frees and clears the components
+ *                 of a DHM context.
  *
- * \param ctx      The DHM context to free and clear.
+ * \param ctx      The DHM context to free and clear. 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 DHM context.
  */
 void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
 
@@ -270,14 +302,16 @@ void mbedtls_dhm_free( mbedtls_dhm_context *ctx );
 /**
  * \brief             This function parses DHM parameters in PEM or DER format.
  *
- * \param dhm         The DHM context to initialize.
+ * \param dhm         The DHM context to import the DHM parameters into.
- * \param dhmin       The input buffer.
+ *                    This must be initialized.
- * \param dhminlen    The size of the buffer, including the terminating null
+ * \param dhmin       The input buffer. This must be a readable buffer of
- *                    Byte for PEM data.
+ *                    length \p dhminlen Bytes.
+ * \param dhminlen    The size of the input buffer \p dhmin, including the
+ *                    terminating \c NULL Byte for PEM data.
  *
  * \return            \c 0 on success.
- * \return            An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
+ * \return            An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error
- *                    error code on failure.
+ *                    code on failure.
  */
 int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
                            size_t dhminlen );
@@ -288,10 +322,12 @@ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
  * \brief          This function loads and parses DHM parameters from a file.
  *
  * \param dhm      The DHM context to load the parameters to.
+ *                 This must be initialized.
  * \param path     The filename to read the DHM parameters from.
+ *                 This must not be \c NULL.
  *
  * \return         \c 0 on success.
- * \return            An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX error code
+ * \return         An \c MBEDTLS_ERR_DHM_XXX or \c MBEDTLS_ERR_PEM_XXX
  *                 error code on failure.
  */
 int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path );

library/dhm.c

@@ -60,6 +60,11 @@
 
 #if !defined(MBEDTLS_DHM_ALT)
 
+#define DHM_VALIDATE_RET( cond )    \
+    MBEDTLS_INTERNAL_VALIDATE_RET( cond, MBEDTLS_ERR_DHM_BAD_INPUT_DATA )
+#define DHM_VALIDATE( cond )        \
+    MBEDTLS_INTERNAL_VALIDATE( cond )
+
 /*
  * helper to validate the mbedtls_mpi size and import it
  */
@@ -121,6 +126,7 @@ cleanup:
 
 void mbedtls_dhm_init( mbedtls_dhm_context *ctx )
 {
+    DHM_VALIDATE( ctx != NULL );
     memset( ctx, 0, sizeof( mbedtls_dhm_context ) );
 }
 
@@ -132,6 +138,9 @@ int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
                      const unsigned char *end )
 {
     int ret;
+    DHM_VALIDATE_RET( ctx != NULL );
+    DHM_VALIDATE_RET( p != NULL && *p != NULL );
+    DHM_VALIDATE_RET( end != NULL );
 
     if( ( ret = dhm_read_bignum( &ctx->P,  p, end ) ) != 0 ||
         ( ret = dhm_read_bignum( &ctx->G,  p, end ) ) != 0 ||
@@ -157,6 +166,10 @@ int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
     int ret, count = 0;
     size_t n1, n2, n3;
     unsigned char *p;
+    DHM_VALIDATE_RET( ctx != NULL );
+    DHM_VALIDATE_RET( output != NULL );
+    DHM_VALIDATE_RET( olen != NULL );
+    DHM_VALIDATE_RET( f_rng != NULL );
 
     if( mbedtls_mpi_cmp_int( &ctx->P, 0 ) == 0 )
         return( MBEDTLS_ERR_DHM_BAD_INPUT_DATA );
@@ -227,9 +240,9 @@ int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
                            const mbedtls_mpi *G )
 {
     int ret;
-
+    DHM_VALIDATE_RET( ctx != NULL );
-    if( ctx == NULL || P == NULL || G == NULL )
+    DHM_VALIDATE_RET( P != NULL );
-        return( MBEDTLS_ERR_DHM_BAD_INPUT_DATA );
+    DHM_VALIDATE_RET( G != NULL );
 
     if( ( ret = mbedtls_mpi_copy( &ctx->P, P ) ) != 0 ||
         ( ret = mbedtls_mpi_copy( &ctx->G, G ) ) != 0 )
@@ -248,8 +261,10 @@ int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
                      const unsigned char *input, size_t ilen )
 {
     int ret;
+    DHM_VALIDATE_RET( ctx != NULL );
+    DHM_VALIDATE_RET( input != NULL );
 
-    if( ctx == NULL || ilen < 1 || ilen > ctx->len )
+    if( ilen < 1 || ilen > ctx->len )
         return( MBEDTLS_ERR_DHM_BAD_INPUT_DATA );
 
     if( ( ret = mbedtls_mpi_read_binary( &ctx->GY, input, ilen ) ) != 0 )
@@ -267,8 +282,11 @@ int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
                      void *p_rng )
 {
     int ret, count = 0;
+    DHM_VALIDATE_RET( ctx != NULL );
+    DHM_VALIDATE_RET( output != NULL );
+    DHM_VALIDATE_RET( f_rng != NULL );
 
-    if( ctx == NULL || olen < 1 || olen > ctx->len )
+    if( olen < 1 || olen > ctx->len )
         return( MBEDTLS_ERR_DHM_BAD_INPUT_DATA );
 
     if( mbedtls_mpi_cmp_int( &ctx->P, 0 ) == 0 )
@@ -380,8 +398,11 @@ int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
 {
     int ret;
     mbedtls_mpi GYb;
+    DHM_VALIDATE_RET( ctx != NULL );
+    DHM_VALIDATE_RET( output != NULL );
+    DHM_VALIDATE_RET( olen != NULL );
 
-    if( ctx == NULL || output_size < ctx->len )
+    if( output_size < ctx->len )
         return( MBEDTLS_ERR_DHM_BAD_INPUT_DATA );
 
     if( ( ret = dhm_check_range( &ctx->GY, &ctx->P ) ) != 0 )
@@ -428,6 +449,9 @@ cleanup:
  */
 void mbedtls_dhm_free( mbedtls_dhm_context *ctx )
 {
+    if( ctx == NULL )
+        return;
+
     mbedtls_mpi_free( &ctx->pX ); mbedtls_mpi_free( &ctx->Vf );
     mbedtls_mpi_free( &ctx->Vi ); mbedtls_mpi_free( &ctx->RP );
     mbedtls_mpi_free( &ctx->K  ); mbedtls_mpi_free( &ctx->GY );
@@ -449,7 +473,12 @@ int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
     unsigned char *p, *end;
 #if defined(MBEDTLS_PEM_PARSE_C)
     mbedtls_pem_context pem;
+#endif /* MBEDTLS_PEM_PARSE_C */
 
+    DHM_VALIDATE_RET( dhm != NULL );
+    DHM_VALIDATE_RET( dhmin != NULL );
+
+#if defined(MBEDTLS_PEM_PARSE_C)
     mbedtls_pem_init( &pem );
 
     /* Avoid calling mbedtls_pem_read_buffer() on non-null-terminated string */
@@ -596,6 +625,8 @@ int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path )
     int ret;
     size_t n;
     unsigned char *buf;
+    DHM_VALIDATE_RET( dhm != NULL );
+    DHM_VALIDATE_RET( path != NULL );
 
     if( ( ret = load_file( path, &buf, &n ) ) != 0 )
         return( ret );

tests/suites/test_suite_dhm.data

@@ -1,3 +1,6 @@
+Diffie-Hellman parameter validation
+dhm_invalid_params:
+
 Diffie-Hellman full exchange #1
 dhm_do_dhm:10:"23":10:"5":0
 

tests/suites/test_suite_dhm.function

@@ -7,6 +7,113 @@
  * END_DEPENDENCIES
  */
 
+/* BEGIN_CASE depends_on:MBEDTLS_CHECK_PARAMS:!MBEDTLS_PARAM_FAILED_ALT */
+void dhm_invalid_params( )
+{
+    mbedtls_dhm_context ctx;
+    unsigned char buf[42] = { 0 };
+    unsigned char *buf_null = NULL;
+    mbedtls_mpi X;
+    size_t const buflen = sizeof( buf );
+    size_t len;
+
+    TEST_INVALID_PARAM( mbedtls_dhm_init( NULL ) );
+    TEST_VALID_PARAM( mbedtls_dhm_free( NULL ) );
+
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_read_params( NULL,
+                                                     (unsigned char**) &buf,
+                                                     buf ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_read_params( &ctx, &buf_null, buf ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_read_params( &ctx, NULL, buf ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_read_params( &ctx,
+                                                     (unsigned char**) &buf,
+                                                     NULL ) );
+
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_make_params( NULL, buflen,
+                                                     buf, &len,
+                                                     rnd_std_rand,
+                                                     NULL ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_make_params( &ctx, buflen,
+                                                     NULL, &len,
+                                                     rnd_std_rand,
+                                                     NULL ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_make_params( &ctx, buflen,
+                                                     buf, NULL,
+                                                     rnd_std_rand,
+                                                     NULL ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_make_params( &ctx, buflen,
+                                                     buf, &len,
+                                                     NULL,
+                                                     NULL ) );
+
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_set_group( NULL, &X, &X ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_set_group( &ctx, NULL, &X ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_set_group( &ctx, &X, NULL ) );
+
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_read_public( NULL, buf, buflen ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_read_public( &ctx, NULL, buflen ) );
+
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_make_public( NULL, buflen,
+                                                     buf, buflen,
+                                                     rnd_std_rand,
+                                                     NULL ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_make_public( &ctx, buflen,
+                                                     NULL, buflen,
+                                                     rnd_std_rand,
+                                                     NULL ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_make_public( &ctx, buflen,
+                                                     buf, buflen,
+                                                     NULL,
+                                                     NULL ) );
+
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_calc_secret( NULL, buf, buflen,
+                                                     &len, rnd_std_rand,
+                                                     NULL ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_calc_secret( &ctx, NULL, buflen,
+                                                     &len, rnd_std_rand,
+                                                     NULL ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_calc_secret( &ctx, buf, buflen,
+                                                     NULL, rnd_std_rand,
+                                                     NULL ) );
+
+#if defined(MBEDTLS_ASN1_PARSE_C)
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_parse_dhm( NULL, buf, buflen ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_parse_dhm( &ctx, NULL, buflen ) );
+
+#if defined(MBEDTLS_FS_IO)
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_parse_dhmfile( NULL, "" ) );
+    TEST_INVALID_PARAM_RET( MBEDTLS_ERR_DHM_BAD_INPUT_DATA,
+                            mbedtls_dhm_parse_dhmfile( &ctx, NULL ) );
+#endif /* MBEDTLS_FS_IO */
+#endif /* MBEDTLS_ASN1_PARSE_C */
+
+exit:
+    return;
+}
+/* END_CASE */
+
 /* BEGIN_CASE */
 void dhm_do_dhm( int radix_P, char *input_P,
                  int radix_G, char *input_G, int result )