diff options
author | Dr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> | 2018-02-27 19:02:24 +0100 |
---|---|---|
committer | Dr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> | 2018-03-30 00:10:38 +0200 |
commit | a73d990e2b6b1a406b1c85837a176bf7525d3914 (patch) | |
tree | 59aaa4b3929db741e928c44174a0d6c75727fc7f /doc/man7/RAND.pod | |
parent | 3484236d8d7afedd3e5c7771bd49d3385340e3bf (diff) |
Add documentation for the RAND_DRBG API
The RAND_DRBG API was added in PR #5462 and modified by PR #5547.
This commit adds the corresponding documention.
Reviewed-by: Kurt Roeckx <kurt@roeckx.be>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5461)
Diffstat (limited to 'doc/man7/RAND.pod')
-rw-r--r-- | doc/man7/RAND.pod | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/doc/man7/RAND.pod b/doc/man7/RAND.pod new file mode 100644 index 0000000000..6ec7548972 --- /dev/null +++ b/doc/man7/RAND.pod @@ -0,0 +1,78 @@ +=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 don't 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 don't take randomness for granted. + +For long-term secrets, 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 long-term secrets 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. + +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 |