wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update various RAND podpages

Browse source 
Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3883)
This commit is contained in:
Rich Salz 2017-07-07 16:47:39 -04:00
parent 222417eb71
commit 04256277cb
5 changed files with 51 additions and 93 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
doc/man3/RAND_add.pod
View file

@ -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 RAND_add() may be called with sensitive data such as user entered
passwords. The seed values cannot be recovered from the PRNG output. 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>. 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. RAND_event() and RAND_screen() are deprecated and should not be called.
=head1 RETURN VALUES =head1 RETURN VALUES
@ -65,11 +63,11 @@ RAND_event() and RAND_screen() are deprecated since OpenSSL
=head1 SEE ALSO =head1 SEE ALSO
L<RAND_bytes(3)>, L<RAND_egd(3)>, L<RAND_bytes(3)>, L<RAND_egd(3)>,
L<RAND_load_file(3)>, L<RAND_cleanup(3)> L<RAND_load_file(3)>
=head1 COPYRIGHT =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 Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy this file except in compliance with the License. You can obtain a copy

9
doc/man3/RAND_cleanup.pod
View file

@ -14,9 +14,10 @@ RAND_cleanup - erase the PRNG state
=head1 DESCRIPTION =head1 DESCRIPTION
Prior to OpenSSL 1.1.0 RAND_cleanup() erases the memory used by the PRNG. This Prior to OpenSSL 1.1.0, RAND_cleanup() released all resources used by
function is deprecated and as of version 1.1.0 does nothing. No explicit the PRNG. As of version 1.1.0, it does nothing and should not be called,
initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>. since since no explicit initialisation or de-initialisation is necessary. See
L<OPENSSL_init_crypto(3)>.
=head1 RETURN VALUE =head1 RETURN VALUE
@ -32,7 +33,7 @@ RAND_cleanup() was deprecated in OpenSSL 1.1.0.
=head1 COPYRIGHT =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 Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy this file except in compliance with the License. You can obtain a copy

70
doc/man3/RAND_egd.pod
View file

@ -8,76 +8,48 @@ RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon
#include <openssl/rand.h> #include <openssl/rand.h>
int RAND_egd_bytes(const char *path, int num);
int RAND_egd(const char *path); 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 =head1 DESCRIPTION
RAND_egd() queries the Entropy Gathering Daemon (EGD) on socket B<path>. On older platforms without a good source of randomness such as C</dev/urandom>,
It queries 255 bytes and uses L<RAND_add(3)> to seed the it is possible to query an Entropy Gathering Daemon (EGD) over a local
OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for socket to obtain randomness and seed the OpenSSL RNG.
RAND_egd_bytes(path, 255); 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>. RAND_egd_bytes() requests B<num> bytes of randomness from an EGD at the
It queries B<bytes> bytes and uses L<RAND_add(3)> to seed the specified socket B<path>, and passes the data it receives into RAND_add().
OpenSSL built-in PRNG. RAND_egd() is equivalent to RAND_egd_bytes() with B<num> set to 255.
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 RAND_query_egd_bytes() requests B<num> bytes of randomness from an EGD at
B<path>. If B<buf> is given, B<bytes> bytes are queried and written into the specified socket B<path>.
B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the If B<buf> is B<NULL>, it is equivalent to RAND_egd_bytes().
OpenSSL built-in PRNG using L<RAND_add(3)>. If B<buf> is not B<NULL>, then the data is copied to the buffer and
RAND_add() is not called.
=head1 NOTES OpenSSL can be configured at build time to try to use the EGD for seeding
automatically.
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.
=head1 RETURN VALUE =head1 RETURN VALUE
RAND_egd() and RAND_egd_bytes() return the number of bytes read from the 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. return enough data to fully seed the PRNG.
RAND_query_egd_bytes() returns the number of bytes read from the daemon on 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 =head1 SEE ALSO
L<RAND_bytes(3)>, L<RAND_add(3)>, L<RAND_bytes(3)>, L<RAND_add(3)>
L<RAND_cleanup(3)>
=head1 COPYRIGHT =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 Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy this file except in compliance with the License. You can obtain a copy

4
doc/man3/RAND_load_file.pod
View file

@ -64,7 +64,7 @@ error.
=head1 SEE ALSO =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 HISTORY
@ -75,7 +75,7 @@ poorly enforced before OpenSSL version 1.1.1.
=head1 COPYRIGHT =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 Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy this file except in compliance with the License. You can obtain a copy

45
doc/man3/RAND_set_rand_method.pod
View file

@ -8,35 +8,32 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method
#include <openssl/rand.h> #include <openssl/rand.h>
RAND_METHOD *RAND_OpenSSL(void);
void RAND_set_rand_method(const RAND_METHOD *meth); void RAND_set_rand_method(const RAND_METHOD *meth);
const RAND_METHOD *RAND_get_rand_method(void); const RAND_METHOD *RAND_get_rand_method(void);
RAND_METHOD *RAND_OpenSSL(void);
=head1 DESCRIPTION =head1 DESCRIPTION
A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number
generation. By modifying the method, alternative implementations such as generation.
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.
Initially, the default RAND_METHOD is the OpenSSL internal implementation, as Initially, the default B<RAND_METHOD> is the OpenSSL internal implementation,
returned by RAND_OpenSSL(). 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 If an B<ENGINE> is loaded that provides the RAND API, however, it will
true only whilst no ENGINE has been set as a default for RAND, so this function be used instead of the method returned by RAND_OpenSSL().
is no longer recommended.
RAND_get_default_method() returns a pointer to the current RAND_METHOD. RAND_set_rand_method() makes B<meth> the method for PRNG use. If an
However, the meaningfulness of this result is dependent on whether the ENGINE ENGINE was providing the method, it will be released first.
API is being used, so this function is no longer recommended.
RAND_get_rand_method() returns a pointer to the current B<RAND_METHOD>.
=head1 THE RAND_METHOD STRUCTURE =head1 THE RAND_METHOD STRUCTURE
typedef struct rand_meth_st typedef struct rand_meth_st {
{
void (*seed)(const void *buf, int num); void (*seed)(const void *buf, int num);
int (*bytes)(unsigned char *buf, int num); int (*bytes)(unsigned char *buf, int num);
void (*cleanup)(void); void (*cleanup)(void);
@ -45,33 +42,23 @@ API is being used, so this function is no longer recommended.
int (*status)(void); int (*status)(void);
} RAND_METHOD; } 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() RAND_seed(), RAND_bytes(), internal RAND cleanup, RAND_add(), RAND_pseudo_rand()
and RAND_status(). 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 =head1 RETURN VALUES
RAND_set_rand_method() returns no value. RAND_get_rand_method() and RAND_set_rand_method() returns no value. RAND_get_rand_method() and
RAND_OpenSSL() return pointers to the respective methods. 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 =head1 SEE ALSO
L<RAND_bytes(3)>, L<ENGINE_by_id(3)> L<RAND_bytes(3)>, L<ENGINE_by_id(3)>
=head1 COPYRIGHT =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 Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy this file except in compliance with the License. You can obtain a copy