{ "content": [ { "type": "text", "text": "# EVP_KEYEXCH-ECDH (man)\n\n## NAME\n\nEVPKEYEXCH-ECDH - ECDH Key Exchange algorithm support\n\n## DESCRIPTION\n\nKey exchange support for the ECDH key type.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION** (1 subsections)\n- **EXAMPLES**\n- **SEE ALSO**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "EVP_KEYEXCH-ECDH", "section": "", "mode": "man", "summary": "EVPKEYEXCH-ECDH - ECDH Key Exchange algorithm support", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "Keys for the host and peer must be generated as shown in \"Examples\" in EVPPKEY-EC(7) using", "the same curve name.", "The code to generate a shared secret for the normal case is identical to \"Examples\" in", "EVPKEYEXCH-DH(7).", "To derive a shared secret on the host using the host's key and the peer's public key but also", "using X963KDF with a user key material:", "/* It is assumed that the hostkey, peerpubkey and ukm are set up */", "void derivesecret(EVPPKEY *hostkey, EVPPKEY *peerkey,", "unsigned char *ukm, sizet ukmlen)", "unsigned char secret[64];", "sizet outlen = sizeof(secret);", "sizet secretlen = outlen;", "unsigned int pad = 1;", "OSSLPARAM params[6];", "EVPPKEYCTX *dctx = EVPPKEYCTXnewfrompkey(NULL, hostkey, NULL);", "EVPPKEYderiveinit(dctx);", "params[0] = OSSLPARAMconstructuint(OSSLEXCHANGEPARAMPAD, &pad);", "params[1] = OSSLPARAMconstructutf8string(OSSLEXCHANGEPARAMKDFTYPE,", "\"X963KDF\", 0);", "params[2] = OSSLPARAMconstructutf8string(OSSLEXCHANGEPARAMKDFDIGEST,", "\"SHA1\", 0);", "params[3] = OSSLPARAMconstructsizet(OSSLEXCHANGEPARAMKDFOUTLEN,", "&outlen);", "params[4] = OSSLPARAMconstructoctetstring(OSSLEXCHANGEPARAMKDFUKM,", "ukm, ukmlen);", "params[5] = OSSLPARAMconstructend();", "EVPPKEYCTXsetparams(dctx, params);", "EVPPKEYderivesetpeer(dctx, peerpubkey);", "EVPPKEYderive(dctx, secret, &secretlen);", "...", "OPENSSLclearfree(secret, secretlen);", "EVPPKEYCTXfree(dctx);" ], "see_also": [ { "name": "EVPPKEY-EC", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/EVPPKEY-EC/7/json" }, { "name": "EVPPKEY", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/EVPPKEY/3/json" }, { "name": "provider-keyexch", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/provider-keyexch/7/json" }, { "name": "provider-keymgmt", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/provider-keymgmt/7/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" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 2, "subsections": [ { "name": "ECDH Key Exchange parameters", "lines": 32 } ] }, { "name": "EXAMPLES", "lines": 41, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "COPYRIGHT", "lines": 9, "subsections": [] } ], "sections": { "NAME": { "content": "EVPKEYEXCH-ECDH - ECDH Key Exchange algorithm support\n", "subsections": [] }, "DESCRIPTION": { "content": "Key exchange support for the ECDH key type.\n", "subsections": [ { "name": "ECDH Key Exchange parameters", "content": "\"ecdh-cofactor-mode\" (OSSLEXCHANGEPARAMECECDHCOFACTORMODE) \nSets or gets the ECDH mode of operation for the associated key exchange ctx.\n\nIn the context of an Elliptic Curve Diffie-Hellman key exchange, this parameter can be\nused to select between the plain Diffie-Hellman (DH) or Cofactor Diffie-Hellman (CDH)\nvariants of the key exchange algorithm.\n\nWhen setting, the value should be 1, 0 or -1, respectively forcing cofactor mode on, off,\nor resetting it to the default for the private key associated with the given key exchange\nctx.\n\nWhen getting, the value should be either 1 or 0, respectively signaling if the cofactor\nmode is on or off.\n\nSee also provider-keymgmt(7) for the related OSSLPKEYPARAMUSECOFACTORECDH parameter\nthat can be set on a per-key basis.\n\n\"kdf-type\" (OSSLEXCHANGEPARAMKDFTYPE) \nSee \"Common Key Exchange parameters\" in provider-keyexch(7).\n\n\"kdf-digest\" (OSSLEXCHANGEPARAMKDFDIGEST) \nSee \"Common Key Exchange parameters\" in provider-keyexch(7).\n\n\"kdf-digest-props\" (OSSLEXCHANGEPARAMKDFDIGESTPROPS) \nSee \"Common Key Exchange parameters\" in provider-keyexch(7).\n\n\"kdf-outlen\" (OSSLEXCHANGEPARAMKDFOUTLEN) \nSee \"Common Key Exchange parameters\" in provider-keyexch(7).\n\n\"kdf-ukm\" (OSSLEXCHANGEPARAMKDFUKM) \nSee \"Common Key Exchange parameters\" in provider-keyexch(7).\n" } ] }, "EXAMPLES": { "content": "Keys for the host and peer must be generated as shown in \"Examples\" in EVPPKEY-EC(7) using\nthe same curve name.\n\nThe code to generate a shared secret for the normal case is identical to \"Examples\" in\nEVPKEYEXCH-DH(7).\n\nTo derive a shared secret on the host using the host's key and the peer's public key but also\nusing X963KDF with a user key material:\n\n/* It is assumed that the hostkey, peerpubkey and ukm are set up */\nvoid derivesecret(EVPPKEY *hostkey, EVPPKEY *peerkey,\nunsigned char *ukm, sizet ukmlen)\n{\nunsigned char secret[64];\nsizet outlen = sizeof(secret);\nsizet secretlen = outlen;\nunsigned int pad = 1;\nOSSLPARAM params[6];\nEVPPKEYCTX *dctx = EVPPKEYCTXnewfrompkey(NULL, hostkey, NULL);\n\nEVPPKEYderiveinit(dctx);\n\nparams[0] = OSSLPARAMconstructuint(OSSLEXCHANGEPARAMPAD, &pad);\nparams[1] = OSSLPARAMconstructutf8string(OSSLEXCHANGEPARAMKDFTYPE,\n\"X963KDF\", 0);\nparams[2] = OSSLPARAMconstructutf8string(OSSLEXCHANGEPARAMKDFDIGEST,\n\"SHA1\", 0);\nparams[3] = OSSLPARAMconstructsizet(OSSLEXCHANGEPARAMKDFOUTLEN,\n&outlen);\nparams[4] = OSSLPARAMconstructoctetstring(OSSLEXCHANGEPARAMKDFUKM,\nukm, ukmlen);\nparams[5] = OSSLPARAMconstructend();\nEVPPKEYCTXsetparams(dctx, params);\n\nEVPPKEYderivesetpeer(dctx, peerpubkey);\nEVPPKEYderive(dctx, secret, &secretlen);\n...\nOPENSSLclearfree(secret, secretlen);\nEVPPKEYCTXfree(dctx);\n}\n", "subsections": [] }, "SEE ALSO": { "content": "EVPPKEY-EC(7) EVPPKEY(3), provider-keyexch(7), provider-keymgmt(7),\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 .\n\n\n\n3.0.2 2026-06-02 EVPKEYEXCH-ECDH(7SSL)", "subsections": [] } } } }