diff options
author | Jung-uk Kim <jkim@FreeBSD.org> | 2018-09-13 19:18:07 +0000 |
---|---|---|
committer | Jung-uk Kim <jkim@FreeBSD.org> | 2018-09-13 19:18:07 +0000 |
commit | a43ce912fc025d11e1395506111f75fc194d7ba5 (patch) | |
tree | 9794cf7720d75938ed0ea4f499c0dcd4b6eacdda /doc/man7/RAND.pod | |
parent | 02be298e504b8554caca6dc85af450e1ea44d19d (diff) | |
download | src-test2-a43ce912fc025d11e1395506111f75fc194d7ba5.tar.gz src-test2-a43ce912fc025d11e1395506111f75fc194d7ba5.zip |
Notes
Diffstat (limited to 'doc/man7/RAND.pod')
-rw-r--r-- | doc/man7/RAND.pod | 81 |
1 files changed, 81 insertions, 0 deletions
diff --git a/doc/man7/RAND.pod b/doc/man7/RAND.pod new file mode 100644 index 000000000000..971b3cdb1612 --- /dev/null +++ b/doc/man7/RAND.pod @@ -0,0 +1,81 @@ +=pod + +=head1 NAME + +RAND +- the OpenSSL random generator + +=head1 DESCRIPTION + +Random numbers are a vital part of cryptography, they are needed to provide +unpredictability for tasks like key generation, creating salts, and many more. +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. + +OpenSSL comes with a default implementation of the RAND API which is based on +the deterministic random bit generator (DRBG) model as described in +[NIST SP 800-90A Rev. 1]. The default random generator will initialize +automatically on first use and will be fully functional without having +to be initialized ('seeded') explicitly. +It seeds and reseeds itself automatically using trusted random sources +provided by the operating system. + +As a normal application developer, you do not have to worry about any details, +just use L<RAND_bytes(3)> to obtain random data. +Having said that, there is one important rule to obey: Always check the error +return value of L<RAND_bytes(3)> and do not take randomness for granted. + +For values that should remain secret, you can use L<RAND_priv_bytes(3)> +instead. +This method does not provide 'better' randomness, it uses the same type of CSPRNG. +The intention behind using a dedicated CSPRNG exclusively for private +values is that none of its output should be visible to an attacker (e.g., +used as salt value), in order to reveal as little information as +possible about its internal state, and that a compromise of the "public" +CSPRNG instance will not affect the secrecy of these private values. + +In the rare case where the default implementation does not satisfy your special +requirements, there are two options: + +=over 2 + +=item * + +Replace the default RAND method by your own RAND method using +L<RAND_set_rand_method(3)>. + +=item * + +Modify the default settings of the OpenSSL RAND method by modifying the security +parameters of the underlying DRBG, which is described in detail in L<RAND_DRBG(7)>. + +=back + +Changing the default random generator or its default parameters should be necessary +only in exceptional cases and is not recommended, unless you have a profound knowledge +of cryptographic principles and understand the implications of your changes. + +=head1 SEE ALSO + +L<RAND_add(3)>, +L<RAND_bytes(3)>, +L<RAND_priv_bytes(3)>, +L<RAND_get_rand_method(3)>, +L<RAND_set_rand_method(3)>, +L<RAND_OpenSSL(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 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 +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |