diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/RAND_bytes.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/RAND_bytes.3 | 168 |
1 files changed, 168 insertions, 0 deletions
diff --git a/secure/lib/libcrypto/man/man3/RAND_bytes.3 b/secure/lib/libcrypto/man/man3/RAND_bytes.3 new file mode 100644 index 000000000000..2b9fff02773e --- /dev/null +++ b/secure/lib/libcrypto/man/man3/RAND_bytes.3 @@ -0,0 +1,168 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "RAND_BYTES 3ossl" +.TH RAND_BYTES 3ossl 2025-09-16 3.5.3 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +RAND_bytes, RAND_priv_bytes, RAND_bytes_ex, RAND_priv_bytes_ex, +RAND_pseudo_bytes, RAND_set1_random_provider \- generate random data +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/rand.h> +\& +\& int RAND_bytes(unsigned char *buf, int num); +\& int RAND_priv_bytes(unsigned char *buf, int num); +\& +\& int RAND_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, size_t num, +\& unsigned int strength); +\& int RAND_priv_bytes_ex(OSSL_LIB_CTX *ctx, unsigned char *buf, size_t num, +\& unsigned int strength); +\& +\& int RAND_set1_random_provider(OSSL_LIB_CTX *ctx, OSSL_PROVIDER *p); +.Ve +.PP +The following function has been deprecated since OpenSSL 1.1.0, and can be +hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 1 +\& int RAND_pseudo_bytes(unsigned char *buf, int num); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBRAND_bytes()\fR generates \fBnum\fR random bytes using a cryptographically +secure pseudo random generator (CSPRNG) and stores them in \fBbuf\fR. \fBbuf\fR \fBMUST NOT\fR be NULL. +.PP +\&\fBRAND_priv_bytes()\fR has the same semantics as \fBRAND_bytes()\fR. It is intended to +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 \fBRAND\fR\|(7) +and \fBEVP_RAND\fR\|(7). +.PP +\&\fBRAND_bytes_ex()\fR and \fBRAND_priv_bytes_ex()\fR are the same as \fBRAND_bytes()\fR and +\&\fBRAND_priv_bytes()\fR except that they both take additional \fIstrength\fR and +\&\fIctx\fR parameters. The bytes generated will have a security strength of at +least \fIstrength\fR bits. +The DRBG used for the operation is the public or private DRBG associated with +the specified \fIctx\fR. The parameter can be NULL, in which case +the default library context is used (see \fBOSSL_LIB_CTX\fR\|(3). +If the default RAND_METHOD has been changed then for compatibility reasons the +RAND_METHOD will be used in preference and the DRBG of the library context +ignored. +.PP +\&\fBRAND_set1_random_provider()\fR specifies a provider, \fIprov\fR, which will be used +by the library context \fIctx\fR for all of the generate calls above instead +of the built-in in DRBGs and entropy source. Pass NULL for the provider +to disable the random provider functionality. In this case, the built-in DRBGs +and entropy source will be used. This call should not be considered thread safe. +.SH NOTES +.IX Header "NOTES" +By default, the OpenSSL CSPRNG supports a security level of 256 bits, provided it +was able to seed itself from a trusted entropy source. +On all major platforms supported by OpenSSL (including the Unix-like platforms +and Windows), OpenSSL is configured to automatically seed the CSPRNG on first use +using the operating systems's random generator. +.PP +If the entropy source fails or is not available, the CSPRNG will enter an +error state and refuse to generate random bytes. For that reason, it is important +to always check the error return value of \fBRAND_bytes()\fR and \fBRAND_priv_bytes()\fR and +not take randomness for granted. +.PP +On other platforms, there might not be a trusted entropy source available +or OpenSSL might have been explicitly configured to use different entropy sources. +If you are in doubt about the quality of the entropy source, don't hesitate to ask +your operating system vendor or post a question on GitHub or the openssl-users +mailing list. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBRAND_bytes()\fR and \fBRAND_priv_bytes()\fR +return 1 on success, \-1 if not supported by the current +RAND method, or 0 on other failure. The error code can be +obtained by \fBERR_get_error\fR\|(3). +.PP +\&\fBRAND_set1_random_provider()\fR returns 1 on success and 0 on failure. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBRAND_add\fR\|(3), +\&\fBRAND_bytes\fR\|(3), +\&\fBRAND_priv_bytes\fR\|(3), +\&\fBERR_get_error\fR\|(3), +\&\fBRAND\fR\|(7), +\&\fBEVP_RAND\fR\|(7) +.SH HISTORY +.IX Header "HISTORY" +.IP \(bu 2 +\&\fBRAND_pseudo_bytes()\fR was deprecated in OpenSSL 1.1.0; use \fBRAND_bytes()\fR instead. +.IP \(bu 2 +The \fBRAND_priv_bytes()\fR function was added in OpenSSL 1.1.1. +.IP \(bu 2 +The \fBRAND_bytes_ex()\fR and \fBRAND_priv_bytes_ex()\fR functions were added in OpenSSL 3.0 +.IP \(bu 2 +The \fBRAND_set1_random_provider()\fR function was added in OpenSSL 3.5 +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2000\-2025 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (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 +<https://www.openssl.org/source/license.html>. |