Update various RAND podpages

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</dev/urandom>, 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<RAND_egd(3)>

or L<RAND_load_file(3)>.

RAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>.

On systems that provide C</dev/urandom> or similar source of randomess,

it will be used

to seed the PRNG transparently. On older systems, however, it might

be necessary to use RAND_add(), L<RAND_egd(3)> or L<RAND_load_file(3)>.

RAND_event() and RAND_screen() are deprecated and should not be called.

=head1 RETURN VALUES

=head1 SEE ALSO

L<RAND_bytes(3)>, L<RAND_egd(3)>,

L<RAND_load_file(3)>, L<RAND_cleanup(3)>

L<RAND_load_file(3)>

=head1 COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Copyright 2000-2017 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

=head1 DESCRIPTION

Prior to OpenSSL 1.1.0 RAND_cleanup() erases the memory used by the PRNG. This

function is deprecated and as of version 1.1.0 does nothing. No explicit

initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>.

Prior to OpenSSL 1.1.0, RAND_cleanup() released all resources used by

the PRNG.  As of version 1.1.0, it does nothing and should not be called,

since since no explicit initialisation or de-initialisation is necessary. See

L<OPENSSL_init_crypto(3)>.

=head1 RETURN VALUE

=head1 COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Copyright 2000-2017 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

 #include <openssl/rand.h>

 int RAND_egd_bytes(const char *path, int num);

 int RAND_egd(const char *path);

 int RAND_egd_bytes(const char *path, int bytes);

 int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes);

 int RAND_query_egd_bytes(const char *path, unsigned char *buf, int num);

=head1 DESCRIPTION

RAND_egd() queries the Entropy Gathering Daemon (EGD) on socket B<path>.

It queries 255 bytes and uses L<RAND_add(3)> to seed the

OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for

RAND_egd_bytes(path, 255);

RAND_egd_bytes() queries EGD on socket B<path>.

It queries B<bytes> bytes and uses L<RAND_add(3)> to seed the

OpenSSL built-in PRNG.

This function is more flexible than RAND_egd().

When only one secret key must

be generated, it is not necessary to request the full amount 255 bytes from

the EGD socket. This can be advantageous, since the amount of randomness

that can be retrieved from EGD over time is limited.

RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket

B<path>. If B<buf> is given, B<bytes> bytes are queried and written into

B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the

OpenSSL built-in PRNG using L<RAND_add(3)>.

=head1 NOTES

On systems without /dev/*random devices providing randomness from the kernel,

EGD provides

a socket interface through which randomness can be gathered in chunks up to

255 bytes. Several chunks can be queried during one connection.

EGD is available from http://www.lothar.com/tech/crypto/ (C<perl

Makefile.PL; make; make install> to install). It is run as B<egd>

I<path>, where I<path> is an absolute path designating a socket. When

RAND_egd() is called with that path as an argument, it tries to read

random bytes that EGD has collected. RAND_egd() retrieves randomness from the

daemon using the daemon's "non-blocking read" command which shall

be answered immediately by the daemon without waiting for additional

randomness to be collected. The write and read socket operations in the

communication are blocking.

Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is

available from

http://prngd.sourceforge.net/ .

PRNGD does employ an internal PRNG itself and can therefore never run

out of randomness.

OpenSSL automatically queries EGD when randomness is requested via RAND_bytes()

or the status is checked via RAND_status() for the first time, if the socket

is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool.

On older platforms without a good source of randomness such as C</dev/urandom>,

it is possible to query an Entropy Gathering Daemon (EGD) over a local

socket to obtain randomness and seed the OpenSSL RNG.

The protocol used is defined by the EGDs available at

L<http://egd.sourceforge.net/> or L<http://prngd.sourceforge.net>.

RAND_egd_bytes() requests B<num> bytes of randomness from an EGD at the

specified socket B<path>, and passes the data it receives into RAND_add().

RAND_egd() is equivalent to RAND_egd_bytes() with B<num> set to 255.

RAND_query_egd_bytes() requests B<num> bytes of randomness from an EGD at

the specified socket B<path>.

If B<buf> is B<NULL>, it is equivalent to RAND_egd_bytes().

If B<buf> is not B<NULL>, then the data is copied to the buffer and

RAND_add() is not called.

OpenSSL can be configured at build time to try to use the EGD for seeding

automatically.

=head1 RETURN VALUE

RAND_egd() and RAND_egd_bytes() return the number of bytes read from the

daemon on success, and -1 if the connection failed or the daemon did not

daemon on success, or -1 if the connection failed or the daemon did not

return enough data to fully seed the PRNG.

RAND_query_egd_bytes() returns the number of bytes read from the daemon on

success, and -1 if the connection failed. The PRNG state is not considered.

success, or -1 if the connection failed.

=head1 SEE ALSO

L<RAND_bytes(3)>, L<RAND_add(3)>,

L<RAND_cleanup(3)>

L<RAND_bytes(3)>, L<RAND_add(3)>

=head1 COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Copyright 2000-2017 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

=head1 SEE ALSO

L<RAND_bytes(3)>, L<RAND_add(3)>, L<RAND_cleanup(3)>

L<RAND_bytes(3)>, L<RAND_add(3)>

=head1 HISTORY

=head1 COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Copyright 2000-2017 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

 #include <openssl/rand.h>

 RAND_METHOD *RAND_OpenSSL(void);

 void RAND_set_rand_method(const RAND_METHOD *meth);

 const RAND_METHOD *RAND_get_rand_method(void);

 RAND_METHOD *RAND_OpenSSL(void);

=head1 DESCRIPTION

A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number

generation. By modifying the method, alternative implementations such as

hardware RNGs may be used. IMPORTANT: See the NOTES section for important

information about how these RAND API functions are affected by the use of

B<ENGINE> API calls.

generation.

Initially, the default RAND_METHOD is the OpenSSL internal implementation, as

returned by RAND_OpenSSL().

Initially, the default B<RAND_METHOD> is the OpenSSL internal implementation,

as returned by RAND_OpenSSL().

This implementation ensures that the PRNG state is unique for each thread.

RAND_set_default_method() makes B<meth> the method for PRNG use. B<NB>: This is

true only whilst no ENGINE has been set as a default for RAND, so this function

is no longer recommended.

If an B<ENGINE> is loaded that provides the RAND API, however, it will

be used instead of the method returned by RAND_OpenSSL().

RAND_get_default_method() returns a pointer to the current RAND_METHOD.

However, the meaningfulness of this result is dependent on whether the ENGINE

API is being used, so this function is no longer recommended.

RAND_set_rand_method() makes B<meth> the method for PRNG use.  If an

ENGINE was providing the method, it will be released first.

RAND_get_rand_method() returns a pointer to the current B<RAND_METHOD>.

=head1 THE RAND_METHOD STRUCTURE

 typedef struct rand_meth_st

 {

 typedef struct rand_meth_st {

     void (*seed)(const void *buf, int num);

     int (*bytes)(unsigned char *buf, int num);

     void (*cleanup)(void);

     int (*status)(void);

 } RAND_METHOD;

The components point to method implementations used by (or called by), in order,

The fields point to functions that are used by, in order,

RAND_seed(), RAND_bytes(), internal RAND cleanup, RAND_add(), RAND_pseudo_rand()

and RAND_status().

Each component may be NULL if the function is not implemented.

Each pointer may be NULL if the function is not implemented.

=head1 RETURN VALUES

RAND_set_rand_method() returns no value. RAND_get_rand_method() and

RAND_OpenSSL() return pointers to the respective methods.

=head1 NOTES

RAND_METHOD implementations are grouped together with other

algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a

default ENGINE is specified for RAND functionality using an ENGINE API function,

that will override any RAND defaults set using the RAND API (ie.

RAND_set_rand_method()). For this reason, the ENGINE API is the recommended way

to control default implementations for use in RAND and other cryptographic

algorithms.

=head1 SEE ALSO

L<RAND_bytes(3)>, L<ENGINE_by_id(3)>

=head1 COPYRIGHT

Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.

Copyright 2000-2017 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