X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FRAND_add.pod;h=b6753fd2ed0b1b0cac0885303226b90d76ed0622;hp=62ff79444a464b30be757856fb4e2ad0c89f3c0b;hb=c7504aeb640a88949dfe3146f7e0f275f517464c;hpb=b97fdb57a269656fa20024a4404d3f543f06ac61 diff --git a/doc/man3/RAND_add.pod b/doc/man3/RAND_add.pod index 62ff79444a..b6753fd2ed 100644 --- a/doc/man3/RAND_add.pod +++ b/doc/man3/RAND_add.pod @@ -2,74 +2,99 @@ =head1 NAME -RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add -entropy to the PRNG +RAND_add, RAND_poll, RAND_seed, RAND_status, RAND_event, RAND_screen, +RAND_keep_random_devices_open +- add randomness to the PRNG or get its status =head1 SYNOPSIS #include + int RAND_status(void); + int RAND_poll(); + + void RAND_add(const void *buf, int num, double randomness); void RAND_seed(const void *buf, int num); - void RAND_add(const void *buf, int num, double entropy); + void RAND_keep_random_devices_open(int keep); - int RAND_status(void); +Deprecated: #if OPENSSL_API_COMPAT < 0x10100000L - int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); + int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); void RAND_screen(void); #endif =head1 DESCRIPTION -RAND_add() mixes the B bytes at B into the PRNG state. Thus, -if the data at B are unpredictable to an adversary, this -increases the uncertainty about the state and makes the PRNG output -less predictable. Suitable input comes from user interaction (random -key presses, mouse movements) and certain hardware events. The -B argument is (the lower bound of) an estimate of how much -randomness is contained in B, measured in bytes. Details about -sources of randomness and how to estimate their entropy can be found -in the literature, e.g. RFC 1750. - -RAND_add() may be called with sensitive data such as user entered -passwords. The seed values cannot be recovered from the PRNG output. - -OpenSSL makes sure that the PRNG state is unique for each thread. On -systems that provide C, the randomness device is used -to seed the PRNG transparently. However, on all other systems, the -application is responsible for seeding the PRNG by calling RAND_add(), -L -or L. - -RAND_seed() is equivalent to RAND_add() when B. - -RAND_event() and RAND_screen() are deprecated and should not be called. +These functions can be used to seed the random generator and to check its +seeded state. +In general, manual (re-)seeding of the default OpenSSL random generator +(L) is not necessary (but allowed), since it does (re-)seed +itself automatically using trusted system entropy sources. +This holds unless the default RAND_METHOD has been replaced or OpenSSL was +built with automatic reseeding disabled, see L for more details. + +RAND_status() indicates whether or not the random generator has been sufficiently +seeded. If not, functions such as L will fail. + +RAND_poll() uses the system's capabilities to seed the random generator using +random input obtained from polling various trusted entropy sources. +The default choice of the entropy source can be modified at build time, +see L for more details. + +RAND_add() mixes the B bytes at B into the internal state +of the random generator. +This function will not normally be needed, as mentioned above. +The B argument is an estimate of how much randomness is +contained in +B, in bytes, and should be a number between zero and B. +Details about sources of randomness and how to estimate their randomness +can be found in the literature; for example [NIST SP 800-90B]. +The content of B cannot be recovered from subsequent random generator output. +Applications that intend to save and restore random state in an external file +should consider using L instead. + +RAND_seed() is equivalent to RAND_add() with B set to B. + +RAND_keep_random_devices_open() is used to control file descriptor +usage by the random seed sources. Some seed sources maintain open file +descriptors by default, which allows such sources to operate in a +chroot(2) jail without the associated device nodes being available. When +the B argument is zero, this call disables the retention of file +descriptors. Conversely, a non-zero argument enables the retention of +file descriptors. This function is usually called during initialization +and it takes effect immediately. + +RAND_event() and RAND_screen() are equivalent to RAND_poll() and exist +for compatibility reasons only. See HISTORY section below. =head1 RETURN VALUES -RAND_status() returns 1 if the PRNG has been seeded +RAND_status() returns 1 if the random generator has been seeded with enough data, 0 otherwise. -RAND_event() calls RAND_poll() and returns RAND_status(). +RAND_poll() returns 1 if it generated seed data, 0 otherwise. -RAND_screen calls RAND_poll(). +RAND_event() returns RAND_status(). The other functions do not return values. =head1 HISTORY -RAND_event() and RAND_screen() are deprecated since OpenSSL -1.1.0. Use the functions described above instead. +RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should +not be used. =head1 SEE ALSO -L, L, -L, L +L, +L, +L, +L =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2018 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