{
    "mode": "man",
    "parameter": "EVP_KEYMGMT-DH",
    "section": "7ssl",
    "url": "https://www.chedong.com/phpMan.php/man/EVP_KEYMGMT-DH/7ssl/json",
    "generated": "2026-10-08T08:53:23Z",
    "sections": {
        "NAME": {
            "content": "EVPPKEY-DH, EVPPKEY-DHX, EVPKEYMGMT-DH, EVPKEYMGMT-DHX - EVPPKEY DH and DHX keytype and\nalgorithm support\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "For DH FFC key agreement, two classes of domain parameters can be used: \"safe\" domain\nparameters that are associated with approved named safe-prime groups, and a class of\n\"FIPS186-type\" domain parameters. FIPS186-type domain parameters should only be used for\nbackward compatibility with existing applications that cannot be upgraded to use the approved\nsafe-prime groups.\n\nSee EVPPKEY-FFC(7) for more information about FFC keys.\n\nThe DH key type uses PKCS#3 format which saves p and g, but not the q value.  The DHX key\ntype uses X9.42 format which saves the value of q and this must be used for FIPS186-4. If key\nvalidation is required, users should be aware of the nuances associated with FIPS186-4 style\nparameters as discussed in \"DH key validation\".\n",
            "subsections": [
                {
                    "name": "DH and DHX domain parameters",
                    "content": "In addition to the common FCC parameters that all FFC keytypes should support (see \"FFC\nparameters\" in EVPPKEY-FFC(7)) the DHX and DH keytype implementations support the following:\n\n\"group\" (OSSLPKEYPARAMGROUPNAME) <UTF8 string>\nSets  or  gets  a  string  that  associates a DH or DHX named safe prime group with known\nvalues for p, q and g.\n\nThe  following  values  can  be  used  by  the  OpenSSL's  default  and  FIPS  providers:\n\"ffdhe2048\",    \"ffdhe3072\",    \"ffdhe4096\",   \"ffdhe6144\",   \"ffdhe8192\",   \"modp2048\",\n\"modp3072\", \"modp4096\", \"modp6144\", \"modp8192\".\n\nThe following  additional  values  can  also  be  used  by  OpenSSL's  default  provider:\n\"modp1536\", \"dh1024160\", \"dh2048224\", \"dh2048256\".\n\nDH/DHX  named  groups  can  be easily validated since the parameters are well known.  For\nprotocols that only transfer p and g the value of q can also be retrieved.\n"
                },
                {
                    "name": "DH and DHX additional parameters",
                    "content": "\"encoded-pub-key\" (OSSLPKEYPARAMENCODEDPUBLICKEY) <octet string>\nUsed for getting and setting the encoding of the DH public key used  in  a  key  exchange\nmessage    for    the   TLS   protocol.    See   EVPPKEYset1encodedpublickey()   and\nEVPPKEYget1encodedpublickey().\n"
                },
                {
                    "name": "DH additional domain parameters",
                    "content": "\"safeprime-generator\" (OSSLPKEYPARAMDHGENERATOR) <integer>\nUsed for DH generation of safe primes using the  old  safe  prime  generator  code.   The\ndefault value is 2.  It is recommended to use a named safe prime group instead, if domain\nparameter validation is required.\n\nRandomly  generated  safe  primes  are not allowed by FIPS, so setting this value for the\nOpenSSL FIPS provider will instead choose a named safe prime group based on the  size  of\np.\n"
                },
                {
                    "name": "DH and DHX domain parameter / key generation parameters",
                    "content": "In addition to the common FFC key generation parameters that all FFC key types should support\n(see   \"FFC   key   generation  parameters\"  in  EVPPKEY-FFC(7))  the  DH  and  DHX  keytype\nimplementation supports the following:\n\n\"type\" (OSSLPKEYPARAMFFCTYPE) <UTF8 string>\nSets the type of parameter generation. For DH valid values are:\n\n\"fips1864\"\n\"default\"\n\"fips1862\"\nThese are described in \"FFC key generation parameters\" in EVPPKEY-FFC(7)\n\n\"group\"\nThis specifies that a named safe prime name will be chosen using the \"pbits\" type.\n\n\"generator\"\nA safe prime generator. See the \"safeprime-generator\" type above.  This is only valid\nfor DH keys.\n\n\"pbits\" (OSSLPKEYPARAMFFCPBITS) <unsigned integer>\nSets the size (in bits) of the prime 'p'.\n\nFor \"fips1864\" this must be 2048.  For \"fips1862\" this must be 1024.  For \"group\"  this\ncan be any one of 2048, 3072, 4096, 6144 or 8192.\n\n\"privlen\" (OSSLPKEYPARAMDHPRIVLEN) <integer>\nAn  optional  value  to set the maximum length of the generated private key.  The default\nvalue used if this is not set is the maximum value of BNnumbits(q)). The minimum  value\nthat  this can be set to is 2 * s.  Where s is the security strength of the key which has\nvalues of 112, 128, 152, 176 and 200 for key sizes of 2048, 3072, 4096, 6144 and 8192.\n"
                },
                {
                    "name": "DH key validation",
                    "content": "For DHX that is not a named group the FIPS186-4 standard specifies that the values  used  for\nFFC parameter generation are also required for parameter validation. This means that optional\nFFC domain parameter values for seed, pcounter and gindex or hindex may need to be stored for\nvalidation  purposes.   For  DHX  the  seed  and pcounter can be stored in ASN1 data (but the\ngindex or hindex cannot be stored). It is  recommended  to  use  a  named  safe  prime  group\ninstead.\n\nFor  DH keys, EVPPKEYparamcheck(3) behaves in the following way: The OpenSSL FIPS provider\ntests if the parameters are either an approved safe prime group OR that  the  FFC  parameters\nconform  to FIPS186-4 as defined in SP800-56Ar3 Assurances of Domain-Parameter Validity.  The\nOpenSSL default provider uses simpler checks that allows there to be no q value for backwards\ncompatibility.\n\nFor DH keys, EVPPKEYparamcheckquick(3) is equivalent to EVPPKEYparamcheck(3).\n\nFor DH keys, EVPPKEYpubliccheck(3) conforms to SP800-56Ar3 FFC Full Public-Key Validation.\n\nFor DH keys, EVPPKEYpubliccheckquick(3) conforms to SP800-56Ar3  FFC  Partial  Public-Key\nValidation when the DH key is an approved named safe prime group, otherwise it is the same as\nEVPPKEYpubliccheck(3).\n\nFor  DH  Keys,  EVPPKEYprivatecheck(3)  tests that the private key is in the correct range\naccording to SP800-56Ar3. The OpenSSL FIPS provider requires the value of q to be  set  (note\nthat  this  is  set  for  named  safe prime groups).  For backwards compatibility the OpenSSL\ndefault provider only requires p to be set.\n\nFor DH keys, EVPPKEYpairwisecheck(3) conforms to SP800-56Ar3 Owner Assurance of  Pair-wise\nConsistency.\n"
                }
            ]
        },
        "EXAMPLES": {
            "content": "An EVPPKEY context can be obtained by calling:\n\nEVPPKEYCTX *pctx = EVPPKEYCTXnewfromname(NULL, \"DH\", NULL);\n\nA DH key can be generated with a named safe prime group by calling:\n\nint privlen = 2 * 112;\nOSSLPARAM params[3];\nEVPPKEY *pkey = NULL;\nEVPPKEYCTX *pctx = EVPPKEYCTXnewfromname(NULL, \"DH\", NULL);\n\nparams[0] = OSSLPARAMconstructutf8string(\"group\", \"ffdhe2048\", 0);\n/* \"privlen\" is optional */\nparams[1] = OSSLPARAMconstructint(\"privlen\", &privlen);\nparams[2] = OSSLPARAMconstructend();\n\nEVPPKEYkeygeninit(pctx);\nEVPPKEYCTXsetparams(pctx, params);\nEVPPKEYgenerate(pctx, &pkey);\n...\nEVPPKEYfree(pkey);\nEVPPKEYCTXfree(pctx);\n\nDHX domain parameters can be generated according to FIPS186-4 by calling:\n\nint gindex = 2;\nunsigned int pbits = 2048;\nunsigned int qbits = 256;\nOSSLPARAM params[6];\nEVPPKEY *paramkey = NULL;\nEVPPKEYCTX *pctx = NULL;\n\npctx = EVPPKEYCTXnewfromname(NULL, \"DHX\", NULL);\nEVPPKEYparamgeninit(pctx);\n\nparams[0] = OSSLPARAMconstructuint(\"pbits\", &pbits);\nparams[1] = OSSLPARAMconstructuint(\"qbits\", &qbits);\nparams[2] = OSSLPARAMconstructint(\"gindex\", &gindex);\nparams[3] = OSSLPARAMconstructutf8string(\"type\", \"fips1864\", 0);\nparams[4] = OSSLPARAMconstructutf8string(\"digest\", \"SHA256\", 0);\nparams[5] = OSSLPARAMconstructend();\nEVPPKEYCTXsetparams(pctx, params);\n\nEVPPKEYgenerate(pctx, &paramkey);\n\nEVPPKEYprintparams(bioout, paramkey, 0, NULL);\n...\nEVPPKEYfree(paramkey);\nEVPPKEYCTXfree(pctx);\n\nA DH key can be generated using domain parameters by calling:\n\nEVPPKEY *key = NULL;\nEVPPKEYCTX *gctx = EVPPKEYCTXnewfrompkey(NULL, paramkey, NULL);\n\nEVPPKEYkeygeninit(gctx);\nEVPPKEYgenerate(gctx, &key);\nEVPPKEYprintprivate(bioout, key, 0, NULL);\n...\nEVPPKEYfree(key);\nEVPPKEYCTXfree(gctx);\n\nTo  validate  FIPS186-4 DHX domain parameters decoded from PEM or DER data, additional values\nused during generation may be required to be set into the key.\n\nEVPPKEYtodata(), OSSLPARAMmerge(),  and  EVPPKEYfromdata()  are  useful  to  add  these\nparameters  to  the  original  key  or  domain  parameters  before  the actual validation. In\nproduction code the return values should be checked.\n\nEVPPKEY *receiveddomp = ...; /* parameters received and decoded */\nunsigned char *seed = ...;     /* and additional parameters received */\nsizet seedlen = ...;          /* by other means, required */\nint gindex = ...;              /* for the validation */\nint pcounter = ...;\nint hindex = ...;\nOSSLPARAM extraparams[4];\nOSSLPARAM *domainparams = NULL;\nOSSLPARAM *mergedparams = NULL;\nEVPPKEYCTX *ctx = NULL, *validatectx = NULL;\nEVPPKEY *completedomp = NULL;\n\nEVPPKEYtodata(receiveddomp, OSSLKEYMGMTSELECTDOMAINPARAMETERS,\n&domainparams);\nextraparams[0] = OSSLPARAMconstructoctetstring(\"seed\", seed, seedlen);\n/*\n* NOTE: For unverifiable g use \"hindex\" instead of \"gindex\"\n* extraparams[1] = OSSLPARAMconstructint(\"hindex\", &hindex);\n*/\nextraparams[1] = OSSLPARAMconstructint(\"gindex\", &gindex);\nextraparams[2] = OSSLPARAMconstructint(\"pcounter\", &pcounter);\nextraparams[3] = OSSLPARAMconstructend();\nmergedparams = OSSLPARAMmerge(domainparams, extraparams);\n\nctx = EVPPKEYCTXnewfromname(NULL, \"DHX\", NULL);\nEVPPKEYfromdatainit(ctx);\nEVPPKEYfromdata(ctx, &completedomp, OSSLKEYMGMTSELECTALL,\nmergedparams);\n\nvalidatectx = EVPPKEYCTXnewfrompkey(NULL, completedomp, NULL);\nif (EVPPKEYparamcheck(validatectx) > 0)\n/* validationpassed(); */\nelse\n/* validationfailed(); */\n\nOSSLPARAMfree(domainparams);\nOSSLPARAMfree(mergedparams);\nEVPPKEYCTXfree(ctx);\nEVPPKEYCTXfree(validatectx);\nEVPPKEYfree(completedomp);\n",
            "subsections": []
        },
        "CONFORMING TO": {
            "content": "RFC 7919 (TLS ffdhe named safe prime groups)\nRFC 3526 (IKE modp named safe prime groups)\nRFC 5114 (Additional DH named groups for dh1024160\", \"dh2048224\" and \"dh2048256\").\n\nThe following sections of SP800-56Ar3:\n\n5.5.1.1 FFC Domain Parameter Selection/Generation\nAppendix D: FFC Safe-prime Groups\n\nThe following sections of FIPS186-4:\n\nA.1.1.2 Generation of Probable Primes p and q Using an Approved Hash Function.\nA.2.3 Generation of canonical generator g.\nA.2.1 Unverifiable Generation of the Generator g.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "EVPPKEY-FFC(7),   EVPKEYEXCH-DH(7)   EVPPKEY(3),   provider-keymgmt(7),    EVPKEYMGMT(3),\nOSSLPROVIDER-default(7), OSSLPROVIDER-FIPS(7)\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright 2020-2022 The OpenSSL Project Authors. All Rights Reserved.\n\nLicensed  under  the Apache License 2.0 (the \"License\").  You may not use this file except in\ncompliance with the License.  You can obtain a  copy  in  the  file  LICENSE  in  the  source\ndistribution or at <https://www.openssl.org/source/license.html>.\n\n3.0.13                                       2026-07-29                            EVPPKEY-DH(7SSL)",
            "subsections": []
        }
    },
    "summary": "EVPPKEY-DH, EVPPKEY-DHX, EVPKEYMGMT-DH, EVPKEYMGMT-DHX - EVPPKEY DH and DHX keytype and algorithm support",
    "flags": [],
    "examples": [
        "An EVPPKEY context can be obtained by calling:",
        "EVPPKEYCTX *pctx = EVPPKEYCTXnewfromname(NULL, \"DH\", NULL);",
        "A DH key can be generated with a named safe prime group by calling:",
        "int privlen = 2 * 112;",
        "OSSLPARAM params[3];",
        "EVPPKEY *pkey = NULL;",
        "EVPPKEYCTX *pctx = EVPPKEYCTXnewfromname(NULL, \"DH\", NULL);",
        "params[0] = OSSLPARAMconstructutf8string(\"group\", \"ffdhe2048\", 0);",
        "/* \"privlen\" is optional */",
        "params[1] = OSSLPARAMconstructint(\"privlen\", &privlen);",
        "params[2] = OSSLPARAMconstructend();",
        "EVPPKEYkeygeninit(pctx);",
        "EVPPKEYCTXsetparams(pctx, params);",
        "EVPPKEYgenerate(pctx, &pkey);",
        "...",
        "EVPPKEYfree(pkey);",
        "EVPPKEYCTXfree(pctx);",
        "DHX domain parameters can be generated according to FIPS186-4 by calling:",
        "int gindex = 2;",
        "unsigned int pbits = 2048;",
        "unsigned int qbits = 256;",
        "OSSLPARAM params[6];",
        "EVPPKEY *paramkey = NULL;",
        "EVPPKEYCTX *pctx = NULL;",
        "pctx = EVPPKEYCTXnewfromname(NULL, \"DHX\", NULL);",
        "EVPPKEYparamgeninit(pctx);",
        "params[0] = OSSLPARAMconstructuint(\"pbits\", &pbits);",
        "params[1] = OSSLPARAMconstructuint(\"qbits\", &qbits);",
        "params[2] = OSSLPARAMconstructint(\"gindex\", &gindex);",
        "params[3] = OSSLPARAMconstructutf8string(\"type\", \"fips1864\", 0);",
        "params[4] = OSSLPARAMconstructutf8string(\"digest\", \"SHA256\", 0);",
        "params[5] = OSSLPARAMconstructend();",
        "EVPPKEYCTXsetparams(pctx, params);",
        "EVPPKEYgenerate(pctx, &paramkey);",
        "EVPPKEYprintparams(bioout, paramkey, 0, NULL);",
        "...",
        "EVPPKEYfree(paramkey);",
        "EVPPKEYCTXfree(pctx);",
        "A DH key can be generated using domain parameters by calling:",
        "EVPPKEY *key = NULL;",
        "EVPPKEYCTX *gctx = EVPPKEYCTXnewfrompkey(NULL, paramkey, NULL);",
        "EVPPKEYkeygeninit(gctx);",
        "EVPPKEYgenerate(gctx, &key);",
        "EVPPKEYprintprivate(bioout, key, 0, NULL);",
        "...",
        "EVPPKEYfree(key);",
        "EVPPKEYCTXfree(gctx);",
        "To  validate  FIPS186-4 DHX domain parameters decoded from PEM or DER data, additional values",
        "used during generation may be required to be set into the key.",
        "EVPPKEYtodata(), OSSLPARAMmerge(),  and  EVPPKEYfromdata()  are  useful  to  add  these",
        "parameters  to  the  original  key  or  domain  parameters  before  the actual validation. In",
        "production code the return values should be checked.",
        "EVPPKEY *receiveddomp = ...; /* parameters received and decoded */",
        "unsigned char *seed = ...;     /* and additional parameters received */",
        "sizet seedlen = ...;          /* by other means, required */",
        "int gindex = ...;              /* for the validation */",
        "int pcounter = ...;",
        "int hindex = ...;",
        "OSSLPARAM extraparams[4];",
        "OSSLPARAM *domainparams = NULL;",
        "OSSLPARAM *mergedparams = NULL;",
        "EVPPKEYCTX *ctx = NULL, *validatectx = NULL;",
        "EVPPKEY *completedomp = NULL;",
        "EVPPKEYtodata(receiveddomp, OSSLKEYMGMTSELECTDOMAINPARAMETERS,",
        "&domainparams);",
        "extraparams[0] = OSSLPARAMconstructoctetstring(\"seed\", seed, seedlen);",
        "/*",
        "* NOTE: For unverifiable g use \"hindex\" instead of \"gindex\"",
        "* extraparams[1] = OSSLPARAMconstructint(\"hindex\", &hindex);",
        "*/",
        "extraparams[1] = OSSLPARAMconstructint(\"gindex\", &gindex);",
        "extraparams[2] = OSSLPARAMconstructint(\"pcounter\", &pcounter);",
        "extraparams[3] = OSSLPARAMconstructend();",
        "mergedparams = OSSLPARAMmerge(domainparams, extraparams);",
        "ctx = EVPPKEYCTXnewfromname(NULL, \"DHX\", NULL);",
        "EVPPKEYfromdatainit(ctx);",
        "EVPPKEYfromdata(ctx, &completedomp, OSSLKEYMGMTSELECTALL,",
        "mergedparams);",
        "validatectx = EVPPKEYCTXnewfrompkey(NULL, completedomp, NULL);",
        "if (EVPPKEYparamcheck(validatectx) > 0)",
        "/* validationpassed(); */",
        "else",
        "/* validationfailed(); */",
        "OSSLPARAMfree(domainparams);",
        "OSSLPARAMfree(mergedparams);",
        "EVPPKEYCTXfree(ctx);",
        "EVPPKEYCTXfree(validatectx);",
        "EVPPKEYfree(completedomp);"
    ],
    "see_also": [
        {
            "name": "EVPPKEY-FFC",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/EVPPKEY-FFC/7/json"
        },
        {
            "name": "EVPKEYEXCH-DH",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/EVPKEYEXCH-DH/7/json"
        },
        {
            "name": "EVPPKEY",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/EVPPKEY/3/json"
        },
        {
            "name": "provider-keymgmt",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/provider-keymgmt/7/json"
        },
        {
            "name": "EVPKEYMGMT",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/EVPKEYMGMT/3/json"
        },
        {
            "name": "OSSLPROVIDER-default",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-default/7/json"
        },
        {
            "name": "OSSLPROVIDER-FIPS",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/OSSLPROVIDER-FIPS/7/json"
        }
    ]
}