1.\" $OpenBSD: BN_rand.3,v 1.16 2019/06/10 14:58:48 schwarze 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: June 10 2019 $ 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 "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 -1, the most significant bit of the random number can be zero. 85If 86.Fa top 87is 0, it is set to 1, and if 88.Fa top 89is 1, the two most significant bits of the number will be set to 1, so 90that the product of two such random numbers will always have 91.Pf 2* Fa bits 92length. 93If 94.Fa bottom 95is true, the number will be odd. 96The value of 97.Fa bits 98must be zero or greater. 99If 100.Fa bits 101is +1 then 102.Fa top 103cannot also be 1. 104.Pp 105.Fn BN_rand_range 106generates a cryptographically strong pseudo-random number 107.Fa rnd 108in the range 0 <= 109.Fa rnd No < Fa range . 110.Pp 111.Fn BN_pseudo_rand 112is a deprecated alias for 113.Fn BN_rand , 114and 115.Fn BN_pseudo_rand_range 116for 117.Fn BN_rand_range . 118.Sh RETURN VALUES 119The functions return 1 on success, 0 on error. 120The error codes can be obtained by 121.Xr ERR_get_error 3 . 122.Sh SEE ALSO 123.Xr BN_new 3 124.Sh HISTORY 125.Fn BN_rand 126first appeared in SSLeay 0.5.1 and has been available since 127.Ox 2.4 . 128.Pp 129The 130.Fa top 131== -1 case and the function 132.Fn BN_rand_range 133first appeared in OpenSSL 0.9.6a and have been available since 134.Ox 3.0 . 135