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