Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_tmp_dh_callback.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_TMP_DH_CALLBACK 3SSL"
58 .TH SSL_CTX_SET_TMP_DH_CALLBACK 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_dh_auto, SSL_set_dh_auto, SSL_CTX_set0_tmp_dh_pkey,
65 SSL_set0_tmp_dh_pkey, SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh,
66 SSL_set_tmp_dh_callback, SSL_set_tmp_dh
67 \&\- handle DH keys for ephemeral key exchange
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/ssl.h>
72 \&
73 \& long SSL_CTX_set_dh_auto(SSL_CTX *ctx, int onoff);
74 \& long SSL_set_dh_auto(SSL *s, int onoff);
75 \& int SSL_CTX_set0_tmp_dh_pkey(SSL_CTX *ctx, EVP_PKEY *dhpkey);
76 \& int SSL_set0_tmp_dh_pkey(SSL *s, EVP_PKEY *dhpkey);
77 .Ve
78 .PP
79 The following functions have been deprecated since OpenSSL 3.0, and can be
80 hidden entirely by defining \fBOPENSSL_API_COMPAT\fR with a suitable version value,
81 see \fBopenssl_user_macros\fR\|(7):
82 .PP
83 .Vb 4
84 \& void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
85 \& DH *(*tmp_dh_callback)(SSL *ssl, int is_export,
86 \& int keylength));
87 \& long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);
88 \&
89 \& void SSL_set_tmp_dh_callback(SSL *ctx,
90 \& DH *(*tmp_dh_callback)(SSL *ssl, int is_export,
91 \& int keylength));
92 \& long SSL_set_tmp_dh(SSL *ssl, DH *dh);
93 .Ve
94 .SH DESCRIPTION
95 .IX Header "DESCRIPTION"
96 The functions described on this page are relevant for servers only.
97 .PP
98 Some ciphersuites may use ephemeral Diffie-Hellman (DH) key exchange. In these
99 cases, the session data is negotiated using the ephemeral/temporary DH key and
100 the key supplied and certified by the certificate chain is only used for
101 signing. Anonymous ciphers (without a permanent server key) also use ephemeral
102 DH keys.
103 .PP
104 Using ephemeral DH key exchange yields forward secrecy as the connection
105 can only be decrypted when the DH key is known. By generating a temporary
106 DH key inside the server application that is lost when the application
107 is left, it becomes impossible for an attacker to decrypt past sessions,
108 even if they get hold of the normal (certified) key, as this key was
109 only used for signing.
110 .PP
111 In order to perform a DH key exchange the server must use a DH group
112 (DH parameters) and generate a DH key. The server will always generate
113 a new DH key during the negotiation.
114 .PP
115 As generating DH parameters is extremely time consuming, an application
116 should not generate the parameters on the fly. DH parameters can be reused, as
117 the actual key is newly generated during the negotiation.
118 .PP
119 Typically applications should use well known DH parameters that have built-in
120 support in OpenSSL. The macros \fBSSL_CTX_set_dh_auto()\fR and \fBSSL_set_dh_auto()\fR
121 configure OpenSSL to use the default built-in DH parameters for the \fBSSL_CTX\fR
122 and \fBSSL\fR objects respectively. Passing a value of 2 or 1 in the \fIonoff\fR
123 parameter switches it on. If the \fIonoff\fR parameter is set to 2, it will force
124 the DH key size to 1024 if the \fBSSL_CTX\fR or \fBSSL\fR security level
125 \&\fBSSL_CTX_set_security_level\fR\|(3) is 0 or 1. Passing a value of 0 switches
126 it off. The default setting is off.
127 .PP
128 If "auto" DH parameters are switched on then the parameters will be selected to
129 be consistent with the size of the key associated with the server's certificate.
130 If there is no certificate (e.g. for PSK ciphersuites), then it it will be
131 consistent with the size of the negotiated symmetric cipher key.
132 .PP
133 Applications may supply their own DH parameters instead of using the built-in
134 values. This approach is discouraged and applications should in preference use
135 the built-in parameter support described above. Applications wishing to supply
136 their own DH parameters should call \fBSSL_CTX_set0_tmp_dh_pkey()\fR or
137 \&\fBSSL_set0_tmp_dh_pkey()\fR to supply the parameters for the \fBSSL_CTX\fR or \fBSSL\fR
138 respectively. The parameters should be supplied in the \fIdhpkey\fR argument as
139 an \fBEVP_PKEY\fR containing DH parameters. Ownership of the \fIdhpkey\fR value is
140 passed to the \fBSSL_CTX\fR or \fBSSL\fR object as a result of this call, and so the
141 caller should not free it if the function call is successful.
142 .PP
143 The deprecated macros \fBSSL_CTX_set_tmp_dh()\fR and \fBSSL_set_tmp_dh()\fR do the same
144 thing as \fBSSL_CTX_set0_tmp_dh_pkey()\fR and \fBSSL_set0_tmp_dh_pkey()\fR except that the
145 DH parameters are supplied in a \fBDH\fR object instead in the \fIdh\fR argument, and
146 ownership of the \fBDH\fR object is retained by the application. Applications
147 should use "auto" parameters instead, or call \fBSSL_CTX_set0_tmp_dh_pkey()\fR or
148 \&\fBSSL_set0_tmp_dh_pkey()\fR as appropriate.
149 .PP
150 An application may instead specify the DH parameters via a callback function
151 using the functions \fBSSL_CTX_set_tmp_dh_callback()\fR or \fBSSL_set_tmp_dh_callback()\fR
152 to set the callback for the \fBSSL_CTX\fR or \fBSSL\fR object respectively. These
153 functions are deprecated. Applications should instead use "auto" parameters, or
154 specify the parameters via \fBSSL_CTX_set0_tmp_dh_pkey()\fR or \fBSSL_set0_tmp_dh_pkey()\fR
155 as appropriate.
156 .PP
157 The callback will be invoked during a connection when DH parameters are
158 required. The \fBSSL\fR object for the current connection is supplied as an
159 argument. Previous versions of OpenSSL used the \fBis_export\fR and \fBkeylength\fR
160 arguments to control parameter generation for export and non-export
161 cipher suites. Modern OpenSSL does not support export ciphersuites and so these
162 arguments are unused and can be ignored by the callback. The callback should
163 return the parameters to be used in a DH object. Ownership of the DH object is
164 retained by the application and should later be freed.
165 .SH "RETURN VALUES"
166 .IX Header "RETURN VALUES"
167 All of these functions/macros return 1 for success or 0 on error.
168 .SH "SEE ALSO"
169 .IX Header "SEE ALSO"
170 \&\fBssl\fR\|(7), \fBSSL_CTX_set_cipher_list\fR\|(3),
171 \&\fBSSL_CTX_set_options\fR\|(3),
172 \&\fBopenssl\-ciphers\fR\|(1), \fBopenssl\-dhparam\fR\|(1)
173 .SH COPYRIGHT
174 .IX Header "COPYRIGHT"
175 Copyright 2001\-2025 The OpenSSL Project Authors. All Rights Reserved.
176 .PP
177 Licensed under the Apache License 2.0 (the "License"). You may not use
178 this file except in compliance with the License. You can obtain a copy
179 in the file LICENSE in the source distribution or at
180 <https://www.openssl.org/source/license.html>.