#include <openssl/ssl.h>
- long SSL_CTX_set_options(SSL_CTX *ctx, long options);
- long SSL_set_options(SSL *ssl, long options);
+ uint64_t SSL_CTX_set_options(SSL_CTX *ctx, uint64_t options);
+ uint64_t SSL_set_options(SSL *ssl, uint64_t options);
- long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
- long SSL_clear_options(SSL *ssl, long options);
+ uint64_t SSL_CTX_clear_options(SSL_CTX *ctx, uint64_t options);
+ uint64_t SSL_clear_options(SSL *ssl, uint64_t options);
- long SSL_CTX_get_options(SSL_CTX *ctx);
- long SSL_get_options(SSL *ssl);
+ uint64_t SSL_CTX_get_options(const SSL_CTX *ctx);
+ uint64_t SSL_get_options(const SSL *ssl);
long SSL_get_secure_renegotiation_support(SSL *ssl);
=head1 DESCRIPTION
-SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
+SSL_CTX_set_options() adds the options set via bit-mask in B<options> to B<ctx>.
Options already set before are not cleared!
-SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
+SSL_set_options() adds the options set via bit-mask in B<options> to B<ssl>.
Options already set before are not cleared!
-SSL_CTX_clear_options() clears the options set via bitmask in B<options>
+SSL_CTX_clear_options() clears the options set via bit-mask in B<options>
to B<ctx>.
-SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>.
+SSL_clear_options() clears the options set via bit-mask in B<options> to B<ssl>.
SSL_CTX_get_options() returns the options set for B<ctx>.
=head1 NOTES
The behaviour of the SSL library can be changed by setting several options.
-The options are coded as bitmasks and can be combined by a bitwise B<or>
+The options are coded as bit-masks and can be combined by a bitwise B<or>
operation (|).
SSL_CTX_set_options() and SSL_set_options() affect the (external)
=over 4
-=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG
+=item SSL_OP_CRYPTOPRO_TLSEXT_BUG
-Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X.
-OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.
+Add server-hello extension from the early version of cryptopro draft
+when GOST ciphersuite is negotiated. Required for interoperability with CryptoPro
+CSP 3.x.
=item SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
broken SSL implementations. This option has no effect for connections
using other ciphers.
+=item SSL_OP_SAFARI_ECDHE_ECDSA_BUG
+
+Don't prefer ECDHE-ECDSA ciphers when the client appears to be Safari on OS X.
+OS X 10.8..10.8.3 has broken support for ECDHE-ECDSA ciphers.
+
=item SSL_OP_TLSEXT_PADDING
Adds a padding extension to ensure the ClientHello size is never between
=item SSL_OP_ALL
-All of the above bug workarounds plus B<SSL_OP_LEGACY_SERVER_CONNECT> as
-mentioned below.
+All of the above bug workarounds.
=back
=over 4
-=item SSL_OP_TLS_ROLLBACK_BUG
+=item SSL_OP_ALLOW_CLIENT_RENEGOTIATION
-Disable version rollback attack detection.
+Client-initiated renegotiation is disabled by default. Use
+this option to enable it.
-During the client key exchange, the client must send the same information
-about acceptable SSL/TLS protocol levels as during the first hello. Some
-clients violate this rule by adapting to the server's answer. (Example:
-the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
-only understands up to SSLv3. In this case the client must still use the
-same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
-to the server's answer and violate the version rollback protection.)
+=item SSL_OP_ALLOW_NO_DHE_KEX
+
+In TLSv1.3 allow a non-(ec)dhe based key exchange mode on resumption. This means
+that there will be no forward secrecy for the resumed session.
+
+=item SSL_OP_PREFER_NO_DHE_KEX
+
+In TLSv1.3, on resumption let the server prefer a non-(ec)dhe based key
+exchange mode over an (ec)dhe based one. Ignored without B<SSL_OP_ALLOW_NO_DHE_KEX>
+being set as well. Always ignored on the client.
+
+=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
+
+Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
+servers. See the B<SECURE RENEGOTIATION> section for more details.
=item SSL_OP_CIPHER_SERVER_PREFERENCE
preferences. When set, the SSL/TLS server will choose following its
own preferences.
-=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
-
-These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol
-versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
-respectively.
-As of OpenSSL 1.1.0, these options are deprecated, use
-L<SSL_CTX_set_min_proto_version(3)> and
-L<SSL_CTX_set_max_proto_version(3)> instead.
+=item SSL_OP_CISCO_ANYCONNECT
-=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
+Use Cisco's version identifier of DTLS_BAD_VER when establishing a DTLSv1
+connection. Only available when using the deprecated DTLSv1_client_method() API.
-When performing renegotiation as a server, always start a new session
-(i.e., session resumption requests are only accepted in the initial
-handshake). This option is not needed for clients.
+=item SSL_OP_CLEANSE_PLAINTEXT
-=item SSL_OP_NO_COMPRESSION
+By default TLS and QUIC SSL objects keep a copy of received plaintext
+application data in a static buffer until it is overwritten by the
+next portion of data. When enabling SSL_OP_CLEANSE_PLAINTEXT
+deciphered application data is cleansed by calling OPENSSL_cleanse(3)
+after passing data to the application. Data is also cleansed when
+releasing the connection (e.g. L<SSL_free(3)>).
-Do not use compression even if it is supported.
+Since OpenSSL only cleanses internal buffers, the application is still
+responsible for cleansing all other buffers. Most notably, this
+applies to buffers passed to functions like L<SSL_read(3)>,
+L<SSL_peek(3)> but also like L<SSL_write(3)>.
-=item SSL_OP_NO_QUERY_MTU
+TLS connections do not buffer data to be sent in plaintext. QUIC stream
+objects do buffer plaintext data to be sent and this option will also cause
+that data to be cleansed when it is discarded.
-Do not query the MTU. Only affects DTLS connections.
+This option can be set differently on individual QUIC stream objects and
+has no effect on QUIC connection objects (except where a default stream is
+being used).
=item SSL_OP_COOKIE_EXCHANGE
Turn on Cookie Exchange as described in RFC4347 Section 4.2.1. Only affects
DTLS connections.
-=item SSL_OP_NO_TICKET
+=item SSL_OP_DISABLE_TLSEXT_CA_NAMES
-Normally clients and servers will, where possible, transparently make use
-of RFC4507bis tickets for stateless session resumption.
+Disable TLS Extension CA Names. You may want to disable it for security reasons
+or for compatibility with some Windows TLS implementations crashing when this
+extension is larger than 1024 bytes.
-If this option is set this functionality is disabled and tickets will
-not be used by clients or servers.
+=item SSL_OP_ENABLE_KTLS
-=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
+Enable the use of kernel TLS. In order to benefit from kernel TLS OpenSSL must
+have been compiled with support for it, and it must be supported by the
+negotiated ciphersuites and extensions. The specific ciphersuites and extensions
+that are supported may vary by platform and kernel version.
-Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
-servers. See the B<SECURE RENEGOTIATION> section for more details.
+The kernel TLS data-path implements the record layer, and the encryption
+algorithm. The kernel will utilize the best hardware
+available for encryption. Using the kernel data-path should reduce the memory
+footprint of OpenSSL because no buffering is required. Also, the throughput
+should improve because data copy is avoided when user data is encrypted into
+kernel memory instead of the usual encrypt then copy to kernel.
+
+Kernel TLS might not support all the features of OpenSSL. For instance,
+renegotiation, and setting the maximum fragment size is not possible as of
+Linux 4.20.
+
+Note that with kernel TLS enabled some cryptographic operations are performed
+by the kernel directly and not via any available OpenSSL Providers. This might
+be undesirable if, for example, the application requires all cryptographic
+operations to be performed by the FIPS provider.
+
+=item SSL_OP_ENABLE_KTLS_TX_ZEROCOPY_SENDFILE
+
+With this option, sendfile() will use the zerocopy mode, which gives a
+performance boost when used with KTLS hardware offload. Note that invalid TLS
+records might be transmitted if the file is changed while being sent. This
+option has no effect if B<SSL_OP_ENABLE_KTLS> is not enabled.
+
+This option only applies to Linux. KTLS sendfile on FreeBSD doesn't offer an
+option to disable zerocopy and always runs in this mode.
+
+=item SSL_OP_ENABLE_MIDDLEBOX_COMPAT
+
+If set then dummy Change Cipher Spec (CCS) messages are sent in TLSv1.3. This
+has the effect of making TLSv1.3 look more like TLSv1.2 so that middleboxes that
+do not understand TLSv1.3 will not drop the connection. Regardless of whether
+this option is set or not CCS messages received from the peer will always be
+ignored in TLSv1.3. This option is set by default. To switch it off use
+SSL_clear_options(). A future version of OpenSSL may not set this by default.
+
+=item SSL_OP_IGNORE_UNEXPECTED_EOF
+
+Some TLS implementations do not send the mandatory close_notify alert on
+shutdown. If the application tries to wait for the close_notify alert but the
+peer closes the connection without sending it, an error is generated. When this
+option is enabled the peer does not need to send the close_notify alert and a
+closed connection will be treated as if the close_notify alert was received.
+
+You should only enable this option if the protocol running over TLS
+can detect a truncation attack itself, and that the application is checking for
+that truncation attack.
+
+For more information on shutting down a connection, see L<SSL_shutdown(3)>.
=item SSL_OP_LEGACY_SERVER_CONNECT
Allow legacy insecure renegotiation between OpenSSL and unpatched servers
-B<only>: this option is currently set by default. See the
-B<SECURE RENEGOTIATION> section for more details.
+B<only>. See the B<SECURE RENEGOTIATION> section for more details.
+
+=item SSL_OP_NO_ANTI_REPLAY
+
+By default, when a server is configured for early data (i.e., max_early_data > 0),
+OpenSSL will switch on replay protection. See L<SSL_read_early_data(3)> for a
+description of the replay protection feature. Anti-replay measures are required
+to comply with the TLSv1.3 specification. Some applications may be able to
+mitigate the replay risks in other ways and in such cases the built in OpenSSL
+functionality is not required. Those applications can turn this feature off by
+setting this option. This is a server-side option only. It is ignored by
+clients.
+
+=item SSL_OP_NO_TX_CERTIFICATE_COMPRESSION
+
+Normally clients and servers will transparently attempt to negotiate the
+RFC8879 certificate compression option on TLSv1.3 connections.
+
+If this option is set, the certificate compression extension is ignored
+upon receipt and compressed certificates will not be sent to the peer.
+
+=item SSL_OP_NO_RX_CERTIFICATE_COMPRESSION
+
+Normally clients and servers will transparently attempt to negotiate the
+RFC8879 certificate compression option on TLSv1.3 connections.
+
+If this option is set, the certificate compression extension will not be sent
+and compressed certificates will not be accepted from the peer.
+
+=item SSL_OP_NO_COMPRESSION
+
+Do not use TLS record compression even if it is supported. This option is set by
+default. To switch it off use SSL_clear_options(). Note that TLS record
+compression is not recommended and is not available at security level 2 or
+above. From OpenSSL 3.2 the default security level is 2, so clearing this option
+will have no effect without also changing the default security level. See
+L<SSL_CTX_set_security_level(3)>.
=item SSL_OP_NO_ENCRYPT_THEN_MAC
If this option is set, Encrypt-then-MAC is disabled. Clients will not
propose, and servers will not accept the extension.
+=item SSL_OP_NO_EXTENDED_MASTER_SECRET
+
+Normally clients and servers will transparently attempt to negotiate the
+RFC7627 Extended Master Secret option on TLS and DTLS connection.
+
+If this option is set, Extended Master Secret is disabled. Clients will
+not propose, and servers will not accept the extension.
+
+=item SSL_OP_NO_QUERY_MTU
+
+Do not query the MTU. Only affects DTLS connections.
+
=item SSL_OP_NO_RENEGOTIATION
Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest
messages, and ignore renegotiation requests via ClientHello.
+=item SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
+
+When performing renegotiation as a server, always start a new session
+(i.e., session resumption requests are only accepted in the initial
+handshake). This option is not needed for clients.
+
+=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
+
+These options turn off the SSLv3, TLSv1, TLSv1.1, TLSv1.2 or TLSv1.3 protocol
+versions with TLS or the DTLSv1, DTLSv1.2 versions with DTLS,
+respectively.
+As of OpenSSL 1.1.0, these options are deprecated, use
+L<SSL_CTX_set_min_proto_version(3)> and
+L<SSL_CTX_set_max_proto_version(3)> instead.
+
+=item SSL_OP_NO_TICKET
+
+SSL/TLS supports two mechanisms for resuming sessions: session ids and stateless
+session tickets.
+
+When using session ids a copy of the session information is
+cached on the server and a unique id is sent to the client. When the client
+wishes to resume it provides the unique id so that the server can retrieve the
+session information from its cache.
+
+When using stateless session tickets the server uses a session ticket encryption
+key to encrypt the session information. This encrypted data is sent to the
+client as a "ticket". When the client wishes to resume it sends the encrypted
+data back to the server. The server uses its key to decrypt the data and resume
+the session. In this way the server can operate statelessly - no session
+information needs to be cached locally.
+
+The TLSv1.3 protocol only supports tickets and does not directly support session
+ids. However, OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
+and stateless. Stateless tickets work the same way as in TLSv1.2 and below.
+Stateful tickets mimic the session id behaviour available in TLSv1.2 and below.
+The session information is cached on the server and the session id is wrapped up
+in a ticket and sent back to the client. When the client wishes to resume, it
+presents a ticket in the same way as for stateless tickets. The server can then
+extract the session id from the ticket and retrieve the session information from
+its cache.
+
+By default OpenSSL will use stateless tickets. The SSL_OP_NO_TICKET option will
+cause stateless tickets to not be issued. In TLSv1.2 and below this means no
+ticket gets sent to the client at all. In TLSv1.3 a stateful ticket will be
+sent. This is a server-side option only.
+
+In TLSv1.3 it is possible to suppress all tickets (stateful and stateless) from
+being sent by calling L<SSL_CTX_set_num_tickets(3)> or
+L<SSL_set_num_tickets(3)>.
+
+=item SSL_OP_PRIORITIZE_CHACHA
+
+When SSL_OP_CIPHER_SERVER_PREFERENCE is set, temporarily reprioritize
+ChaCha20-Poly1305 ciphers to the top of the server cipher list if a
+ChaCha20-Poly1305 cipher is at the top of the client cipher list. This helps
+those clients (e.g. mobile) use ChaCha20-Poly1305 if that cipher is anywhere
+in the server cipher list; but still allows other clients to use AES and other
+ciphers. Requires B<SSL_OP_CIPHER_SERVER_PREFERENCE>.
+
+=item SSL_OP_TLS_ROLLBACK_BUG
+
+Disable version rollback attack detection.
+
+During the client key exchange, the client must send the same information
+about acceptable SSL/TLS protocol levels as during the first hello. Some
+clients violate this rule by adapting to the server's answer. (Example:
+the client sends a SSLv2 hello and accepts up to SSLv3.1=TLSv1, the server
+only understands up to SSLv3. In this case the client must still use the
+same SSLv3.1=TLSv1 announcement. Some clients step down to SSLv3 with respect
+to the server's answer and violate the version rollback protection.)
+
=back
The following options no longer have any effect but their identifiers are
=item SSL_OP_EPHEMERAL_RSA
+=item SSL_OP_NETSCAPE_CA_DN_BUG
+
+=item SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
+
=back
=head1 SECURE RENEGOTIATION
If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
renegotiation B<always> succeeds.
-=head2 Patched OpenSSL client and unpatched server.
+=head2 Patched OpenSSL client and unpatched server
If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections
succeeds. If neither option is set then initial connections to unpatched
servers will fail.
-The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even
-though it has security implications: otherwise it would be impossible to
-connect to unpatched servers (i.e. all of them initially) and this is clearly
-not acceptable. Renegotiation is permitted because this does not add any
-additional security issues: during an attack clients do not see any
-renegotiations anyway.
-
-As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will
-B<not> be set by default in a future version of OpenSSL.
+Setting the option B<SSL_OP_LEGACY_SERVER_CONNECT> has security implications;
+clients that are willing to connect to servers that do not implement
+RFC 5746 secure renegotiation are subject to attacks such as
+CVE-2009-3555.
OpenSSL client applications wishing to ensure they can connect to unpatched
servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT>
B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections
and renegotiation between OpenSSL and unpatched clients or servers.
+=head2 Applicability of options to QUIC connections and streams
+
+These options apply to SSL objects referencing a QUIC connection:
+
+=over 4
+
+=item SSL_OP_ALLOW_NO_DHE_KEX
+
+=item SSL_OP_NO_TX_CERTIFICATE_COMPRESSION
+
+=item SSL_OP_NO_RX_CERTIFICATE_COMPRESSION
+
+=item SSL_OP_NO_TICKET
+
+=item SSL_OP_PRIORITIZE_CHACHA
+
+=back
+
+These options apply to SSL objects referencing a QUIC stream:
+
+=over 4
+
+=item SSL_OP_CLEANSE_PLAINTEXT
+
+=back
+
+Options on QUIC connections are initialized from the options set on SSL_CTX
+before a QUIC connection SSL object is created. Options on QUIC streams are
+initialised from the options configured on the QUIC connection SSL object
+they are created from.
+
+Setting options which relate to QUIC streams on a QUIC connection SSL object has
+no direct effect on the QUIC connection SSL object itself, but will change the
+options set on the default stream (if there is one) and will also determine the
+default options set on any future streams which are created.
+
+Other options not mentioned above do not have an effect and will be ignored.
+
+Options which relate to QUIC streams may also be set directly on QUIC stream SSL
+objects. Setting connection-related options on such an object has no effect.
+
=head1 RETURN VALUES
-SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
+SSL_CTX_set_options() and SSL_set_options() return the new options bit-mask
after adding B<options>.
-SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask
+SSL_CTX_clear_options() and SSL_clear_options() return the new options bit-mask
after clearing B<options>.
-SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
+SSL_CTX_get_options() and SSL_get_options() return the current bit-mask.
SSL_get_secure_renegotiation_support() returns 1 is the peer supports
secure renegotiation and 0 if it does not.
=head1 SEE ALSO
-L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>,
+L<ssl(7)>, L<SSL_new(3)>, L<SSL_clear(3)>, L<SSL_shutdown(3)>
L<SSL_CTX_set_tmp_dh_callback(3)>,
L<SSL_CTX_set_min_proto_version(3)>,
-L<dhparam(1)>
+L<openssl-dhparam(1)>
=head1 HISTORY
The attempt to always try to use secure renegotiation was added in
-Openssl 0.9.8m.
+OpenSSL 0.9.8m.
+
+The B<SSL_OP_PRIORITIZE_CHACHA> and B<SSL_OP_NO_RENEGOTIATION> options
+were added in OpenSSL 1.1.1.
+
+The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> and B<SSL_OP_IGNORE_UNEXPECTED_EOF>
+options were added in OpenSSL 3.0.
+
+The B<SSL_OP_> constants and the corresponding parameter and return values
+of the affected functions were changed to C<uint64_t> type in OpenSSL 3.0.
+For that reason it is no longer possible use the B<SSL_OP_> macro values
+in preprocessor C<#if> conditions. However it is still possible to test
+whether these macros are defined or not.
=head1 COPYRIGHT
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2023 The OpenSSL Project Authors. All Rights Reserved.
-Licensed under the OpenSSL license (the "License"). You may not use
+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
L<https://www.openssl.org/source/license.html>.
projects / openssl.git / blobdiff