diff options
author | Pauli <pauli@openssl.org> | 2023-09-05 12:51:05 +1000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2023-09-27 17:23:04 +0100 |
commit | 4cde7585ce8eb53682256ba79e6af1949498fbfe (patch) | |
tree | 0a2d79638c8770ff7d97c4c67a19c3a897b94f82 /doc | |
parent | a9483b8aa00753a2a9665273c0e376f3c1d36e65 (diff) |
fips: use seed source requested
Fixes #21909
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21964)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/internal/man3/ossl_rand_get_entropy.pod | 45 | ||||
-rw-r--r-- | doc/man7/EVP_RAND-TEST-RAND.pod | 7 | ||||
-rw-r--r-- | doc/man7/provider-base.pod | 28 |
3 files changed, 66 insertions, 14 deletions
diff --git a/doc/internal/man3/ossl_rand_get_entropy.pod b/doc/internal/man3/ossl_rand_get_entropy.pod index 4da3f1f4d9..48343b6fe0 100644 --- a/doc/internal/man3/ossl_rand_get_entropy.pod +++ b/doc/internal/man3/ossl_rand_get_entropy.pod @@ -2,8 +2,8 @@ =head1 NAME -ossl_rand_get_entropy, ossl_rand_cleanup_entropy, -ossl_rand_get_nonce, ossl_rand_cleanup_nonce +ossl_rand_get_entropy, ossl_rand_get_user_entropy, ossl_rand_cleanup_entropy, +ossl_rand_get_nonce, ossl_rand_get_user_nonce, ossl_rand_cleanup_nonce - get seed material from the operating system =head1 SYNOPSIS @@ -13,11 +13,17 @@ ossl_rand_get_nonce, ossl_rand_cleanup_nonce size_t ossl_rand_get_entropy(OSSL_CORE_HANDLE *handle, unsigned char **pout, int entropy, size_t min_len, size_t max_len); + size_t ossl_rand_get_user_entropy(OSSL_CORE_HANDLE *handle, + unsigned char **pout, int entropy, + size_t min_len, size_t max_len); void ossl_rand_cleanup_entropy(OSSL_CORE_HANDLE *handle, unsigned char *buf, size_t len); size_t ossl_rand_get_nonce(OSSL_CORE_HANDLE *handle, unsigned char **pout, size_t min_len, size_t max_len, const void *salt, size_t salt_len); + size_t ossl_rand_get_user_nonce(OSSL_CORE_HANDLE *handle, unsigned char **pout, + size_t min_len, size_t max_len, + const void *salt, size_t salt_len); void ossl_rand_cleanup_nonce(OSSL_CORE_HANDLE *handle, unsigned char *buf, size_t len); @@ -29,9 +35,14 @@ stored in a buffer which contains at least I<min_len> and at most I<max_len> bytes. The buffer address is stored in I<*pout> and the buffer length is returned to the caller. +ossl_rand_get_user_entropy() is the same as ossl_rand_get_entropy() +except that it retrieves the seeding material from the library context's +DRBG seed source. By default this is the operating system but it can +be changed by calling L<RAND_set_seed_source_type(3)>. + ossl_rand_cleanup_entropy() cleanses and frees any storage allocated by -ossl_rand_get_entropy(). The seeding buffer is pointed to by I<buf> and is -of length I<len> bytes. +ossl_rand_get_entropy() or ossl_rand_get_user_entropy(). The entropy +buffer is pointed to by I<buf> and is of length I<len> bytes. ossl_rand_get_nonce() retrieves a nonce using the passed I<salt> parameter of length I<salt_len> and operating system specific information. @@ -41,18 +52,34 @@ The output is stored in a buffer which contains at least I<min_len> and at most I<max_len> bytes. The buffer address is stored in I<*pout> and the buffer length returned to the caller. +ossl_rand_get_user_nonce() is the same as ossl_rand_get_nonce() except +that it retrieves the seeding material from the library context's DRBG +seed source. By default this is the operating system but it can be +changed by calling L<RAND_set_seed_source_type(3)>. + ossl_rand_cleanup_nonce() cleanses and frees any storage allocated by -ossl_rand_get_nonce(). The nonce buffer is pointed to by I<buf> and is -of length I<len> bytes. +ossl_rand_get_nonce() or ossl_rand_get_user_nonce(). The nonce buffer +is pointed to by I<buf> and is of length I<len> bytes. + +=head1 NOTES + +FIPS providers 3.0.0, 3.0.8 and 3.0.9 incorrectly pass a provider +internal pointer to ossl_rand_get_entropy(), ossl_rand_cleanup_entropy(), +ossl_rand_get_nonce() and ossl_rand_cleanup_nonce(). This pointer cannot +be safely dereferenced. =head1 RETURN VALUES -ossl_rand_get_entropy() and ossl_rand_get_nonce() return the number of bytes -in I<*pout> or 0 on error. +ossl_rand_get_entropy(), ossl_rand_get_user_entropy(), +ossl_rand_get_nonce() and ossl_rand_get_user_nonce() return the number +of bytes in I<*pout> or 0 on error. =head1 HISTORY -The functions described here were all added in OpenSSL 3.0. +The functions ossl_rand_get_user_entropy() and ossl_rand_get_user_nonce() +were added in OpenSSL 3.0.12, 3.1.4 and 3.2.0. + +The remaining functions described here were all added in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man7/EVP_RAND-TEST-RAND.pod b/doc/man7/EVP_RAND-TEST-RAND.pod index ff5207565c..feab01431d 100644 --- a/doc/man7/EVP_RAND-TEST-RAND.pod +++ b/doc/man7/EVP_RAND-TEST-RAND.pod @@ -60,6 +60,13 @@ If there are insufficient data present to satisfy a call, an error is returned. Sets the bytes returned when the test generator is sent a nonce request. Each nonce request will return all of the bytes. +=item "generate" (B<OSSL_RAND_PARAM_GENERATE>) <integer> + +If this parameter is zero, it will only emit the nonce and entropy data +supplied via the aforementioned parameters. Otherwise, low quality +non-cryptographic pseudorandom output is produced. This parameter defaults +to zero. + =back =head1 NOTES diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod index 33d7fe7f55..eb9e8d3575 100644 --- a/doc/man7/provider-base.pod +++ b/doc/man7/provider-base.pod @@ -76,11 +76,17 @@ provider-base size_t get_entropy(const OSSL_CORE_HANDLE *handle, unsigned char **pout, int entropy, size_t min_len, size_t max_len); + size_t get_user_entropy(const OSSL_CORE_HANDLE *handle, + unsigned char **pout, int entropy, + size_t min_len, size_t max_len); void cleanup_entropy(const OSSL_CORE_HANDLE *handle, unsigned char *buf, size_t len); size_t get_nonce(const OSSL_CORE_HANDLE *handle, unsigned char **pout, size_t min_len, size_t max_len, const void *salt, size_t salt_len); + size_t get_user_nonce(const OSSL_CORE_HANDLE *handle, + unsigned char **pout, size_t min_len, size_t max_len, + const void *salt, size_t salt_len); void cleanup_nonce(const OSSL_CORE_HANDLE *handle, unsigned char *buf, size_t len); @@ -171,8 +177,10 @@ provider): OPENSSL_cleanse OSSL_FUNC_OPENSSL_CLEANSE OSSL_SELF_TEST_set_callback OSSL_FUNC_SELF_TEST_CB ossl_rand_get_entropy OSSL_FUNC_GET_ENTROPY + ossl_rand_get_user_entropy OSSL_FUNC_GET_USER_ENTROPY ossl_rand_cleanup_entropy OSSL_FUNC_CLEANUP_ENTROPY ossl_rand_get_nonce OSSL_FUNC_GET_NONCE + ossl_rand_get_user_nonce OSSL_FUNC_GET_USER_NONCE ossl_rand_cleanup_nonce OSSL_FUNC_CLEANUP_NONCE provider_register_child_cb OSSL_FUNC_PROVIDER_REGISTER_CHILD_CB provider_deregister_child_cb OSSL_FUNC_PROVIDER_DEREGISTER_CHILD_CB @@ -302,9 +310,14 @@ output will have at least I<min_len> and at most I<max_len> bytes. The buffer address is stored in I<*pout> and the buffer length is returned to the caller. On error, zero is returned. +get_user_entropy() is the same as get_entropy() except that it will +attempt to gather seed material via the seed source specified by a call to +L<RAND_set_seed_source_type(3)> or via L<config(5)/Random Configuration>. + cleanup_entropy() is used to clean up and free the buffer returned by -get_entropy(). The entropy pointer returned by get_entropy() is passed in -B<buf> and its length in B<len>. +get_entropy() or get_user_entropy(). The entropy pointer returned by +get_entropy() or get_user_entropy() is passed in B<buf> and its length +in B<len>. get_nonce() retrieves a nonce using the passed I<salt> parameter of length I<salt_len> and operating system specific information. @@ -314,9 +327,14 @@ The output is stored in a buffer which contains at least I<min_len> and at most I<max_len> bytes. The buffer address is stored in I<*pout> and the buffer length returned to the caller. On error, zero is returned. -cleanup_nonce() is used to clean up and free the buffer returned by -get_nonce(). The nonce pointer returned by get_nonce() is passed in -B<buf> and its length in B<len>. +get_user_nonce() is the same as get_nonce() except that it will attempt +to gather seed material via the seed source specified by a call to +L<RAND_set_seed_source_type(3)> or via L<config(5)/Random Configuration>. + +cleanup_nonce() is used to clean up and free the buffer returned +by get_nonce() or get_user_nonce(). The nonce pointer returned by +get_nonce() or get_user_nonce() is passed in B<buf> and its length +in B<len>. provider_register_child_cb() registers callbacks for being informed about the loading and unloading of providers in the application's library context. |