Skip to content

3.6 only: document f_rng callbacks #10182

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 3, 2025
Merged

3.6 only: document f_rng callbacks #10182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1337d54
Name and document the type of random generator callbacks
gilles-peskine-arm May 16, 2025
060c70e
Reference mbedtls_f_rng_t in public documentation
gilles-peskine-arm May 16, 2025
ed10e2a
Note functions that store the RNG callback in a context
gilles-peskine-arm May 16, 2025
c0b357d
ECDSA is a special flower
gilles-peskine-arm May 16, 2025
addf8fc
Fix ECDSA documentation: blinding is no longer optional
gilles-peskine-arm May 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions include/mbedtls/bignum.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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)
Expand Down
6 changes: 3 additions & 3 deletions include/mbedtls/dhm.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand Down
10 changes: 5 additions & 5 deletions include/mbedtls/ecdh.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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)
Expand Down
37 changes: 20 additions & 17 deletions include/mbedtls/ecdsa.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand All @@ -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)
/**
Expand Down Expand Up @@ -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 */

Expand Down Expand Up @@ -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
Expand All @@ -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);

Expand Down Expand Up @@ -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);

Expand Down Expand Up @@ -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.
*
Expand All @@ -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);

/**
Expand Down Expand Up @@ -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
Expand All @@ -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);

Expand Down Expand Up @@ -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.
Expand Down
8 changes: 4 additions & 4 deletions include/mbedtls/ecjpake.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand All @@ -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);

/**
Expand Down
16 changes: 8 additions & 8 deletions include/mbedtls/ecp.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand All @@ -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.
Expand Down Expand Up @@ -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.
*
Expand All @@ -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.
*
Expand Down
4 changes: 2 additions & 2 deletions include/mbedtls/lms.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down Expand Up @@ -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);
Expand Down
Loading