Debian Codegraph @

upstream/debian-trixie/man3/SSL_CTX_set_options.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_OPTIONS 3SSL"
58 .TH SSL_CTX_SET_OPTIONS 3SSL 2026-04-07 3.5.6 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_options, SSL_set_options, SSL_CTX_clear_options,
65 SSL_clear_options, SSL_CTX_get_options, SSL_get_options,
66 SSL_get_secure_renegotiation_support \- manipulate SSL options
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/ssl.h>
71 \&
72 \& uint64_t SSL_CTX_set_options(SSL_CTX *ctx, uint64_t options);
73 \& uint64_t SSL_set_options(SSL *ssl, uint64_t options);
74 \&
75 \& uint64_t SSL_CTX_clear_options(SSL_CTX *ctx, uint64_t options);
76 \& uint64_t SSL_clear_options(SSL *ssl, uint64_t options);
77 \&
78 \& uint64_t SSL_CTX_get_options(const SSL_CTX *ctx);
79 \& uint64_t SSL_get_options(const SSL *ssl);
80 \&
81 \& long SSL_get_secure_renegotiation_support(SSL *ssl);
82 .Ve
83 .SH DESCRIPTION
84 .IX Header "DESCRIPTION"
85 \&\fBSSL_CTX_set_options()\fR adds the options set via bit-mask in \fBoptions\fR to \fBctx\fR.
86 \&\fBctx\fR \fBMUST NOT\fR be NULL.
87 Options already set before are not cleared!
88 .PP
89 \&\fBSSL_set_options()\fR adds the options set via bit-mask in \fBoptions\fR to \fBssl\fR.
90 Options already set before are not cleared!
91 .PP
92 \&\fBSSL_CTX_clear_options()\fR clears the options set via bit-mask in \fBoptions\fR
93 to \fBctx\fR.
94 .PP
95 \&\fBSSL_clear_options()\fR clears the options set via bit-mask in \fBoptions\fR to \fBssl\fR.
96 .PP
97 \&\fBSSL_CTX_get_options()\fR returns the options set for \fBctx\fR.
98 .PP
99 \&\fBSSL_get_options()\fR returns the options set for \fBssl\fR.
100 .PP
101 \&\fBSSL_get_secure_renegotiation_support()\fR indicates whether the peer supports
102 secure renegotiation.
103 Note, this is implemented via a macro.
104 .SH NOTES
105 .IX Header "NOTES"
106 The behaviour of the SSL library can be changed by setting several options.
107 The options are coded as bit-masks and can be combined by a bitwise \fBor\fR
108 operation (|).
109 .PP
110 \&\fBSSL_CTX_set_options()\fR and \fBSSL_set_options()\fR affect the (external)
111 protocol behaviour of the SSL library. The (internal) behaviour of
112 the API can be changed by using the similar
113 \&\fBSSL_CTX_set_mode\fR\|(3) and \fBSSL_set_mode()\fR functions.
114 .PP
115 During a handshake, the option settings of the SSL object are used. When
116 a new SSL object is created from a context using \fBSSL_new()\fR, the current
117 option setting is copied. Changes to \fBctx\fR do not affect already created
118 SSL objects. \fBSSL_clear()\fR does not affect the settings.
119 .PP
120 The following \fBbug workaround\fR options are available:
121 .IP SSL_OP_CRYPTOPRO_TLSEXT_BUG 4
122 .IX Item "SSL_OP_CRYPTOPRO_TLSEXT_BUG"
123 Add server-hello extension from the early version of cryptopro draft
124 when GOST ciphersuite is negotiated. Required for interoperability with CryptoPro
125 CSP 3.x.
126 .IP SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 4
127 .IX Item "SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS"
128 Disables a countermeasure against an SSL 3.0/TLS 1.0 protocol
129 vulnerability affecting CBC ciphers, which cannot be handled by some
130 broken SSL implementations. This option has no effect for connections
131 using other ciphers.
132 .IP SSL_OP_SAFARI_ECDHE_ECDSA_BUG 4
133 .IX Item "SSL_OP_SAFARI_ECDHE_ECDSA_BUG"
134 Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X.
135 OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.
136 .IP SSL_OP_TLSEXT_PADDING 4
137 .IX Item "SSL_OP_TLSEXT_PADDING"
138 Adds a padding extension to ensure the ClientHello size is never between
139 256 and 511 bytes in length. This is needed as a workaround for some
140 implementations.
141 .IP SSL_OP_ALL 4
142 .IX Item "SSL_OP_ALL"
143 All of the above bug workarounds.
144 .PP
145 It is usually safe to use \fBSSL_OP_ALL\fR to enable the bug workaround
146 options if compatibility with somewhat broken implementations is
147 desired.
148 .PP
149 The following \fBmodifying\fR options are available:
150 .IP SSL_OP_ALLOW_CLIENT_RENEGOTIATION 4
151 .IX Item "SSL_OP_ALLOW_CLIENT_RENEGOTIATION"
152 Client-initiated renegotiation is disabled by default. Use
153 this option to enable it.
154 .IP SSL_OP_ALLOW_NO_DHE_KEX 4
155 .IX Item "SSL_OP_ALLOW_NO_DHE_KEX"
156 In TLSv1.3 allow a non\-(ec)dhe based key exchange mode on resumption. This means
157 that there will be no forward secrecy for the resumed session.
158 .IP SSL_OP_PREFER_NO_DHE_KEX 4
159 .IX Item "SSL_OP_PREFER_NO_DHE_KEX"
160 In TLSv1.3, on resumption let the server prefer a non\-(ec)dhe based key
161 exchange mode over an (ec)dhe based one. Ignored without \fBSSL_OP_ALLOW_NO_DHE_KEX\fR
162 being set as well. Always ignored on the client.
163 .IP SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION 4
164 .IX Item "SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION"
165 Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
166 servers. See the \fBSECURE RENEGOTIATION\fR section for more details.
167 .IP SSL_OP_CIPHER_SERVER_PREFERENCE 4
168 .IX Item "SSL_OP_CIPHER_SERVER_PREFERENCE"
169 When choosing a cipher, use the server's preferences instead of the client
170 preferences. When not set, the SSL server will always follow the clients
171 preferences. When set, the SSL/TLS server will choose following its
172 own preferences.
173 .IP SSL_OP_CISCO_ANYCONNECT 4
174 .IX Item "SSL_OP_CISCO_ANYCONNECT"
175 Use Cisco's version identifier of DTLS_BAD_VER when establishing a DTLSv1
176 connection. Only available when using the deprecated \fBDTLSv1_client_method()\fR API.
177 .IP SSL_OP_CLEANSE_PLAINTEXT 4
178 .IX Item "SSL_OP_CLEANSE_PLAINTEXT"
179 By default TLS and QUIC SSL objects keep a copy of received plaintext
180 application data in a static buffer until it is overwritten by the
181 next portion of data. When enabling SSL_OP_CLEANSE_PLAINTEXT
182 deciphered application data is cleansed by calling \fBOPENSSL_cleanse\fR\|(3)
183 after passing data to the application. Data is also cleansed when
184 releasing the connection (e.g. \fBSSL_free\fR\|(3)).
185 .Sp
186 Since OpenSSL only cleanses internal buffers, the application is still
187 responsible for cleansing all other buffers. Most notably, this
188 applies to buffers passed to functions like \fBSSL_read\fR\|(3),
189 \&\fBSSL_peek\fR\|(3) but also like \fBSSL_write\fR\|(3).
190 .Sp
191 TLS connections do not buffer data to be sent in plaintext. QUIC stream
192 objects do buffer plaintext data to be sent and this option will also cause
193 that data to be cleansed when it is discarded.
194 .Sp
195 This option can be set differently on individual QUIC stream objects and
196 has no effect on QUIC connection objects (except where a default stream is
197 being used).
198 .IP SSL_OP_COOKIE_EXCHANGE 4
199 .IX Item "SSL_OP_COOKIE_EXCHANGE"
200 Turn on Cookie Exchange as described in RFC4347 Section 4.2.1. Only affects
201 DTLS connections.
202 .IP SSL_OP_DISABLE_TLSEXT_CA_NAMES 4
203 .IX Item "SSL_OP_DISABLE_TLSEXT_CA_NAMES"
204 Disable TLS Extension CA Names. You may want to disable it for security reasons
205 or for compatibility with some Windows TLS implementations crashing when this
206 extension is larger than 1024 bytes.
207 .IP SSL_OP_ENABLE_KTLS 4
208 .IX Item "SSL_OP_ENABLE_KTLS"
209 Enable the use of kernel TLS. In order to benefit from kernel TLS OpenSSL must
210 have been compiled with support for it, and it must be supported by the
211 negotiated ciphersuites and extensions. The specific ciphersuites and extensions
212 that are supported may vary by platform and kernel version.
213 .Sp
214 The kernel TLS data-path implements the record layer, and the encryption
215 algorithm. The kernel will utilize the best hardware
216 available for encryption. Using the kernel data-path should reduce the memory
217 footprint of OpenSSL because no buffering is required. Also, the throughput
218 should improve because data copy is avoided when user data is encrypted into
219 kernel memory instead of the usual encrypt then copy to kernel.
220 .Sp
221 Kernel TLS might not support all the features of OpenSSL. For instance,
222 renegotiation, and setting the maximum fragment size is not possible as of
223 Linux 4.20.
224 .Sp
225 Note that with kernel TLS enabled some cryptographic operations are performed
226 by the kernel directly and not via any available OpenSSL Providers. This might
227 be undesirable if, for example, the application requires all cryptographic
228 operations to be performed by the FIPS provider.
229 .IP SSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE 4
230 .IX Item "SSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE"
231 With this option, \fBsendfile()\fR will use the zerocopy mode, which gives a
232 performance boost when used with KTLS hardware offload. Note that invalid TLS
233 records might be transmitted if the file is changed while being sent. This
234 option has no effect if \fBSSL_OP_ENABLE_KTLS\fR is not enabled.
235 .Sp
236 This option only applies to Linux. KTLS sendfile on FreeBSD doesn't offer an
237 option to disable zerocopy and always runs in this mode.
238 .IP SSL_OP_ENABLE_MIDDLEBOX_COMPAT 4
239 .IX Item "SSL_OP_ENABLE_MIDDLEBOX_COMPAT"
240 If set then dummy Change Cipher Spec (CCS) messages are sent in TLSv1.3. This
241 has the effect of making TLSv1.3 look more like TLSv1.2 so that middleboxes that
242 do not understand TLSv1.3 will not drop the connection. Regardless of whether
243 this option is set or not CCS messages received from the peer will always be
244 ignored in TLSv1.3. This option is set by default. To switch it off use
245 \&\fBSSL_clear_options()\fR. A future version of OpenSSL may not set this by default.
246 .IP SSL_OP_IGNORE_UNEXPECTED_EOF 4
247 .IX Item "SSL_OP_IGNORE_UNEXPECTED_EOF"
248 Some TLS implementations do not send the mandatory close_notify alert on
249 shutdown. If the application tries to wait for the close_notify alert but the
250 peer closes the connection without sending it, an error is generated. When this
251 option is enabled the peer does not need to send the close_notify alert and a
252 closed connection will be treated as if the close_notify alert was received.
253 .Sp
254 You should only enable this option if the protocol running over TLS
255 can detect a truncation attack itself, and that the application is checking for
256 that truncation attack.
257 .Sp
258 For more information on shutting down a connection, see \fBSSL_shutdown\fR\|(3).
259 .IP SSL_OP_LEGACY_SERVER_CONNECT 4
260 .IX Item "SSL_OP_LEGACY_SERVER_CONNECT"
261 Allow legacy insecure renegotiation between OpenSSL and unpatched servers
262 \&\fBonly\fR. See the \fBSECURE RENEGOTIATION\fR section for more details.
263 .IP SSL_OP_NO_ANTI_REPLAY 4
264 .IX Item "SSL_OP_NO_ANTI_REPLAY"
265 By default, when a server is configured for early data (i.e., max_early_data > 0),
266 OpenSSL will switch on replay protection. See \fBSSL_read_early_data\fR\|(3) for a
267 description of the replay protection feature. Anti-replay measures are required
268 to comply with the TLSv1.3 specification. Some applications may be able to
269 mitigate the replay risks in other ways and in such cases the built in OpenSSL
270 functionality is not required. Those applications can turn this feature off by
271 setting this option. This is a server-side option only. It is ignored by
272 clients.
273 .IP SSL_OP_NO_TX_CERTIFICATE_COMPRESSION 4
274 .IX Item "SSL_OP_NO_TX_CERTIFICATE_COMPRESSION"
275 Normally clients and servers will transparently attempt to negotiate the
276 RFC8879 certificate compression option on TLSv1.3 connections.
277 .Sp
278 If this option is set, the certificate compression extension is ignored
279 upon receipt and compressed certificates will not be sent to the peer.
280 .IP SSL_OP_NO_RX_CERTIFICATE_COMPRESSION 4
281 .IX Item "SSL_OP_NO_RX_CERTIFICATE_COMPRESSION"
282 Normally clients and servers will transparently attempt to negotiate the
283 RFC8879 certificate compression option on TLSv1.3 connections.
284 .Sp
285 If this option is set, the certificate compression extension will not be sent
286 and compressed certificates will not be accepted from the peer.
287 .IP SSL_OP_NO_COMPRESSION 4
288 .IX Item "SSL_OP_NO_COMPRESSION"
289 Do not use TLS record compression even if it is supported. This option is set by
290 default. To switch it off use \fBSSL_clear_options()\fR. Note that TLS record
291 compression is not recommended and is not available at security level 2 or
292 above. From OpenSSL 3.2 the default security level is 2, so clearing this option
293 will have no effect without also changing the default security level. See
294 \&\fBSSL_CTX_set_security_level\fR\|(3).
295 .IP SSL_OP_NO_ENCRYPT_THEN_MAC 4
296 .IX Item "SSL_OP_NO_ENCRYPT_THEN_MAC"
297 Normally clients and servers will transparently attempt to negotiate the
298 RFC7366 Encrypt-then-MAC option on TLS and DTLS connection.
299 .Sp
300 If this option is set, Encrypt-then-MAC is disabled. Clients will not
301 propose, and servers will not accept the extension.
302 .IP SSL_OP_NO_EXTENDED_MASTER_SECRET 4
303 .IX Item "SSL_OP_NO_EXTENDED_MASTER_SECRET"
304 Normally clients and servers will transparently attempt to negotiate the
305 RFC7627 Extended Master Secret option on TLS and DTLS connection.
306 .Sp
307 If this option is set, Extended Master Secret is disabled. Clients will
308 not propose, and servers will not accept the extension.
309 .IP SSL_OP_NO_QUERY_MTU 4
310 .IX Item "SSL_OP_NO_QUERY_MTU"
311 Do not query the MTU. Only affects DTLS connections.
312 .IP SSL_OP_NO_RENEGOTIATION 4
313 .IX Item "SSL_OP_NO_RENEGOTIATION"
314 Disable all renegotiation in (D)TLSv1.2 and earlier. Do not send HelloRequest
315 messages, and ignore renegotiation requests via ClientHello.
316 .IP SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 4
317 .IX Item "SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION"
318 When performing renegotiation as a server, always start a new session
319 (i.e., session resumption requests are only accepted in the initial
320 handshake). This option is not needed for clients.
321 .IP "SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2" 4
322 .IX Item "SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1, SSL_OP_NO_TLSv1_2, SSL_OP_NO_TLSv1_3, SSL_OP_NO_DTLSv1, SSL_OP_NO_DTLSv1_2"
323 These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol
324 versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
325 respectively.
326 As of OpenSSL 1.1.0, these options are deprecated, use
327 \&\fBSSL_CTX_set_min_proto_version\fR\|(3) and
328 \&\fBSSL_CTX_set_max_proto_version\fR\|(3) instead.
329 .IP SSL_OP_NO_TICKET 4
330 .IX Item "SSL_OP_NO_TICKET"
331 SSL/TLS supports two mechanisms for resuming sessions: session ids and stateless
332 session tickets.
333 .Sp
334 When using session ids a copy of the session information is
335 cached on the server and a unique id is sent to the client. When the client
336 wishes to resume it provides the unique id so that the server can retrieve the
337 session information from its cache.
338 .Sp
339 When using stateless session tickets the server uses a session ticket encryption
340 key to encrypt the session information. This encrypted data is sent to the
341 client as a "ticket". When the client wishes to resume it sends the encrypted
342 data back to the server. The server uses its key to decrypt the data and resume
343 the session. In this way the server can operate statelessly \- no session
344 information needs to be cached locally.
345 .Sp
346 The TLSv1.3 protocol only supports tickets and does not directly support session
347 ids. However, OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
348 and stateless. Stateless tickets work the same way as in TLSv1.2 and below.
349 Stateful tickets mimic the session id behaviour available in TLSv1.2 and below.
350 The session information is cached on the server and the session id is wrapped up
351 in a ticket and sent back to the client. When the client wishes to resume, it
352 presents a ticket in the same way as for stateless tickets. The server can then
353 extract the session id from the ticket and retrieve the session information from
354 its cache.
355 .Sp
356 By default OpenSSL will use stateless tickets. The SSL_OP_NO_TICKET option will
357 cause stateless tickets to not be issued. In TLSv1.2 and below this means no
358 ticket gets sent to the client at all. In TLSv1.3 a stateful ticket will be
359 sent. This is a server-side option only.
360 .Sp
361 In TLSv1.3 it is possible to suppress all tickets (stateful and stateless) from
362 being sent by calling \fBSSL_CTX_set_num_tickets\fR\|(3) or
363 \&\fBSSL_set_num_tickets\fR\|(3).
364 .IP SSL_OP_PRIORITIZE_CHACHA 4
365 .IX Item "SSL_OP_PRIORITIZE_CHACHA"
366 When SSL_OP_CIPHER_SERVER_PREFERENCE is set, temporarily reprioritize
367 ChaCha20\-Poly1305 ciphers to the top of the server cipher list if a
368 ChaCha20\-Poly1305 cipher is at the top of the client cipher list. This helps
369 those clients (e.g. mobile) use ChaCha20\-Poly1305 if that cipher is anywhere
370 in the server cipher list; but still allows other clients to use AES and other
371 ciphers. Requires \fBSSL_OP_CIPHER_SERVER_PREFERENCE\fR.
372 .IP SSL_OP_TLS_ROLLBACK_BUG 4
373 .IX Item "SSL_OP_TLS_ROLLBACK_BUG"
374 Disable version rollback attack detection.
375 .Sp
376 During the client key exchange, the client must send the same information
377 about acceptable SSL/TLS protocol levels as during the first hello. Some
378 clients violate this rule by adapting to the server's answer. (Example:
379 the client sends an SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
380 only understands up to SSLv3. In this case the client must still use the
381 same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
382 to the server's answer and violate the version rollback protection.)
383 .PP
384 The following options no longer have any effect but their identifiers are
385 retained for compatibility purposes:
386 .IP SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 4
387 .IX Item "SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG"
388 .PD 0
389 .IP SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 4
390 .IX Item "SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER"
391 .IP SSL_OP_SSLEAY_080_CLIENT_DH_BUG 4
392 .IX Item "SSL_OP_SSLEAY_080_CLIENT_DH_BUG"
393 .IP SSL_OP_TLS_D5_BUG 4
394 .IX Item "SSL_OP_TLS_D5_BUG"
395 .IP SSL_OP_TLS_BLOCK_PADDING_BUG 4
396 .IX Item "SSL_OP_TLS_BLOCK_PADDING_BUG"
397 .IP SSL_OP_MSIE_SSLV2_RSA_PADDING 4
398 .IX Item "SSL_OP_MSIE_SSLV2_RSA_PADDING"
399 .IP SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 4
400 .IX Item "SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG"
401 .IP SSL_OP_MICROSOFT_SESS_ID_BUG 4
402 .IX Item "SSL_OP_MICROSOFT_SESS_ID_BUG"
403 .IP SSL_OP_NETSCAPE_CHALLENGE_BUG 4
404 .IX Item "SSL_OP_NETSCAPE_CHALLENGE_BUG"
405 .IP SSL_OP_PKCS1_CHECK_1 4
406 .IX Item "SSL_OP_PKCS1_CHECK_1"
407 .IP SSL_OP_PKCS1_CHECK_2 4
408 .IX Item "SSL_OP_PKCS1_CHECK_2"
409 .IP SSL_OP_SINGLE_DH_USE 4
410 .IX Item "SSL_OP_SINGLE_DH_USE"
411 .IP SSL_OP_SINGLE_ECDH_USE 4
412 .IX Item "SSL_OP_SINGLE_ECDH_USE"
413 .IP SSL_OP_EPHEMERAL_RSA 4
414 .IX Item "SSL_OP_EPHEMERAL_RSA"
415 .IP SSL_OP_NETSCAPE_CA_DN_BUG 4
416 .IX Item "SSL_OP_NETSCAPE_CA_DN_BUG"
417 .IP SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 4
418 .IX Item "SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG"
419 .PD
420 .SH "SECURE RENEGOTIATION"
421 .IX Header "SECURE RENEGOTIATION"
422 OpenSSL always attempts to use secure renegotiation as
423 described in RFC5746. This counters the prefix attack described in
424 CVE\-2009\-3555 and elsewhere.
425 .PP
426 This attack has far reaching consequences which application writers should be
427 aware of. In the description below an implementation supporting secure
428 renegotiation is referred to as \fIpatched\fR. A server not supporting secure
429 renegotiation is referred to as \fIunpatched\fR.
430 .PP
431 The following sections describe the operations permitted by OpenSSL's secure
432 renegotiation implementation.
433 .SS "Patched client and server"
434 .IX Subsection "Patched client and server"
435 Connections and renegotiation are always permitted by OpenSSL implementations.
436 .SS "Unpatched client and patched OpenSSL server"
437 .IX Subsection "Unpatched client and patched OpenSSL server"
438 The initial connection succeeds but client renegotiation is denied by the
439 server with a \fBno_renegotiation\fR warning alert if TLS v1.0 is used or a fatal
440 \&\fBhandshake_failure\fR alert in SSL v3.0.
441 .PP
442 If the patched OpenSSL server attempts to renegotiate a fatal
443 \&\fBhandshake_failure\fR alert is sent. This is because the server code may be
444 unaware of the unpatched nature of the client.
445 .PP
446 If the option \fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR is set then
447 renegotiation \fBalways\fR succeeds.
448 .SS "Patched OpenSSL client and unpatched server"
449 .IX Subsection "Patched OpenSSL client and unpatched server"
450 If the option \fBSSL_OP_LEGACY_SERVER_CONNECT\fR or
451 \&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR is set then initial connections
452 and renegotiation between patched OpenSSL clients and unpatched servers
453 succeeds. If neither option is set then initial connections to unpatched
454 servers will fail.
455 .PP
456 Setting the option \fBSSL_OP_LEGACY_SERVER_CONNECT\fR has security implications;
457 clients that are willing to connect to servers that do not implement
458 RFC 5746 secure renegotiation are subject to attacks such as
459 CVE\-2009\-3555.
460 .PP
461 OpenSSL client applications wishing to ensure they can connect to unpatched
462 servers should always \fBset\fR \fBSSL_OP_LEGACY_SERVER_CONNECT\fR
463 .PP
464 OpenSSL client applications that want to ensure they can \fBnot\fR connect to
465 unpatched servers (and thus avoid any security issues) should always \fBclear\fR
466 \&\fBSSL_OP_LEGACY_SERVER_CONNECT\fR using \fBSSL_CTX_clear_options()\fR or
467 \&\fBSSL_clear_options()\fR.
468 .PP
469 The difference between the \fBSSL_OP_LEGACY_SERVER_CONNECT\fR and
470 \&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR options is that
471 \&\fBSSL_OP_LEGACY_SERVER_CONNECT\fR enables initial connections and secure
472 renegotiation between OpenSSL clients and unpatched servers \fBonly\fR, while
473 \&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR allows initial connections
474 and renegotiation between OpenSSL and unpatched clients or servers.
475 .SS "Applicability of options to QUIC connections and streams"
476 .IX Subsection "Applicability of options to QUIC connections and streams"
477 These options apply to SSL objects referencing a QUIC connection:
478 .IP SSL_OP_ALLOW_NO_DHE_KEX 4
479 .IX Item "SSL_OP_ALLOW_NO_DHE_KEX"
480 .PD 0
481 .IP SSL_OP_NO_TX_CERTIFICATE_COMPRESSION 4
482 .IX Item "SSL_OP_NO_TX_CERTIFICATE_COMPRESSION"
483 .IP SSL_OP_NO_RX_CERTIFICATE_COMPRESSION 4
484 .IX Item "SSL_OP_NO_RX_CERTIFICATE_COMPRESSION"
485 .IP SSL_OP_NO_TICKET 4
486 .IX Item "SSL_OP_NO_TICKET"
487 .IP SSL_OP_PRIORITIZE_CHACHA 4
488 .IX Item "SSL_OP_PRIORITIZE_CHACHA"
489 .PD
490 .PP
491 These options apply to SSL objects referencing a QUIC stream:
492 .IP SSL_OP_CLEANSE_PLAINTEXT 4
493 .IX Item "SSL_OP_CLEANSE_PLAINTEXT"
494 .PP
495 Options on QUIC connections are initialized from the options set on SSL_CTX
496 before a QUIC connection SSL object is created. Options on QUIC streams are
497 initialised from the options configured on the QUIC connection SSL object
498 they are created from.
499 .PP
500 Setting options which relate to QUIC streams on a QUIC connection SSL object has
501 no direct effect on the QUIC connection SSL object itself, but will change the
502 options set on the default stream (if there is one) and will also determine the
503 default options set on any future streams which are created.
504 .PP
505 Other options not mentioned above do not have an effect and will be ignored.
506 .PP
507 Options which relate to QUIC streams may also be set directly on QUIC stream SSL
508 objects. Setting connection-related options on such an object has no effect.
509 .SH "RETURN VALUES"
510 .IX Header "RETURN VALUES"
511 \&\fBSSL_CTX_set_options()\fR and \fBSSL_set_options()\fR return the new options bit-mask
512 after adding \fBoptions\fR.
513 .PP
514 \&\fBSSL_CTX_clear_options()\fR and \fBSSL_clear_options()\fR return the new options bit-mask
515 after clearing \fBoptions\fR.
516 .PP
517 \&\fBSSL_CTX_get_options()\fR and \fBSSL_get_options()\fR return the current bit-mask.
518 .PP
519 \&\fBSSL_get_secure_renegotiation_support()\fR returns 1 is the peer supports
520 secure renegotiation and 0 if it does not.
521 .SH "SEE ALSO"
522 .IX Header "SEE ALSO"
523 \&\fBssl\fR\|(7), \fBSSL_new\fR\|(3), \fBSSL_clear\fR\|(3), \fBSSL_shutdown\fR\|(3)
524 \&\fBSSL_CTX_set_tmp_dh_callback\fR\|(3),
525 \&\fBSSL_CTX_set_min_proto_version\fR\|(3),
526 \&\fBopenssl\-dhparam\fR\|(1)
527 .SH HISTORY
528 .IX Header "HISTORY"
529 The attempt to always try to use secure renegotiation was added in
530 OpenSSL 0.9.8m.
531 .PP
532 The \fBSSL_OP_PRIORITIZE_CHACHA\fR and \fBSSL_OP_NO_RENEGOTIATION\fR options
533 were added in OpenSSL 1.1.1.
534 .PP
535 The \fBSSL_OP_NO_EXTENDED_MASTER_SECRET\fR and \fBSSL_OP_IGNORE_UNEXPECTED_EOF\fR
536 options were added in OpenSSL 3.0.
537 .PP
538 The \fBSSL_OP_\fR constants and the corresponding parameter and return values
539 of the affected functions were changed to \f(CW\*(C`uint64_t\*(C'\fR type in OpenSSL 3.0.
540 For that reason it is no longer possible use the \fBSSL_OP_\fR macro values
541 in preprocessor \f(CW\*(C`#if\*(C'\fR conditions. However it is still possible to test
542 whether these macros are defined or not.
543 .SH COPYRIGHT
544 .IX Header "COPYRIGHT"
545 Copyright 2001\-2025 The OpenSSL Project Authors. All Rights Reserved.
546 .PP
547 Licensed under the Apache License 2.0 (the "License"). You may not use
548 this file except in compliance with the License. You can obtain a copy
549 in the file LICENSE in the source distribution or at
550 <https://www.openssl.org/source/license.html>.