1e71b7053SJung-uk Kim=pod 2e71b7053SJung-uk Kim 3e71b7053SJung-uk Kim=head1 NAME 4e71b7053SJung-uk Kim 5b077aed3SPierre ProncheryRAND_bytes, RAND_priv_bytes, RAND_bytes_ex, RAND_priv_bytes_ex, 6b077aed3SPierre ProncheryRAND_pseudo_bytes - generate random data 7e71b7053SJung-uk Kim 8e71b7053SJung-uk Kim=head1 SYNOPSIS 9e71b7053SJung-uk Kim 10e71b7053SJung-uk Kim #include <openssl/rand.h> 11e71b7053SJung-uk Kim 12e71b7053SJung-uk Kim int RAND_bytes(unsigned char *buf, int num); 13e71b7053SJung-uk Kim int RAND_priv_bytes(unsigned char *buf, int num); 14e71b7053SJung-uk Kim 15b077aed3SPierre Pronchery int RAND_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, size_t num, 16b077aed3SPierre Pronchery unsigned int strength); 17b077aed3SPierre Pronchery int RAND_priv_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, size_t num, 18b077aed3SPierre Pronchery unsigned int strength); 19e71b7053SJung-uk Kim 20b077aed3SPierre ProncheryThe following function has been deprecated since OpenSSL 1.1.0, and can be 21b077aed3SPierre Proncheryhidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 22b077aed3SPierre Proncherysee L<openssl_user_macros(7)>: 23b077aed3SPierre Pronchery 24e71b7053SJung-uk Kim int RAND_pseudo_bytes(unsigned char *buf, int num); 25e71b7053SJung-uk Kim 26e71b7053SJung-uk Kim=head1 DESCRIPTION 27e71b7053SJung-uk Kim 2817f01e99SJung-uk KimRAND_bytes() generates B<num> random bytes using a cryptographically 2917f01e99SJung-uk Kimsecure pseudo random generator (CSPRNG) and stores them in B<buf>. 30e71b7053SJung-uk Kim 31e71b7053SJung-uk KimRAND_priv_bytes() has the same semantics as RAND_bytes(). It is intended to 32e71b7053SJung-uk Kimbe used for generating values that should remain private. If using the 33e71b7053SJung-uk Kimdefault RAND_METHOD, this function uses a separate "private" PRNG 34e71b7053SJung-uk Kiminstance so that a compromise of the "public" PRNG instance will not 35e71b7053SJung-uk Kimaffect the secrecy of these private values, as described in L<RAND(7)> 36b077aed3SPierre Proncheryand L<EVP_RAND(7)>. 37b077aed3SPierre Pronchery 38b077aed3SPierre ProncheryRAND_bytes_ex() and RAND_priv_bytes_ex() are the same as RAND_bytes() and 39b077aed3SPierre ProncheryRAND_priv_bytes() except that they both take additional I<strength> and 40*aa795734SPierre ProncheryI<ctx> parameters. The bytes generated will have a security strength of at 41b077aed3SPierre Proncheryleast I<strength> bits. 42b077aed3SPierre ProncheryThe DRBG used for the operation is the public or private DRBG associated with 43b077aed3SPierre Proncherythe specified I<ctx>. The parameter can be NULL, in which case 44b077aed3SPierre Proncherythe default library context is used (see L<OSSL_LIB_CTX(3)>. 45b077aed3SPierre ProncheryIf the default RAND_METHOD has been changed then for compatibility reasons the 46b077aed3SPierre ProncheryRAND_METHOD will be used in preference and the DRBG of the library context 47b077aed3SPierre Proncheryignored. 48e71b7053SJung-uk Kim 49e71b7053SJung-uk Kim=head1 NOTES 50e71b7053SJung-uk Kim 5117f01e99SJung-uk KimBy default, the OpenSSL CSPRNG supports a security level of 256 bits, provided it 5217f01e99SJung-uk Kimwas able to seed itself from a trusted entropy source. 5317f01e99SJung-uk KimOn all major platforms supported by OpenSSL (including the Unix-like platforms 5417f01e99SJung-uk Kimand Windows), OpenSSL is configured to automatically seed the CSPRNG on first use 5517f01e99SJung-uk Kimusing the operating systems's random generator. 5617f01e99SJung-uk Kim 5717f01e99SJung-uk KimIf the entropy source fails or is not available, the CSPRNG will enter an 5817f01e99SJung-uk Kimerror state and refuse to generate random bytes. For that reason, it is important 5917f01e99SJung-uk Kimto always check the error return value of RAND_bytes() and RAND_priv_bytes() and 6017f01e99SJung-uk Kimnot take randomness for granted. 6117f01e99SJung-uk Kim 6217f01e99SJung-uk KimOn other platforms, there might not be a trusted entropy source available 6317f01e99SJung-uk Kimor OpenSSL might have been explicitly configured to use different entropy sources. 6417f01e99SJung-uk KimIf you are in doubt about the quality of the entropy source, don't hesitate to ask 6517f01e99SJung-uk Kimyour operating system vendor or post a question on GitHub or the openssl-users 6617f01e99SJung-uk Kimmailing list. 67e71b7053SJung-uk Kim 68e71b7053SJung-uk Kim=head1 RETURN VALUES 69e71b7053SJung-uk Kim 70e71b7053SJung-uk KimRAND_bytes() and RAND_priv_bytes() 71e71b7053SJung-uk Kimreturn 1 on success, -1 if not supported by the current 72e71b7053SJung-uk KimRAND method, or 0 on other failure. The error code can be 73e71b7053SJung-uk Kimobtained by L<ERR_get_error(3)>. 74e71b7053SJung-uk Kim 75610a21fdSJung-uk Kim=head1 SEE ALSO 76610a21fdSJung-uk Kim 77610a21fdSJung-uk KimL<RAND_add(3)>, 78610a21fdSJung-uk KimL<RAND_bytes(3)>, 79610a21fdSJung-uk KimL<RAND_priv_bytes(3)>, 80610a21fdSJung-uk KimL<ERR_get_error(3)>, 81610a21fdSJung-uk KimL<RAND(7)>, 82b077aed3SPierre ProncheryL<EVP_RAND(7)> 83610a21fdSJung-uk Kim 84e71b7053SJung-uk Kim=head1 HISTORY 85e71b7053SJung-uk Kim 86e71b7053SJung-uk Kim=over 2 87e71b7053SJung-uk Kim 88e71b7053SJung-uk Kim=item * 89e71b7053SJung-uk Kim 90e71b7053SJung-uk KimRAND_pseudo_bytes() was deprecated in OpenSSL 1.1.0; use RAND_bytes() instead. 91e71b7053SJung-uk Kim 92e71b7053SJung-uk Kim=item * 93e71b7053SJung-uk Kim 946935a639SJung-uk KimThe RAND_priv_bytes() function was added in OpenSSL 1.1.1. 95e71b7053SJung-uk Kim 96b077aed3SPierre Pronchery=item * 97b077aed3SPierre Pronchery 98b077aed3SPierre ProncheryThe RAND_bytes_ex() and RAND_priv_bytes_ex() functions were added in OpenSSL 3.0 99b077aed3SPierre Pronchery 100e71b7053SJung-uk Kim=back 101e71b7053SJung-uk Kim 102e71b7053SJung-uk Kim=head1 COPYRIGHT 103e71b7053SJung-uk Kim 104*aa795734SPierre ProncheryCopyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 105e71b7053SJung-uk Kim 106b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 107e71b7053SJung-uk Kimthis file except in compliance with the License. You can obtain a copy 108e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at 109e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>. 110e71b7053SJung-uk Kim 111e71b7053SJung-uk Kim=cut 112