diff options
author | Pauli <pauli@openssl.org> | 2021-05-28 14:44:38 +1000 |
---|---|---|
committer | Pauli <pauli@openssl.org> | 2021-05-29 17:17:12 +1000 |
commit | e587bccdf9152716e8ff74d8208a064cabf9f3e8 (patch) | |
tree | d3123076b24da406d5ab2c9c6ca5bd544fb53e4b /doc/man3 | |
parent | 83058e810b3abf6b04c20857323b9e487cbd0367 (diff) |
doc: document the strength arugments to the RNG functions
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15513)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/BN_rand.pod | 36 | ||||
-rw-r--r-- | doc/man3/RAND_bytes.pod | 10 |
2 files changed, 28 insertions, 18 deletions
diff --git a/doc/man3/BN_rand.pod b/doc/man3/BN_rand.pod index 1c50c692b9..06ee99d28e 100644 --- a/doc/man3/BN_rand.pod +++ b/doc/man3/BN_rand.pod @@ -11,16 +11,20 @@ BN_pseudo_rand_range #include <openssl/bn.h> - int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, BN_CTX *ctx); + int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, + unsigned int strength, BN_CTX *ctx); int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); - int BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, BN_CTX *ctx); + int BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, + unsigned int strength, BN_CTX *ctx); int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom); - int BN_rand_range_ex(BIGNUM *rnd, BIGNUM *range, BN_CTX *ctx); + int BN_rand_range_ex(BIGNUM *rnd, BIGNUM *range, unsigned int strength, + BN_CTX *ctx); int BN_rand_range(BIGNUM *rnd, BIGNUM *range); - int BN_priv_rand_range_ex(BIGNUM *rnd, BIGNUM *range, BN_CTX *ctx); + int BN_priv_rand_range_ex(BIGNUM *rnd, BIGNUM *range, unsigned int strength, + BN_CTX *ctx); int BN_priv_rand_range(BIGNUM *rnd, BIGNUM *range); Deprecated since OpenSSL 3.0, can be hidden entirely by defining @@ -32,30 +36,32 @@ openssl_user_macros(7): =head1 DESCRIPTION -BN_rand_ex() generate a cryptographically strong pseudo-random -number of B<bits> in length and stores it in B<rnd> using the random number -generator for the library context associated with B<ctx>. The parameter B<ctx> +BN_rand_ex() generates a cryptographically strong pseudo-random +number of I<bits> in length and security strength at least I<strength> bits +using the random number generator for the library context associated with +I<ctx>. The function stores the generated data in I<rnd>. The parameter I<ctx> may be NULL in which case the default library context is used. -If B<bits> is less than zero, or too small to -accommodate the requirements specified by the B<top> and B<bottom> +If I<bits> is less than zero, or too small to +accommodate the requirements specified by the I<top> and I<bottom> parameters, an error is returned. -The B<top> parameters specifies +The I<top> parameters specifies requirements on the most significant bit of the generated number. If it is B<BN_RAND_TOP_ANY>, there is no constraint. If it is B<BN_RAND_TOP_ONE>, the top bit must be one. If it is B<BN_RAND_TOP_TWO>, the two most significant bits of the number will be set to 1, so that the product of two such random -numbers will always have 2*B<bits> length. -If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it +numbers will always have 2*I<bits> length. +If I<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it is B<BN_RAND_BOTTOM_ANY> it can be odd or even. -If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>. +If I<bits> is 1 then I<top> cannot also be B<BN_RAND_FLG_TOPTWO>. BN_rand() is the same as BN_rand_ex() except that the default library context is always used. BN_rand_range_ex() generates a cryptographically strong pseudo-random -number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range> using the random number -generator for the library context associated with B<ctx>. The parameter B<ctx> +number I<rnd>, of security stength at least I<strength> bits, +in the range 0 E<lt>= I<rnd> E<lt> I<range> using the random number +generator for the library context associated with I<ctx>. The parameter I<ctx> may be NULL in which case the default library context is used. BN_rand_range() is the same as BN_rand_range_ex() except that the default diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod index aeec94dd8b..832790fb95 100644 --- a/doc/man3/RAND_bytes.pod +++ b/doc/man3/RAND_bytes.pod @@ -12,8 +12,10 @@ RAND_pseudo_bytes - generate random data int RAND_bytes(unsigned char *buf, int num); int RAND_priv_bytes(unsigned char *buf, int num); - int RAND_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, int num); - int RAND_priv_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, int num); + int RAND_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, int num, + unsigned int strength); + int RAND_priv_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, int num, + unsigned int strength); Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, see @@ -34,7 +36,9 @@ affect the secrecy of these private values, as described in L<RAND(7)> and L<EVP_RAND(7)>. RAND_bytes_ex() and RAND_priv_bytes_ex() are the same as RAND_bytes() and -RAND_priv_bytes() except that they both take an additional I<ctx> parameter. +RAND_priv_bytes() except that they both take additional I<strength> and +I<ctx> parameters. The bytes genreated will have a security strength of at +least I<strength> bits. The DRBG used for the operation is the public or private DRBG associated with the specified I<ctx>. The parameter can be NULL, in which case the default library context is used (see L<OSSL_LIB_CTX(3)>. |