--- /dev/null
+=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
=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>
=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>
=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>
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);
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>):
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
projects / openssl.git / commitdiff