diff options
-rw-r--r-- | crypto/rand/rand_pool.c (renamed from providers/implementations/rands/rand_pool.c) | 0 | ||||
-rw-r--r-- | doc/internal/man3/ossl_rand_get_entropy.pod | 66 | ||||
-rw-r--r-- | doc/man7/EVP_RAND-CTR-DRBG.pod | 4 | ||||
-rw-r--r-- | doc/man7/EVP_RAND-HASH-DRBG.pod | 4 | ||||
-rw-r--r-- | doc/man7/EVP_RAND-HMAC-DRBG.pod | 4 | ||||
-rw-r--r-- | doc/man7/provider-base.pod | 36 | ||||
-rw-r--r-- | include/crypto/rand_pool.h (renamed from providers/implementations/include/prov/rand_pool.h) | 0 |
7 files changed, 108 insertions, 6 deletions
diff --git a/providers/implementations/rands/rand_pool.c b/crypto/rand/rand_pool.c index c66c0e3fa8..c66c0e3fa8 100644 --- a/providers/implementations/rands/rand_pool.c +++ b/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 0000000000..4da3f1f4d9 --- /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<entropy> bytes of randomness and 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 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<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. +The I<salt> 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<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_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. + +=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<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man7/EVP_RAND-CTR-DRBG.pod b/doc/man7/EVP_RAND-CTR-DRBG.pod index d8e2d4f2aa..a31b22390a 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<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> +=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer> + =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer> -=item "max_request" (B<OSSL_DRBG_PARAM_MAX_REQUEST>) <unsigned integer> - =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer> diff --git a/doc/man7/EVP_RAND-HASH-DRBG.pod b/doc/man7/EVP_RAND-HASH-DRBG.pod index b85010dd41..631383c74a 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<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> +=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer> + =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer> -=item "max_request" (B<OSSL_DRBG_PARAM_MAX_REQUEST>) <unsigned integer> - =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer> diff --git a/doc/man7/EVP_RAND-HMAC-DRBG.pod b/doc/man7/EVP_RAND-HMAC-DRBG.pod index e9620783b0..f04ae336fc 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<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer> +=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer> + =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer> =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer> -=item "max_request" (B<OSSL_DRBG_PARAM_MAX_REQUEST>) <unsigned integer> - =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer> =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer> diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod index 536c5ed430..7e8f5188a5 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<OSSL_DISPATCH> array passed from the provider to F<libcrypto>): @@ -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<entropy> bytes of randomness and the +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. + +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_nonce() retrieves a nonce using the passed I<salt> parameter +of length I<salt_len> and operating system specific information. +The I<salt> 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<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>. + =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 index 9c5c92e365..9c5c92e365 100644 --- a/providers/implementations/include/prov/rand_pool.h +++ b/include/crypto/rand_pool.h |