Debian Codegraph @

upstream/debian-unstable/man3/BN_rand.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BN_RAND 3SSL"
58 .TH BN_RAND 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BN_rand_ex, BN_rand, BN_priv_rand_ex, BN_priv_rand, BN_pseudo_rand,
65 BN_rand_range_ex, BN_rand_range, BN_priv_rand_range_ex, BN_priv_rand_range,
66 BN_pseudo_rand_range
67 \&\- generate pseudo\-random number
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/bn.h>
72 \&
73 \& int BN_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,
74 \& unsigned int strength, BN_CTX *ctx);
75 \& int BN_rand(BIGNUM *rnd, int bits, int top, int bottom);
76 \&
77 \& int BN_priv_rand_ex(BIGNUM *rnd, int bits, int top, int bottom,
78 \& unsigned int strength, BN_CTX *ctx);
79 \& int BN_priv_rand(BIGNUM *rnd, int bits, int top, int bottom);
80 \&
81 \& int BN_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength,
82 \& BN_CTX *ctx);
83 \& int BN_rand_range(BIGNUM *rnd, const BIGNUM *range);
84 \&
85 \& int BN_priv_rand_range_ex(BIGNUM *rnd, const BIGNUM *range, unsigned int strength,
86 \& BN_CTX *ctx);
87 \& int BN_priv_rand_range(BIGNUM *rnd, const BIGNUM *range);
88 .Ve
89 .PP
90 The following functions have been deprecated since OpenSSL 3.0, and can be
91 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
92 see \fBopenssl_user_macros\fR\|(7):
93 .PP
94 .Vb 2
95 \& int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom);
96 \& int BN_pseudo_rand_range(BIGNUM *rnd, const BIGNUM *range);
97 .Ve
98 .SH DESCRIPTION
99 .IX Header "DESCRIPTION"
100 \&\fBBN_rand_ex()\fR generates a cryptographically strong pseudo-random
101 number of \fIbits\fR in length and security strength at least \fIstrength\fR bits
102 using the random number generator for the library context associated with
103 \&\fIctx\fR. The function stores the generated data in \fIrnd\fR. The parameter \fIctx\fR
104 may be NULL in which case the default library context is used.
105 If \fIbits\fR is less than zero, or too small to
106 accommodate the requirements specified by the \fItop\fR and \fIbottom\fR
107 parameters, an error is returned.
108 The \fItop\fR parameters specifies
109 requirements on the most significant bit of the generated number.
110 If it is \fBBN_RAND_TOP_ANY\fR, there is no constraint.
111 If it is \fBBN_RAND_TOP_ONE\fR, the top bit must be one.
112 If it is \fBBN_RAND_TOP_TWO\fR, the two most significant bits of
113 the number will be set to 1, so that the product of two such random
114 numbers will always have 2*\fIbits\fR length.
115 If \fIbottom\fR is \fBBN_RAND_BOTTOM_ODD\fR, the number will be odd; if it
116 is \fBBN_RAND_BOTTOM_ANY\fR it can be odd or even.
117 If \fIbits\fR is 1 then \fItop\fR cannot also be \fBBN_RAND_TOP_TWO\fR.
118 .PP
119 \&\fBBN_rand()\fR is the same as \fBBN_rand_ex()\fR except that the default library context
120 is always used.
121 .PP
122 \&\fBBN_rand_range_ex()\fR generates a cryptographically strong pseudo-random
123 number \fIrnd\fR, of security strength at least \fIstrength\fR bits,
124 in the range 0 <= \fIrnd\fR < \fIrange\fR using the random number
125 generator for the library context associated with \fIctx\fR. The parameter \fIctx\fR
126 may be NULL in which case the default library context is used.
127 .PP
128 \&\fBBN_rand_range()\fR is the same as \fBBN_rand_range_ex()\fR except that the default
129 library context is always used.
130 .PP
131 \&\fBBN_priv_rand_ex()\fR, \fBBN_priv_rand()\fR, \fBBN_priv_rand_rand_ex()\fR and
132 \&\fBBN_priv_rand_range()\fR have the same semantics as \fBBN_rand_ex()\fR, \fBBN_rand()\fR,
133 \&\fBBN_rand_range_ex()\fR and \fBBN_rand_range()\fR respectively. They are intended to be
134 used for generating values that should remain private, and mirror the
135 same difference between \fBRAND_bytes\fR\|(3) and \fBRAND_priv_bytes\fR\|(3).
136 .SH NOTES
137 .IX Header "NOTES"
138 Always check the error return value of these functions and do not take
139 randomness for granted: an error occurs if the CSPRNG has not been
140 seeded with enough randomness to ensure an unpredictable byte sequence.
141 .SH "RETURN VALUES"
142 .IX Header "RETURN VALUES"
143 The functions return 1 on success, 0 on error.
144 The error codes can be obtained by \fBERR_get_error\fR\|(3).
145 .SH "SEE ALSO"
146 .IX Header "SEE ALSO"
147 \&\fBERR_get_error\fR\|(3),
148 \&\fBRAND_add\fR\|(3),
149 \&\fBRAND_bytes\fR\|(3),
150 \&\fBRAND_priv_bytes\fR\|(3),
151 \&\fBRAND\fR\|(7),
152 \&\fBEVP_RAND\fR\|(7)
153 .SH HISTORY
154 .IX Header "HISTORY"
155 .IP \(bu 2
156 Starting with OpenSSL release 1.1.0, \fBBN_pseudo_rand()\fR has been identical
157 to \fBBN_rand()\fR and \fBBN_pseudo_rand_range()\fR has been identical to
158 \&\fBBN_rand_range()\fR.
159 The \fBBN_pseudo_rand()\fR and \fBBN_pseudo_rand_range()\fR functions were
160 deprecated in OpenSSL 3.0.
161 .IP \(bu 2
162 The \fBBN_priv_rand()\fR and \fBBN_priv_rand_range()\fR functions were added in
163 OpenSSL 1.1.1.
164 .IP \(bu 2
165 The \fBBN_rand_ex()\fR, \fBBN_priv_rand_ex()\fR, \fBBN_rand_range_ex()\fR and
166 \&\fBBN_priv_rand_range_ex()\fR functions were added in OpenSSL 3.0.
167 .SH COPYRIGHT
168 .IX Header "COPYRIGHT"
169 Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved.
170 .PP
171 Licensed under the Apache License 2.0 (the "License"). You may not use
172 this file except in compliance with the License. You can obtain a copy
173 in the file LICENSE in the source distribution or at
174 <https://www.openssl.org/source/license.html>.