Debian Codegraph @

upstream/debian-unstable/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.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_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_SERVER_PREFERENCE 4
168 .IX Item "SSL_OP_SERVER_PREFERENCE"
169 When choosing a cipher, signature, (TLS 1.2) curve or (TLS 1.3) group, use the
170 server's preferences instead of the client preferences. When not set, the SSL
171 server will always follow the clients preferences. When set, the SSL/TLS server
172 will choose following its own preferences.
173 Use of the old but somewhat misleading name SSL_OP_CIPHER_SERVER_PREFERENCE
174 is still possible but discouraged.
175 .IP SSL_OP_CISCO_ANYCONNECT 4
176 .IX Item "SSL_OP_CISCO_ANYCONNECT"
177 Use Cisco's version identifier of DTLS_BAD_VER when establishing a DTLSv1
178 connection. Only available when using the deprecated \fBDTLSv1_client_method()\fR API.
179 .IP SSL_OP_CLEANSE_PLAINTEXT 4
180 .IX Item "SSL_OP_CLEANSE_PLAINTEXT"
181 By default TLS and QUIC SSL objects keep a copy of received plaintext
182 application data in a static buffer until it is overwritten by the
183 next portion of data. When enabling SSL_OP_CLEANSE_PLAINTEXT
184 deciphered application data is cleansed by calling \fBOPENSSL_cleanse\fR\|(3)
185 after passing data to the application. Data is also cleansed when
186 releasing the connection (e.g. \fBSSL_free\fR\|(3)).
187 .Sp
188 Since OpenSSL only cleanses internal buffers, the application is still
189 responsible for cleansing all other buffers. Most notably, this
190 applies to buffers passed to functions like \fBSSL_read\fR\|(3),
191 \&\fBSSL_peek\fR\|(3) but also like \fBSSL_write\fR\|(3).
192 .Sp
193 TLS connections do not buffer data to be sent in plaintext. QUIC stream
194 objects do buffer plaintext data to be sent and this option will also cause
195 that data to be cleansed when it is discarded.
196 .Sp
197 This option can be set differently on individual QUIC stream objects and
198 has no effect on QUIC connection objects (except where a default stream is
199 being used).
200 .IP SSL_OP_COOKIE_EXCHANGE 4
201 .IX Item "SSL_OP_COOKIE_EXCHANGE"
202 Turn on Cookie Exchange as described in RFC4347 Section 4.2.1. Only affects
203 DTLS connections.
204 .IP SSL_OP_DISABLE_TLSEXT_CA_NAMES 4
205 .IX Item "SSL_OP_DISABLE_TLSEXT_CA_NAMES"
206 Disable TLS Extension CA Names. You may want to disable it for security reasons
207 or for compatibility with some Windows TLS implementations crashing when this
208 extension is larger than 1024 bytes.
209 .IP SSL_OP_ENABLE_KTLS 4
210 .IX Item "SSL_OP_ENABLE_KTLS"
211 Enable the use of kernel TLS. In order to benefit from kernel TLS OpenSSL must
212 have been compiled with support for it, and it must be supported by the
213 negotiated ciphersuites and extensions. The specific ciphersuites and extensions
214 that are supported may vary by platform and kernel version.
215 .Sp
216 The kernel TLS data-path implements the record layer, and the encryption
217 algorithm. The kernel will utilize the best hardware
218 available for encryption. Using the kernel data-path should reduce the memory
219 footprint of OpenSSL because no buffering is required. Also, the throughput
220 should improve because data copy is avoided when user data is encrypted into
221 kernel memory instead of the usual encrypt then copy to kernel.
222 .Sp
223 Kernel TLS might not support all the features of OpenSSL. For instance,
224 renegotiation, and setting the maximum fragment size is not possible as of
225 Linux 4.20.
226 .Sp
227 Note that with kernel TLS enabled some cryptographic operations are performed
228 by the kernel directly and not via any available OpenSSL Providers. This might
229 be undesirable if, for example, the application requires all cryptographic
230 operations to be performed by the FIPS provider.
231 .IP SSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE 4
232 .IX Item "SSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE"
233 With this option, \fBsendfile()\fR will use the zerocopy mode, which gives a
234 performance boost when used with KTLS hardware offload. Note that invalid TLS
235 records might be transmitted if the file is changed while being sent. This
236 option has no effect if \fBSSL_OP_ENABLE_KTLS\fR is not enabled.
237 .Sp
238 This option only applies to Linux. KTLS sendfile on FreeBSD doesn't offer an
239 option to disable zerocopy and always runs in this mode.
240 .IP SSL_OP_ENABLE_MIDDLEBOX_COMPAT 4
241 .IX Item "SSL_OP_ENABLE_MIDDLEBOX_COMPAT"
242 If set then dummy Change Cipher Spec (CCS) messages are sent in TLSv1.3. This
243 has the effect of making TLSv1.3 look more like TLSv1.2 so that middleboxes that
244 do not understand TLSv1.3 will not drop the connection. Regardless of whether
245 this option is set or not CCS messages received from the peer will always be
246 ignored in TLSv1.3. This option is set by default. To switch it off use
247 \&\fBSSL_clear_options()\fR. A future version of OpenSSL may not set this by default.
248 .IP SSL_OP_IGNORE_UNEXPECTED_EOF 4
249 .IX Item "SSL_OP_IGNORE_UNEXPECTED_EOF"
250 Some TLS implementations do not send the mandatory close_notify alert on
251 shutdown. If the application tries to wait for the close_notify alert but the
252 peer closes the connection without sending it, an error is generated. When this
253 option is enabled the peer does not need to send the close_notify alert and a
254 closed connection will be treated as if the close_notify alert was received.
255 .Sp
256 You should only enable this option if the protocol running over TLS
257 can detect a truncation attack itself, and that the application is checking for
258 that truncation attack.
259 .Sp
260 For more information on shutting down a connection, see \fBSSL_shutdown\fR\|(3).
261 .IP SSL_OP_LEGACY_SERVER_CONNECT 4
262 .IX Item "SSL_OP_LEGACY_SERVER_CONNECT"
263 Allow legacy insecure renegotiation between OpenSSL and unpatched servers
264 \&\fBonly\fR. See the \fBSECURE RENEGOTIATION\fR section for more details.
265 .IP SSL_OP_LEGACY_EC_POINT_FORMATS 4
266 .IX Item "SSL_OP_LEGACY_EC_POINT_FORMATS"
267 Enable use of the legacy point formats for elliptic curves. This option enables
268 support for the deprecated ANSI X9.62 prime and char2 compressed point formats,
269 in addition to the uncompressed format that is enabled by default.
270 .IP SSL_OP_NO_ANTI_REPLAY 4
271 .IX Item "SSL_OP_NO_ANTI_REPLAY"
272 By default, when a server is configured for early data (i.e., max_early_data > 0),
273 OpenSSL will switch on replay protection. See \fBSSL_read_early_data\fR\|(3) for a
274 description of the replay protection feature. Anti-replay measures are required
275 to comply with the TLSv1.3 specification. Some applications may be able to
276 mitigate the replay risks in other ways and in such cases the built in OpenSSL
277 functionality is not required. Those applications can turn this feature off by
278 setting this option. This is a server-side option only. It is ignored by
279 clients.
280 .IP SSL_OP_NO_TX_CERTIFICATE_COMPRESSION 4
281 .IX Item "SSL_OP_NO_TX_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 is ignored
286 upon receipt and compressed certificates will not be sent to the peer.
287 .IP SSL_OP_NO_RX_CERTIFICATE_COMPRESSION 4
288 .IX Item "SSL_OP_NO_RX_CERTIFICATE_COMPRESSION"
289 Normally clients and servers will transparently attempt to negotiate the
290 RFC8879 certificate compression option on TLSv1.3 connections.
291 .Sp
292 If this option is set, the certificate compression extension will not be sent
293 and compressed certificates will not be accepted from the peer.
294 .IP SSL_OP_NO_COMPRESSION 4
295 .IX Item "SSL_OP_NO_COMPRESSION"
296 Do not use TLS record compression even if it is supported. This option is set by
297 default. To switch it off use \fBSSL_clear_options()\fR. Note that TLS record
298 compression is not recommended and is not available at security level 2 or
299 above. From OpenSSL 3.2 the default security level is 2, so clearing this option
300 will have no effect without also changing the default security level. See
301 \&\fBSSL_CTX_set_security_level\fR\|(3).
302 .IP SSL_OP_NO_ENCRYPT_THEN_MAC 4
303 .IX Item "SSL_OP_NO_ENCRYPT_THEN_MAC"
304 Normally clients and servers will transparently attempt to negotiate the
305 RFC7366 Encrypt-then-MAC option on TLS and DTLS connection.
306 .Sp
307 If this option is set, Encrypt-then-MAC is disabled. Clients will not
308 propose, and servers will not accept the extension.
309 .IP SSL_OP_NO_EXTENDED_MASTER_SECRET 4
310 .IX Item "SSL_OP_NO_EXTENDED_MASTER_SECRET"
311 Normally clients and servers will transparently attempt to negotiate the
312 RFC7627 Extended Master Secret option on TLS and DTLS connection.
313 .Sp
314 If this option is set, Extended Master Secret is disabled. Clients will
315 not propose, and servers will not accept the extension.
316 .IP SSL_OP_NO_QUERY_MTU 4
317 .IX Item "SSL_OP_NO_QUERY_MTU"
318 Do not query the MTU. Only affects DTLS connections.
319 .IP SSL_OP_NO_RENEGOTIATION 4
320 .IX Item "SSL_OP_NO_RENEGOTIATION"
321 Disable all renegotiation in (D)TLSv1.2 and earlier. Do not send HelloRequest
322 messages, and ignore renegotiation requests via ClientHello.
323 .IP SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION 4
324 .IX Item "SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION"
325 When performing renegotiation as a server, always start a new session
326 (i.e., session resumption requests are only accepted in the initial
327 handshake). This option is not needed for clients.
328 .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
329 .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"
330 These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol
331 versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
332 respectively.
333 As of OpenSSL 1.1.0, these options are deprecated, use
334 \&\fBSSL_CTX_set_min_proto_version\fR\|(3) and
335 \&\fBSSL_CTX_set_max_proto_version\fR\|(3) instead.
336 .IP SSL_OP_NO_TICKET 4
337 .IX Item "SSL_OP_NO_TICKET"
338 SSL/TLS supports two mechanisms for resuming sessions: session ids and stateless
339 session tickets.
340 .Sp
341 When using session ids a copy of the session information is
342 cached on the server and a unique id is sent to the client. When the client
343 wishes to resume it provides the unique id so that the server can retrieve the
344 session information from its cache.
345 .Sp
346 When using stateless session tickets the server uses a session ticket encryption
347 key to encrypt the session information. This encrypted data is sent to the
348 client as a "ticket". When the client wishes to resume it sends the encrypted
349 data back to the server. The server uses its key to decrypt the data and resume
350 the session. In this way the server can operate statelessly \- no session
351 information needs to be cached locally.
352 .Sp
353 The TLSv1.3 protocol only supports tickets and does not directly support session
354 ids. However, OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
355 and stateless. Stateless tickets work the same way as in TLSv1.2 and below.
356 Stateful tickets mimic the session id behaviour available in TLSv1.2 and below.
357 The session information is cached on the server and the session id is wrapped up
358 in a ticket and sent back to the client. When the client wishes to resume, it
359 presents a ticket in the same way as for stateless tickets. The server can then
360 extract the session id from the ticket and retrieve the session information from
361 its cache.
362 .Sp
363 By default OpenSSL will use stateless tickets. The SSL_OP_NO_TICKET option will
364 cause stateless tickets to not be issued. In TLSv1.2 and below this means no
365 ticket gets sent to the client at all. In TLSv1.3 a stateful ticket will be
366 sent. This is a server-side option only.
367 .Sp
368 In TLSv1.3 it is possible to suppress all tickets (stateful and stateless) from
369 being sent by calling \fBSSL_CTX_set_num_tickets\fR\|(3) or
370 \&\fBSSL_set_num_tickets\fR\|(3).
371 .IP SSL_OP_PRIORITIZE_CHACHA 4
372 .IX Item "SSL_OP_PRIORITIZE_CHACHA"
373 When SSL_OP_SERVER_PREFERENCE is set, temporarily reprioritize
374 ChaCha20\-Poly1305 ciphers to the top of the server cipher list if a
375 ChaCha20\-Poly1305 cipher is at the top of the client cipher list. This helps
376 those clients (e.g. mobile) use ChaCha20\-Poly1305 if that cipher is anywhere
377 in the server cipher list; but still allows other clients to use AES and other
378 ciphers. Requires \fBSSL_OP_SERVER_PREFERENCE\fR.
379 .IP SSL_OP_TLS_ROLLBACK_BUG 4
380 .IX Item "SSL_OP_TLS_ROLLBACK_BUG"
381 Disable version rollback attack detection.
382 .Sp
383 During the client key exchange, the client must send the same information
384 about acceptable SSL/TLS protocol levels as during the first hello. Some
385 clients violate this rule by adapting to the server's answer. (Example:
386 the client sends an SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
387 only understands up to SSLv3. In this case the client must still use the
388 same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
389 to the server's answer and violate the version rollback protection.)
390 .PP
391 The following options no longer have any effect but their identifiers are
392 retained for compatibility purposes:
393 .IP SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 4
394 .IX Item "SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG"
395 .PD 0
396 .IP SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 4
397 .IX Item "SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER"
398 .IP SSL_OP_SSLEAY_080_CLIENT_DH_BUG 4
399 .IX Item "SSL_OP_SSLEAY_080_CLIENT_DH_BUG"
400 .IP SSL_OP_TLS_D5_BUG 4
401 .IX Item "SSL_OP_TLS_D5_BUG"
402 .IP SSL_OP_TLS_BLOCK_PADDING_BUG 4
403 .IX Item "SSL_OP_TLS_BLOCK_PADDING_BUG"
404 .IP SSL_OP_MSIE_SSLV2_RSA_PADDING 4
405 .IX Item "SSL_OP_MSIE_SSLV2_RSA_PADDING"
406 .IP SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 4
407 .IX Item "SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG"
408 .IP SSL_OP_MICROSOFT_SESS_ID_BUG 4
409 .IX Item "SSL_OP_MICROSOFT_SESS_ID_BUG"
410 .IP SSL_OP_NETSCAPE_CHALLENGE_BUG 4
411 .IX Item "SSL_OP_NETSCAPE_CHALLENGE_BUG"
412 .IP SSL_OP_PKCS1_CHECK_1 4
413 .IX Item "SSL_OP_PKCS1_CHECK_1"
414 .IP SSL_OP_PKCS1_CHECK_2 4
415 .IX Item "SSL_OP_PKCS1_CHECK_2"
416 .IP SSL_OP_SINGLE_DH_USE 4
417 .IX Item "SSL_OP_SINGLE_DH_USE"
418 .IP SSL_OP_SINGLE_ECDH_USE 4
419 .IX Item "SSL_OP_SINGLE_ECDH_USE"
420 .IP SSL_OP_EPHEMERAL_RSA 4
421 .IX Item "SSL_OP_EPHEMERAL_RSA"
422 .IP SSL_OP_NETSCAPE_CA_DN_BUG 4
423 .IX Item "SSL_OP_NETSCAPE_CA_DN_BUG"
424 .IP SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 4
425 .IX Item "SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG"
426 .PD
427 .SH "SECURE RENEGOTIATION"
428 .IX Header "SECURE RENEGOTIATION"
429 OpenSSL always attempts to use secure renegotiation as
430 described in RFC5746. This counters the prefix attack described in
431 CVE\-2009\-3555 and elsewhere.
432 .PP
433 This attack has far reaching consequences which application writers should be
434 aware of. In the description below an implementation supporting secure
435 renegotiation is referred to as \fIpatched\fR. A server not supporting secure
436 renegotiation is referred to as \fIunpatched\fR.
437 .PP
438 The following sections describe the operations permitted by OpenSSL's secure
439 renegotiation implementation.
440 .SS "Patched client and server"
441 .IX Subsection "Patched client and server"
442 Connections and renegotiation are always permitted by OpenSSL implementations.
443 .SS "Unpatched client and patched OpenSSL server"
444 .IX Subsection "Unpatched client and patched OpenSSL server"
445 The initial connection succeeds but client renegotiation is denied by the
446 server with a \fBno_renegotiation\fR warning alert if TLS v1.0 is used or a fatal
447 \&\fBhandshake_failure\fR alert in SSL v3.0.
448 .PP
449 If the patched OpenSSL server attempts to renegotiate a fatal
450 \&\fBhandshake_failure\fR alert is sent. This is because the server code may be
451 unaware of the unpatched nature of the client.
452 .PP
453 If the option \fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR is set then
454 renegotiation \fBalways\fR succeeds.
455 .SS "Patched OpenSSL client and unpatched server"
456 .IX Subsection "Patched OpenSSL client and unpatched server"
457 If the option \fBSSL_OP_LEGACY_SERVER_CONNECT\fR or
458 \&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR is set then initial connections
459 and renegotiation between patched OpenSSL clients and unpatched servers
460 succeeds. If neither option is set then initial connections to unpatched
461 servers will fail.
462 .PP
463 Setting the option \fBSSL_OP_LEGACY_SERVER_CONNECT\fR has security implications;
464 clients that are willing to connect to servers that do not implement
465 RFC 5746 secure renegotiation are subject to attacks such as
466 CVE\-2009\-3555.
467 .PP
468 OpenSSL client applications wishing to ensure they can connect to unpatched
469 servers should always \fBset\fR \fBSSL_OP_LEGACY_SERVER_CONNECT\fR
470 .PP
471 OpenSSL client applications that want to ensure they can \fBnot\fR connect to
472 unpatched servers (and thus avoid any security issues) should always \fBclear\fR
473 \&\fBSSL_OP_LEGACY_SERVER_CONNECT\fR using \fBSSL_CTX_clear_options()\fR or
474 \&\fBSSL_clear_options()\fR.
475 .PP
476 The difference between the \fBSSL_OP_LEGACY_SERVER_CONNECT\fR and
477 \&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR options is that
478 \&\fBSSL_OP_LEGACY_SERVER_CONNECT\fR enables initial connections and secure
479 renegotiation between OpenSSL clients and unpatched servers \fBonly\fR, while
480 \&\fBSSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION\fR allows initial connections
481 and renegotiation between OpenSSL and unpatched clients or servers.
482 .SS "Applicability of options to QUIC connections and streams"
483 .IX Subsection "Applicability of options to QUIC connections and streams"
484 These options apply to SSL objects referencing a QUIC connection:
485 .IP SSL_OP_ALLOW_NO_DHE_KEX 4
486 .IX Item "SSL_OP_ALLOW_NO_DHE_KEX"
487 .PD 0
488 .IP SSL_OP_NO_TX_CERTIFICATE_COMPRESSION 4
489 .IX Item "SSL_OP_NO_TX_CERTIFICATE_COMPRESSION"
490 .IP SSL_OP_NO_RX_CERTIFICATE_COMPRESSION 4
491 .IX Item "SSL_OP_NO_RX_CERTIFICATE_COMPRESSION"
492 .IP SSL_OP_NO_TICKET 4
493 .IX Item "SSL_OP_NO_TICKET"
494 .IP SSL_OP_PRIORITIZE_CHACHA 4
495 .IX Item "SSL_OP_PRIORITIZE_CHACHA"
496 .PD
497 .PP
498 These options apply to SSL objects referencing a QUIC stream:
499 .IP SSL_OP_CLEANSE_PLAINTEXT 4
500 .IX Item "SSL_OP_CLEANSE_PLAINTEXT"
501 .PP
502 Options on QUIC connections are initialized from the options set on SSL_CTX
503 before a QUIC connection SSL object is created. Options on QUIC streams are
504 initialised from the options configured on the QUIC connection SSL object
505 they are created from.
506 .PP
507 Setting options which relate to QUIC streams on a QUIC connection SSL object has
508 no direct effect on the QUIC connection SSL object itself, but will change the
509 options set on the default stream (if there is one) and will also determine the
510 default options set on any future streams which are created.
511 .PP
512 Other options not mentioned above do not have an effect and will be ignored.
513 .PP
514 Options which relate to QUIC streams may also be set directly on QUIC stream SSL
515 objects. Setting connection-related options on such an object has no effect.
516 .SH "RETURN VALUES"
517 .IX Header "RETURN VALUES"
518 \&\fBSSL_CTX_set_options()\fR and \fBSSL_set_options()\fR return the new options bit-mask
519 after adding \fBoptions\fR.
520 .PP
521 \&\fBSSL_CTX_clear_options()\fR and \fBSSL_clear_options()\fR return the new options bit-mask
522 after clearing \fBoptions\fR.
523 .PP
524 \&\fBSSL_CTX_get_options()\fR and \fBSSL_get_options()\fR return the current bit-mask.
525 .PP
526 \&\fBSSL_get_secure_renegotiation_support()\fR returns 1 is the peer supports
527 secure renegotiation and 0 if it does not.
528 .SH "SEE ALSO"
529 .IX Header "SEE ALSO"
530 \&\fBssl\fR\|(7), \fBSSL_new\fR\|(3), \fBSSL_clear\fR\|(3), \fBSSL_shutdown\fR\|(3)
531 \&\fBSSL_CTX_set_tmp_dh_callback\fR\|(3),
532 \&\fBSSL_CTX_set_min_proto_version\fR\|(3),
533 \&\fBopenssl\-dhparam\fR\|(1)
534 .SH HISTORY
535 .IX Header "HISTORY"
536 The attempt to always try to use secure renegotiation was added in
537 OpenSSL 0.9.8m.
538 .PP
539 The \fBSSL_OP_PRIORITIZE_CHACHA\fR and \fBSSL_OP_NO_RENEGOTIATION\fR options
540 were added in OpenSSL 1.1.1.
541 .PP
542 The \fBSSL_OP_NO_EXTENDED_MASTER_SECRET\fR and \fBSSL_OP_IGNORE_UNEXPECTED_EOF\fR
543 options were added in OpenSSL 3.0.
544 .PP
545 The \fBSSL_OP_\fR constants and the corresponding parameter and return values
546 of the affected functions were changed to \f(CW\*(C`uint64_t\*(C'\fR type in OpenSSL 3.0.
547 For that reason it is no longer possible use the \fBSSL_OP_\fR macro values
548 in preprocessor \f(CW\*(C`#if\*(C'\fR conditions. However it is still possible to test
549 whether these macros are defined or not.
550 .PP
551 As of OpenSSL 3.6, use of the \fBSSL_OP_CIPHER_SERVER_PREFERENCE\fR constant
552 is discouraged and its semantics became available using the more aptly named
553 \&\fBSSL_OP_SERVER_PREFERENCE\fR constant.
554 .SH COPYRIGHT
555 .IX Header "COPYRIGHT"
556 Copyright 2001\-2025 The OpenSSL Project Authors. All Rights Reserved.
557 .PP
558 Licensed under the Apache License 2.0 (the "License"). You may not use
559 this file except in compliance with the License. You can obtain a copy
560 in the file LICENSE in the source distribution or at
561 <https://www.openssl.org/source/license.html>.