8389ec4b49
Add a new config param to specify how the CSPRNG should be seeded. Illegal values or nonsensical combinations (e.g., anything other than "os" on VMS or HP VOS etc) result in build failures. Add RDSEED support. Add RDTSC but leave it disabled for now pending more investigation. Refactor and reorganization all seeding files (rand_unix/win/vms) so that they are simpler. Only require 128 bits of seeding material. Many document improvements, including why to not use RAND_add() and the limitations around using load_file/write_file. Document RAND_poll(). Cleanup Windows RAND_poll and return correct status More completely initialize the default DRBG. Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/3965)
90 lines
2.9 KiB
Text
90 lines
2.9 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
RAND_add, RAND_poll, RAND_seed, RAND_status, RAND_event, RAND_screen
|
|
- add randomness to the PRNG or get its status
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/rand.h>
|
|
|
|
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);
|
|
|
|
Deprecated:
|
|
|
|
#if OPENSSL_API_COMPAT < 0x10100000L
|
|
int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);
|
|
void RAND_screen(void);
|
|
#endif
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Random numbers are a vital part of cryptography, including key generation,
|
|
creating salts, etc., and software-based
|
|
generators must be "seeded" with external randomness before they can be
|
|
used as a cryptographically-secure pseudo-random number generator (CSPRNG).
|
|
The availability of common hardware with special instructions and
|
|
modern operating systems, which may use items such as interrupt jitter
|
|
and network packet timings, can be reasonable sources of seeding material.
|
|
|
|
RAND_status() indicates whether or not the CSPRNG has been sufficiently
|
|
seeded. If not, functions such as RAND_bytes(3) will fail.
|
|
|
|
RAND_poll() uses the current capabilities to seed the CSPRNG. The
|
|
exact features used depends on how OpenSSL was configured, and can
|
|
be displayed with the OpenSSL L<version(1)> command. This function is
|
|
normally called automatically during OpenSSL initialization, but
|
|
can be called by the application to reseed the CSPRNG.
|
|
|
|
RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state.
|
|
The B<randomness> argument is an estimate of how much randomness is
|
|
contained in
|
|
B<buf>, in bytes, and should be a number between zero and B<num>.
|
|
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<buf> cannot be recovered from subsequent CSPRNG output.
|
|
This function will not normally be needed, as RAND_poll() should have been
|
|
configured to do the appropriate seeding for the local platform.
|
|
Applications that need to keep random state in an external file should
|
|
use L<RAND_load_file(3)>.
|
|
|
|
RAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>.
|
|
|
|
RAND_event() and RAND_screen() are equivalent to RAND_poll().
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
RAND_status() returns 1 if the CSPRNG has been seeded
|
|
with enough data, 0 otherwise.
|
|
|
|
RAND_poll() returns 1 if it generated seed data, 0 otherwise.
|
|
|
|
RAND_event() returns RAND_status().
|
|
|
|
The other functions do not return values.
|
|
|
|
=head1 HISTORY
|
|
|
|
RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should
|
|
not be used.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<RAND_bytes(3)>, L<RAND_egd(3)>,
|
|
L<RAND_load_file(3)>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
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
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|