SSL_CTX_SET_TMP_DH_CALLBACK(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💅 SSL_CTX_SET_TMP_DH_CALLBACK 🔥

okay bestie so this whole page lives in OpenSSL, manual section 3SSL, and it's all about handling DH keys for ephemeral key exchange. the actual functions it covers are SSL_CTX_set_dh_auto, SSL_set_dh_auto, SSL_CTX_set0_tmp_dh_pkey, SSL_set0_tmp_dh_pkey, SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, and SSL_set_tmp_dh. yes that's a lot of names, we'll get through them together 🫶

✨ SYNOPSIS ✨

#include <openssl/ssl.h>

long SSL_CTX_set_dh_auto(SSL_CTX *ctx, int onoff);
long SSL_set_dh_auto(SSL *s, int onoff);
int SSL_CTX_set0_tmp_dh_pkey(SSL_CTX *ctx, EVP_PKEY *dhpkey);
int SSL_set0_tmp_dh_pkey(SSL *s, EVP_PKEY *dhpkey);

so far so good, right? but here's the part where things get a lil deprecated. The following functions have been deprecated since OpenSSL 3.0, and you can hide them entirely by defining OPENSSL_API_COMPAT with a suitable version value — peep openssl_user_macros(7) for the tea:

 void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
                                  DH *(*tmp_dh_callback)(SSL *ssl, int is_export,
                                                         int keylength));
 long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);

 void SSL_set_tmp_dh_callback(SSL *ctx,
                              DH *(*tmp_dh_callback)(SSL *ssl, int is_export,
                                                     int keylength));
 long SSL_set_tmp_dh(SSL *ssl, DH *dh);

🌸 DESCRIPTION 🌸

first things first: every single one of these functions is for servers only. servers, bestie. not clients. don't be out here using them on a client, that's not the vibe 🙈

Some ciphersuites may use ephemeral Diffie-Hellman (DH) key exchange. When that happens, the session data gets negotiated using the ephemeral/temporary DH key, and the key that's supplied and certified by the certificate chain is only used for signing. Anonymous ciphers (aka the ones with no permanent server key) also use ephemeral DH keys. iconic behavior honestly 💖

Using ephemeral DH key exchange gives you forward secrecy, because the connection can only be decrypted when the DH key is known. By generating a temporary DH key inside the server application — one that's lost when the application is left — it becomes impossible for an attacker to decrypt past sessions, even if they get hold of the normal (certified) key. because that key was only ever used for signing. the way that protection works?? obsessed 😭🔥

To do a DH key exchange, the server must use a DH group (DH parameters) and generate a DH key. And the server will always generate a new DH key during the negotiation. no recycling of the actual key, periodt.

Now, generating DH parameters is extremely time consuming, so an application should not generate the parameters on the fly. DH parameters can be reused — because the actual key is newly generated during the negotiation anyway. so the params chill, the key is fresh ✨

Typically applications should use the well known DH parameters that have built-in support in OpenSSL. The macros SSL_CTX_set_dh_auto() and SSL_set_dh_auto() configure OpenSSL to use the default built-in DH parameters for the SSL_CTX and SSL objects respectively. Here's the switch logic, no cap:

  • Passing a value of 2 or 1 in the onoff parameter switches it on.
  • If the onoff parameter is set to 2, it will force the DH key size to 1024 if the SSL_CTX or SSL security level SSL_CTX_set_security_level(3) is 0 or 1.
  • Passing a value of 0 switches it off.
  • The default setting is off.

If "auto" DH parameters are switched on, then the parameters will be selected to be consistent with the size of the key associated with the server's certificate. If there is no certificate (e.g. for PSK ciphersuites), then it will be consistent with the size of the negotiated symmetric cipher key. matching energy, love that for them 💅

Applications may supply their own DH parameters instead of using the built-in values. But this approach is discouraged and applications should in preference use the built-in parameter support described above. If you are an application wishing to supply your own DH parameters, call SSL_CTX_set0_tmp_dh_pkey() or SSL_set0_tmp_dh_pkey() to supply the parameters for the SSL_CTX or SSL respectively. The parameters should be supplied in the dhpkey argument as an EVP_PKEY containing DH parameters. And listen: ownership of the dhpkey value is passed to the SSL_CTX or SSL object as a result of this call, so the caller should not free it if the function call is successful. hand it over and let it go, bestie 🎀

The deprecated macros SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do the same thing as SSL_CTX_set0_tmp_dh_pkey() and SSL_set0_tmp_dh_pkey() — except the DH parameters are supplied in a DH object instead, in the dh argument, and ownership of the DH object is retained by the application. Applications should use "auto" parameters instead, or call SSL_CTX_set0_tmp_dh_pkey() or SSL_set0_tmp_dh_pkey() as appropriate. lowkey just use the new ones fr fr 🙏

An application may instead specify the DH parameters via a callback function, using SSL_CTX_set_tmp_dh_callback() or SSL_set_tmp_dh_callback() to set the callback for the SSL_CTX or SSL object respectively. These functions are deprecated though. Applications should instead use "auto" parameters, or specify the parameters via SSL_CTX_set0_tmp_dh_pkey() or SSL_set0_tmp_dh_pkey() as appropriate. we love a glow-up, and the glow-up is called "auto" 💜

So how does the callback actually behave when you do use it? The callback will be invoked during a connection when DH parameters are required. The SSL object for the current connection is supplied as an argument. Previous versions of OpenSSL used the is_export and keylength arguments to control parameter generation for export and non-export cipher suites. Modern OpenSSL does not support export ciphersuites, so these arguments are unused and can be ignored by the callback. The callback should return the parameters to be used in a DH object. Ownership of the DH object is retained by the application and should later be freed. so yeah, you gotta clean up after yourself 🧚

⚠️ reminder bestie: SSL_CTX_set_tmp_dh_callback(), SSL_CTX_set_tmp_dh(), SSL_set_tmp_dh_callback() and SSL_set_tmp_dh() are all deprecated since OpenSSL 3.0. use "auto" or the set0_tmp_dh_pkey crew instead 💖

🫶 RETURN VALUES 🫶

All of these functions/macros return 1 for success or 0 on error. that's it, that's the whole section. 1 = slay, 0 = not slay 💀

🌈 SEE ALSO 🌈

Copyright 2001-2026 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page bestie 💅 this was SSL_CTX_SET_TMP_DH_CALLBACK(3SSL) from OpenSSL 4.0.3, dated 2026-09-29 — go forth and configure your DH keys responsibly, mwah 🎀🦋✨

📦 where this page comes from