doc: document the two new RAND functions

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/14162)

diff --git a/doc/man7/provider-rand.pod b/doc/man7/provider-rand.pod
index d75a36d01ea490afbae013857e26436cfbe8a6a0..795924e6b7b55b8b6f8e36d0866e5e55d91b23be 100644 (file)
--- a/doc/man7/provider-rand.pod
+++ b/doc/man7/provider-rand.pod
@@ -37,7 +37,13 @@ functions
 
  /* Random number generator functions: additional */
  size_t OSSL_FUNC_rand_nonce(void *ctx, unsigned char *out, size_t outlen,
-                             int strength, size_t min_noncelen, size_t max_noncelen);
+                             int strength, size_t min_noncelen,
+                             size_t max_noncelen);
+ size_t OSSL_FUNC_rand_get_seed(void *ctx, unsigned char **buffer,
+                                int entropy, size_t min_len, size_t max_len,
+                                int prediction_resistance,
+                                const unsigned char *adin, size_t adin_len);
+ void OSSL_FUNC_rand_clear_seed(void *ctx, unsigned char *buffer, size_t b_len);
  int OSSL_FUNC_rand_verify_zeroization(void *ctx);
 
  /* Context Locking */
@@ -110,6 +116,18 @@ OSSL_FUNC_rand_nonce() is used to generate a nonce of the given I<strength> with
 length from I<min_noncelen> to I<max_noncelen>. If the output buffer I<out> is
 NULL, the length of the nonce should be returned.
 
+OSSL_FUNC_rand_get_seed() is used by deterministic generators to obtain their
+seeding material from their parent.  The seed bytes will meet the specified
+security level of I<entropy> bits and there will be between I<min_len>
+and I<max_len> inclusive bytes in total.  If I<prediction_resistance> is
+true, the bytes will be produced from a live entropy source.  Additional
+input I<addin> of length I<addin_len> bytes can optionally be provided.
+A pointer to the seed material is returned in I<*buffer> and this must be
+freed by a later call to OSSL_FUNC_rand_clear_seed().
+
+OSSL_FUNC_rand_clear_seed() frees a seed I<buffer> of length I<b_len> bytes
+which was previously allocated by OSSL_FUNC_rand_get_seed().
+
 OSSL_FUNC_rand_verify_zeroization() is used to determine if the internal state of the
 DRBG is zero.  This capability is mandated by NIST as part of the self
 tests, it is unlikely to be useful in other circumstances.
@@ -240,6 +258,9 @@ array, or NULL if none is offered.
 
 OSSL_FUNC_rand_nonce() returns the size of the generated nonce, or 0 on error.
 
+OSSL_FUNC_rand_get_seed() returns the size of the generated seed, or 0 on
+error.
+
 All of the remaining functions should return 1 for success or 0 on error.
 
 =head1 SEE ALSO