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)

diff --git a/doc/internal/man3/ossl_provider_new.pod b/doc/internal/man3/ossl_provider_new.pod
index 54dd3f8a1852b30d1a55a675fc9323085e07c9cb..b2f966887297ba8f6ad94ceaa14f05964854769c 100644 (file)
--- 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)>