1.\" $OpenBSD: BN_rand.3,v 1.18 2021/11/30 18:34:35 tb Exp $ 2.\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400 3.\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100 4.\" 5.\" This file was written by Ulf Moeller <ulf@openssl.org>. 6.\" Copyright (c) 2000, 2001, 2002, 2013, 2015 The OpenSSL Project. 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: November 30 2021 $ 54.Dt BN_RAND 3 55.Os 56.Sh NAME 57.Nm BN_rand , 58.Nm BN_rand_range , 59.Nm BN_pseudo_rand , 60.Nm BN_pseudo_rand_range 61.Nd generate pseudo-random number 62.Sh SYNOPSIS 63.In openssl/bn.h 64.Ft int 65.Fo BN_rand 66.Fa "BIGNUM *rnd" 67.Fa "int bits" 68.Fa "int top" 69.Fa "int bottom" 70.Fc 71.Ft int 72.Fo BN_rand_range 73.Fa "BIGNUM *rnd" 74.Fa "const BIGNUM *range" 75.Fc 76.Sh DESCRIPTION 77.Fn BN_rand 78generates a cryptographically strong pseudo-random number of 79.Fa bits 80in length and stores it in 81.Fa rnd . 82If 83.Fa top 84is 85.Dv BN_RAND_TOP_ANY , 86the most significant bit of the random number can be zero. 87If 88.Fa top 89is 90.Dv BN_RAND_TOP_ONE , 91the most significant bit is set to 1, and if 92.Fa top 93is 94.Dv BN_RAND_TOP_TWO , 95the two most significant bits of the number will be set to 1, so 96that the product of two such random numbers will always have 97.Pf 2* Fa bits 98length. 99If 100.Fa bottom 101is 102.Dv BN_RAND_BOTTOM_ODD , 103the number will be odd; 104if it is 105.Dv BN_RAND_BOTTOM_ANY , 106it can be odd or even. 107The value of 108.Fa bits 109must be zero or greater. 110If 111.Fa bits 112is +1 then 113.Fa top 114cannot be 115.Dv BN_RAND_TOP_TWO . 116.Pp 117.Fn BN_rand_range 118generates a cryptographically strong pseudo-random number 119.Fa rnd 120in the range 0 <= 121.Fa rnd No < Fa range . 122.Pp 123.Fn BN_pseudo_rand 124is a deprecated alias for 125.Fn BN_rand , 126and 127.Fn BN_pseudo_rand_range 128for 129.Fn BN_rand_range . 130.Sh RETURN VALUES 131The functions return 1 on success, 0 on error. 132The error codes can be obtained by 133.Xr ERR_get_error 3 . 134.Sh SEE ALSO 135.Xr BN_new 3 136.Sh HISTORY 137.Fn BN_rand 138first appeared in SSLeay 0.5.1 and has been available since 139.Ox 2.4 . 140.Pp 141The 142.Fa top 143== -1 case and the function 144.Fn BN_rand_range 145first appeared in OpenSSL 0.9.6a and have been available since 146.Ox 3.0 . 147