Merge pull request #10182 from gilles-peskine-arm/f_rng-documentation-3.6

3.6 only: document f_rng callbacks

Author: gilles-peskine-arm

include/mbedtls/bignum.h

@@ -12,6 +12,7 @@
 #include "mbedtls/private_access.h"
 
 #include "mbedtls/build_info.h"
+#include "mbedtls/platform_util.h"
 
 #include <stddef.h>
 #include <stdint.h>
@@ -928,7 +929,7 @@ int mbedtls_mpi_exp_mod(mbedtls_mpi *X, const mbedtls_mpi *A,
  *                 be relevant in applications like deterministic ECDSA.
  */
 int mbedtls_mpi_fill_random(mbedtls_mpi *X, size_t size,
-                            int (*f_rng)(void *, unsigned char *, size_t),
+                            mbedtls_f_rng_t *f_rng,
                             void *p_rng);
 
 /** Generate a random number uniformly in a range.
@@ -966,7 +967,7 @@ int mbedtls_mpi_fill_random(mbedtls_mpi *X, size_t size,
 int mbedtls_mpi_random(mbedtls_mpi *X,
                        mbedtls_mpi_sint min,
                        const mbedtls_mpi *N,
-                       int (*f_rng)(void *, unsigned char *, size_t),
+                       mbedtls_f_rng_t *f_rng,
                        void *p_rng);
 
 /**
@@ -1030,7 +1031,7 @@ int mbedtls_mpi_inv_mod(mbedtls_mpi *X, const mbedtls_mpi *A,
  * \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),
+                             mbedtls_f_rng_t *f_rng,
                              void *p_rng);
 /**
  * \brief Flags for mbedtls_mpi_gen_prime()
@@ -1063,7 +1064,7 @@ typedef enum {
  *                 \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),
+                          mbedtls_f_rng_t *f_rng,
                           void *p_rng);
 
 #if defined(MBEDTLS_SELF_TEST)

include/mbedtls/dhm.h

@@ -183,7 +183,7 @@ int mbedtls_dhm_read_params(mbedtls_dhm_context *ctx,
  */
 int mbedtls_dhm_make_params(mbedtls_dhm_context *ctx, int x_size,
                             unsigned char *output, size_t *olen,
-                            int (*f_rng)(void *, unsigned char *, size_t),
+                            mbedtls_f_rng_t *f_rng,
                             void *p_rng);
 
 /**
@@ -250,7 +250,7 @@ int mbedtls_dhm_read_public(mbedtls_dhm_context *ctx,
  */
 int mbedtls_dhm_make_public(mbedtls_dhm_context *ctx, int x_size,
                             unsigned char *output, size_t olen,
-                            int (*f_rng)(void *, unsigned char *, size_t),
+                            mbedtls_f_rng_t *f_rng,
                             void *p_rng);
 
 /**
@@ -281,7 +281,7 @@ int mbedtls_dhm_make_public(mbedtls_dhm_context *ctx, int x_size,
  */
 int mbedtls_dhm_calc_secret(mbedtls_dhm_context *ctx,
                             unsigned char *output, size_t output_size, size_t *olen,
-                            int (*f_rng)(void *, unsigned char *, size_t),
+                            mbedtls_f_rng_t *f_rng,
                             void *p_rng);
 
 /**

include/mbedtls/ecdh.h

@@ -189,7 +189,7 @@ int mbedtls_ecdh_can_do(mbedtls_ecp_group_id gid);
  *                  \c MBEDTLS_MPI_XXX error code on failure.
  */
 int mbedtls_ecdh_gen_public(mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
-                            int (*f_rng)(void *, unsigned char *, size_t),
+                            mbedtls_f_rng_t *f_rng,
                             void *p_rng);
 
 /**
@@ -225,7 +225,7 @@ int mbedtls_ecdh_gen_public(mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_
  */
 int mbedtls_ecdh_compute_shared(mbedtls_ecp_group *grp, mbedtls_mpi *z,
                                 const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
-                                int (*f_rng)(void *, unsigned char *, size_t),
+                                mbedtls_f_rng_t *f_rng,
                                 void *p_rng);
 
 /**
@@ -290,7 +290,7 @@ void mbedtls_ecdh_free(mbedtls_ecdh_context *ctx);
  */
 int mbedtls_ecdh_make_params(mbedtls_ecdh_context *ctx, size_t *olen,
                              unsigned char *buf, size_t blen,
-                             int (*f_rng)(void *, unsigned char *, size_t),
+                             mbedtls_f_rng_t *f_rng,
                              void *p_rng);
 
 /**
@@ -372,7 +372,7 @@ int mbedtls_ecdh_get_params(mbedtls_ecdh_context *ctx,
  */
 int mbedtls_ecdh_make_public(mbedtls_ecdh_context *ctx, size_t *olen,
                              unsigned char *buf, size_t blen,
-                             int (*f_rng)(void *, unsigned char *, size_t),
+                             mbedtls_f_rng_t *f_rng,
                              void *p_rng);
 
 /**
@@ -428,7 +428,7 @@ int mbedtls_ecdh_read_public(mbedtls_ecdh_context *ctx,
  */
 int mbedtls_ecdh_calc_secret(mbedtls_ecdh_context *ctx, size_t *olen,
                              unsigned char *buf, size_t blen,
-                             int (*f_rng)(void *, unsigned char *, size_t),
+                             mbedtls_f_rng_t *f_rng,
                              void *p_rng);
 
 #if defined(MBEDTLS_ECP_RESTARTABLE)

include/mbedtls/ecdsa.h

@@ -150,7 +150,8 @@ int mbedtls_ecdsa_can_do(mbedtls_ecp_group_id gid);
  *                  buffer of length \p blen Bytes. It may be \c NULL if
  *                  \p blen is zero.
  * \param blen      The length of \p buf in Bytes.
- * \param f_rng     The RNG function. This must not be \c NULL.
+ * \param f_rng     The RNG function, used both to generate the ECDSA nonce
+ *                  and for blinding. 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 parameter.
  *
@@ -160,7 +161,7 @@ int mbedtls_ecdsa_can_do(mbedtls_ecp_group_id gid);
  */
 int mbedtls_ecdsa_sign(mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s,
                        const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
-                       int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
+                       mbedtls_f_rng_t *f_rng, void *p_rng);
 
 #if defined(MBEDTLS_ECDSA_DETERMINISTIC)
 /**
@@ -207,7 +208,7 @@ int mbedtls_ecdsa_sign_det_ext(mbedtls_ecp_group *grp, mbedtls_mpi *r,
                                mbedtls_mpi *s, const mbedtls_mpi *d,
                                const unsigned char *buf, size_t blen,
                                mbedtls_md_type_t md_alg,
-                               int (*f_rng_blind)(void *, unsigned char *, size_t),
+                               mbedtls_f_rng_t *f_rng_blind,
                                void *p_rng_blind);
 #endif /* MBEDTLS_ECDSA_DETERMINISTIC */
 
@@ -247,7 +248,8 @@ int mbedtls_ecdsa_sign_det_ext(mbedtls_ecp_group *grp, mbedtls_mpi *r,
  *                      buffer of length \p blen Bytes. It may be \c NULL if
  *                      \p blen is zero.
  * \param blen          The length of \p buf in Bytes.
- * \param f_rng         The RNG function. This must not be \c NULL.
+ * \param f_rng         The RNG function used to generate the ECDSA nonce.
+ *                      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 parameter.
  * \param f_rng_blind   The RNG function used for blinding. This must not be
@@ -271,9 +273,9 @@ int mbedtls_ecdsa_sign_restartable(
     mbedtls_mpi *r, mbedtls_mpi *s,
     const mbedtls_mpi *d,
     const unsigned char *buf, size_t blen,
-    int (*f_rng)(void *, unsigned char *, size_t),
+    mbedtls_f_rng_t *f_rng,
     void *p_rng,
-    int (*f_rng_blind)(void *, unsigned char *, size_t),
+    mbedtls_f_rng_t *f_rng_blind,
     void *p_rng_blind,
     mbedtls_ecdsa_restart_ctx *rs_ctx);
 
@@ -334,7 +336,7 @@ int mbedtls_ecdsa_sign_det_restartable(
     mbedtls_mpi *r, mbedtls_mpi *s,
     const mbedtls_mpi *d, const unsigned char *buf, size_t blen,
     mbedtls_md_type_t md_alg,
-    int (*f_rng_blind)(void *, unsigned char *, size_t),
+    mbedtls_f_rng_t *f_rng_blind,
     void *p_rng_blind,
     mbedtls_ecdsa_restart_ctx *rs_ctx);
 
@@ -458,10 +460,10 @@ int mbedtls_ecdsa_verify_restartable(mbedtls_ecp_group *grp,
  * \param sig_size  The size of the \p sig buffer in bytes.
  * \param slen      The address at which to store the actual length of
  *                  the signature written. Must not be \c NULL.
- * \param f_rng     The RNG function. This must not be \c NULL if
- *                  #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
- *                  it is used only for blinding and may be set to \c NULL, but
- *                  doing so is DEPRECATED.
+ * \param f_rng     The RNG function. This is used for blinding.
+ *                  If #MBEDTLS_ECDSA_DETERMINISTIC is unset, this is also
+ *                  used to generate the ECDSA nonce.
+ *                  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 is \c NULL or doesn't use a context.
  *
@@ -473,7 +475,7 @@ int mbedtls_ecdsa_write_signature(mbedtls_ecdsa_context *ctx,
                                   mbedtls_md_type_t md_alg,
                                   const unsigned char *hash, size_t hlen,
                                   unsigned char *sig, size_t sig_size, size_t *slen,
-                                  int (*f_rng)(void *, unsigned char *, size_t),
+                                  mbedtls_f_rng_t *f_rng,
                                   void *p_rng);
 
 /**
@@ -501,9 +503,10 @@ int mbedtls_ecdsa_write_signature(mbedtls_ecdsa_context *ctx,
  * \param sig_size  The size of the \p sig buffer in bytes.
  * \param slen      The address at which to store the actual length of
  *                  the signature written. Must not be \c NULL.
- * \param f_rng     The RNG function. This must not be \c NULL if
- *                  #MBEDTLS_ECDSA_DETERMINISTIC is unset. Otherwise,
- *                  it is unused and may be set to \c NULL.
+ * \param f_rng     The RNG function. This is used for blinding.
+ *                  If #MBEDTLS_ECDSA_DETERMINISTIC is unset, this is also
+ *                  used to generate the ECDSA nonce.
+ *                  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 is \c NULL or doesn't use a context.
  * \param rs_ctx    The restart context to use. This may be \c NULL to disable
@@ -520,7 +523,7 @@ int mbedtls_ecdsa_write_signature_restartable(mbedtls_ecdsa_context *ctx,
                                               mbedtls_md_type_t md_alg,
                                               const unsigned char *hash, size_t hlen,
                                               unsigned char *sig, size_t sig_size, size_t *slen,
-                                              int (*f_rng)(void *, unsigned char *, size_t),
+                                              mbedtls_f_rng_t *f_rng,
                                               void *p_rng,
                                               mbedtls_ecdsa_restart_ctx *rs_ctx);
 
@@ -608,7 +611,7 @@ int mbedtls_ecdsa_read_signature_restartable(mbedtls_ecdsa_context *ctx,
  * \return         An \c MBEDTLS_ERR_ECP_XXX code on failure.
  */
 int mbedtls_ecdsa_genkey(mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid,
-                         int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
+                         mbedtls_f_rng_t *f_rng, void *p_rng);
 
 /**
  * \brief           This function sets up an ECDSA context from an EC key pair.

include/mbedtls/ecjpake.h

@@ -162,7 +162,7 @@ int mbedtls_ecjpake_check(const mbedtls_ecjpake_context *ctx);
  */
 int mbedtls_ecjpake_write_round_one(mbedtls_ecjpake_context *ctx,
                                     unsigned char *buf, size_t len, size_t *olen,
-                                    int (*f_rng)(void *, unsigned char *, size_t),
+                                    mbedtls_f_rng_t *f_rng,
                                     void *p_rng);
 
 /**
@@ -203,7 +203,7 @@ int mbedtls_ecjpake_read_round_one(mbedtls_ecjpake_context *ctx,
  */
 int mbedtls_ecjpake_write_round_two(mbedtls_ecjpake_context *ctx,
                                     unsigned char *buf, size_t len, size_t *olen,
-                                    int (*f_rng)(void *, unsigned char *, size_t),
+                                    mbedtls_f_rng_t *f_rng,
                                     void *p_rng);
 
 /**
@@ -243,7 +243,7 @@ int mbedtls_ecjpake_read_round_two(mbedtls_ecjpake_context *ctx,
  */
 int mbedtls_ecjpake_derive_secret(mbedtls_ecjpake_context *ctx,
                                   unsigned char *buf, size_t len, size_t *olen,
-                                  int (*f_rng)(void *, unsigned char *, size_t),
+                                  mbedtls_f_rng_t *f_rng,
                                   void *p_rng);
 
 /**
@@ -266,7 +266,7 @@ int mbedtls_ecjpake_derive_secret(mbedtls_ecjpake_context *ctx,
  */
 int mbedtls_ecjpake_write_shared_key(mbedtls_ecjpake_context *ctx,
                                      unsigned char *buf, size_t len, size_t *olen,
-                                     int (*f_rng)(void *, unsigned char *, size_t),
+                                     mbedtls_f_rng_t *f_rng,
                                      void *p_rng);
 
 /**

include/mbedtls/ecp.h

@@ -966,7 +966,7 @@ int mbedtls_ecp_tls_write_group(const mbedtls_ecp_group *grp,
  */
 int mbedtls_ecp_mul(mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
                     const mbedtls_mpi *m, const mbedtls_ecp_point *P,
-                    int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
+                    mbedtls_f_rng_t *f_rng, void *p_rng);
 
 /**
  * \brief           This function performs multiplication of a point by
@@ -1000,7 +1000,7 @@ int mbedtls_ecp_mul(mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
  */
 int mbedtls_ecp_mul_restartable(mbedtls_ecp_group *grp, mbedtls_ecp_point *R,
                                 const mbedtls_mpi *m, const mbedtls_ecp_point *P,
-                                int (*f_rng)(void *, unsigned char *, size_t), void *p_rng,
+                                mbedtls_f_rng_t *f_rng, void *p_rng,
                                 mbedtls_ecp_restart_ctx *rs_ctx);
 
 #if defined(MBEDTLS_ECP_SHORT_WEIERSTRASS_ENABLED)
@@ -1179,7 +1179,7 @@ int mbedtls_ecp_check_privkey(const mbedtls_ecp_group *grp,
  */
 int mbedtls_ecp_gen_privkey(const mbedtls_ecp_group *grp,
                             mbedtls_mpi *d,
-                            int (*f_rng)(void *, unsigned char *, size_t),
+                            mbedtls_f_rng_t *f_rng,
                             void *p_rng);
 
 /**
@@ -1212,7 +1212,7 @@ int mbedtls_ecp_gen_privkey(const mbedtls_ecp_group *grp,
 int mbedtls_ecp_gen_keypair_base(mbedtls_ecp_group *grp,
                                  const mbedtls_ecp_point *G,
                                  mbedtls_mpi *d, mbedtls_ecp_point *Q,
-                                 int (*f_rng)(void *, unsigned char *, size_t),
+                                 mbedtls_f_rng_t *f_rng,
                                  void *p_rng);
 
 /**
@@ -1240,7 +1240,7 @@ int mbedtls_ecp_gen_keypair_base(mbedtls_ecp_group *grp,
  */
 int mbedtls_ecp_gen_keypair(mbedtls_ecp_group *grp, mbedtls_mpi *d,
                             mbedtls_ecp_point *Q,
-                            int (*f_rng)(void *, unsigned char *, size_t),
+                            mbedtls_f_rng_t *f_rng,
                             void *p_rng);
 
 /**
@@ -1257,7 +1257,7 @@ int mbedtls_ecp_gen_keypair(mbedtls_ecp_group *grp, mbedtls_mpi *d,
  *                  on failure.
  */
 int mbedtls_ecp_gen_key(mbedtls_ecp_group_id grp_id, mbedtls_ecp_keypair *key,
-                        int (*f_rng)(void *, unsigned char *, size_t),
+                        mbedtls_f_rng_t *f_rng,
                         void *p_rng);
 
 /** \brief          Set the public key in a key pair object.
@@ -1451,7 +1451,7 @@ int mbedtls_ecp_write_public_key(const mbedtls_ecp_keypair *key,
  */
 int mbedtls_ecp_check_pub_priv(
     const mbedtls_ecp_keypair *pub, const mbedtls_ecp_keypair *prv,
-    int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
+    mbedtls_f_rng_t *f_rng, void *p_rng);
 
 /** \brief          Calculate the public key from a private key in a key pair.
  *
@@ -1468,7 +1468,7 @@ int mbedtls_ecp_check_pub_priv(
  */
 int mbedtls_ecp_keypair_calc_public(
     mbedtls_ecp_keypair *key,
-    int (*f_rng)(void *, unsigned char *, size_t), void *p_rng);
+    mbedtls_f_rng_t *f_rng, void *p_rng);
 
 /** \brief          Query the group that a key pair belongs to.
  *

include/mbedtls/lms.h

@@ -364,7 +364,7 @@ void mbedtls_lms_private_free(mbedtls_lms_private_t *ctx);
 int mbedtls_lms_generate_private_key(mbedtls_lms_private_t *ctx,
                                      mbedtls_lms_algorithm_type_t type,
                                      mbedtls_lmots_algorithm_type_t otstype,
-                                     int (*f_rng)(void *, unsigned char *, size_t),
+                                     mbedtls_f_rng_t *f_rng,
                                      void *p_rng, const unsigned char *seed,
                                      size_t seed_size);
 
@@ -427,7 +427,7 @@ int mbedtls_lms_calculate_public_key(mbedtls_lms_public_t *ctx,
  * \return         A non-zero error code on failure.
  */
 int mbedtls_lms_sign(mbedtls_lms_private_t *ctx,
-                     int (*f_rng)(void *, unsigned char *, size_t),
+                     mbedtls_f_rng_t *f_rng,
                      void *p_rng, const unsigned char *msg,
                      unsigned int msg_size, unsigned char *sig, size_t sig_size,
                      size_t *sig_len);