Add #defines for magic numbers in API.

[openssl.git] / doc / crypto / BN_rand.pod

diff --git a/doc/crypto/BN_rand.pod b/doc/crypto/BN_rand.pod
index d6b975ccf64385a96b5c880e4ddab4a5cf725dda..ba505e1e647d0523e8e0cd4df35cbefa5a5d02fe 100644 (file)
--- a/doc/crypto/BN_rand.pod
+++ b/doc/crypto/BN_rand.pod
@@ -19,12 +19,18 @@ BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-r
 =head1 DESCRIPTION
 
 BN_rand() generates a cryptographically strong pseudo-random number of
 =head1 DESCRIPTION
 
 BN_rand() generates a cryptographically strong pseudo-random number of

-B<bits> bits in length and stores it in B<rnd>. If B<top> is -1, the
-most significant bit of the random number can be zero. If B<top> is 0,
-it is set to 1, and if B<top> is 1, the two most significant bits of
+B<bits> in length and stores it in B<rnd>.
+The value of B<bits> must be zero or greater.
+The B<top> parameters specifies
+requirements on the most significant bit of the generated number.
+If it is B<BN_RAND_TOP_ANY>, there is no constraint.
+If it is B<BN_RAND_TOP_ONE>, the top bit must be one.
+If it is B<BN_RAND_TOP_TWO>, the two most significant bits of

 the number will be set to 1, so that the product of two such random
 the number will be set to 1, so that the product of two such random

-numbers will always have 2*B<bits> length.  If B<bottom> is true, the
-number will be odd.
+numbers will always have 2*B<bits> length.
+If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it
+is B<BN_RAND_BOTTOM_ANY> it can be odd or even.
+If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>.

 
 BN_pseudo_rand() does the same, but pseudo-random numbers generated by
 this function are not necessarily unpredictable. They can be used for
 
 BN_pseudo_rand() does the same, but pseudo-random numbers generated by
 this function are not necessarily unpredictable. They can be used for


@@ -32,7 +38,7 @@ non-cryptographic purposes and for certain purposes in cryptographic
 protocols, but usually not for key generation etc.
 
 BN_rand_range() generates a cryptographically strong pseudo-random
 protocols, but usually not for key generation etc.
 
 BN_rand_range() generates a cryptographically strong pseudo-random

-number B<rnd> in the range 0 <lt>= B<rnd> E<lt> B<range>.
+number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>.

 BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(),
 and hence numbers generated by it are not necessarily unpredictable.
 
 BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(),
 and hence numbers generated by it are not necessarily unpredictable.
 


@@ -41,18 +47,20 @@ The PRNG must be seeded prior to calling BN_rand() or BN_rand_range().
 =head1 RETURN VALUES
 
 The functions return 1 on success, 0 on error.
 =head1 RETURN VALUES
 
 The functions return 1 on success, 0 on error.

-The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
+The error codes can be obtained by L<ERR_get_error(3)>.

 
 =head1 SEE ALSO
 
 
 =head1 SEE ALSO
 

-L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
-L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)>
+L<bn(3)>, L<ERR_get_error(3)>, L<rand(3)>,
+L<RAND_add(3)>, L<RAND_bytes(3)>

 
 

-=head1 HISTORY
+=head1 COPYRIGHT

 
 

-BN_rand() is available in all versions of SSLeay and OpenSSL.
-BN_pseudo_rand() was added in OpenSSL 0.9.5. The B<top> == -1 case
-and the function BN_rand_range() were added in OpenSSL 0.9.6a.
-BN_pseudo_rand_range() was added in OpenSSL 0.9.6c.
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.

 
 =cut
 
 =cut