root
/
openssl
mirror of https://github.com/openssl/openssl.git
1
0
Fork 0
Code Issues Actions 7 Packages Projects Releases Wiki Activity
openssl/doc/man3/RAND_bytes.pod

79 lines
2.0 KiB
Plaintext
Raw Normal View History

Document RAND library.
2000-01-22 01:50:27 +08:00
=pod
=head1 NAME
Add RAND_priv_bytes() for private keys Add a new global DRBG for private keys used by RAND_priv_bytes. Add BN_priv_rand() and BN_priv_rand_range() which use RAND_priv_bytes(). Change callers to use the appropriate BN_priv... function. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/4076)
2017-08-03 02:00:52 +08:00
RAND_bytes, RAND_priv_bytes, RAND_pseudo_bytes - generate random data
Document RAND library.
2000-01-22 01:50:27 +08:00
=head1 SYNOPSIS
#include <openssl/rand.h>
int RAND_bytes(unsigned char *buf, int num);
Add RAND_priv_bytes() for private keys Add a new global DRBG for private keys used by RAND_priv_bytes. Add BN_priv_rand() and BN_priv_rand_range() which use RAND_priv_bytes(). Change callers to use the appropriate BN_priv... function. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/4076)
2017-08-03 02:00:52 +08:00
int RAND_priv_bytes(unsigned char *buf, int num);
Document RAND library.
2000-01-22 01:50:27 +08:00
Docs: better deprecation text Expand the text on deprecation to be more descriptive and to refer back to openssl_user_macros(7). Incidently, this required a small change in util/find-doc-nits, to have it skip over any line that isn't part of a block (i.e. that hasn't been indented with at least one space. That makes it skip over deprecation text. Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/7745)
2018-12-03 17:59:11 +08:00
Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining
B<OPENSSL_API_COMPAT> with a suitable version value, see
L<openssl_user_macros(7)>:
Deprecate RAND_pseudo_bytes The justification for RAND_pseudo_bytes is somewhat dubious, and the reality is that it is frequently being misused. RAND_bytes and RAND_pseudo_bytes in the default implementation both end up calling ssleay_rand_bytes. Both may return -1 in an error condition. If there is insufficient entropy then both will return 0, but RAND_bytes will additionally add an error to the error queue. They both return 1 on success. Therefore the fundamental difference between the two is that one will add an error to the error queue with insufficient entory whilst the other will not. Frequently there are constructions of this form: if(RAND_pseudo_bytes(...) <= 1) goto err; In the above form insufficient entropy is treated as an error anyway, so RAND_bytes is probably the better form to use. This form is also seen: if(!RAND_pseudo_bytes(...)) goto err; This is technically not correct at all since a -1 return value is incorrectly handled - but this form will also treat insufficient entropy as an error. Within libssl it is required that you have correctly seeded your entropy pool and so there seems little benefit in using RAND_pseudo_bytes. Similarly in libcrypto many operations also require a correctly seeded entropy pool and so in most interesting cases you would be better off using RAND_bytes anyway. There is a significant risk of RAND_pseudo_bytes being incorrectly used in scenarios where security can be compromised by insufficient entropy. If you are not using the default implementation, then most engines use the same function to implement RAND_bytes and RAND_pseudo_bytes in any case. Given its misuse, limited benefit, and potential to compromise security, RAND_pseudo_bytes has been deprecated. Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-02-26 21:52:30 +08:00
Document RAND library.
2000-01-22 01:50:27 +08:00
int RAND_pseudo_bytes(unsigned char *buf, int num);
=head1 DESCRIPTION
Avoid integer overflow in entropy counter. Slightly clarify the RAND_... documentation.
2000-01-22 03:54:22 +08:00
RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes
Fix & update documentation about RAND_priv_bytes() Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Ben Kaduk <kaduk@mit.edu> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/6514)
2018-06-19 00:13:36 +08:00
into B<buf>.
Avoid integer overflow in entropy counter. Slightly clarify the RAND_... documentation.
2000-01-22 03:54:22 +08:00
Add RAND_priv_bytes() for private keys Add a new global DRBG for private keys used by RAND_priv_bytes. Add BN_priv_rand() and BN_priv_rand_range() which use RAND_priv_bytes(). Change callers to use the appropriate BN_priv... function. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/4076)
2017-08-03 02:00:52 +08:00
RAND_priv_bytes() has the same semantics as RAND_bytes(). It is intended to
Fix & update documentation about RAND_priv_bytes() Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Ben Kaduk <kaduk@mit.edu> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/6514)
2018-06-19 00:13:36 +08:00
be used for generating values that should remain private. If using the
default RAND_METHOD, this function uses a separate "private" PRNG
instance so that a compromise of the "public" PRNG instance will not
affect the secrecy of these private values, as described in L<RAND(7)>
and L<RAND_DRBG(7)>.
=head1 NOTES
Always check the error return value of RAND_bytes() and
RAND_priv_bytes() and do not take randomness for granted: an error occurs
if the CSPRNG has not been seeded with enough randomness to ensure an
unpredictable byte sequence.
Add RAND_priv_bytes() for private keys Add a new global DRBG for private keys used by RAND_priv_bytes. Add BN_priv_rand() and BN_priv_rand_range() which use RAND_priv_bytes(). Change callers to use the appropriate BN_priv... function. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/4076)
2017-08-03 02:00:52 +08:00
Document RAND library.
2000-01-22 01:50:27 +08:00
=head1 RETURN VALUES
Add documentation for the RAND_DRBG API The RAND_DRBG API was added in PR #5462 and modified by PR #5547. This commit adds the corresponding documention. Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Rich Salz <rsalz@openssl.org> (Merged from https://github.com/openssl/openssl/pull/5461)
2018-02-28 02:02:24 +08:00
RAND_bytes() and RAND_priv_bytes()
Add RAND_priv_bytes() for private keys Add a new global DRBG for private keys used by RAND_priv_bytes. Add BN_priv_rand() and BN_priv_rand_range() which use RAND_priv_bytes(). Change callers to use the appropriate BN_priv... function. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/4076)
2017-08-03 02:00:52 +08:00
return 1 on success, -1 if not supported by the current
Add RAND_UNIMPLEMENTED error code See old GitHub PR 38. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3714)
2017-06-20 00:58:06 +08:00
RAND method, or 0 on other failure. The error code can be
obtained by L<ERR_get_error(3)>.
Update various man pages to place HISTORY section after SEE ALSO SEE ALSO before HISTORY is the more common pattern in OpenSSL manual pages and seems to be the prevalent order based on sampling my system manual pages. Fixes #8631 Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8729)
2019-04-09 22:13:55 +08:00
=head1 SEE ALSO
L<RAND_add(3)>,
L<RAND_bytes(3)>,
L<RAND_priv_bytes(3)>,
L<ERR_get_error(3)>,
L<RAND(7)>,
L<RAND_DRBG(7)>
Various doc fixes Fix a =head1 section name Fix a typo in POD label Remove a spurious =back Add a missing blank line Avoid 'legacy' -- use 'deprecated' if still needed if we cannot just reword. Always do strict checking Do not warn about missing "RETURN VALUES" unless -s is set. Change OpenSSL version 1.1 -> 1.1.0 Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3830)
2017-07-03 00:16:38 +08:00
=head1 HISTORY
Add RAND_UNIMPLEMENTED error code See old GitHub PR 38. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3714)
2017-06-20 00:58:06 +08:00
Fix & update documentation about RAND_priv_bytes() Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Ben Kaduk <kaduk@mit.edu> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/6514)
2018-06-19 00:13:36 +08:00
=over 2
=item *
BN_pseudo_rand is really BN_rand And BN_pseudo_rand_range is really BN_rand_range. Document that we might deprecate those functions. Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3743)
2017-06-21 20:55:02 +08:00
RAND_pseudo_bytes() was deprecated in OpenSSL 1.1.0; use RAND_bytes() instead.
Document RAND library.
2000-01-22 01:50:27 +08:00
Fix & update documentation about RAND_priv_bytes() Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Ben Kaduk <kaduk@mit.edu> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/6514)
2018-06-19 00:13:36 +08:00
=item *
man: harmonize the various formulations in the HISTORY sections While stereotyped repetitions are frowned upon in literature, they serve a useful purpose in manual pages, because it is easier for the user to find certain information if it is always presented in the same way. For that reason, this commit harmonizes the varying formulations in the HISTORY section about which functions, flags, etc. were added in which OpenSSL version. It also attempts to make the pod files more grep friendly by avoiding to insert line breaks between the symbol names and the corresponding version number in which they were introduced (wherever possible). Some punctuation and typographical errors were fixed on the way. Reviewed-by: Tim Hudson <tjh@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7854)
2018-12-09 08:02:36 +08:00
The RAND_priv_bytes() function was added in OpenSSL 1.1.1.
Fix & update documentation about RAND_priv_bytes() Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Ben Kaduk <kaduk@mit.edu> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/6514)
2018-06-19 00:13:36 +08:00
=back
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
=head1 COPYRIGHT
Update various man pages to place HISTORY section after SEE ALSO SEE ALSO before HISTORY is the more common pattern in OpenSSL manual pages and seems to be the prevalent order based on sampling my system manual pages. Fixes #8631 Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/8729)
2019-04-09 22:13:55 +08:00
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
Following the license change, modify the boilerplates in doc/man3/ [skip ci] Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7829)
2018-12-06 21:04:44 +08:00
Licensed under the Apache License 2.0 (the "License"). You may not use
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
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