From: Pauli Date: Fri, 30 Oct 2020 05:39:10 +0000 (+1000) Subject: doc: Documentation changes for moving the entropy source out of the fips provider X-Git-Tag: openssl-3.0.0-alpha9~45 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=71febb399225ec5b0f85292fe9487d507fbafb7e;p=thirdparty%2Fopenssl.git doc: Documentation changes for moving the entropy source out of the fips provider Reviewed-by: Matt Caswell Reviewed-by: Matthias St. Pierre (Merged from https://github.com/openssl/openssl/pull/13226) --- diff --git a/providers/implementations/rands/rand_pool.c b/crypto/rand/rand_pool.c similarity index 100% rename from providers/implementations/rands/rand_pool.c rename to crypto/rand/rand_pool.c diff --git a/doc/internal/man3/ossl_rand_get_entropy.pod b/doc/internal/man3/ossl_rand_get_entropy.pod new file mode 100644 index 00000000000..4da3f1f4d9d --- /dev/null +++ b/doc/internal/man3/ossl_rand_get_entropy.pod @@ -0,0 +1,66 @@ +=pod + +=head1 NAME + +ossl_rand_get_entropy, ossl_rand_cleanup_entropy, +ossl_rand_get_nonce, ossl_rand_cleanup_nonce +- get seed material from the operating system + +=head1 SYNOPSIS + + #include "crypto/rand.h" + + size_t ossl_rand_get_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); + void ossl_rand_cleanup_nonce(OSSL_CORE_HANDLE *handle, + unsigned char *buf, size_t len); + +=head1 DESCRIPTION + +ossl_rand_get_entropy() retrieves seeding material from the operating system. +The seeding material will have at least I bytes of randomness and is +stored in a buffer which contains at least I and at most I +bytes. The buffer address is stored in I<*pout> and the buffer length is +returned to the caller. + +ossl_rand_cleanup_entropy() cleanses and frees any storage allocated by +ossl_rand_get_entropy(). The seeding buffer is pointed to by I and is +of length I bytes. + +ossl_rand_get_nonce() retrieves a nonce using the passed I parameter +of length I and operating system specific information. +The I should contain uniquely identifying information and this is +included, in an unspecified manner, as part of the output. +The output is stored in a buffer which contains at least I and at +most I bytes. The buffer address is stored in I<*pout> and the +buffer length returned to the caller. + +ossl_rand_cleanup_nonce() cleanses and frees any storage allocated by +ossl_rand_get_nonce(). The nonce buffer is pointed to by I and is +of length I bytes. + +=head1 RETURN VALUES + +ossl_rand_get_entropy() and ossl_rand_get_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. + +=head1 COPYRIGHT + +Copyright 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. + +=cut diff --git a/doc/man7/EVP_RAND-CTR-DRBG.pod b/doc/man7/EVP_RAND-CTR-DRBG.pod index d8e2d4f2aac..a31b22390a8 100644 --- a/doc/man7/EVP_RAND-CTR-DRBG.pod +++ b/doc/man7/EVP_RAND-CTR-DRBG.pod @@ -24,12 +24,12 @@ The supported parameters are: =item "strength" (B) +=item "max_request" (B) + =item "reseed_requests" (B) =item "reseed_time_interval" (B) -=item "max_request" (B) - =item "min_entropylen" (B) =item "max_entropylen" (B) diff --git a/doc/man7/EVP_RAND-HASH-DRBG.pod b/doc/man7/EVP_RAND-HASH-DRBG.pod index b85010dd41d..631383c74a3 100644 --- a/doc/man7/EVP_RAND-HASH-DRBG.pod +++ b/doc/man7/EVP_RAND-HASH-DRBG.pod @@ -24,12 +24,12 @@ The supported parameters are: =item "strength" (B) +=item "max_request" (B) + =item "reseed_requests" (B) =item "reseed_time_interval" (B) -=item "max_request" (B) - =item "min_entropylen" (B) =item "max_entropylen" (B) diff --git a/doc/man7/EVP_RAND-HMAC-DRBG.pod b/doc/man7/EVP_RAND-HMAC-DRBG.pod index e9620783b09..f04ae336fcc 100644 --- a/doc/man7/EVP_RAND-HMAC-DRBG.pod +++ b/doc/man7/EVP_RAND-HMAC-DRBG.pod @@ -24,12 +24,12 @@ The supported parameters are: =item "strength" (B) +=item "max_request" (B) + =item "reseed_requests" (B) =item "reseed_time_interval" (B) -=item "max_request" (B) - =item "min_entropylen" (B) =item "max_entropylen" (B) diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod index 536c5ed430b..7e8f5188a55 100644 --- a/doc/man7/provider-base.pod +++ b/doc/man7/provider-base.pod @@ -65,6 +65,16 @@ provider-base void self_test_cb(OPENSSL_CORE_CTX *ctx, OSSL_CALLBACK **cb, void **cbarg) + size_t get_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) + void cleanup_nonce(const OSSL_CORE_HANDLE *handle, + unsigned char *buf, size_t len) /* Functions offered by the provider to libcrypto */ void provider_teardown(void *provctx); @@ -129,6 +139,10 @@ provider): BIO_vprintf OSSL_FUNC_BIO_VPRINTF 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_cleanup_entropy OSSL_FUNC_CLEANUP_ENTROPY + ossl_rand_get_nonce OSSL_FUNC_GET_NONCE + ossl_rand_cleanup_nonce OSSL_FUNC_CLEANUP_NONCE For I<*out> (the B array passed from the provider to F): @@ -210,6 +224,28 @@ side (the two are not compatible). OSSL_SELF_TEST_set_callback() is used to set an optional callback that can be passed into a provider. This may be ignored by a provider. +get_entropy() retrieves seeding material from the operating system. +The seeding material will have at least I bytes of randomness and the +output will have at least I and at most I bytes. +The buffer address is stored in I<*pout> and the buffer length is +returned to the caller. On error, zero is returned. + +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 and its length in B. + +get_nonce() retrieves a nonce using the passed I parameter +of length I and operating system specific information. +The I should contain uniquely identifying information and this is +included, in an unspecified manner, as part of the output. +The output is stored in a buffer which contrains at least I and at +most I 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 and its length in B. + =head2 Provider functions provider_teardown() is called when a provider is shut down and removed diff --git a/providers/implementations/include/prov/rand_pool.h b/include/crypto/rand_pool.h similarity index 100% rename from providers/implementations/include/prov/rand_pool.h rename to include/crypto/rand_pool.h