Update various RAND podpages
Reviewed-by: Tim Hudson <tjh@openssl.org> (Merged from https://github.com/openssl/openssl/pull/3883)
This commit is contained in:
Rich Salz
parent
222417eb71
commit
04256277cb
5 changed files with 51 additions and 93 deletions
|
|
@ -35,15 +35,13 @@ can be found in the literature; for example IETF RFC 4086.
|
|||
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
|
||||
|
|
@ -65,11 +63,11 @@ RAND_event() and RAND_screen() are deprecated since OpenSSL
|
|||
=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
|
||||
|
|
|
|||
|
|
@ -14,9 +14,10 @@ RAND_cleanup - erase the PRNG state
|
|||
|
||||
=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
|
||||
|
||||
|
|
@ -32,7 +33,7 @@ RAND_cleanup() was deprecated in OpenSSL 1.1.0.
|
|||
|
||||
=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
|
||||
|
|
|
|||
|
|
@ -8,76 +8,48 @@ RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon
|
|||
|
||||
#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);
|
||||
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() 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_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() 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)>.
|
||||
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.
|
||||
|
||||
=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.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ error.
|
|||
|
||||
=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
|
||||
|
||||
|
|
@ -75,7 +75,7 @@ poorly enforced before OpenSSL version 1.1.1.
|
|||
|
||||
=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
|
||||
|
|
|
|||
|
|
@ -8,35 +8,32 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method
|
|||
|
||||
#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);
|
||||
|
|
@ -45,33 +42,23 @@ API is being used, so this function is no longer recommended.
|
|||
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue