diff options
Diffstat (limited to 'doc/internal/man3/ossl_rand_get_entropy.pod')
| -rw-r--r-- | doc/internal/man3/ossl_rand_get_entropy.pod | 45 |
1 files changed, 36 insertions, 9 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 |