From 815416ba8d388db3473a83f75a066b90c7d32638 Mon Sep 17 00:00:00 2001
From: Pauli <ppzgs1@gmail.com>
Date: Mon, 27 May 2024 14:26:25 +1000
Subject: [PATCH] document internal ossl_provider_random_bytes rand funtion

Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/24498)
---
 doc/internal/man3/ossl_provider_new.pod | 26 +++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod
index 54dd3f8a18..b2f9668872 100644
--- a/doc/internal/man3/ossl_provider_new.pod
+++ b/doc/internal/man3/ossl_provider_new.pod
@@ -17,6 +17,7 @@ ossl_provider_libctx,
 ossl_provider_teardown, ossl_provider_gettable_params,
 ossl_provider_get_params,
 ossl_provider_query_operation, ossl_provider_unquery_operation,
+ossl_provider_random_bytes,
 ossl_provider_set_operation_bit, ossl_provider_test_operation_bit,
 ossl_provider_get_capabilities
 - internal provider routines
@@ -86,6 +87,8 @@ ossl_provider_get_capabilities
  void ossl_provider_unquery_operation(const OSSL_PROVIDER *prov,
                                       int operation_id,
                                       const OSSL_ALGORITHM *algs);
+ int ossl_provider_random_bytes(const OSSL_PROVIDER *prov, int which,
+                                void *buf, size_t n, unsigned int strength);
 
  int ossl_provider_set_operation_bit(OSSL_PROVIDER *provider, size_t bitnum);
  int ossl_provider_test_operation_bit(OSSL_PROVIDER *provider, size_t bitnum,
@@ -276,6 +279,26 @@ ossl_provider_unquery_operation() informs the provider that the result of
 ossl_provider_query_operation() is no longer going to be directly accessed and
 that all relevant information has been copied.
 
+ossl_provider_random_bytes() queries the provider, I<prov>, randomness
+source for I<n> bytes of entropy which are returned in the buffer
+I<buf>, the returned entropy will have a number of bits of I<strength>.
+The entropy is drawn from the source, I<which>, which can be:
+
+=over 4
+
+=item *
+
+OSSL_PROV_RANDOM_PUBLIC for a source equivalent to L<RAND_bytes(3)> or
+
+=item *
+
+.OSSL_PROV_RANDOM_PRIVATE for a source equivalent to L<RAND_priv_bytes(3)>.
+
+=back
+
+Specifying other values for I<which> will result in an unspecified source but will
+not result in an error.
+
 ossl_provider_set_operation_bit() registers a 1 for operation I<bitnum>
 in a bitstring that's internal to I<provider>.
 
@@ -364,6 +387,9 @@ ossl_provider_get_capabilities() returns 1 on success, or 0 on error.
 If this function isn't available in the provider or the provider does not
 support the requested capability then 0 is returned.
 
+ossl_provider_random_bytes() returns 1 on success or 0 or -1 on error as per
+L<RAND_bytes(3)>.
+
 =head1 SEE ALSO
 
 L<OSSL_PROVIDER(3)>, L<provider(7)>, L<openssl(1)>