diff options
author | Matthias St. Pierre <matthias.st.pierre@ncp-e.com> | 2023-10-16 23:48:03 +0200 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2023-10-20 09:48:34 +0100 |
commit | 5516d20226c496c2b22fa741698b4d48dad0428f (patch) | |
tree | d257c2536b7eb711cdc47fbd9d0495507bdde172 /doc | |
parent | 098f27f9ef8be2a418f76896ee3c824e8709fcf7 (diff) |
rand: add callbacks to cleanup the user entropy resp. nonce
The `get_user_{entropy,nonce}` callbacks were add recently to the
dispatch table in commit 4cde7585ce8e. Instead of adding corresponding
`cleanup_user_{entropy,nonce}` callbacks, the `cleanup_{entropy,nonce}`
callbacks were reused. This can cause a problem in the case where the
seed source is replaced by a provider: the buffer gets allocated by
the provider but cleared by the core.
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22423)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/internal/man3/ossl_rand_get_entropy.pod | 23 | ||||
-rw-r--r-- | doc/man7/provider-base.pod | 26 |
2 files changed, 36 insertions, 13 deletions
diff --git a/doc/internal/man3/ossl_rand_get_entropy.pod b/doc/internal/man3/ossl_rand_get_entropy.pod index 5c7a076336..be39369f2b 100644 --- a/doc/internal/man3/ossl_rand_get_entropy.pod +++ b/doc/internal/man3/ossl_rand_get_entropy.pod @@ -2,8 +2,10 @@ =head1 NAME -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 +ossl_rand_get_entropy, ossl_rand_get_user_entropy, +ossl_rand_cleanup_entropy, ossl_rand_cleanup_user_entropy, +ossl_rand_get_nonce, ossl_rand_get_user_nonce, +ossl_rand_cleanup_nonce, ossl_rand_cleanup_user_nonce - get seed material from the operating system =head1 SYNOPSIS @@ -18,6 +20,8 @@ ossl_rand_get_nonce, ossl_rand_get_user_nonce, ossl_rand_cleanup_nonce size_t min_len, size_t max_len); void ossl_rand_cleanup_entropy(OSSL_CORE_HANDLE *handle, unsigned char *buf, size_t len); + void ossl_rand_cleanup_user_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); @@ -26,6 +30,8 @@ ossl_rand_get_nonce, ossl_rand_get_user_nonce, ossl_rand_cleanup_nonce const void *salt, size_t salt_len); void ossl_rand_cleanup_nonce(OSSL_CORE_HANDLE *handle, unsigned char *buf, size_t len); + void ossl_rand_cleanup_user_nonce(OSSL_CORE_HANDLE *handle, + unsigned char *buf, size_t len); =head1 DESCRIPTION @@ -41,8 +47,12 @@ 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() 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_entropy(). The entropy buffer is pointed to by I<buf> +and is of length I<len> bytes. + +ossl_rand_cleanup_user_entropy() cleanses and frees any storage allocated by +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. @@ -76,8 +86,9 @@ of bytes in I<*pout> or 0 on error. =head1 HISTORY -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 functions ossl_rand_get_user_entropy(), ossl_rand_get_user_nonce(), +ossl_rand_cleanup_user_entropy(), and ossl_rand_cleanup_user_nonce() +were added in OpenSSL 3.1.4 and 3.2.0. The remaining functions described here were all added in OpenSSL 3.0. diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod index eb9e8d3575..5dcbbed221 100644 --- a/doc/man7/provider-base.pod +++ b/doc/man7/provider-base.pod @@ -81,6 +81,8 @@ provider-base size_t min_len, size_t max_len); void cleanup_entropy(const OSSL_CORE_HANDLE *handle, unsigned char *buf, size_t len); + void cleanup_user_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); @@ -89,6 +91,8 @@ provider-base const void *salt, size_t salt_len); void cleanup_nonce(const OSSL_CORE_HANDLE *handle, unsigned char *buf, size_t len); + void cleanup_user_nonce(const OSSL_CORE_HANDLE *handle, + unsigned char *buf, size_t len); /* Functions for querying the providers in the application library context */ int provider_register_child_cb(const OSSL_CORE_HANDLE *handle, @@ -179,9 +183,11 @@ provider): 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_cleanup_user_entropy OSSL_FUNC_CLEANUP_USER_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 + ossl_rand_cleanup_user_nonce OSSL_FUNC_CLEANUP_USER_NONCE provider_register_child_cb OSSL_FUNC_PROVIDER_REGISTER_CHILD_CB provider_deregister_child_cb OSSL_FUNC_PROVIDER_DEREGISTER_CHILD_CB provider_name OSSL_FUNC_PROVIDER_NAME @@ -315,9 +321,12 @@ 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() 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_entropy(). The entropy pointer returned by get_entropy() +is passed in B<buf> and its length in B<len>. + +cleanup_user_entropy() is used to clean up and free the buffer returned by +get_user_entropy(). The entropy pointer returned by 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. @@ -331,10 +340,13 @@ 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>. +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>. + +cleanup_user_nonce() is used to clean up and free the buffer returned by +get_user_nonce(). The nonce pointer returned by 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. |