]>
Commit | Line | Data |
---|---|---|
dd8dec69 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
ee1d4f3d MC |
5 | BN_rand_ex, BN_rand, BN_priv_rand_ex, BN_priv_rand, BN_pseudo_rand, |
6 | BN_rand_range_ex, BN_rand_range, BN_priv_rand_range_ex, BN_priv_rand_range, | |
7 | BN_pseudo_rand_range | |
b26befb5 | 8 | - generate pseudo-random number |
dd8dec69 UM |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/bn.h> | |
13 | ||
ee1d4f3d | 14 | int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, BN_CTX *ctx); |
dd8dec69 UM |
15 | int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); |
16 | ||
ee1d4f3d | 17 | int BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom, BN_CTX *ctx); |
b26befb5 NT |
18 | int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom); |
19 | ||
4d524e10 | 20 | int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); |
38e33cef | 21 | |
ee1d4f3d | 22 | int BN_rand_range_ex(BIGNUM *rnd, BIGNUM *range, BN_CTX *ctx); |
e3068929 | 23 | int BN_rand_range(BIGNUM *rnd, BIGNUM *range); |
57e7d3ce | 24 | |
ee1d4f3d | 25 | int BN_priv_rand_range_ex(BIGNUM *rnd, BIGNUM *range, BN_CTX *ctx); |
b26befb5 NT |
26 | int BN_priv_rand_range(BIGNUM *rnd, BIGNUM *range); |
27 | ||
b49053ca | 28 | int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); |
983495c4 | 29 | |
dd8dec69 UM |
30 | =head1 DESCRIPTION |
31 | ||
ee1d4f3d MC |
32 | BN_rand_ex() generate a cryptographically strong pseudo-random |
33 | number of B<bits> in length and stores it in B<rnd> using the random number | |
34 | generator for the library context associated with B<ctx>. The parameter B<ctx> | |
35 | may be NULL in which case the default library context is used. | |
01c09f9f | 36 | If B<bits> is less than zero, or too small to |
69687aa8 | 37 | accommodate the requirements specified by the B<top> and B<bottom> |
01c09f9f | 38 | parameters, an error is returned. |
f67cbb74 RS |
39 | The B<top> parameters specifies |
40 | requirements on the most significant bit of the generated number. | |
41 | If it is B<BN_RAND_TOP_ANY>, there is no constraint. | |
42 | If it is B<BN_RAND_TOP_ONE>, the top bit must be one. | |
43 | If it is B<BN_RAND_TOP_TWO>, the two most significant bits of | |
335c4f09 | 44 | the number will be set to 1, so that the product of two such random |
f67cbb74 RS |
45 | numbers will always have 2*B<bits> length. |
46 | If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it | |
47 | is B<BN_RAND_BOTTOM_ANY> it can be odd or even. | |
48 | If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>. | |
dd8dec69 | 49 | |
ee1d4f3d MC |
50 | BN_rand() is the same as BN_rand_ex() except that the default library context |
51 | is always used. | |
57e7d3ce | 52 | |
ee1d4f3d MC |
53 | BN_rand_range_ex() generates a cryptographically strong pseudo-random |
54 | number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range> using the random number | |
55 | generator for the library context associated with B<ctx>. The parameter B<ctx> | |
56 | may be NULL in which case the default library context is used. | |
57 | ||
58 | BN_rand_range() is the same as BN_rand_range_ex() except that the default | |
59 | library context is always used. | |
60 | ||
61 | BN_priv_rand_ex(), BN_priv_rand(), BN_priv_rand_rand_ex() and | |
62 | BN_priv_rand_range() have the same semantics as BN_rand_ex(), BN_rand(), | |
63 | BN_rand_range_ex() and BN_rand_range() respectively. They are intended to be | |
b26befb5 NT |
64 | used for generating values that should remain private, and mirror the |
65 | same difference between L<RAND_bytes(3)> and L<RAND_priv_bytes(3)>. | |
66 | ||
67 | =head1 NOTES | |
68 | ||
69 | Always check the error return value of these functions and do not take | |
70 | randomness for granted: an error occurs if the CSPRNG has not been | |
71 | seeded with enough randomness to ensure an unpredictable byte sequence. | |
dd8dec69 UM |
72 | |
73 | =head1 RETURN VALUES | |
74 | ||
57e7d3ce | 75 | The functions return 1 on success, 0 on error. |
9b86974e | 76 | The error codes can be obtained by L<ERR_get_error(3)>. |
dd8dec69 | 77 | |
b5c4bbbe JL |
78 | =head1 SEE ALSO |
79 | ||
80 | L<ERR_get_error(3)>, | |
81 | L<RAND_add(3)>, | |
82 | L<RAND_bytes(3)>, | |
83 | L<RAND_priv_bytes(3)>, | |
84 | L<RAND(7)>, | |
85 | L<RAND_DRBG(7)> | |
86 | ||
5ecff87d RS |
87 | =head1 HISTORY |
88 | ||
b26befb5 NT |
89 | =over 2 |
90 | ||
91 | =item * | |
92 | ||
93 | Starting with OpenSSL release 1.1.0, BN_pseudo_rand() has been identical | |
94 | to BN_rand() and BN_pseudo_rand_range() has been identical to | |
95 | BN_rand_range(). | |
5ecff87d RS |
96 | The "pseudo" functions should not be used and may be deprecated in |
97 | a future release. | |
98 | ||
b26befb5 NT |
99 | =item * |
100 | ||
fc5ecadd DMSP |
101 | The |
102 | BN_priv_rand() and BN_priv_rand_range() functions were added in OpenSSL 1.1.1. | |
b26befb5 | 103 | |
ee1d4f3d MC |
104 | =item * |
105 | ||
106 | The BN_rand_ex(), BN_priv_rand_ex(), BN_rand_range_ex() and | |
107 | BN_priv_rand_range_ex() functions were added in OpenSSL 3.0. | |
108 | ||
b26befb5 NT |
109 | =back |
110 | ||
e2f92610 RS |
111 | =head1 COPYRIGHT |
112 | ||
b5c4bbbe | 113 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 114 | |
4746f25a | 115 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
116 | this file except in compliance with the License. You can obtain a copy |
117 | in the file LICENSE in the source distribution or at | |
118 | L<https://www.openssl.org/source/license.html>. | |
119 | ||
120 | =cut |