From: Shane Lontis <shane.lontis@oracle.com>
Date: Tue, 20 Apr 2021 03:29:26 +0000 (+1000)
Subject: Doc updates for DH/DSA examples
X-Git-Tag: openssl-3.0.0-alpha16~131
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=990aa405dbf5899cc24c167b4c0a29a3db58e343;p=thirdparty%2Fopenssl.git

Doc updates for DH/DSA examples

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14936)
---

diff --git a/doc/man7/EVP_PKEY-DH.pod b/doc/man7/EVP_PKEY-DH.pod
index 60865a7120e..63ab9d10d11 100644
--- a/doc/man7/EVP_PKEY-DH.pod
+++ b/doc/man7/EVP_PKEY-DH.pod
@@ -161,9 +161,10 @@ A B<DH> key can be generated with a named safe prime group by calling:
 
 B<DHX> domain parameters can be generated according to B<FIPS 186-4> by calling:
 
+    int gindex = 2;
     unsigned int pbits = 2048;
     unsigned int qbits = 256;
-    OSSL_PARAM params[5];
+    OSSL_PARAM params[6];
     EVP_PKEY *param_key = NULL;
     EVP_PKEY_CTX *pctx = NULL;
 
@@ -172,9 +173,10 @@ B<DHX> domain parameters can be generated according to B<FIPS 186-4> by calling:
 
     params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
     params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
-    params[2] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0);
-    params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0);
-    params[4] = OSSL_PARAM_construct_end();
+    params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
+    params[3] = OSSL_PARAM_construct_utf8_string("type", "fips186_4", 0);
+    params[4] = OSSL_PARAM_construct_utf8_string("digest", "SHA256", 0);
+    params[5] = OSSL_PARAM_construct_end();
     EVP_PKEY_CTX_set_params(pctx, params);
 
     EVP_PKEY_gen(pctx, &param_key);
@@ -202,7 +204,7 @@ be set into the key.
 
 EVP_PKEY_todata(), OSSL_PARAM_merge(), and EVP_PKEY_fromdata() are useful
 to add these parameters to the original key or domain parameters before
-the actual validation.
+the actual validation. In production code the return values should be checked.
 
     EVP_PKEY *received_domp = ...; /* parameters received and decoded */
     unsigned char *seed = ...;     /* and additional parameters received */
@@ -210,7 +212,7 @@ the actual validation.
     int gindex = ...;              /* for the validation */
     int pcounter = ...;
     int hindex = ...;
-    OSSL_PARAM extra_params[5];
+    OSSL_PARAM extra_params[4];
     OSSL_PARAM *domain_params = NULL;
     OSSL_PARAM *merged_params = NULL;
     EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL;
@@ -219,10 +221,13 @@ the actual validation.
     EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS,
                     &domain_params);
     extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen);
+    /*
+     * NOTE: For unverifiable g use "hindex" instead of "gindex"
+     * extra_params[1] = OSSL_PARAM_construct_int("hindex", &hindex);
+     */
     extra_params[1] = OSSL_PARAM_construct_int("gindex", &gindex);
     extra_params[2] = OSSL_PARAM_construct_int("pcounter", &pcounter);
-    extra_params[3] = OSSL_PARAM_construct_int("hindex", &hindex);
-    extra_params[4] = OSSL_PARAM_construct_end();
+    extra_params[3] = OSSL_PARAM_construct_end();
     merged_params = OSSL_PARAM_merge(domain_params, extra_params);
 
     ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
diff --git a/doc/man7/EVP_PKEY-DSA.pod b/doc/man7/EVP_PKEY-DSA.pod
index 5f922f46fc7..119d4b893ac 100644
--- a/doc/man7/EVP_PKEY-DSA.pod
+++ b/doc/man7/EVP_PKEY-DSA.pod
@@ -35,7 +35,7 @@ An B<EVP_PKEY> context can be obtained by calling:
 
     EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DSA", NULL);
 
-A B<DSA> domain parameters can be generated by calling:
+The B<DSA> domain parameters can be generated by calling:
 
     unsigned int pbits = 2048;
     unsigned int qbits = 256;