diff options
author | Pauli <paul.dale@oracle.com> | 2020-07-22 12:55:31 +1000 |
---|---|---|
committer | Pauli <paul.dale@oracle.com> | 2020-08-07 14:16:47 +1000 |
commit | 7d615e2178fbffa53f05a67f68e5741374340308 (patch) | |
tree | 8e5cdbb8c39e24727e64af790831980b2a5d9e6a /doc/man3 | |
parent | 4df0d37ff6cc399b93f9ef2524d087c2d67d41b5 (diff) |
rand_drbg: remove RAND_DRBG.
The RAND_DRBG API did not fit well into the new provider concept as
implemented by EVP_RAND and EVP_RAND_CTX. The main reason is that the
RAND_DRBG API is a mixture of 'front end' and 'back end' API calls
and some of its API calls are rather low-level. This holds in particular
for the callback mechanism (RAND_DRBG_set_callbacks()) and the RAND_DRBG
type changing mechanism (RAND_DRBG_set()).
Adding a compatibility layer to continue supporting the RAND_DRBG API as
a legacy API for a regular deprecation period turned out to come at the
price of complicating the new provider API unnecessarily. Since the
RAND_DRBG API exists only since version 1.1.1, it was decided by the OMC
to drop it entirely.
Other related changes:
Use RNG instead of DRBG in EVP_RAND documentation. The documentation was
using DRBG in places where it should have been RNG or CSRNG.
Move the RAND_DRBG(7) documentation to EVP_RAND(7).
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/12509)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/BIO_get_ex_new_index.pod | 3 | ||||
-rw-r--r-- | doc/man3/BN_rand.pod | 2 | ||||
-rw-r--r-- | doc/man3/CRYPTO_get_ex_new_index.pod | 1 | ||||
-rw-r--r-- | doc/man3/EVP_RAND.pod | 20 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_generate.pod | 90 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_get0_public.pod | 97 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_new.pod | 170 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_reseed.pod | 118 | ||||
-rw-r--r-- | doc/man3/RAND_DRBG_set_callbacks.pod | 171 | ||||
-rw-r--r-- | doc/man3/RAND_add.pod | 4 | ||||
-rw-r--r-- | doc/man3/RAND_bytes.pod | 4 | ||||
-rw-r--r-- | doc/man3/RAND_get0_primary.pod | 78 |
12 files changed, 88 insertions, 670 deletions
diff --git a/doc/man3/BIO_get_ex_new_index.pod b/doc/man3/BIO_get_ex_new_index.pod index 7e5c2852a6..a2d2f1b312 100644 --- a/doc/man3/BIO_get_ex_new_index.pod +++ b/doc/man3/BIO_get_ex_new_index.pod @@ -10,7 +10,6 @@ ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data, EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data, ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data, EVP_PKEY_get_ex_new_index, EVP_PKEY_set_ex_data, EVP_PKEY_get_ex_data, -RAND_DRBG_set_ex_data, RAND_DRBG_get_ex_data, RAND_DRBG_get_ex_new_index, RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data, RSA_set_app_data, RSA_get_app_data, SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data, @@ -70,8 +69,6 @@ TYPE_set_app_data() is a macro that invokes TYPE_set_ex_data() with B<idx> set to zero. TYPE_get_app_data() is a macro that invokes TYPE_get_ex_data() with B<idx> set to zero. -Note that these functions are not defined for the B<RAND_DRBG> type because -there are no backward compatibility concerns. =head1 RETURN VALUES diff --git a/doc/man3/BN_rand.pod b/doc/man3/BN_rand.pod index fc41322f8e..529d6471e4 100644 --- a/doc/man3/BN_rand.pod +++ b/doc/man3/BN_rand.pod @@ -82,7 +82,7 @@ L<RAND_add(3)>, L<RAND_bytes(3)>, L<RAND_priv_bytes(3)>, L<RAND(7)>, -L<RAND_DRBG(7)> +L<EVP_RAND(7)> =head1 HISTORY diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod index b673f00862..463e2c8646 100644 --- a/doc/man3/CRYPTO_get_ex_new_index.pod +++ b/doc/man3/CRYPTO_get_ex_new_index.pod @@ -50,7 +50,6 @@ The specific structures are: EC_KEY ENGINE EVP_PKEY - RAND_DRBG RSA SSL SSL_CTX diff --git a/doc/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod index 5cf62fa359..dfd2a7eb4c 100644 --- a/doc/man3/EVP_RAND.pod +++ b/doc/man3/EVP_RAND.pod @@ -5,7 +5,7 @@ EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX, EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate, EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed, -EVP_RAND_nonce, EVP_RAND_enable_locking, EVP_RAND_set_callbacks, +EVP_RAND_nonce, EVP_RAND_enable_locking, EVP_RAND_verify_zeroization, EVP_RAND_strength, EVP_RAND_state, EVP_RAND_provider, EVP_RAND_CTX_rand, EVP_RAND_is_a, EVP_RAND_number, EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_get_ctx_params, @@ -57,10 +57,6 @@ EVP_RAND_STATE_ERROR - EVP RAND routines const unsigned char *addin, size_t addin_len); int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen); int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx); - int EVP_RAND_set_callbacks(EVP_RAND_CTX *ctx, OSSL_CALLBACK *get_entropy, - OSSL_CALLBACK *cleanup_entropy, - OSSL_CALLBACK *get_nonce, - OSSL_CALLBACK *cleanup_nonce, void *arg); int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx); unsigned int EVP_RAND_strength(EVP_RAND_CTX *ctx); int EVP_RAND_state(EVP_RAND_CTX *ctx); @@ -157,12 +153,6 @@ EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of its parents. After this I<ctx> will operate in a thread safe manner, albeit more slowly. -EVP_RAND_set_callbacks() sets callbacks on the RAND I<ctx> to accept -external entropy and nonce input. The callback I<get_entropy> fills a buffer -with new randomness and the callback I<cleanup_entropy> clears and frees the -buffer. Likewise for I<get_nonce> and I<cleanup_nonce>. In all cases the -callbacks are passed I<arg> in addition to an OSSL_PARAM array. - EVP_RAND_get_params() retrieves details about the implementation I<rand>. The set of parameters given with I<params> determine exactly what @@ -198,22 +188,22 @@ See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor. EVP_RAND_strength() returns the security strength of the RAND I<ctx>. EVP_RAND_state() returns the current state of the RAND I<ctx>. -States defined by the OpenSSL DRBGs are: +States defined by the OpenSSL RNGs are: =over 4 =item * -EVP_RAND_STATE_UNINITIALISED: this DRBG is currently uninitialised. +EVP_RAND_STATE_UNINITIALISED: this RNG is currently uninitialised. The instantiate call will change this to the ready state. =item * -EVP_RAND_STATE_READY: this DRBG is currently ready to generate output. +EVP_RAND_STATE_READY: this RNG is currently ready to generate output. =item * -EVP_RAND_STATE_ERROR: this DRBG is in an error state. +EVP_RAND_STATE_ERROR: this RNG is in an error state. =back diff --git a/doc/man3/RAND_DRBG_generate.pod b/doc/man3/RAND_DRBG_generate.pod deleted file mode 100644 index def98a9680..0000000000 --- a/doc/man3/RAND_DRBG_generate.pod +++ /dev/null @@ -1,90 +0,0 @@ -=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. -Requesting prediction resistance is a relative expensive operation. -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 a live entropy source (section 5.5.2 of [NIST SP 800-90C]). -It is up to the user to ensure that a live entropy source is configured -and is being used. - -=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 HISTORY - -The RAND_DRBG functions were added in OpenSSL 1.1.1. - -Prediction resistance is supported from OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (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_public.pod b/doc/man3/RAND_DRBG_get0_public.pod deleted file mode 100644 index 18b15bc9b9..0000000000 --- a/doc/man3/RAND_DRBG_get0_public.pod +++ /dev/null @@ -1,97 +0,0 @@ -=pod - -=head1 NAME - -OPENSSL_CTX_get0_primary_drbg, -OPENSSL_CTX_get0_public_drbg, -OPENSSL_CTX_get0_private_drbg, -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 *OPENSSL_CTX_get0_primary_drbg(OPENSSL_CTX *ctx); - RAND_DRBG *OPENSSL_CTX_get0_public_drbg(OPENSSL_CTX *ctx); - RAND_DRBG *OPENSSL_CTX_get0_private_drbg(OPENSSL_CTX *ctx); - 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 I<public> and I<private> DRBG are thread-local instances, which are used -by RAND_bytes() and RAND_priv_bytes(), respectively. -The I<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 - -OPENSSL_CTX_get0_primary_drbg() returns a pointer to the I<master> DRBG instance -for the given OPENSSL_CTX B<ctx>. - -OPENSSL_CTX_get0_public_drbg() returns a pointer to the I<public> DRBG instance -for the given OPENSSL_CTX B<ctx>. - -OPENSSL_CTX_get0_private_drbg() returns a pointer to the I<private> DRBG instance -for the given OPENSSL_CTX B<ctx>. - -In all the above cases the B<ctx> parameter can -be NULL in which case the default OPENSSL_CTX is used. RAND_DRBG_get0_master(), -RAND_DRBG_get0_public() and RAND_DRBG_get0_private() are the same as -OPENSSL_CTX_get0_primary_drbg(), OPENSSL_CTX_get0_public_drbg() and -OPENSSL_CTX_get0_private_drbg() respectively except that the default OPENSSL_CTX -is always used. - -=head1 NOTES - -It is not thread-safe to access the I<master> DRBG instance. -The I<public> and I<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 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 HISTORY - -The OPENSSL_CTX_get0_primary_drbg(), OPENSSL_CTX_get0_public_drbg() and -OPENSSL_CTX_get0_private_drbg() functions were added in OpenSSL 3.0. - -All other RAND_DRBG functions were added in OpenSSL 1.1.1. - -=head1 COPYRIGHT - -Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (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 deleted file mode 100644 index 340fccdce6..0000000000 --- a/doc/man3/RAND_DRBG_new.pod +++ /dev/null @@ -1,170 +0,0 @@ -=pod - -=head1 NAME - -RAND_DRBG_new_ex, -RAND_DRBG_new, -RAND_DRBG_set, -RAND_DRBG_set_defaults, -RAND_DRBG_instantiate, -RAND_DRBG_uninstantiate, -RAND_DRBG_free, -RAND_DRBG_verify_zeroization -- initialize and cleanup a RAND_DRBG instance - -=head1 SYNOPSIS - - #include <openssl/rand_drbg.h> - - RAND_DRBG *RAND_DRBG_new_ex(OPENSSL_CTX *ctx, - int type, - unsigned int flags, - RAND_DRBG *parent); - - RAND_DRBG *RAND_DRBG_new(int type, - unsigned int flags, - RAND_DRBG *parent); - - 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); - int RAND_DRBG_verify_zeroization(RAND_DRBG *drbg); - -Deprecated since OpenSSL 3.0, can be hidden entirely by defining -B<OPENSSL_API_COMPAT> with a suitable version value, see -L<openssl_user_macros(7)>: - - int RAND_DRBG_set(RAND_DRBG *drbg, - int type, unsigned int flags); - -=head1 DESCRIPTION - -RAND_DRBG_new_ex() creates a new DRBG instance of the given B<type> for the -given OPENSSL_CTX <ctx>. -The <ctx> parameter can be NULL in which case the default OPENSSL_CTX is used. -RAND_DRBG_new() is the same as RAND_DRBG_new_ex() except that the default -OPENSSL_CTX is always used. - -RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>. -This function is deprecated. Applications should instead use -RAND_DRBG_new_ex() to create a new DRBG. - -RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG -instances. - -The DRBG types are AES-CTR, HMAC and HASH so B<type> can be one of the -following values: - -NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr, NID_sha1, NID_sha224, -NID_sha256, NID_sha384, NID_sha512, NID_sha512_224, NID_sha512_256, -NID_sha3_224, NID_sha3_256, NID_sha3_384 or NID_sha3_512. - -If this method is not called then the default type is given by NID_aes_256_ctr -and the default flags are zero. - -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. The supported flags are: - -=over 4 - -=item RAND_DRBG_FLAG_CTR_NO_DF - -Disables the use of the derivation function ctr_df. For an explanation, -see [NIST SP 800-90A Rev. 1]. - -=item RAND_DRBG_FLAG_HMAC - -Enables use of HMAC instead of the HASH DRBG. - -=item RAND_DRBG_FLAG_PRIMARY - -=item RAND_DRBG_FLAG_PUBLIC - -=item RAND_DRBG_FLAG_PRIVATE - -These 3 flags can be used to set the individual DRBG types created. Multiple -calls are required to set the types to different values. If none of these 3 -flags are used, then the same type and flags are used for all 3 DRBGs in the -B<drbg> chain (<master>, <public> and <private>). - -=back - -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. - -RAND_DRBG_verify_zeroization() confirms if the internal DRBG state is -currently zeroed. - -=head1 RETURN VALUES - - -RAND_DRBG_new_ex() and RAND_DRBG_new() return a pointer to a DRBG instance -allocated on the heap. - -RAND_DRBG_set(), -RAND_DRBG_instantiate(), and -RAND_DRBG_uninstantiate() -return 1 on success, and 0 on failure. - -RAND_DRBG_verify_zeroization() returns 1 if the DRBG state is current zeroed, -and 0 if not. - -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 SEE ALSO - -L<RAND_DRBG_generate(3)>, -L<RAND_DRBG(7)> - -=head1 HISTORY - -The RAND_DRBG_set() function was deprecated in OpenSSL 3.0. - -The RAND_DRBG functions were added in OpenSSL 1.1.1. - -=head1 COPYRIGHT - -Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (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 deleted file mode 100644 index 8bf2669a87..0000000000 --- a/doc/man3/RAND_DRBG_reseed.pod +++ /dev/null @@ -1,118 +0,0 @@ -=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 prediction_resistance); - - 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 primary_reseed_interval, - unsigned int secondary_reseed_interval, - time_t primary_reseed_time_interval, - time_t secondary_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. -An immediate reseeding can be requested by setting the -B<prediction_resistance> flag to 1. -Requesting prediction resistance is a relative expensive operation. -See NOTES section for more details. - -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<primary_reseed_interval> and B<secondary_reseed_interval>) -and the reseed time interval -(B<primary_reseed_time_interval> and B<secondary_reseed_tme_interval>) -of DRBG instances. -The default values are set independently for primary DRBG instances (which don't -have a parent) and secondary 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 -(<primary>, 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 SEE ALSO - -L<RAND_DRBG_generate(3)>, -L<RAND_DRBG_bytes(3)>, -L<RAND_DRBG_set_callbacks(3)>. -L<RAND_DRBG(7)> - -=head1 HISTORY - -The RAND_DRBG functions were added in OpenSSL 1.1.1. - -Prediction resistance is supported from OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (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 deleted file mode 100644 index 53022c8194..0000000000 --- a/doc/man3/RAND_DRBG_set_callbacks.pod +++ /dev/null @@ -1,171 +0,0 @@ -=pod - -=head1 NAME - -RAND_DRBG_set_callbacks, -RAND_DRBG_set_callback_data, -RAND_DRBG_get_callback_data, -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); - - int RAND_DRBG_set_callback_data(RAND_DRBG *drbg, void *ctx); - - void *RAND_DRBG_get_callback_data(RAND_DRBG *drbg); - -=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. - -RAND_DRBG_set_callback_data() can be used to store a pointer to some context -specific data, which can subsequently be retrieved by the entropy and nonce -callbacks using RAND_DRBG_get_callback_data(). -The ownership of the context data remains with the caller, i.e., it is the -caller's responsibility to keep it available as long as it is needed by the -callbacks and free it after use. -For more information about the callback data see the NOTES section. - -Setting the callbacks or the callback data 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 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() returns 1 on success, and 0 on failure. - -RAND_DRBG_set_callback_data() returns 1 on success, and 0 on failure. - -RAND_DRBG_get_callback_data() returns the pointer to the callback data, -which is NULL if none has been set previously. - -=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 a live entropy source (section 5.5.2 of [NIST SP 800-90C]). -It is up to the user to ensure that a live entropy source is configured -and is being used. - -The derivation function is disabled by calling the RAND_DRBG_new_ex() -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 speaking it can be omitted if the random source has "full -entropy", that is, it contains 8 bits of entropy per byte. In a FIPS context, -the derivation function can never be omitted. - -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. - -The callback data is a rather specialized feature, because in general the -random sources don't (and in fact, they must not) depend on any state provided -by the DRBG. -There are however exceptional cases where this feature is useful, most notably -for implementing known answer tests (KATs) or deterministic signatures like -those specified in RFC6979, which require passing a specified entropy and nonce -for instantiating the DRBG. - -=head1 SEE ALSO - -L<RAND_DRBG_new(3)>, -L<RAND_DRBG_reseed(3)>, -L<RAND_DRBG(7)> - -=head1 HISTORY - -The RAND_DRBG functions were added in OpenSSL 1.1.1. - -=head1 COPYRIGHT - -Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (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 2f12e0963c..990f6978d3 100644 --- a/doc/man3/RAND_add.pod +++ b/doc/man3/RAND_add.pod @@ -58,7 +58,7 @@ should consider using L<RAND_load_file(3)> instead. NOTE: In FIPS mode, random data provided by the application is not considered to be a trusted entropy source. It is mixed into the internal state of the RNG as additional data only and this does not count as a full reseed. -For more details, see L<RAND_DRBG(7)>. +For more details, see L<EVP_RAND(7)>. RAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>. @@ -92,7 +92,7 @@ L<RAND_bytes(3)>, L<RAND_egd(3)>, L<RAND_load_file(3)>, L<RAND(7)> -L<RAND_DRBG(7)> +L<EVP_RAND(7)> =head1 HISTORY diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod index 935113add8..0673f1b839 100644 --- a/doc/man3/RAND_bytes.pod +++ b/doc/man3/RAND_bytes.pod @@ -31,7 +31,7 @@ be used for generating values that should remain private. If using the default RAND_METHOD, this function uses a separate "private" PRNG instance so that a compromise of the "public" PRNG instance will not affect the secrecy of these private values, as described in L<RAND(7)> -and L<RAND_DRBG(7)>. +and L<EVP_RAND(7)>. RAND_bytes_ex() and RAND_priv_bytes_ex() are the same as RAND_bytes() and RAND_priv_bytes() except that they both take an additional I<ctx> parameter. @@ -75,7 +75,7 @@ L<RAND_bytes(3)>, L<RAND_priv_bytes(3)>, L<ERR_get_error(3)>, L<RAND(7)>, -L<RAND_DRBG(7)> +L<EVP_RAND(7)> =head1 HISTORY diff --git a/doc/man3/RAND_get0_primary.pod b/doc/man3/RAND_get0_primary.pod new file mode 100644 index 0000000000..16bb223d4a --- /dev/null +++ b/doc/man3/RAND_get0_primary.pod @@ -0,0 +1,78 @@ +=pod + +=head1 NAME + +RAND_get0_primary, +RAND_get0_public, +RAND_get0_private +- get access to the global EVP_RAND_CTX instances + +=head1 SYNOPSIS + + #include <openssl/rand.h> + + EVP_RAND_CTX *RAND_get0_primary(OPENSSL_CTX *ctx); + EVP_RAND_CTX *RAND_get0_public(OPENSSL_CTX *ctx); + EVP_RAND_CTX *RAND_get0_private(OPENSSL_CTX *ctx); + + +=head1 DESCRIPTION + +The default RAND API implementation |