diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/BN_rand.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/BN_rand.3 | 92 |
1 files changed, 61 insertions, 31 deletions
diff --git a/secure/lib/libcrypto/man/man3/BN_rand.3 b/secure/lib/libcrypto/man/man3/BN_rand.3 index 8a20e690b9c0..b93aac8dd3b6 100644 --- a/secure/lib/libcrypto/man/man3/BN_rand.3 +++ b/secure/lib/libcrypto/man/man3/BN_rand.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== @@ -68,8 +68,6 @@ . \} .\} .rr rF -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ @@ -132,54 +130,83 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "BN_RAND 3" -.TH BN_RAND 3 "2022-07-05" "1.1.1q" "OpenSSL" +.IX Title "BN_RAND 3ossl" +.TH BN_RAND 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" -BN_rand, BN_priv_rand, BN_pseudo_rand, BN_rand_range, BN_priv_rand_range, BN_pseudo_rand_range \&\- generate pseudo\-random number +BN_rand_ex, BN_rand, BN_priv_rand_ex, BN_priv_rand, BN_pseudo_rand, +BN_rand_range_ex, BN_rand_range, BN_priv_rand_range_ex, BN_priv_rand_range, +BN_pseudo_rand_range +\&\- generate pseudo\-random number .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/bn.h> \& +\& 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, +\& unsigned int strength, BN_CTX *ctx); \& int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom); \& -\& int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); -\& -\& int BN_rand_range(BIGNUM *rnd, BIGNUM *range); +\& int BN_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength, +\& BN_CTX *ctx); +\& int BN_rand_range(BIGNUM *rnd, const BIGNUM *range); \& -\& int BN_priv_rand_range(BIGNUM *rnd, BIGNUM *range); -\& -\& int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); +\& int BN_priv_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength, +\& BN_CTX *ctx); +\& int BN_priv_rand_range(BIGNUM *rnd, const BIGNUM *range); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 2 +\& int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); +\& int BN_pseudo_rand_range(BIGNUM *rnd, const BIGNUM *range); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" -\&\fBBN_rand()\fR generates a cryptographically strong pseudo-random number of -\&\fBbits\fR in length and stores it in \fBrnd\fR. -If \fBbits\fR is less than zero, or too small to -accommodate the requirements specified by the \fBtop\fR and \fBbottom\fR +\&\fBBN_rand_ex()\fR generates a cryptographically strong pseudo-random +number of \fIbits\fR in length and security strength at least \fIstrength\fR bits +using the random number generator for the library context associated with +\&\fIctx\fR. The function stores the generated data in \fIrnd\fR. The parameter \fIctx\fR +may be \s-1NULL\s0 in which case the default library context is used. +If \fIbits\fR is less than zero, or too small to +accommodate the requirements specified by the \fItop\fR and \fIbottom\fR parameters, an error is returned. -The \fBtop\fR parameters specifies +The \fItop\fR parameters specifies requirements on the most significant bit of the generated number. If it is \fB\s-1BN_RAND_TOP_ANY\s0\fR, there is no constraint. If it is \fB\s-1BN_RAND_TOP_ONE\s0\fR, the top bit must be one. If it is \fB\s-1BN_RAND_TOP_TWO\s0\fR, 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*\fBbits\fR length. -If \fBbottom\fR is \fB\s-1BN_RAND_BOTTOM_ODD\s0\fR, the number will be odd; if it +numbers will always have 2*\fIbits\fR length. +If \fIbottom\fR is \fB\s-1BN_RAND_BOTTOM_ODD\s0\fR, the number will be odd; if it is \fB\s-1BN_RAND_BOTTOM_ANY\s0\fR it can be odd or even. -If \fBbits\fR is 1 then \fBtop\fR cannot also be \fB\s-1BN_RAND_TOP_TWO\s0\fR. +If \fIbits\fR is 1 then \fItop\fR cannot also be \fB\s-1BN_RAND_TOP_TWO\s0\fR. +.PP +\&\fBBN_rand()\fR is the same as \fBBN_rand_ex()\fR except that the default library context +is always used. .PP -\&\fBBN_rand_range()\fR generates a cryptographically strong pseudo-random -number \fBrnd\fR in the range 0 <= \fBrnd\fR < \fBrange\fR. +\&\fBBN_rand_range_ex()\fR generates a cryptographically strong pseudo-random +number \fIrnd\fR, of security strength at least \fIstrength\fR bits, +in the range 0 <= \fIrnd\fR < \fIrange\fR using the random number +generator for the library context associated with \fIctx\fR. The parameter \fIctx\fR +may be \s-1NULL\s0 in which case the default library context is used. .PP -\&\fBBN_priv_rand()\fR and \fBBN_priv_rand_range()\fR have the same semantics as -\&\fBBN_rand()\fR and \fBBN_rand_range()\fR respectively. They are intended to be +\&\fBBN_rand_range()\fR is the same as \fBBN_rand_range_ex()\fR except that the default +library context is always used. +.PP +\&\fBBN_priv_rand_ex()\fR, \fBBN_priv_rand()\fR, \fBBN_priv_rand_rand_ex()\fR and +\&\fBBN_priv_rand_range()\fR have the same semantics as \fBBN_rand_ex()\fR, \fBBN_rand()\fR, +\&\fBBN_rand_range_ex()\fR and \fBBN_rand_range()\fR respectively. They are intended to be used for generating values that should remain private, and mirror the same difference between \fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3). .SH "NOTES" @@ -198,23 +225,26 @@ The error codes can be obtained by \fBERR_get_error\fR\|(3). \&\fBRAND_bytes\fR\|(3), \&\fBRAND_priv_bytes\fR\|(3), \&\s-1\fBRAND\s0\fR\|(7), -\&\s-1\fBRAND_DRBG\s0\fR\|(7) +\&\s-1\fBEVP_RAND\s0\fR\|(7) .SH "HISTORY" .IX Header "HISTORY" .IP "\(bu" 2 Starting with OpenSSL release 1.1.0, \fBBN_pseudo_rand()\fR has been identical to \fBBN_rand()\fR and \fBBN_pseudo_rand_range()\fR has been identical to \&\fBBN_rand_range()\fR. -The \*(L"pseudo\*(R" functions should not be used and may be deprecated in -a future release. +The \fBBN_pseudo_rand()\fR and \fBBN_pseudo_rand_range()\fR functions were +deprecated in OpenSSL 3.0. +.IP "\(bu" 2 +The \fBBN_priv_rand()\fR and \fBBN_priv_rand_range()\fR functions were added in +OpenSSL 1.1.1. .IP "\(bu" 2 -The -\&\fBBN_priv_rand()\fR and \fBBN_priv_rand_range()\fR functions were added in OpenSSL 1.1.1. +The \fBBN_rand_ex()\fR, \fBBN_priv_rand_ex()\fR, \fBBN_rand_range_ex()\fR and +\&\fBBN_priv_rand_range_ex()\fR functions were added in OpenSSL 3.0. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2000\-2021 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>. |