From: Pauli <ppzgs1@gmail.com>
Date: Fri, 26 Feb 2021 00:56:46 +0000 (+1000)
Subject: doc: update documenation with params argument on DRBG instantiate calls
X-Git-Tag: openssl-3.0.0-alpha13~104
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f8a5822cff0b05df8fa937b5aca72ef5b4c1b47a;p=thirdparty%2Fopenssl.git

doc: update documenation with params argument on DRBG instantiate calls

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

diff --git a/doc/man7/EVP_RAND-CTR-DRBG.pod b/doc/man7/EVP_RAND-CTR-DRBG.pod
index a31b22390a8..61dfa2672e5 100644
--- a/doc/man7/EVP_RAND-CTR-DRBG.pod
+++ b/doc/man7/EVP_RAND-CTR-DRBG.pod
@@ -81,7 +81,7 @@ A context for CTR DRBG can be obtained by calling:
  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
                                          SN_aes_256_ctr, 0);
  *p = OSSL_PARAM_construct_end();
- EVP_RAND_set_ctx_params(rctx, params);
+ EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 
  EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 
diff --git a/doc/man7/EVP_RAND-HASH-DRBG.pod b/doc/man7/EVP_RAND-HASH-DRBG.pod
index 631383c74a3..a212add6d2a 100644
--- a/doc/man7/EVP_RAND-HASH-DRBG.pod
+++ b/doc/man7/EVP_RAND-HASH-DRBG.pod
@@ -73,7 +73,7 @@ A context for HASH DRBG can be obtained by calling:
 
  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha512, 0);
  *p = OSSL_PARAM_construct_end();
- EVP_RAND_set_ctx_params(rctx, params);
+ EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 
  EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 
diff --git a/doc/man7/EVP_RAND-HMAC-DRBG.pod b/doc/man7/EVP_RAND-HMAC-DRBG.pod
index f04ae336fcc..f345255efca 100644
--- a/doc/man7/EVP_RAND-HMAC-DRBG.pod
+++ b/doc/man7/EVP_RAND-HMAC-DRBG.pod
@@ -76,7 +76,7 @@ A context for HMAC DRBG can be obtained by calling:
  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_MAC, SN_hmac, 0);
  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_DIGEST, SN_sha256, 0);
  *p = OSSL_PARAM_construct_end();
- EVP_RAND_set_ctx_params(rctx, params);
+ EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 
  EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 
diff --git a/doc/man7/EVP_RAND-SEED-SRC.pod b/doc/man7/EVP_RAND-SEED-SRC.pod
index f301ed25f9f..4d21e4cd6eb 100644
--- a/doc/man7/EVP_RAND-SEED-SRC.pod
+++ b/doc/man7/EVP_RAND-SEED-SRC.pod
@@ -63,7 +63,7 @@ A context for the seed source can be obtained by calling:
  *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
                                          SN_aes_256_ctr, 0);
  *p = OSSL_PARAM_construct_end();
- EVP_RAND_set_ctx_params(rctx, params);
+ EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 
  EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 
diff --git a/doc/man7/EVP_RAND-TEST-RAND.pod b/doc/man7/EVP_RAND-TEST-RAND.pod
index 9eb7001d645..c5f1a4d5262 100644
--- a/doc/man7/EVP_RAND-TEST-RAND.pod
+++ b/doc/man7/EVP_RAND-TEST-RAND.pod
@@ -90,7 +90,7 @@ A context for a test generator can be obtained by calling:
  *p++ = OSSL_PARAM_construct_octet_string(OSSL_RAND_PARAM_TEST_NONCE,
                                           nonce, sizeof(nonce));
  *p = OSSL_PARAM_construct_end();
- EVP_RAND_set_ctx_params(rctx, params);
+ EVP_RAND_instantiate(rctx, strength, 0, NULL, 0, params);
 
  EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
 
diff --git a/doc/man7/provider-rand.pod b/doc/man7/provider-rand.pod
index 5de3a15f38f..157f6227e9c 100644
--- a/doc/man7/provider-rand.pod
+++ b/doc/man7/provider-rand.pod
@@ -26,7 +26,8 @@ functions
  /* Random number generator functions: NIST */
  int OSSL_FUNC_rand_instantiate(void *ctx, unsigned int strength,
                                 int prediction_resistance,
-                                const unsigned char *pstr, size_t pstr_len);
+                                const unsigned char *pstr, size_t pstr_len,
+                                const OSSL_PARAM params[]);
  int OSSL_FUNC_rand_uninstantiate(void *ctx);
  int OSSL_FUNC_rand_generate(void *ctx, unsigned char *out, size_t outlen,
                              unsigned int strength, int prediction_resistance,
@@ -97,7 +98,8 @@ These functions correspond to those defined in NIST SP 800-90A and SP 800-90C.
 OSSL_FUNC_rand_instantiate() is used to instantiate the DRBG I<ctx> at a requested
 security I<strength>.  In addition, I<prediction_resistance> can be requested.
 Additional input I<addin> of length I<addin_len> bytes can optionally
-be provided.
+be provided.  The parameters specified in I<params> configure the DRBG and these
+should be processed before instantiation.
 
 OSSL_FUNC_rand_uninstantiate() is used to uninstantiate the DRBG I<ctx>.  After being
 uninstantiated, a DRBG is unable to produce output until it is instantiated