Add DHX FIPS 186-4 domain parameter validation example

Fixes #14369

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

doc/man7/EVP_PKEY-DH.pod

@@ -118,7 +118,7 @@ An B<EVP_PKEY> context can be obtained by calling:
 
     EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
 
-An B<DH> key can be generated with a named safe prime group by calling:
+A B<DH> key can be generated with a named safe prime group by calling:
 
     int priv_len = 2 * 112;
     OSSL_PARAM params[3];
@@ -137,22 +137,21 @@ An B<DH> key can be generated with a named safe prime group by calling:
     EVP_PKEY_free(key);
     EVP_PKEY_CTX_free(pctx);
 
-Legacy B<DH> domain parameters can be generated by calling:
+B<DHX> domain parameters can be generated according to B<FIPS 186-4> by calling:
 
     unsigned int pbits = 2048;
     unsigned int qbits = 256;
-    int gindex = 1;
     OSSL_PARAM params[5];
     EVP_PKEY *param_key = NULL;
     EVP_PKEY_CTX *pctx = NULL;
 
-    pctx = EVP_PKEY_CTX_new_from_name(NULL, "DH", NULL);
+    pctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
     EVP_PKEY_paramgen_init(pctx);
 
     params[0] = OSSL_PARAM_construct_uint("pbits", &pbits);
     params[1] = OSSL_PARAM_construct_uint("qbits", &qbits);
-    params[2] = OSSL_PARAM_construct_int("gindex", &gindex);
-    params[3] = OSSL_PARAM_construct_utf8_string("digest", "SHA384", 0);
+    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();
     EVP_PKEY_CTX_set_params(pctx, params);
 
@@ -163,7 +162,7 @@ Legacy B<DH> domain parameters can be generated by calling:
     EVP_PKEY_free(param_key);
     EVP_PKEY_CTX_free(pctx);
 
-An B<DH> key can be generated using domain parameters by calling:
+A B<DH> key can be generated using domain parameters by calling:
 
     EVP_PKEY *key = NULL;
     EVP_PKEY_CTX *gctx = EVP_PKEY_CTX_new_from_pkey(NULL, param_key, NULL);
@@ -175,8 +174,51 @@ An B<DH> key can be generated using domain parameters by calling:
     EVP_PKEY_free(key);
     EVP_PKEY_CTX_free(gctx);
 
-=for comment TODO(3.0): To validate domain parameters, additional values used
-during generation may be required to be set into the key.
+To validate B<FIPS 186-4> B<DHX> domain parameters decoded from B<PEM> or
+B<DER> data, additional values used during generation may be required to
+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.
+
+    EVP_PKEY *received_domp = ...; /* parameters received and decoded */
+    unsigned char *seed = ...;     /* and additional parameters received */
+    size_t seedlen = ...;          /* by other means, required */
+    int gindex = ...;              /* for the validation */
+    int pcounter = ...;
+    int hindex = ...;
+    OSSL_PARAM extra_params[5];
+    OSSL_PARAM *domain_params = NULL;
+    OSSL_PARAM *merged_params = NULL;
+    EVP_PKEY_CTX *ctx = NULL, *validate_ctx = NULL;
+    EVP_PKEY *complete_domp = NULL;
+
+    EVP_PKEY_todata(received_domp, OSSL_KEYMGMT_SELECT_DOMAIN_PARAMETERS,
+                    &domain_params);
+    extra_params[0] = OSSL_PARAM_construct_octet_string("seed", seed, seedlen);
+    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();
+    merged_params = OSSL_PARAM_merge(domain_params, extra_params);
+
+    ctx = EVP_PKEY_CTX_new_from_name(NULL, "DHX", NULL);
+    EVP_PKEY_fromdata_init(ctx);
+    EVP_PKEY_fromdata(ctx, &complete_domp, OSSL_KEYMGMT_SELECT_ALL,
+                      merged_params);
+
+    validate_ctx = EVP_PKEY_CTX_new_from_pkey(NULL, complete_domp, NULL);
+    if (EVP_PKEY_param_check(validate_ctx) > 0)
+        /* validation_passed(); */
+    else
+        /* validation_failed(); */
+
+    OSSL_PARAM_free(domain_params);
+    OSSL_PARAM_free(merged_params);
+    EVP_PKEY_CTX_free(ctx);
+    EVP_PKEY_CTX_free(validate_ctx);
+    EVP_PKEY_free(complete_domp);
 
 =head1 CONFORMING TO
 

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);
 
-An B<DH> domain parameters key can be generated by calling:
+A B<DSA> domain parameters can be generated by calling:
 
     unsigned int pbits = 2048;
     unsigned int qbits = 256;
@@ -59,7 +59,7 @@ An B<DH> domain parameters key can be generated by calling:
 
     EVP_PKEY_print_params(bio_out, param_key, 0, NULL);
 
-An B<DSA> key can be generated using domain parameters by calling:
+A B<DSA> key can be generated using domain parameters by calling:
 
     EVP_PKEY *key = NULL;
     EVP_PKEY_CTX *gctx = NULL;