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 | |
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')
-rw-r--r-- | doc/man3/CRYPTO_get_ex_new_index.pod | 20 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_generate.pod | 88 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_get0_master.pod | 80 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_new.pod | 127 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_reseed.pod | 111 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_set_callbacks.pod | 147 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_set_ex_data.pod | 68 | ||||
-rw-r--r-- | doc/man3/RAND_add.pod | 123 | ||||
-rw-r--r-- | doc/man3/RAND_bytes.pod | 12 | ||||
-rw-r--r-- | doc/man3/RAND_cleanup.pod | 4 | ||||
-rw-r--r-- | doc/man3/RAND_egd.pod | 4 | ||||
-rw-r--r-- | doc/man3/RAND_load_file.pod | 6 | ||||
-rw-r--r-- | doc/man3/RAND_set_rand_method.pod | 9 | ||||
-rw-r--r-- | doc/man7/RAND.pod | 78 | ||||
-rw-r--r-- | doc/man7/RAND_DRBG.pod | 300 |
15 files changed, 1062 insertions, 115 deletions
diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod index 1a4ad52de0..4d5a2b93a0 100644 --- a/doc/man3/CRYPTO_get_ex_new_index.pod +++ b/doc/man3/CRYPTO_get_ex_new_index.pod @@ -40,20 +40,22 @@ Several OpenSSL structures can have application-specific data attached to them, known as "exdata." The specific structures are: - SSL - SSL_CTX - SSL_SESSION - X509 - X509_STORE - X509_STORE_CTX + APP + BIO DH + DRBG DSA EC_KEY - RSA ENGINE + RSA + SSL + SSL_CTX + SSL_SESSION UI UI_METHOD - BIO + X509 + X509_STORE + X509_STORE_CTX Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h> header file. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for @@ -155,7 +157,7 @@ dup_func() should return 0 for failure and 1 for success. =head1 COPYRIGHT -Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2015-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 diff --git a/doc/man3/RAND_DRBG_generate.pod b/doc/man3/RAND_DRBG_generate.pod new file mode 100644 index 0000000000..b39ee93f51 --- /dev/null +++ b/doc/man3/RAND_DRBG_generate.pod @@ -0,0 +1,88 @@ +=pod + +=head1 NAME + +RAND_DRBG_generate, +RAND_DRBG_bytes +- generate random bytes using the given drbg instance + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + int RAND_DRBG_generate(RAND_DRBG *drbg, + unsigned char *out, size_t outlen, + int prediction_resistance, + const unsigned char *adin, size_t adinlen); + + int RAND_DRBG_bytes(RAND_DRBG *drbg, + unsigned char *out, size_t outlen); + + +=head1 DESCRIPTION + +RAND_DRBG_generate() generates B<outlen> random bytes using the given +DRBG instance B<drbg> and stores them in the buffer at B<out>. + +Before generating the output, the DRBG instance checks whether the maximum +number of generate requests (I<reseed interval>) or the maximum timespan +(I<reseed time interval>) since its last seeding have been reached. +If this is the case, the DRBG reseeds automatically. +Additionally, an immediate reseeding can be requested by setting the +B<prediction_resistance> flag to 1. See NOTES section for more details. + +The caller can optionally provide additional data to be used for reseeding +by passing a pointer B<adin> to a buffer of length B<adinlen>. +This additional data is mixed into the internal state of the random +generator but does not contribute to the entropy count. +The additional data can be omitted by setting B<adin> to NULL and +B<adinlen> to 0; + +RAND_DRBG_bytes() generates B<outlen> random bytes using the given +DRBG instance B<drbg> and stores them in the buffer at B<out>. +This function is a wrapper around the RAND_DRBG_generate() call, +which collects some additional data from low entropy sources +(e.g., a high resolution timer) and calls +RAND_DRBG_generate(drbg, out, outlen, 0, adin, adinlen). + + +=head1 RETURN VALUES + +RAND_DRBG_generate() and RAND_DRBG_bytes() return 1 on success, +and 0 on failure. + +=head1 NOTES + +The I<reseed interval> and I<reseed time interval> of the B<drbg> are set to +reasonable default values, which in general do not have to be adjusted. +If necessary, they can be changed using L<RAND_DRBG_set_reseed_interval(3)> +and L<RAND_DRBG_set_reseed_time_interval(3)>, respectively. + +A request for prediction resistance can only be satisfied by pulling fresh +entropy from one of the approved entropy sources listed in section 5.5.2 of +[NIST SP 800-90C]. +Since the default DRBG implementation does not have access to such an approved +entropy source, a request for prediction resistance will always fail. +In other words, prediction resistance is currently not supported yet by the DRBG. + +=head1 HISTORY + +The RAND_DRBG functions were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L<RAND_bytes(3)>, +L<RAND_DRBG_set_reseed_interval(3)>, +L<RAND_DRBG_set_reseed_time_interval(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2017-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 diff --git a/doc/man3/RAND_DRBG_get0_master.pod b/doc/man3/RAND_DRBG_get0_master.pod new file mode 100644 index 0000000000..c958bf20ec --- /dev/null +++ b/doc/man3/RAND_DRBG_get0_master.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +RAND_DRBG_get0_master, +RAND_DRBG_get0_public, +RAND_DRBG_get0_private +- get access to the global RAND_DRBG instances + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + RAND_DRBG *RAND_DRBG_get0_master(void); + RAND_DRBG *RAND_DRBG_get0_public(void); + RAND_DRBG *RAND_DRBG_get0_private(void); + + +=head1 DESCRIPTION + +The default RAND API implementation (RAND_OpenSSL()) utilizes three +shared DRBG instances which are accessed via the RAND API: + +The <public> and <private> DRBG are thread-local instances, which are used +by RAND_bytes() and RAND_priv_bytes(), respectively. +The <master> DRBG is a global instance, which is not intended to be used +directly, but is used internally to reseed the other two instances. + +These functions here provide access to the shared DRBG instances. + +=head1 RETURN VALUES + +RAND_DRBG_get0_master() returns a pointer to the <master> DRBG instance. + +RAND_DRBG_get0_public() returns a pointer to the <public> DRBG instance. + +RAND_DRBG_get0_private() returns a pointer to the <private> DRBG instance. + + +=head1 NOTES + +It is not thread-safe to access the <master> DRBG instance. +The <public> and <private> DRBG instance can be accessed safely, because +they are thread-local. Note however, that changes to these two instances +apply only to the current thread. + +For that reason it is recommended not to change the settings of these +three instances directly. +Instead, an application should change the default settings for new DRBG instances +at initialization time, before creating additional threads. + +During initialization, it is possible to change the reseed interval +and reseed time interval. +It is also possible to exchange the reseeding callbacks entirely. + + +=head1 HISTORY + +The RAND_DRBG functions were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L<RAND_DRBG_set_callbacks(3)>, +L<RAND_DRBG_set_reseed_defaults(3)>, +L<RAND_DRBG_set_reseed_interval(3)>, +L<RAND_DRBG_set_reseed_time_interval(3)>, +L<RAND_DRBG_set_callbacks(3)>, +L<RAND_DRBG_generate(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2017-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 diff --git a/doc/man3/RAND_DRBG_new.pod b/doc/man3/RAND_DRBG_new.pod new file mode 100644 index 0000000000..dcd7a94419 --- /dev/null +++ b/doc/man3/RAND_DRBG_new.pod @@ -0,0 +1,127 @@ +=pod + +=head1 NAME + +RAND_DRBG_new, +RAND_DRBG_secure_new, +RAND_DRBG_set, +RAND_DRBG_set_defaults, +RAND_DRBG_instantiate, +RAND_DRBG_uninstantiate, +RAND_DRBG_free +- initialize and cleanup a RAND_DRBG instance + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + + RAND_DRBG *RAND_DRBG_new(int type, + unsigned int flags, + RAND_DRBG *parent); + + RAND_DRBG *RAND_DRBG_secure_new(int type, + unsigned int flags, + RAND_DRBG *parent); + + int RAND_DRBG_set(RAND_DRBG *drbg, + int type, unsigned int flags); + + int RAND_DRBG_set_defaults(int type, unsigned int flags); + + int RAND_DRBG_instantiate(RAND_DRBG *drbg, + const unsigned char *pers, size_t perslen); + + int RAND_DRBG_uninstantiate(RAND_DRBG *drbg); + + void RAND_DRBG_free(RAND_DRBG *drbg); + + +=head1 DESCRIPTION + +RAND_DRBG_new() and RAND_DRBG_secure_new() +create a new DRBG instance of the given B<type>, allocated from the heap resp. +the secure heap +(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()). + +RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>. + +RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG +instances. + +Currently, all DRBG types are based on AES-CTR, so B<type> can be one of the +following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr. +Before the DRBG can be used to generate random bits, it is necessary to set +its type and to instantiate it. + +The optional B<flags> argument specifies a set of bit flags which can be +joined using the | operator. Currently, the only flag is +RAND_DRBG_FLAG_CTR_NO_DF, which disables the use of a the derivation function +ctr_df. For an explanation, see [NIST SP 800-90A Rev. 1]. + +If a B<parent> instance is specified then this will be used instead of +the default entropy source for reseeding the B<drbg>. It is said that the +B<drbg> is I<chained> to its B<parent>. +For more information, see the NOTES section. + + +RAND_DRBG_instantiate() +seeds the B<drbg> instance using random input from trusted entropy sources. +Optionally, a personalization string B<pers> of length B<perslen> can be +specified. +To omit the personalization string, set B<pers>=NULL and B<perslen>=0; + +RAND_DRBG_uninstantiate() +clears the internal state of the B<drbg> and puts it back in the +uninstantiated state. + +=head1 RETURN VALUES + + +RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG +instance allocated on the heap, resp. secure heap. + +RAND_DRBG_set(), +RAND_DRBG_instantiate(), and +RAND_DRBG_uninstantiate() +return 1 on success, and 0 on failure. + +RAND_DRBG_free() does not return a value. + +=head1 NOTES + +The DRBG design supports I<chaining>, which means that a DRBG instance can +use another B<parent> DRBG instance instead of the default entropy source +to obtain fresh random input for reseeding, provided that B<parent> DRBG +instance was properly instantiated, either from a trusted entropy source, +or from yet another parent DRBG instance. +For a detailed description of the reseeding process, see L<RAND_DRBG(7)>. + +The default DRBG type and flags are applied only during creation of a DRBG +instance. +To ensure that they are applied to the global and thread-local DRBG instances +(<master>, resp. <public> and <private>), it is necessary to call +RAND_DRBG_set_defaults() before creating any thread and before calling any +cryptographic routines that obtain random data directly or indirectly. + +=head1 HISTORY + +The RAND_DRBG functions were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L<OPENSSL_zalloc(3)>, +L<OPENSSL_secure_zalloc(3)>, +L<RAND_DRBG_generate(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2017-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 diff --git a/doc/man3/RAND_DRBG_reseed.pod b/doc/man3/RAND_DRBG_reseed.pod new file mode 100644 index 0000000000..da3a40be44 --- /dev/null +++ b/doc/man3/RAND_DRBG_reseed.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +RAND_DRBG_reseed, +RAND_DRBG_set_reseed_interval, +RAND_DRBG_set_reseed_time_interval, +RAND_DRBG_set_reseed_defaults +- reseed a RAND_DRBG instance + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + int RAND_DRBG_reseed(RAND_DRBG *drbg, + const unsigned char *adin, size_t adinlen); + + int RAND_DRBG_set_reseed_interval(RAND_DRBG *drbg, + unsigned int interval); + + int RAND_DRBG_set_reseed_time_interval(RAND_DRBG *drbg, + time_t interval); + + int RAND_DRBG_set_reseed_defaults( + unsigned int master_reseed_interval, + unsigned int slave_reseed_interval, + time_t master_reseed_time_interval, + time_t slave_reseed_time_interval + ); + + +=head1 DESCRIPTION + +RAND_DRBG_reseed() +reseeds the given B<drbg>, obtaining entropy input from its entropy source +and mixing in the specified additional data provided in the buffer B<adin> +of length B<adinlen>. +The additional data can be omitted by setting B<adin> to NULL and B<adinlen> +to 0. + +RAND_DRBG_set_reseed_interval() +sets the reseed interval of the B<drbg>, which is the maximum allowed number +of generate requests between consecutive reseedings. +If B<interval> > 0, then the B<drbg> will reseed automatically whenever the +number of generate requests since its last seeding exceeds the given reseed +interval. +If B<interval> == 0, then this feature is disabled. + + +RAND_DRBG_set_reseed_time_interval() +sets the reseed time interval of the B<drbg>, which is the maximum allowed +number of seconds between consecutive reseedings. +If B<interval> > 0, then the B<drbg> will reseed automatically whenever the +elapsed time since its last reseeding exceeds the given reseed time interval. +If B<interval> == 0, then this feature is disabled. + +RAND_DRBG_set_reseed_defaults() sets the default values for the reseed interval +(B<master_reseed_interval> and B<slave_reseed_interval>) +and the reseed time interval +(B<master_reseed_time_interval> and B<slave_reseed_tme_interval>) +of DRBG instances. +The default values are set independently for master DRBG instances (which don't +have a parent) and slave DRBG instances (which are chained to a parent DRBG). + +=head1 RETURN VALUES + +RAND_DRBG_reseed(), +RAND_DRBG_set_reseed_interval(), and +RAND_DRBG_set_reseed_time_interval(), +return 1 on success, 0 on failure. + + +=head1 NOTES + +The default OpenSSL random generator is already set up for automatic reseeding, +so in general it is not necessary to reseed it explicitly, or to modify +its reseeding thresholds. + +Normally, the entropy input for seeding a DRBG is either obtained from a +trusted os entropy source or from a parent DRBG instance, which was seeded +(directly or indirectly) from a trusted os entropy source. +In exceptional cases it is possible to replace the reseeding mechanism entirely +by providing application defined callbacks using RAND_DRBG_set_callbacks(). + +The reseeding default values are applied only during creation of a DRBG instance. +To ensure that they are applied to the global and thread-local DRBG instances +(<master>, resp. <public> and <private>), it is necessary to call +RAND_DRBG_set_reseed_defaults() before creating any thread and before calling any + cryptographic routines that obtain random data directly or indirectly. + +=head1 HISTORY + +The RAND_DRBG functions were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L<RAND_DRBG_generate(3)>, +L<RAND_DRBG_bytes(3)>, +L<RAND_DRBG_set_callbacks(3)>. +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2017-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 diff --git a/doc/man3/RAND_DRBG_set_callbacks.pod b/doc/man3/RAND_DRBG_set_callbacks.pod new file mode 100644 index 0000000000..3e9a98585e --- /dev/null +++ b/doc/man3/RAND_DRBG_set_callbacks.pod @@ -0,0 +1,147 @@ +=pod + +=head1 NAME + +RAND_DRBG_set_callbacks, +RAND_DRBG_get_entropy_fn, +RAND_DRBG_cleanup_entropy_fn, +RAND_DRBG_get_nonce_fn, +RAND_DRBG_cleanup_nonce_fn +- set callbacks for reseeding + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + + int RAND_DRBG_set_callbacks(RAND_DRBG *drbg, + RAND_DRBG_get_entropy_fn get_entropy, + RAND_DRBG_cleanup_entropy_fn cleanup_entropy, + RAND_DRBG_get_nonce_fn get_nonce, + RAND_DRBG_cleanup_nonce_fn cleanup_nonce); + + +=head2 Callback Functions + + typedef size_t (*RAND_DRBG_get_entropy_fn)( + RAND_DRBG *drbg, + unsigned char **pout, + int entropy, + size_t min_len, size_t max_len, + int prediction_resistance); + + typedef void (*RAND_DRBG_cleanup_entropy_fn)( + RAND_DRBG *drbg, + unsigned char *out, size_t outlen); + + typedef size_t (*RAND_DRBG_get_nonce_fn)( + RAND_DRBG *drbg, + unsigned char **pout, + int entropy, + size_t min_len, size_t max_len); + + typedef void (*RAND_DRBG_cleanup_nonce_fn)( + RAND_DRBG *drbg, + unsigned char *out, size_t outlen); + + + +=head1 DESCRIPTION + +RAND_DRBG_set_callbacks() sets the callbacks for obtaining fresh entropy and +the nonce when reseeding the given B<drbg>. +The callback functions are implemented and provided by the caller. +Their parameter lists need to match the function prototypes above. + +Setting the callbacks is allowed only if the DRBG has not been initialized yet. +Otherwise, the operation will fail. +To change the settings for one of the three shared DRBGs it is necessary to call +RAND_DRBG_uninstantiate() first. + +The B<get_entropy>() callback is called by the B<drbg> when it requests fresh +random input. +It is expected that the callback allocates and fills a random buffer of size +B<min_len> <= size <= B<max_len> (in bytes) which contains at least B<entropy> +bits of randomness. +The B<prediction_resistance> flag indicates whether the reseeding was +triggered by a prediction resistance request. + +The buffer's address is to be returned in *B<pout> and the number of collected +randomness bytes as return value. + +If the callback fails to acquire at least B<entropy> bits of randomness, +it must indicate an error by returning a buffer length of 0. + +If B<prediction_resistance> was requested and the random source of the DRBG +does not satisfy the conditions requested by [NIST SP 800-90C], then +it must also indicate an error by returning a buffer length of 0. +See NOTES section for more details. + +The B<cleanup_entropy>() callback is called from the B<drbg> to to clear and +free the buffer allocated previously by get_entropy(). +The values B<out> and B<outlen> are the random buffer's address and length, +as returned by the get_entropy() callback. + +The B<get_nonce>() and B<cleanup_nonce>() callbacks are used to obtain a nonce +and free it again. A nonce is only required for instantiation (not for reseeding) +and only in the case where the DRBG uses a derivation function. +The callbacks are analogous to get_entropy() and cleanup_entropy(), +except for the missing prediction_resistance flag. + +If the derivation function is disabled, then no nonce is used for instantiation, +and the B<get_nonce>() and B<cleanup_nonce>() callbacks can be omitted by +setting them to NULL. + + +=head1 RETURN VALUES + +RAND_DRBG_set_callbacks() return 1 on success, and 0 on failure + +=head1 NOTES + +It is important that B<cleanup_entropy>() and B<cleanup_nonce>() clear the buffer +contents safely before freeing it, in order not to leave sensitive information +about the DRBG's state in memory. + +A request for prediction resistance can only be satisfied by pulling fresh +entropy from one of the approved entropy sources listed in section 5.5.2 of +[NIST SP 800-90C]. +Since the default implementation of the get_entropy callback does not have access +to such an approved entropy source, a request for prediction resistance will +always fail. +In other words, prediction resistance is currently not supported yet by the DRBG. + +The derivation function is disabled during initialization by calling the +RAND_DRBG_set() function with the RAND_DRBG_FLAG_CTR_NO_DF flag. +For more information on the derivation function and when it can be omitted, +see [NIST SP 800-90A Rev. 1]. Roughly speeking it can be omitted if the random +source has "full entropy", i.e., contains 8 bits of entropy per byte. + +Even if a nonce is required, the B<get_nonce>() and B<cleanup_nonce>() +callbacks can be omitted by setting them to NULL. +In this case the DRBG will automatically request an extra amount of entropy +(using the B<get_entropy>() and B<cleanup_entropy>() callbacks) which it will +utilize for the nonce, following the recommendations of [NIST SP 800-90A Rev. 1], +section 8.6.7. + + +=head1 HISTORY + +The RAND_DRBG functions were added in OpenSSL 1.1.1. + +=head1 SEE ALSO + +L<RAND_DRBG_new(3)>, +L<RAND_DRBG_reseed(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2017-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 diff --git a/doc/man3/RAND_DRBG_set_ex_data.pod b/doc/man3/RAND_DRBG_set_ex_data.pod new file mode 100644 index 0000000000..22b7332571 --- /dev/null +++ b/doc/man3/RAND_DRBG_set_ex_data.pod @@ -0,0 +1,68 @@ +=pod + +=head1 NAME + +RAND_DRBG_set_ex_data, +RAND_DRBG_get_ex_data, +RAND_DRBG_get_ex_new_index +- store and retrieve extra data from the DRBG instance + +=head1 SYNOPSIS + + #include <openssl/rand_drbg.h> + + int RAND_DRBG_set_ex_data(RAND_DRBG *drbg, int idx, void *data); + + void *RAND_DRBG_get_ex_data(const RAND_DRBG *drbg, int idx); + + int RAND_DRBG_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + + +=head1 DESCRIPTION + +RAND_DRBG_set_ex_data() enables an application to store arbitrary application +specific data B<data> in a RAND_DRBG instance B<drbg>. The index B<idx> should +be a value previously returned from a call to RAND_DRBG_get_ex_new_index(). + +RAND_DRBG_get_ex_data() retrieves application specific data previously stored +in an RAND_DRBG instance B<drbg>. The B<idx> value should be the same as that +used when originally storing the data. + +For more detailed information see L<CRYPTO_get_ex_data(3)> and +L<CRYPTO_set_ex_data(3)> which implement these functions and +L<CRYPTO_get_ex_new_index(3)> for generating a unique index. + +=head1 RETURN VALUES + +RAND_DRBG_set_ex_data() returns 1 for success or 0 for failure. + +RAND_DRBG_get_ex_data() returns the previously stored value or NULL on +failure. NULL may also be a valid value. + + +=head1 NOTES + +RAND_DRBG_get_ex_new_index(...) is implemented as a macro and equivalent to +CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_DRBG,...). + +=head1 SEE ALSO + +L<CRYPTO_get_ex_data(3)>, +L<CRYPTO_set_ex_data(3)>, +L<CRYPTO_get_ex_new_index(3)>, +L<RAND_DRBG(7)> + +=head1 COPYRIGHT + +Copyright 2017-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 diff --git a/doc/man3/RAND_add.pod b/doc/man3/RAND_add.pod index 62048e6792..1b06d1be87 100644 --- a/doc/man3/RAND_add.pod +++ b/doc/man3/RAND_add.pod @@ -24,43 +24,42 @@ Deprecated: =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 system's capabilities to seed the CSPRNG using +These functions can be used to seed the random generator and to check its +seeded state. +In general, manual (re-)seeding of the default OpenSSL random generator +(L<RAND_OpenSSL(3)>) is not necessary (but allowed), since it does (re-)seed +itself automatically using trusted system entropy sources. +This holds unless the default RAND_METHOD has been replaced or OpenSSL was +built with automatic reseeding disabled, see L<RAND(7)> for more details. + +RAND_status() indicates whether or not the random generator has been sufficiently +seeded. If not, functions such as L<RAND_bytes(3)> will fail. + +RAND_poll() uses the system's capabilities to seed the random generator using random input obtained from polling various trusted entropy sources. -The default choice of the entropy source can be modified at build time -using the --with-rand-seed configure option, see also the B<NOTES> section. -A summary of the configure options can be displayed with the OpenSSL -L<version(1)> command. +The default choice of the entropy source can be modified at build time, +see L<RAND(7)> for more details. -RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. +RAND_add() mixes the B<num> bytes at B<buf> into the internal state +of the random generator. +This function will not normally be needed, as mentioned above. 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)>. +can be found in the literature; for example [NIST SP 800-90B]. +The content of B<buf> cannot be recovered from subsequent random generator output. +Applications that intend to save and restore random state in an external file +should consider using L<RAND_load_file(3)> instead. RAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>. -RAND_event() and RAND_screen() are equivalent to RAND_poll(). +RAND_event() and RAND_screen() are equivalent to RAND_poll() and exist +for compatibility reasons only. See HISTORY section below. =head1 RETURN VALUES -RAND_status() returns 1 if the CSPRNG has been seeded +RAND_status() returns 1 if the random generator has been seeded with enough data, 0 otherwise. RAND_poll() returns 1 if it generated seed data, 0 otherwise. @@ -69,72 +68,6 @@ RAND_event() returns RAND_status(). The other functions do not return values. -=head1 NOTES - -The new OpenSSL DRBG has some peculiarities which need to be taken -into account when it is selected as the default OpenSSL CSPRNG, i.e., -when RAND_get_rand_method() == RAND_OpenSSL(). -This applies in particular to the way reseeding is done by the DRBG: - -=over 2 - -=item * - -The DRBG seeds itself automatically, pulling random input from trusted -entropy sources. -Automatic reseeding occurs after a predefined number of generate requests. -The selection of the trusted entropy sources is configured at build -time using the --with-rand-seed option. - -=item * - -The DRBG distinguishes two different types of random input: -'entropy', which comes from a trusted source, and 'additional input', -which can optionally be added by the user and is considered untrusted. - -=back - -Automatic seeding can be disabled using the --with-rand-seed=none option. - -=head2 DRBG with automatic seeding enabled - -Calling RAND_poll() or RAND_add() is not necessary, because the DRBG -polls the entropy source automatically. -However, both calls are permitted, and do reseed the RNG. - -RAND_add() can be used to add both kinds of random input, depending on the -value of the B<randomness> argument: - -=over 4 - -=item randomness == 0: - -The random bytes are mixed as additional input into the current state of -the DRBG. -Mixing in additional input is not considered a full reseeding, hence the -reseed counter is not reset. - - -=item randomness > 0: - -The random bytes are used as entropy input for a full reseeding -(resp. reinstantiation) if the DRBG is instantiated -(resp. uninstantiated or in an error state). -A reseeding requires 16 bytes (128 bits) of randomness. -It is possible to provide less randomness than required. -In this case the missing randomness will be obtained by pulling random input -from the trusted entropy sources. - -=back - -=head2 DRBG with automatic seeding disabled (--with-rand-seed=none) - -Calling RAND_poll() will always fail. - -RAND_add() needs to be called for initial seeding and periodic reseeding. -At least 16 bytes (128 bits) of randomness have to be provided, otherwise -the (re-)seeding of the DRBG will fail. - =head1 HISTORY RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should @@ -142,12 +75,14 @@ not be used. =head1 SEE ALSO -L<RAND_bytes(3)>, L<RAND_egd(3)>, -L<RAND_load_file(3)> +L<RAND_bytes(3)>, +L<RAND_egd(3)>, +L<RAND_load_file(3)>, +L<RAND(7)> =head1 COPYRIGHT -Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2018 The OpenSSL Project Authors. A |