OpenSSLWiki - User contributions [en]

TLS1.3

2018-10-07T16:47:40Z

Kurt: /* Non-application data records */

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

The TLSv1.3 standard has now been published as [[https://tools.ietf.org/html/rfc8446 RFC 8446]]. During the development of the standard the TLS Working Group published various draft versions. Implementations of draft versions of the standard identify the specific draft version that they are using. This means that implementations based on different draft versions, and also the final RFC version, do not interoperate with each other.

The OpenSSL git master branch (and the 1.1.1-pre9 beta version) contain our development TLSv1.3 code which is based on the final version of RFC8446 and can be used for testing purposes (i.e. it is not for production use). Earlier beta versions of OpenSSL 1.1.1 implemented draft versions of the standard. Those versions contained the macro TLS1_3_VERSION_DRAFT_TXT in the tls1.h header file which identified the specific draft version that was implemented. This macro has been removed from 1.1.1-pre9 and the current master branch.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Although the latest 1.1.1 versions support the final standard version, other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS_AES_256_GCM_SHA384
* TLS_CHACHA20_POLY1305_SHA256
* TLS_AES_128_GCM_SHA256
* TLS_AES_128_CCM_8_SHA256
* TLS_AES_128_CCM_SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

Applications should use the SSL_CTX_set_ciphersuites() or SSL_set_ciphersuites() functions to configure TLSv1.3 ciphersuites. Note that the functions SSL_CTX_get_ciphers() and SSL_get_ciphers() will return
the full list of ciphersuites that have been configured for both TLSv1.2 and below and TLSv1.3.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/manmaster/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the [https://www.openssl.org/docs/manmaster/man3/SSL_get1_session.html SSL_get1_session()] function (or similar).

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_remove_session.html SSL_CTX_remove_session()] to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce single use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session(). Calling SSL_get1_session() after a 2 way shutdown will give a resumable session if any was sent. You can check that a session is resumable with [https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html SSL_SESSION_is_resumable()].

Client application developers should consider using the [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html SSL_CTX_sess_set_new_cb()] API instead. This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in previous versions of OpenSSL. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. The number of tickets can be set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html SSL_CTX_set_num_tickets]. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

If a client sends it's data and directly sends the close notify request and closes the connection, the server will still try to send tickets if configured to do so. Since the connection is already closed by the client, this might result in a write error and receiving the SIGPIPE signal. The write error will be ignored if it's a session ticket. But server applications can still get SIGPIPE they didn't get before.

If the server sends session tickets and you want to be able to get a resumable session, you need to either call SSL_read() after the ticket was sent or do a 2 way shutdown.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. From OpenSSL 1.1.0 and above ciphersuites for TLSv1.2 and below based on DSA are no longer available by default (you must compile OpenSSL with the "enable-weak-ssl-ciphers" option, and explicitly configure the ciphersuites at run time). If your server application is using a DSA certificate and has made the necessary configuration changes to enable the ciphersuites then TLSv1.3 will never be negotiated when that certificate is used for a connection (the maximum version will be TLSv1.2).

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be sent depending on the hostname that was sent in the SNI extension. If the SNI extension is not sent the server's options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some sites want to encourage the use of SNI and configure a default certificate that fails WebPKI authentication when the client supports TLS 1.3. This is under the assumption that if a hostname is not sent, then it means that the client does not verify the server certificate (unauthenticated opportunistic TLS). For implementation that actually don't send the SNI extension, but do verify the server certificate this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/manmaster/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== PSKs ==

Pre-shared Keys work differently in TLSv1.2 and below compared to TLSv1.3.

In TLSv1.2 (and below) special PSK specific ciphersuites are used. A client wishing to use a PSK will offer one (or more) of those ciphersuites to the server in the initial ClientHello message. If the server also wishes to use a PSK, then it will select that ciphersuite and will (optionally) send back an "identity hint" to the client. Finally the client sends back to the server identity details so that the server knows which PSK to use. In OpenSSL 1.1.0 and below this is implemented using a callback mechanism. The callback is called passing in the identity hint (or NULL if there is no hint) and the callback responds by filling in the identity details, as well as the PSK itself.

In TLSv1.3, if a client wishes to use a PSK, then the identity details are sent immediately in the initial ClientHello message. Use of a PSK is independent of any ciphersuite selection. If the server wishes to use the PSK then it will signal this in its response to the client. Otherwise a full (non-PSK) handshake will occur. Note that there is no identity hint in TLSv1.3.

OpenSSL 1.1.1 introduces new TLSv1.3 specific PSK callbacks. See [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_use_session_callback.html here] and [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_find_session_callback.html here] for further details. These are the preferred callbacks to use for TLSv1.3 PSKs. However, if an application has set up the TLSv1.2 PSK callbacks and TLSv1.3 is enabled then OpenSSL will attempt to fallback to using the old style callbacks. In this case, on the client side, the callback will be invoked before any communication with the server has taken place during construction of the initial ClientHello. This is because the identity details must be sent immediately in TLSv1.3. The identity hint value will always be NULL in this case.

Note that the TLSv1.2 callbacks could end up being called twice for the same connection. For example if a client application provides no TLSv1.3 callback and TLSv1.3 is enabled, then it will be called first during the initial ClientHello construction. If the server subsequently selects TLSv1.2 then the callback will be called again later on in the handshake to set up the TLSv1.2 PSK.

TLSv1.3 PSKs must specify a message digest (e.g. such as SHA-256). Where old style TLSv1.2 callbacks are used in a TLSv1.3 context then the message digest will default to SHA-256 (as specified in the standard). A server which has been configured with TLSv1.2 PSK callbacks, but negotiates TLSv1.3 with a client, will prefer ciphersuites based on SHA-256 in order to maximise the chances of a PSK being used.

== Non-application data records ==

TLSv1.3 sends more non-application data records after the handshake is finished. At least the session ticket and possibly a key update is send after the finished message. With TLSv1.2 it happened in case of renegotiation. [https://www.openssl.org/docs/manmaster/man3/SSL_read.html SSL_read()] has always documented that it can return SSL_ERROR_WANT_READ after processing non-application data, even when there is still data that can be read. When SSL_MODE_AUTO_RETRY is set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_mode.html SSL_CTX_set_mode()] OpenSSL will try to process the next record, and so not return SSL_ERROR_WANT_READ while it still has data available. Because many applications did not handle this properly, SSL_MODE_AUTO_RETRY has been made the default. If the application is using blocking sockets and SSL_MODE_AUTO_RETRY is enabled, and select() is used to check if a socket is readable this results in SSL_read() processing the non-application data records, but then try to read an application data record which might not be available and hang.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

TLS1.3

2018-09-05T20:58:47Z

Kurt: /* Sessions */

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

The TLSv1.3 standard has now been published as [[https://tools.ietf.org/html/rfc8446 RFC 8446]]. During the development of the standard the TLS Working Group published various draft versions. Implementations of draft versions of the standard identify the specific draft version that they are using. This means that implementations based on different draft versions, and also the final RFC version, do not interoperate with each other.

The OpenSSL git master branch (and the 1.1.1-pre9 beta version) contain our development TLSv1.3 code which is based on the final version of RFC8446 and can be used for testing purposes (i.e. it is not for production use). Earlier beta versions of OpenSSL 1.1.1 implemented draft versions of the standard. Those versions contained the macro TLS1_3_VERSION_DRAFT_TXT in the tls1.h header file which identified the specific draft version that was implemented. This macro has been removed from 1.1.1-pre9 and the current master branch.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Although the latest 1.1.1 versions support the final standard version, other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS_AES_256_GCM_SHA384
* TLS_CHACHA20_POLY1305_SHA256
* TLS_AES_128_GCM_SHA256
* TLS_AES_128_CCM_8_SHA256
* TLS_AES_128_CCM_SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/manmaster/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the [https://www.openssl.org/docs/manmaster/man3/SSL_get1_session.html SSL_get1_session()] function (or similar).

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_remove_session.html SSL_CTX_remove_session()] to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce single use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session(). Calling SSL_get1_session() after a 2 way shutdown will give a resumable session if any was sent. You can check that a session is resumable with [https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html SSL_SESSION_is_resumable()].

Client application developers should consider using the [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html SSL_CTX_sess_set_new_cb()] API instead. This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in previous versions of OpenSSL. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. The number of tickets can be set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html SSL_CTX_set_num_tickets]. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

If a client sends it's data and directly sends the close notify request and closes the connection, the server will still try to send tickets if configured to do so. Since the connection is already closed by the client, this might result in a write error and receiving the SIGPIPE signal. The write error will be ignored if it's a session ticket. But server applications can still get SIGPIPE they didn't get before.

If the server sends session tickets and you want to be able to get a resumable session, you need to either call SSL_read() after the ticket was sent or do a 2 way shutdown.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. From OpenSSL 1.1.0 and above ciphersuites for TLSv1.2 and below based on DSA are no longer available by default (you must compile OpenSSL with the "enable-weak-ssl-ciphers" option, and explicitly configure the ciphersuites at run time). If your server application is using a DSA certificate and has made the necessary configuration changes to enable the ciphersuites then TLSv1.3 will never be negotiated when that certificate is used for a connection (the maximum version will be TLSv1.2).

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be sent depending on the hostname that was sent in the SNI extension. If the SNI extension is not sent the server's options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some sites want to encourage the use of SNI and configure a default certificate that fails WebPKI authentication when the client supports TLS 1.3. This is under the assumption that if a hostname is not sent, then it means that the client does not verify the server certificate (unauthenticated opportunistic TLS). For implementation that actually don't send the SNI extension, but do verify the server certificate this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/manmaster/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== PSKs ==

Pre-shared Keys work differently in TLSv1.2 and below compared to TLSv1.3.

In TLSv1.2 (and below) special PSK specific ciphersuites are used. A client wishing to use a PSK will offer one (or more) of those ciphersuites to the server in the initial ClientHello message. If the server also wishes to use a PSK, then it will select that ciphersuite and will (optionally) send back an "identity hint" to the client. Finally the client sends back to the server identity details so that the server knows which PSK to use. In OpenSSL 1.1.0 and below this is implemented using a callback mechanism. The callback is called passing in the identity hint (or NULL if there is no hint) and the callback responds by filling in the identity details, as well as the PSK itself.

In TLSv1.3, if a client wishes to use a PSK, then the identity details are sent immediately in the initial ClientHello message. Use of a PSK is independent of any ciphersuite selection. If the server wishes to use the PSK then it will signal this in its response to the client. Otherwise a full (non-PSK) handshake will occur. Note that there is no identity hint in TLSv1.3.

OpenSSL 1.1.1 introduces new TLSv1.3 specific PSK callbacks. See [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_use_session_callback.html here] and [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_find_session_callback.html here] for further details. These are the preferred callbacks to use for TLSv1.3 PSKs. However, if an application has set up the TLSv1.2 PSK callbacks and TLSv1.3 is enabled then OpenSSL will attempt to fallback to using the old style callbacks. In this case, on the client side, the callback will be invoked before any communication with the server has taken place during construction of the initial ClientHello. This is because the identity details must be sent immediately in TLSv1.3. The identity hint value will always be NULL in this case.

Note that the TLSv1.2 callbacks could end up being called twice for the same connection. For example if a client application provides no TLSv1.3 callback and TLSv1.3 is enabled, then it will be called first during the initial ClientHello construction. If the server subsequently selects TLSv1.2 then the callback will be called again later on in the handshake to set up the TLSv1.2 PSK.

TLSv1.3 PSKs must specify a message digest (e.g. such as SHA-256). Where old style TLSv1.2 callbacks are used in a TLSv1.3 context then the message digest will default to SHA-256 (as specified in the standard). A server which has been configured with TLSv1.2 PSK callbacks, but negotiates TLSv1.3 with a client, will prefer ciphersuites based on SHA-256 in order to maximise the chances of a PSK being used.

== Non-application data records ==

TLSv1.3 sends more non-application data records after the handshake is finished. At least the session ticket and possibly a key update is send after the finished message. With TLSv1.2 it happened in case of renegotiation. [https://www.openssl.org/docs/manmaster/man3/SSL_read.html SSL_read()] has always documented that it can return SSL_ERROR_WANT_READ after processing non-application data, even when there is still data that can be read. When SSL_MODE_AUTO_RETRY is set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_mode.html SSL_CTX_set_mode()] OpenSSL will try to process the next record, and so not return SSL_ERROR_WANT_READ while it still has data available. Because many applications did not handle this properly, SSL_MODE_AUTO_RETRY has been made the default. If the application is using non-blocking sockets and SSL_MODE_AUTO_RETRY is enabled, and select() is used to check if a socket is readable this results in SSL_read() processing the non-application data records, but then try to read an application data record which might not be available and hang.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

TLS1.3

2018-09-05T20:50:16Z

Kurt: /* Sessions */

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

The TLSv1.3 standard has now been published as [[https://tools.ietf.org/html/rfc8446 RFC 8446]]. During the development of the standard the TLS Working Group published various draft versions. Implementations of draft versions of the standard identify the specific draft version that they are using. This means that implementations based on different draft versions, and also the final RFC version, do not interoperate with each other.

The OpenSSL git master branch (and the 1.1.1-pre9 beta version) contain our development TLSv1.3 code which is based on the final version of RFC8446 and can be used for testing purposes (i.e. it is not for production use). Earlier beta versions of OpenSSL 1.1.1 implemented draft versions of the standard. Those versions contained the macro TLS1_3_VERSION_DRAFT_TXT in the tls1.h header file which identified the specific draft version that was implemented. This macro has been removed from 1.1.1-pre9 and the current master branch.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Although the latest 1.1.1 versions support the final standard version, other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS_AES_256_GCM_SHA384
* TLS_CHACHA20_POLY1305_SHA256
* TLS_AES_128_GCM_SHA256
* TLS_AES_128_CCM_8_SHA256
* TLS_AES_128_CCM_SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/manmaster/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the [https://www.openssl.org/docs/manmaster/man3/SSL_get1_session.html SSL_get1_session()] function (or similar).

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_remove_session.html SSL_CTX_remove_session()] to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce single use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session(). Calling SSL_get1_session() after a 2 way shutdown will give a resumable session if any was sent. You can check that a session is resumable with [https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html SSL_SESSION_is_resumable()].

Client application developers should consider using the [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html SSL_CTX_sess_set_new_cb()] API instead. This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in previous versions of OpenSSL. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. The number of tickets can be set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html SSL_CTX_set_num_tickets]. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

If a client sends it's data and directly sends the close notify request and closes the connection, the server will still try to send tickets if configured to do so. Since the connection is already closed by the client, this might result in a write error and receiving the SIGPIPE signal. The write error will be ignored if it's a session ticket. But server applications can still get SIGPIPE they didn't get before.

To be able to get a resumable session, you need to either call SSL_read() or do 2 way shutdown.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. From OpenSSL 1.1.0 and above ciphersuites for TLSv1.2 and below based on DSA are no longer available by default (you must compile OpenSSL with the "enable-weak-ssl-ciphers" option, and explicitly configure the ciphersuites at run time). If your server application is using a DSA certificate and has made the necessary configuration changes to enable the ciphersuites then TLSv1.3 will never be negotiated when that certificate is used for a connection (the maximum version will be TLSv1.2).

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be sent depending on the hostname that was sent in the SNI extension. If the SNI extension is not sent the server's options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some sites want to encourage the use of SNI and configure a default certificate that fails WebPKI authentication when the client supports TLS 1.3. This is under the assumption that if a hostname is not sent, then it means that the client does not verify the server certificate (unauthenticated opportunistic TLS). For implementation that actually don't send the SNI extension, but do verify the server certificate this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/manmaster/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== PSKs ==

Pre-shared Keys work differently in TLSv1.2 and below compared to TLSv1.3.

In TLSv1.2 (and below) special PSK specific ciphersuites are used. A client wishing to use a PSK will offer one (or more) of those ciphersuites to the server in the initial ClientHello message. If the server also wishes to use a PSK, then it will select that ciphersuite and will (optionally) send back an "identity hint" to the client. Finally the client sends back to the server identity details so that the server knows which PSK to use. In OpenSSL 1.1.0 and below this is implemented using a callback mechanism. The callback is called passing in the identity hint (or NULL if there is no hint) and the callback responds by filling in the identity details, as well as the PSK itself.

In TLSv1.3, if a client wishes to use a PSK, then the identity details are sent immediately in the initial ClientHello message. Use of a PSK is independent of any ciphersuite selection. If the server wishes to use the PSK then it will signal this in its response to the client. Otherwise a full (non-PSK) handshake will occur. Note that there is no identity hint in TLSv1.3.

OpenSSL 1.1.1 introduces new TLSv1.3 specific PSK callbacks. See [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_use_session_callback.html here] and [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_find_session_callback.html here] for further details. These are the preferred callbacks to use for TLSv1.3 PSKs. However, if an application has set up the TLSv1.2 PSK callbacks and TLSv1.3 is enabled then OpenSSL will attempt to fallback to using the old style callbacks. In this case, on the client side, the callback will be invoked before any communication with the server has taken place during construction of the initial ClientHello. This is because the identity details must be sent immediately in TLSv1.3. The identity hint value will always be NULL in this case.

Note that the TLSv1.2 callbacks could end up being called twice for the same connection. For example if a client application provides no TLSv1.3 callback and TLSv1.3 is enabled, then it will be called first during the initial ClientHello construction. If the server subsequently selects TLSv1.2 then the callback will be called again later on in the handshake to set up the TLSv1.2 PSK.

TLSv1.3 PSKs must specify a message digest (e.g. such as SHA-256). Where old style TLSv1.2 callbacks are used in a TLSv1.3 context then the message digest will default to SHA-256 (as specified in the standard). A server which has been configured with TLSv1.2 PSK callbacks, but negotiates TLSv1.3 with a client, will prefer ciphersuites based on SHA-256 in order to maximise the chances of a PSK being used.

== Non-application data records ==

TLSv1.3 sends more non-application data records after the handshake is finished. At least the session ticket and possibly a key update is send after the finished message. With TLSv1.2 it happened in case of renegotiation. [https://www.openssl.org/docs/manmaster/man3/SSL_read.html SSL_read()] has always documented that it can return SSL_ERROR_WANT_READ after processing non-application data, even when there is still data that can be read. When SSL_MODE_AUTO_RETRY is set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_mode.html SSL_CTX_set_mode()] OpenSSL will try to process the next record, and so not return SSL_ERROR_WANT_READ while it still has data available. Because many applications did not handle this properly, SSL_MODE_AUTO_RETRY has been made the default. If the application is using non-blocking sockets and SSL_MODE_AUTO_RETRY is enabled, and select() is used to check if a socket is readable this results in SSL_read() processing the non-application data records, but then try to read an application data record which might not be available and hang.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

TLS1.3

2018-09-05T20:04:45Z

Kurt: /* Sessions */

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

The TLSv1.3 standard has now been published as [[https://tools.ietf.org/html/rfc8446 RFC 8446]]. During the development of the standard the TLS Working Group published various draft versions. Implementations of draft versions of the standard identify the specific draft version that they are using. This means that implementations based on different draft versions, and also the final RFC version, do not interoperate with each other.

The OpenSSL git master branch (and the 1.1.1-pre9 beta version) contain our development TLSv1.3 code which is based on the final version of RFC8446 and can be used for testing purposes (i.e. it is not for production use). Earlier beta versions of OpenSSL 1.1.1 implemented draft versions of the standard. Those versions contained the macro TLS1_3_VERSION_DRAFT_TXT in the tls1.h header file which identified the specific draft version that was implemented. This macro has been removed from 1.1.1-pre9 and the current master branch.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Although the latest 1.1.1 versions support the final standard version, other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS_AES_256_GCM_SHA384
* TLS_CHACHA20_POLY1305_SHA256
* TLS_AES_128_GCM_SHA256
* TLS_AES_128_CCM_8_SHA256
* TLS_AES_128_CCM_SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/manmaster/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the [https://www.openssl.org/docs/manmaster/man3/SSL_get1_session.html SSL_get1_session()] function (or similar).

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_remove_session.html SSL_CTX_remove_session()] to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce single use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session(). Calling SSL_get1_session() after a 2 way shutdown will give a resumable session if any was sent. You can check that a session is resumable with [https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html SSL_SESSION_is_resumable()].

Client application developers should consider using the [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html SSL_CTX_sess_set_new_cb()] API instead. This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in previous versions of OpenSSL. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. The number of tickets can be set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html SSL_CTX_set_num_tickets]. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

If a client sends it's data and directly sends the close notify request and closes the connection, the server will still try to send tickets if configured to do so. Since the connection is already closed by the client, this might result in a write error and receiving the SIGPIPE signal. The write error will be ignored if it's a session ticket. But server applications can still get SIGPIPE they didn't get before.

In TLS 1.2 and earlier, sending data, sending the close notify and closing the connection without reading anything or waiting for the close notify from the peer still created a resumable session. Since the session ticket is send after the negotiation in TLS 1.3, you need to make sure that the session ticket message from the server is processed by either calling SSL_read() or doing a 2 way shut shutdown.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. From OpenSSL 1.1.0 and above ciphersuites for TLSv1.2 and below based on DSA are no longer available by default (you must compile OpenSSL with the "enable-weak-ssl-ciphers" option, and explicitly configure the ciphersuites at run time). If your server application is using a DSA certificate and has made the necessary configuration changes to enable the ciphersuites then TLSv1.3 will never be negotiated when that certificate is used for a connection (the maximum version will be TLSv1.2).

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be sent depending on the hostname that was sent in the SNI extension. If the SNI extension is not sent the server's options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some sites want to encourage the use of SNI and configure a default certificate that fails WebPKI authentication when the client supports TLS 1.3. This is under the assumption that if a hostname is not sent, then it means that the client does not verify the server certificate (unauthenticated opportunistic TLS). For implementation that actually don't send the SNI extension, but do verify the server certificate this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/manmaster/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== PSKs ==

Pre-shared Keys work differently in TLSv1.2 and below compared to TLSv1.3.

In TLSv1.2 (and below) special PSK specific ciphersuites are used. A client wishing to use a PSK will offer one (or more) of those ciphersuites to the server in the initial ClientHello message. If the server also wishes to use a PSK, then it will select that ciphersuite and will (optionally) send back an "identity hint" to the client. Finally the client sends back to the server identity details so that the server knows which PSK to use. In OpenSSL 1.1.0 and below this is implemented using a callback mechanism. The callback is called passing in the identity hint (or NULL if there is no hint) and the callback responds by filling in the identity details, as well as the PSK itself.

In TLSv1.3, if a client wishes to use a PSK, then the identity details are sent immediately in the initial ClientHello message. Use of a PSK is independent of any ciphersuite selection. If the server wishes to use the PSK then it will signal this in its response to the client. Otherwise a full (non-PSK) handshake will occur. Note that there is no identity hint in TLSv1.3.

OpenSSL 1.1.1 introduces new TLSv1.3 specific PSK callbacks. See [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_use_session_callback.html here] and [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_find_session_callback.html here] for further details. These are the preferred callbacks to use for TLSv1.3 PSKs. However, if an application has set up the TLSv1.2 PSK callbacks and TLSv1.3 is enabled then OpenSSL will attempt to fallback to using the old style callbacks. In this case, on the client side, the callback will be invoked before any communication with the server has taken place during construction of the initial ClientHello. This is because the identity details must be sent immediately in TLSv1.3. The identity hint value will always be NULL in this case.

Note that the TLSv1.2 callbacks could end up being called twice for the same connection. For example if a client application provides no TLSv1.3 callback and TLSv1.3 is enabled, then it will be called first during the initial ClientHello construction. If the server subsequently selects TLSv1.2 then the callback will be called again later on in the handshake to set up the TLSv1.2 PSK.

TLSv1.3 PSKs must specify a message digest (e.g. such as SHA-256). Where old style TLSv1.2 callbacks are used in a TLSv1.3 context then the message digest will default to SHA-256 (as specified in the standard). A server which has been configured with TLSv1.2 PSK callbacks, but negotiates TLSv1.3 with a client, will prefer ciphersuites based on SHA-256 in order to maximise the chances of a PSK being used.

== Non-application data records ==

TLSv1.3 sends more non-application data records after the handshake is finished. At least the session ticket and possibly a key update is send after the finished message. With TLSv1.2 it happened in case of renegotiation. [https://www.openssl.org/docs/manmaster/man3/SSL_read.html SSL_read()] has always documented that it can return SSL_ERROR_WANT_READ after processing non-application data, even when there is still data that can be read. When SSL_MODE_AUTO_RETRY is set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_mode.html SSL_CTX_set_mode()] OpenSSL will try to process the next record, and so not return SSL_ERROR_WANT_READ while it still has data available. Because many applications did not handle this properly, SSL_MODE_AUTO_RETRY has been made the default. If the application is using non-blocking sockets and SSL_MODE_AUTO_RETRY is enabled, and select() is used to check if a socket is readable this results in SSL_read() processing the non-application data records, but then try to read an application data record which might not be available and hang.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

TLS1.3

2018-08-26T19:54:58Z

Kurt:

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

The TLSv1.3 standard has now been published as [[https://tools.ietf.org/html/rfc8446 RFC 8446]]. During the development of the standard the TLS Working Group published various draft versions. Implementations of draft versions of the standard identify the specific draft version that they are using. This means that implementations based on different draft versions, and also the final RFC version, do not interoperate with each other.

The OpenSSL git master branch (and the 1.1.1-pre9 beta version) contain our development TLSv1.3 code which is based on the final version of RFC8446 and can be used for testing purposes (i.e. it is not for production use). Earlier beta versions of OpenSSL 1.1.1 implemented draft versions of the standard. Those versions contained the macro TLS1_3_VERSION_DRAFT_TXT in the tls1.h header file which identified the specific draft version that was implemented. This macro has been removed from 1.1.1-pre9 and the current master branch.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Although the latest 1.1.1 versions support the final standard version, other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS_AES_256_GCM_SHA384
* TLS_CHACHA20_POLY1305_SHA256
* TLS_AES_128_GCM_SHA256
* TLS_AES_128_CCM_8_SHA256
* TLS_AES_128_CCM_SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/manmaster/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the [https://www.openssl.org/docs/manmaster/man3/SSL_get1_session.html SSL_get1_session()] function (or similar).

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_remove_session.html SSL_CTX_remove_session()] to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce single use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session(). Calling SSL_get1_session() after a 2 way shutdown will give a resumable session if any was sent. You can check that a session is resumable with [https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html SSL_SESSION_is_resumable()].

Client application developers should consider using the [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html SSL_CTX_sess_set_new_cb()] API instead. This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in previous versions of OpenSSL. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. The number of tickets can be set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html SSL_CTX_set_num_tickets]. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

An OpenSSL client will only process received sessions when they attempt to read application data. During the read if a session ticket message is encountered then it will be automatically processed. A consequence of this is that if a client application never attempts to read data from the server then it will never receive a session and hence resumption will not be possible. For that reason, if session resumption is required, then it is recommended that clients always perform at least one read between establishing and shutting down a connection.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. From OpenSSL 1.1.0 and above ciphersuites for TLSv1.2 and below based on DSA are no longer available by default (you must compile OpenSSL with the "enable-weak-ssl-ciphers" option, and explicitly configure the ciphersuites at run time). If your server application is using a DSA certificate and has made the necessary configuration changes to enable the ciphersuites then TLSv1.3 will never be negotiated when that certificate is used for a connection (the maximum version will be TLSv1.2).

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be sent depending on the hostname that was sent in the SNI extension. If the SNI extension is not sent the server's options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some sites want to encourage the use of SNI and configure a default certificate that fails WebPKI authentication when the client supports TLS 1.3. This is under the assumption that if a hostname is not sent, then it means that the client does not verify the server certificate (unauthenticated opportunistic TLS). For implementation that actually don't send the SNI extension, but do verify the server certificate this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/manmaster/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== PSKs ==

Pre-shared Keys work differently in TLSv1.2 and below compared to TLSv1.3.

In TLSv1.2 (and below) special PSK specific ciphersuites are used. A client wishing to use a PSK will offer one (or more) of those ciphersuites to the server in the initial ClientHello message. If the server also wishes to use a PSK, then it will select that ciphersuite and will (optionally) send back an "identity hint" to the client. Finally the client sends back to the server identity details so that the server knows which PSK to use. In OpenSSL 1.1.0 and below this is implemented using a callback mechanism. The callback is called passing in the identity hint (or NULL if there is no hint) and the callback responds by filling in the identity details, as well as the PSK itself.

In TLSv1.3, if a client wishes to use a PSK, then the identity details are sent immediately in the initial ClientHello message. Use of a PSK is independent of any ciphersuite selection. If the server wishes to use the PSK then it will signal this in its response to the client. Otherwise a full (non-PSK) handshake will occur. Note that there is no identity hint in TLSv1.3.

OpenSSL 1.1.1 introduces new TLSv1.3 specific PSK callbacks. See [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_use_session_callback.html here] and [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_psk_find_session_callback.html here] for further details. These are the preferred callbacks to use for TLSv1.3 PSKs. However, if an application has set up the TLSv1.2 PSK callbacks and TLSv1.3 is enabled then OpenSSL will attempt to fallback to using the old style callbacks. In this case, on the client side, the callback will be invoked before any communication with the server has taken place during construction of the initial ClientHello. This is because the identity details must be sent immediately in TLSv1.3. The identity hint value will always be NULL in this case.

Note that the TLSv1.2 callbacks could end up being called twice for the same connection. For example if a client application provides no TLSv1.3 callback and TLSv1.3 is enabled, then it will be called first during the initial ClientHello construction. If the server subsequently selects TLSv1.2 then the callback will be called again later on in the handshake to set up the TLSv1.2 PSK.

TLSv1.3 PSKs must specify a message digest (e.g. such as SHA-256). Where old style TLSv1.2 callbacks are used in a TLSv1.3 context then the message digest will default to SHA-256 (as specified in the standard). A server which has been configured with TLSv1.2 PSK callbacks, but negotiates TLSv1.3 with a client, will prefer ciphersuites based on SHA-256 in order to maximise the chances of a PSK being used.

== Non-application data records ==

TLSv1.3 sends more non-application data records after the handshake is finished. At least the session ticket and possibly a key update is send after the finished message. With TLSv1.2 it happened in case of renegotiation. [https://www.openssl.org/docs/manmaster/man3/SSL_read.html SSL_read()] has always documented that it can return SSL_ERROR_WANT_READ after processing non-application data, even when there is still data that can be read. When SSL_MODE_AUTO_RETRY is set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_mode.html SSL_CTX_set_mode()] OpenSSL will try to process the next record, and so not return SSL_ERROR_WANT_READ while it still has data available. Because many applications did not handle this properly, SSL_MODE_AUTO_RETRY has been made the default. If the application is using non-blocking sockets and SSL_MODE_AUTO_RETRY is enabled, and select() is used to check if a socket is readable this results in SSL_read() processing the non-application data records, but then try to read an application data record which might not be available and hang.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

TLS1.3

2018-08-26T19:51:51Z

Kurt: /* Sessions */

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

The TLSv1.3 standard has now been published as [[https://tools.ietf.org/html/rfc8446 RFC 8446]]. During the development of the standard the TLS Working Group published various draft versions. Implementations of draft versions of the standard identify the specific draft version that they are using. This means that implementations based on different draft versions, and also the final RFC version, do not interoperate with each other.

The OpenSSL git master branch (and the 1.1.1-pre9 beta version) contain our development TLSv1.3 code which is based on the final version of RFC8446 and can be used for testing purposes (i.e. it is not for production use). Earlier beta versions of OpenSSL 1.1.1 implemented draft versions of the standard. Those versions contained the macro TLS1_3_VERSION_DRAFT_TXT in the tls1.h header file which identified the specific draft version that was implemented. This macro has been removed from 1.1.1-pre9 and the current master branch.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Although the latest 1.1.1 versions support the final standard version, other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS_AES_256_GCM_SHA384
* TLS_CHACHA20_POLY1305_SHA256
* TLS_AES_128_GCM_SHA256
* TLS_AES_128_CCM_8_SHA256
* TLS_AES_128_CCM_SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the [https://www.openssl.org/docs/man1.1.1/man3/SSL_get1_session.html SSL_get1_session()] function (or similar).

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_remove_session.html SSL_CTX_remove_session()] to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce single use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session(). Calling SSL_get1_session() after a 2 way shutdown will give a resumable session if any was sent. You can check that a session is resumable with [https://www.openssl.org/docs/man1.1.1/man3/SSL_SESSION_is_resumable.html SSL_SESSION_is_resumable()].

Client application developers should consider using the [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_sess_set_new_cb.html SSL_CTX_sess_set_new_cb()] API instead. This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in previous versions of OpenSSL. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. The number of tickets can be set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html SSL_CTX_set_num_tickets]. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

An OpenSSL client will only process received sessions when they attempt to read application data. During the read if a session ticket message is encountered then it will be automatically processed. A consequence of this is that if a client application never attempts to read data from the server then it will never receive a session and hence resumption will not be possible. For that reason, if session resumption is required, then it is recommended that clients always perform at least one read between establishing and shutting down a connection.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. From OpenSSL 1.1.0 and above ciphersuites for TLSv1.2 and below based on DSA are no longer available by default (you must compile OpenSSL with the "enable-weak-ssl-ciphers" option, and explicitly configure the ciphersuites at run time). If your server application is using a DSA certificate and has made the necessary configuration changes to enable the ciphersuites then TLSv1.3 will never be negotiated when that certificate is used for a connection (the maximum version will be TLSv1.2).

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be sent depending on the hostname that was sent in the SNI extension. If the SNI extension is not sent the server's options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some sites want to encourage the use of SNI and configure a default certificate that fails WebPKI authentication when the client supports TLS 1.3. This is under the assumption that if a hostname is not sent, then it means that the client does not verify the server certificate (unauthenticated opportunistic TLS). For implementation that actually don't send the SNI extension, but do verify the server certificate this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/man1.1.1/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== PSKs ==

Pre-shared Keys work differently in TLSv1.2 and below compared to TLSv1.3.

In TLSv1.2 (and below) special PSK specific ciphersuites are used. A client wishing to use a PSK will offer one (or more) of those ciphersuites to the server in the initial ClientHello message. If the server also wishes to use a PSK, then it will select that ciphersuite and will (optionally) send back an "identity hint" to the client. Finally the client sends back to the server identity details so that the server knows which PSK to use. In OpenSSL 1.1.0 and below this is implemented using a callback mechanism. The callback is called passing in the identity hint (or NULL if there is no hint) and the callback responds by filling in the identity details, as well as the PSK itself.

In TLSv1.3, if a client wishes to use a PSK, then the identity details are sent immediately in the initial ClientHello message. Use of a PSK is independent of any ciphersuite selection. If the server wishes to use the PSK then it will signal this in its response to the client. Otherwise a full (non-PSK) handshake will occur. Note that there is no identity hint in TLSv1.3.

OpenSSL 1.1.1 introduces new TLSv1.3 specific PSK callbacks. See [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_psk_use_session_callback.html here] and [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_psk_find_session_callback.html here] for further details. These are the preferred callbacks to use for TLSv1.3 PSKs. However, if an application has set up the TLSv1.2 PSK callbacks and TLSv1.3 is enabled then OpenSSL will attempt to fallback to using the old style callbacks. In this case, on the client side, the callback will be invoked before any communication with the server has taken place during construction of the initial ClientHello. This is because the identity details must be sent immediately in TLSv1.3. The identity hint value will always be NULL in this case.

Note that the TLSv1.2 callbacks could end up being called twice for the same connection. For example if a client application provides no TLSv1.3 callback and TLSv1.3 is enabled, then it will be called first during the initial ClientHello construction. If the server subsequently selects TLSv1.2 then the callback will be called again later on in the handshake to set up the TLSv1.2 PSK.

TLSv1.3 PSKs must specify a message digest (e.g. such as SHA-256). Where old style TLSv1.2 callbacks are used in a TLSv1.3 context then the message digest will default to SHA-256 (as specified in the standard). A server which has been configured with TLSv1.2 PSK callbacks, but negotiates TLSv1.3 with a client, will prefer ciphersuites based on SHA-256 in order to maximise the chances of a PSK being used.

== Non-application data records ==

TLSv1.3 sends more non-application data records after the handshake is finished. At least the session ticket and possibly a key update is send after the finished message. With TLSv1.2 it happened in case of renegotiation. [https://www.openssl.org/docs/manmaster/man3/SSL_read.html SSL_read()] has always documented that it can return SSL_ERROR_WANT_READ after processing non-application data, even when there is still data that can be read. When SSL_MODE_AUTO_RETRY is set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_mode.html SSL_CTX_set_mode()] OpenSSL will try to process the next record, and so not return SSL_ERROR_WANT_READ while it still has data available. Because many applications did not handle this properly, SSL_MODE_AUTO_RETRY has been made the default. If the application is using non-blocking sockets and SSL_MODE_AUTO_RETRY is enabled, and select() is used to check if a socket is readable this results in SSL_read() processing the non-application data records, but then try to read an application data record which might not be available and hang.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

TLS1.3

2018-08-26T11:28:20Z

Kurt: /* Non-application data records */

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

The TLSv1.3 standard has now been published as [[https://tools.ietf.org/html/rfc8446 RFC 8446]]. During the development of the standard the TLS Working Group published various draft versions. Implementations of draft versions of the standard identify the specific draft version that they are using. This means that implementations based on different draft versions, and also the final RFC version, do not interoperate with each other.

The OpenSSL git master branch (and the 1.1.1-pre9 beta version) contain our development TLSv1.3 code which is based on the final version of RFC8446 and can be used for testing purposes (i.e. it is not for production use). Earlier beta versions of OpenSSL 1.1.1 implemented draft versions of the standard. Those versions contained the macro TLS1_3_VERSION_DRAFT_TXT in the tls1.h header file which identified the specific draft version that was implemented. This macro has been removed from 1.1.1-pre9 and the current master branch.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Although the latest 1.1.1 versions support the final standard version, other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS_AES_256_GCM_SHA384
* TLS_CHACHA20_POLY1305_SHA256
* TLS_AES_128_GCM_SHA256
* TLS_AES_128_CCM_8_SHA256
* TLS_AES_128_CCM_SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the SSL_get1_session() function (or similar). See [https://www.openssl.org/docs/man1.1.1/man3/SSL_get1_session.html here] for further details.

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use SSL_CTX_remove_session() to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce single use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session().

Client application developers should consider using the SSL_CTX_sess_set_new_cb() API instead (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_sess_set_new_cb.html here]). This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in previous versions of OpenSSL. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

An OpenSSL client will only process received sessions when they attempt to read application data. During the read if a session ticket message is encountered then it will be automatically processed. A consequence of this is that if a client application never attempts to read data from the server then it will never receive a session and hence resumption will not be possible. For that reason, if session resumption is required, then it is recommended that clients always perform at least one read between establishing and shutting down a connection.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. From OpenSSL 1.1.0 and above ciphersuites for TLSv1.2 and below based on DSA are no longer available by default (you must compile OpenSSL with the "enable-weak-ssl-ciphers" option, and explicitly configure the ciphersuites at run time). If your server application is using a DSA certificate and has made the necessary configuration changes to enable the ciphersuites then TLSv1.3 will never be negotiated when that certificate is used for a connection (the maximum version will be TLSv1.2).

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be sent depending on the hostname that was sent in the SNI extension. If the SNI extension is not sent the server's options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some sites want to encourage the use of SNI and configure a default certificate that fails WebPKI authentication when the client supports TLS 1.3. This is under the assumption that if a hostname is not sent, then it means that the client does not verify the server certificate (unauthenticated opportunistic TLS). For implementation that actually don't send the SNI extension, but do verify the server certificate this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/man1.1.1/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== PSKs ==

Pre-shared Keys work differently in TLSv1.2 and below compared to TLSv1.3.

In TLSv1.2 (and below) special PSK specific ciphersuites are used. A client wishing to use a PSK will offer one (or more) of those ciphersuites to the server in the initial ClientHello message. If the server also wishes to use a PSK, then it will select that ciphersuite and will (optionally) send back an "identity hint" to the client. Finally the client sends back to the server identity details so that the server knows which PSK to use. In OpenSSL 1.1.0 and below this is implemented using a callback mechanism. The callback is called passing in the identity hint (or NULL if there is no hint) and the callback responds by filling in the identity details, as well as the PSK itself.

In TLSv1.3, if a client wishes to use a PSK, then the identity details are sent immediately in the initial ClientHello message. Use of a PSK is independent of any ciphersuite selection. If the server wishes to use the PSK then it will signal this in its response to the client. Otherwise a full (non-PSK) handshake will occur. Note that there is no identity hint in TLSv1.3.

OpenSSL 1.1.1 introduces new TLSv1.3 specific PSK callbacks. See [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_psk_use_session_callback.html here] and [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_psk_find_session_callback.html here] for further details. These are the preferred callbacks to use for TLSv1.3 PSKs. However, if an application has set up the TLSv1.2 PSK callbacks and TLSv1.3 is enabled then OpenSSL will attempt to fallback to using the old style callbacks. In this case, on the client side, the callback will be invoked before any communication with the server has taken place during construction of the initial ClientHello. This is because the identity details must be sent immediately in TLSv1.3. The identity hint value will always be NULL in this case.

Note that the TLSv1.2 callbacks could end up being called twice for the same connection. For example if a client application provides no TLSv1.3 callback and TLSv1.3 is enabled, then it will be called first during the initial ClientHello construction. If the server subsequently selects TLSv1.2 then the callback will be called again later on in the handshake to set up the TLSv1.2 PSK.

TLSv1.3 PSKs must specify a message digest (e.g. such as SHA-256). Where old style TLSv1.2 callbacks are used in a TLSv1.3 context then the message digest will default to SHA-256 (as specified in the standard). A server which has been configured with TLSv1.2 PSK callbacks, but negotiates TLSv1.3 with a client, will prefer ciphersuites based on SHA-256 in order to maximise the chances of a PSK being used.

== Non-application data records ==

TLSv1.3 sends more non-application data records after the handshake is finished. At least the session ticket and possibly a key update is send after the finished message. With TLSv1.2 it happened in case of renegotiation. [https://www.openssl.org/docs/manmaster/man3/SSL_read.html SSL_read()] has always documented that it can return SSL_ERROR_WANT_READ after processing non-application data, even when there is still data that can be read. When SSL_MODE_AUTO_RETRY is set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_mode.html SSL_CTX_set_mode()] OpenSSL will try to process the next record, and so not return SSL_ERROR_WANT_READ while it still has data available. Because many applications did not handle this properly, SSL_MODE_AUTO_RETRY has been made the default. If the application is using non-blocking sockets and SSL_MODE_AUTO_RETRY is enabled, and select() is used to check if a socket is readable this results in SSL_read() processing the non-application data records, but then try to read an application data record which might not be available and hang.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

TLS1.3

2018-08-26T10:48:30Z

Kurt: Add section about non-application data

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

The TLSv1.3 standard has now been published as [[https://tools.ietf.org/html/rfc8446 RFC 8446]]. During the development of the standard the TLS Working Group published various draft versions. Implementations of draft versions of the standard identify the specific draft version that they are using. This means that implementations based on different draft versions, and also the final RFC version, do not interoperate with each other.

The OpenSSL git master branch (and the 1.1.1-pre9 beta version) contain our development TLSv1.3 code which is based on the final version of RFC8446 and can be used for testing purposes (i.e. it is not for production use). Earlier beta versions of OpenSSL 1.1.1 implemented draft versions of the standard. Those versions contained the macro TLS1_3_VERSION_DRAFT_TXT in the tls1.h header file which identified the specific draft version that was implemented. This macro has been removed from 1.1.1-pre9 and the current master branch.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Although the latest 1.1.1 versions support the final standard version, other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS_AES_256_GCM_SHA384
* TLS_CHACHA20_POLY1305_SHA256
* TLS_AES_128_GCM_SHA256
* TLS_AES_128_CCM_8_SHA256
* TLS_AES_128_CCM_SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS_AES_256_GCM_SHA384 and TLS_CHACHA20_POLY1305_SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the SSL_get1_session() function (or similar). See [https://www.openssl.org/docs/man1.1.1/man3/SSL_get1_session.html here] for further details.

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use SSL_CTX_remove_session() to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce single use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session().

Client application developers should consider using the SSL_CTX_sess_set_new_cb() API instead (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_sess_set_new_cb.html here]). This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in previous versions of OpenSSL. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

An OpenSSL client will only process received sessions when they attempt to read application data. During the read if a session ticket message is encountered then it will be automatically processed. A consequence of this is that if a client application never attempts to read data from the server then it will never receive a session and hence resumption will not be possible. For that reason, if session resumption is required, then it is recommended that clients always perform at least one read between establishing and shutting down a connection.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. From OpenSSL 1.1.0 and above ciphersuites for TLSv1.2 and below based on DSA are no longer available by default (you must compile OpenSSL with the "enable-weak-ssl-ciphers" option, and explicitly configure the ciphersuites at run time). If your server application is using a DSA certificate and has made the necessary configuration changes to enable the ciphersuites then TLSv1.3 will never be negotiated when that certificate is used for a connection (the maximum version will be TLSv1.2).

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be sent depending on the hostname that was sent in the SNI extension. If the SNI extension is not sent the server's options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some sites want to encourage the use of SNI and configure a default certificate that fails WebPKI authentication when the client supports TLS 1.3. This is under the assumption that if a hostname is not sent, then it means that the client does not verify the server certificate (unauthenticated opportunistic TLS). For implementation that actually don't send the SNI extension, but do verify the server certificate this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/man1.1.1/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== PSKs ==

Pre-shared Keys work differently in TLSv1.2 and below compared to TLSv1.3.

In TLSv1.2 (and below) special PSK specific ciphersuites are used. A client wishing to use a PSK will offer one (or more) of those ciphersuites to the server in the initial ClientHello message. If the server also wishes to use a PSK, then it will select that ciphersuite and will (optionally) send back an "identity hint" to the client. Finally the client sends back to the server identity details so that the server knows which PSK to use. In OpenSSL 1.1.0 and below this is implemented using a callback mechanism. The callback is called passing in the identity hint (or NULL if there is no hint) and the callback responds by filling in the identity details, as well as the PSK itself.

In TLSv1.3, if a client wishes to use a PSK, then the identity details are sent immediately in the initial ClientHello message. Use of a PSK is independent of any ciphersuite selection. If the server wishes to use the PSK then it will signal this in its response to the client. Otherwise a full (non-PSK) handshake will occur. Note that there is no identity hint in TLSv1.3.

OpenSSL 1.1.1 introduces new TLSv1.3 specific PSK callbacks. See [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_psk_use_session_callback.html here] and [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_psk_find_session_callback.html here] for further details. These are the preferred callbacks to use for TLSv1.3 PSKs. However, if an application has set up the TLSv1.2 PSK callbacks and TLSv1.3 is enabled then OpenSSL will attempt to fallback to using the old style callbacks. In this case, on the client side, the callback will be invoked before any communication with the server has taken place during construction of the initial ClientHello. This is because the identity details must be sent immediately in TLSv1.3. The identity hint value will always be NULL in this case.

Note that the TLSv1.2 callbacks could end up being called twice for the same connection. For example if a client application provides no TLSv1.3 callback and TLSv1.3 is enabled, then it will be called first during the initial ClientHello construction. If the server subsequently selects TLSv1.2 then the callback will be called again later on in the handshake to set up the TLSv1.2 PSK.

TLSv1.3 PSKs must specify a message digest (e.g. such as SHA-256). Where old style TLSv1.2 callbacks are used in a TLSv1.3 context then the message digest will default to SHA-256 (as specified in the standard). A server which has been configured with TLSv1.2 PSK callbacks, but negotiates TLSv1.3 with a client, will prefer ciphersuites based on SHA-256 in order to maximise the chances of a PSK being used.

== Non-application data records ==

TLSv1.3 sends more non-application data records after the handshake is finished. At least the session ticket is send after the finished message. [https://www.openssl.org/docs/manmaster/man3/SSL_read.html SSL_read()] has always documented that it can return SSL_ERROR_WANT_READ after processing non-application data, even when there is still data that can be read. When SSL_MODE_AUTO_RETRY is set using [https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_mode.html SSL_CTX_set_mode()] OpenSSL will try to process the next record, and so not return SSL_ERROR_WANT_READ while it still has data available. Because many applications did not handle this properly, SSL_MODE_AUTO_RETRY has been made the default. If the application is using non-blocking sockets and SSL_MODE_AUTO_RETRY is enabled, and select() is used to check if a socket is readable this results in SSL_read() processing the non-application data records, but then try to read an application data record which might not be available and hang.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

TLS1.3

2018-04-27T22:42:47Z

Kurt: /* Server Name Indication */

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

As of the time of writing TLSv1.3 is still in draft. Periodically a new version of the draft standard is published by the TLS Working Group. Implementations of the draft are required to identify the specific draft version that they are using. This means that implementations based on different draft versions do not interoperate with each other.

OpenSSL 1.1.1 will not be released until (at least) TLSv1.3 is finalised. In the meantime the OpenSSL git master branch contains our development TLSv1.3 code which can be used for testing purposes (i.e. it is not for production use). You can check which draft TLSv1.3 version is implemented in any particular OpenSSL checkout by examining the value of the TLS1_3_VERSION_DRAFT_TXT macro in the tls1.h header file. This macro will be removed when the final version of the standard is released.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Currently OpenSSL has implemented the “draft-26” version of TLSv1.3. Other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS13-AES-256-GCM-SHA384
* TLS13-CHACHA20-POLY1305-SHA256
* TLS13-AES-128-GCM-SHA256
* TLS13-AES-128-CCM-8-SHA256
* TLS13-AES-128-CCM-SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS13-AES-256-GCM-SHA384:TLS13-CHACHA20-POLY1305-SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS13-AES-256-GCM-SHA384 and TLS13-CHACHA20-POLY1305-SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. At the time of writing, OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the SSL_get1_session() function (or similar). See [https://www.openssl.org/docs/man1.1.1/man3/SSL_get1_session.html here] for further details.

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use SSL_CTX_remove_session() to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce singly use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session().

Client application developers should consider using the SSL_CTX_sess_set_new_cb() API instead (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_sess_set_new_cb.html here]). This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in OpenSSL 1.1.0. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. If your server application is using a DSA certificate then TLSv1.3 connections will fail with an error message similar to the following:

140348850206144:error:14201076:SSL routines:tls_choose_sigalg:no suitable signature algorithm:ssl/t1_lib.c:2308:

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be send depending on the hostname that was send in the SNI extension. If an SNI is not send the options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some people want to encourage the use of SNI and set up the default certificate to be for an invalid hostname if the client supports TLS 1.3. This is under the assumption that if a hostname is not send, that the client will check that the hostname of the certificate matches the hostname it's trying to connect to. For implementation that actually don't send the SNI, but do check the hostname this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/man1.1.1/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function. For hostname validation see [[Hostname_validation|Hostname validation]].

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

TLS1.3

2018-04-27T21:27:53Z

Kurt: Add SNI section.

The OpenSSL 1.1.1 release includes support for TLSv1.3. The release is binary and API compatible with OpenSSL 1.1.0. In theory, if your application supports OpenSSL 1.1.0, then all you need to do to upgrade is to drop in the new version of OpenSSL and you will automatically start being able to use TLSv1.3. However there are some issues that application developers and deployers need to be aware of.

== Differences with TLS1.2 and below ==

TLSv1.3 is a major rewrite of the specification. There was some debate as to whether it should really be called TLSv2.0 - but TLSv1.3 it is. There are major changes and some things work very differently. A brief, incomplete, summary of some things that you are likely to notice follows:

* There are new ciphersuites that only work in TLSv1.3. The old ciphersuites cannot be used for TLSv1.3 connections and the new ones cannot be used in TLSv1.2 and below.
* The new ciphersuites are defined differently and do not specify the certificate type (e.g. RSA, DSA, ECDSA) or the key exchange mechanism (e.g. DHE or ECHDE). This has implications for ciphersuite configuration.
* Clients provide a “key_share” in the ClientHello. This has consequences for “group” configuration.
* Sessions are not established until after the main handshake has been completed. There may be a gap between the end of the handshake and the establishment of a session (or, in theory, a session may not be established at all). This could have impacts on session resumption code.
* Renegotiation is not possible in a TLSv1.3 connection
* More of the handshake is now encrypted.
* More types of messages can now have extensions (this has an impact on the custom extension APIs and Certificate Transparency)
* DSA certificates are no longer allowed in TLSv1.3 connections

Note that at this stage only TLSv1.3 is supported. DTLSv1.3 is still in the early days of specification and there is no OpenSSL support for it at this time.

== Current status of the TLSv1.3 standard ==

As of the time of writing TLSv1.3 is still in draft. Periodically a new version of the draft standard is published by the TLS Working Group. Implementations of the draft are required to identify the specific draft version that they are using. This means that implementations based on different draft versions do not interoperate with each other.

OpenSSL 1.1.1 will not be released until (at least) TLSv1.3 is finalised. In the meantime the OpenSSL git master branch contains our development TLSv1.3 code which can be used for testing purposes (i.e. it is not for production use). You can check which draft TLSv1.3 version is implemented in any particular OpenSSL checkout by examining the value of the TLS1_3_VERSION_DRAFT_TXT macro in the tls1.h header file. This macro will be removed when the final version of the standard is released.

TLSv1.3 is enabled by default in the latest development versions (there is no need to explicitly enable it). To disable it at compile time you must use the “no-tls1_3” option to “config” or “Configure”.

Currently OpenSSL has implemented the “draft-26” version of TLSv1.3. Other applications that support TLSv1.3 may still be using older draft versions. This is a common source of interoperability problems. If two peers supporting different TLSv1.3 draft versions attempt to communicate then they will fall back to TLSv1.2.

== Ciphersuites ==

OpenSSL has implemented support for five TLSv1.3 ciphersuites as follows:

* TLS13-AES-256-GCM-SHA384
* TLS13-CHACHA20-POLY1305-SHA256
* TLS13-AES-128-GCM-SHA256
* TLS13-AES-128-CCM-8-SHA256
* TLS13-AES-128-CCM-SHA256

Due to the major differences between the way that ciphersuites for TLSv1.2 and below and ciphersuites for TLSv1.3 work, they are configured in OpenSSL differently too.

By default the first three of the above ciphersuites are enabled by default. This means that if you have no explicit ciphersuite configuration then you will automatically use those three and will be able to negotiate TLSv1.3. Note that changing the TLSv1.2 and below cipher list has no impact on the TLSv1.3 ciphersuite configuration.

For the OpenSSL command line applications there is a new "-ciphersuites" option to configure the TLSv1.3 ciphersuite list. This is just a simple colon (":") separated list of TLSv1.3 ciphersuite names in preference order. Note that you cannot use the special characters such as "+", "!", "-" etc, that you can for defining TLSv1.2 ciphersuites. In practice this is not likely to be a problem because there are only a very small number of TLSv1.3 ciphersuites.

For example:

$ openssl s_server -cert mycert.pem -key mykey.pem -cipher ECDHE -ciphersuites "TLS13-AES-256-GCM-SHA384:TLS13-CHACHA20-POLY1305-SHA256"

This will configure OpenSSL to use any ECDHE based ciphersuites for TLSv1.2 and below. For TLSv1.3 the TLS13-AES-256-GCM-SHA384 and TLS13-CHACHA20-POLY1305-SHA256 ciphersuites will be available.

Note that all of the above applies to the "ciphers" command line application as well. This can sometimes lead to surprising results. For example this command:

$ openssl ciphers -s -v ECDHE

Will list all the ciphersuites for TLSv1.2 and below that support ECDHE '''and''' additionally all of the default TLSv1.3 ciphersuites. Use the "-ciphersuites" option to further configure the TLSv1.3 ciphersuites.

== Groups ==

In TLSv1.3 the client selects a “group” that it will use for key exchange. At the time of writing, OpenSSL only supports ECDHE groups for this. The client then sends “key_share” information to the server for its selected group in the ClientHello.

The list of supported groups is configurable. It is possible for a client to select a group that the server does not support. In this case the server requests that the client sends a new key_share that it does support. While this means a connection will still be established (assuming a mutually supported group exists), it does introduce an extra server round trip - so this has implications for performance. In the ideal scenario the client will select a group that the server supports in the first instance.

In practice most clients will use X25519 or P-256 for their initial key_share. For maximum performance it is recommended that servers are configured to support at least those two groups and clients use one of those two for its initial key_share. This is the default case (OpenSSL clients will use X25519).

The group configuration also controls the allowed groups in TLSv1.2 and below. If applications have previously configured their groups in OpenSSL 1.1.0 then you should review that configuration to ensure that it still makes sense for TLSv1.3. The first named (i.e. most preferred group) will be the one used by an OpenSSL client in its intial key_share.

Applications can configure the group list by using SSL_CTX_set1_groups() or a similar function (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set1_groups.html here] for further details). Alternatively, if applications use SSL_CONF style configuration files then this can be configured using the Groups or Curves command (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS here]).

== Sessions ==

In TLSv1.2 and below a session is established as part of the handshake. This session can then be used in a subsequent connection to achieve an abbreviated handshake. Applications might typically obtain a handle on the session after a handshake has completed using the SSL_get1_session() function (or similar). See [https://www.openssl.org/docs/man1.1.1/man3/SSL_get1_session.html here] for further details.

In TLSv1.3 sessions are not established until after the main handshake has completed. The server sends a separate post-handshake message to the client containing the session details. Typically this will happen soon after the handshake has completed, but it could be sometime later (or not at all).

The specification recommends that applications only use a session once (although this may not be enforced). For this reason some servers send multiple session messages to a client. To enforce the “use once” recommendation applications could use SSL_CTX_remove_session() to mark a session as non-resumable (and remove it from the cache) once it has been used. OpenSSL servers that accept "early_data" will automatically enforce singly use sessions. Any attempt to resume with a session that has already been used will fallback to a full handshake.

The old SSL_get1_session() and similar APIs may not operate as expected for client applications written for TLSv1.2 and below. Specifically if a client application calls SSL_get1_session() before the server message containing session details has been received then an SSL_SESSION object will still be returned, but any attempt to resume with it will not succeed and a full handshake will occur instead. In the case where multiple sessions have been sent by the server then only the last session will be returned by SSL_get1_session().

Client application developers should consider using the SSL_CTX_sess_set_new_cb() API instead (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_sess_set_new_cb.html here]). This provides a callback mechanism which gets invoked every time a new session is established. This can get invoked multiple times for a single connection if a server sends multiple session messages.

Note that SSL_CTX_sess_set_new_cb() was also available in OpenSSL 1.1.0. Applications that already used that API will still work, but they may find that the callback is invoked at unexpected times, i.e. post-handshake.

An OpenSSL server will immediately attempt to send session details to a client after the main handshake has completed. To server applications this post-handshake stage will appear to be part of the main handshake, so calls to SSL_get1_session() should continue to work as before.

== Custom Extensions and Certificate Transparency ==

In TLSv1.2 and below the initial ClientHello and ServerHello messages can contain “extensions”. This allows the base specifications to be extended with additional features and capabilities that may not be applicable in all scenarios or could not be foreseen at the time that the base specifications were written. OpenSSL provides support for a number of “built-in” extensions.

Additionally the custom extensions API provides some basic capabilities for application developers to add support for new extensions that are not built-in to OpenSSL.

Built on top of the custom extensions API is the “serverinfo” API. This provides an even more basic interface that can be configured at run time. One use case for this is Certificate Transparency. OpenSSL provides built-in support for the client side of Certificate Transparency but there is no built-in server side support. However this can easily be achieved using “serverinfo” files. A serverinfo file containing the Certificate Transparency information can be configured within OpenSSL and it will then be sent back to the client as appropriate.

In TLSv1.3 the use of extensions is expanded significantly and there are many more messages that can include them. Additionally some extensions that were applicable to TLSv1.2 and below are no longer applicable in TLSv1.3 and some extensions are moved from the ServerHello message to the EncryptedExtensions message. The old custom extensions API does not have the ability to specify which messages the extensions should be associated with. For that reason a new custom extensions API was required.

The old API will still work, but the custom extensions will only be added where TLSv1.2 or below is negotiated. To add custom extensions that work for all TLS versions application developers will need to update their applications to the new API (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_add_custom_ext.html here] for details).

The “serverinfo” data format has also been updated to include additional information about which messages the extensions are relevant to. Applications using “serverinfo” files may need to update to the “version 2” file format to be able to operate in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_use_serverinfo.html here] for details).

== Renegotiation ==

TLSv1.3 does not have renegotiation so calls to SSL_renegotiate() or SSL_renegotiate_abbreviated() will immediately fail if invoked on a connection that has negotiated TLSv1.3.

A common use case for renegotiation is to update the connection keys. The function SSL_key_update() can be used for this purpose in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_key_update.html here] for further details).

Another use case is to request a certificate from the client. This can be achieved by using the SSL_verify_client_post_handshake() function in TLSv1.3 (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_verify_client_post_handshake.html here] for further details).

== DSA certificates ==

DSA certificates are no longer allowed in TLSv1.3. If your server application is using a DSA certificate then TLSv1.3 connections will fail with an error message similar to the following:

140348850206144:error:14201076:SSL routines:tls_choose_sigalg:no suitable signature algorithm:ssl/t1_lib.c:2308:

Please use an ECDSA or RSA certificate instead.

== Middlebox Compatibility Mode ==

During development of the TLSv1.3 standard it became apparent that in some cases, even if a client and server both support TLSv1.3, connections could sometimes still fail. This is because middleboxes on the network between the two peers do not understand the new protocol and prevent the connection from taking place. In order to work around this problem the TLSv1.3 specification introduced a “middlebox compatibility” mode. This made a few optional changes to the protocol to make it appear more like TLSv1.2 so that middleboxes would let it through. Largely these changes are superficial in nature but do include sending some small but unneccessary messages. OpenSSL has middlebox compatibility mode on by default, so most users should not need to worry about this. However applications may choose to switch it off by calling the function SSL_CTX_clear_options() and passing SSL_OP_ENABLE_MIDDLEBOX_COMPAT as an argument (see [https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_clear_options.html here] for further details).

If the remote peer is not using middlebox compatibility mode and there are problematic middleboxes on the network path then this could cause spurious connection failures.

== Server Name Indication ==

Server Name Indication (SNI) can be used by the client to select one of several sites on the same host, and so a different X.509 certificate can be send depending on the hostname that was send in the SNI extension. If an SNI is not send the options are to either disconnect or select a default hostname and matching certificate. The default would typically be the main site.

SNI has been made mandatory to implement in TLS 1.3 but not mandatory to use. Some people want to encourage the use of SNI and set up the default certificate to be for an invalid hostname if the client supports TLS 1.3. This is under the assumption that if a hostname is not send, that the client will check that the hostname of the certificate matches the hostname it's trying to connect to. For implementation that actually don't send the SNI, but do check the hostname this can cause connection failures.

To enable SNI you need to use the [https://www.openssl.org/docs/man1.1.1/man3/SSL_set_tlsext_host_name.html SSL_set_tlsext_host_name()] function.

== Conclusion ==

TLSv1.3 represents a significant step forward and has some exciting new features but there are some hazards for the unwary when upgrading. Mostly these issues have relatively straight forward solutions. Application developers should review their code and consider whether anything should be updated in order to work more effectively with TLSv1.3. Similarly application deployers should review their configuration.

Main Page

2018-04-20T08:10:17Z

Kurt:

This is the OpenSSL wiki. The main site is https://www.openssl.org . If this is your first visit or to get an account please see the [[Welcome]] page. Your participation and [[Contributions]] are valued.

This wiki is intended as a place for collecting, organizing, and refining useful information about OpenSSL that is currently strewn among multiple locations and formats.

== OpenSSL Quick Links ==

<TABLE border=0>
<TR>
<TD>[[OpenSSL Overview]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Compilation and Installation]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Internals]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Mailing Lists]] </TD>
</TR>
<TR>
<TD>[[libcrypto API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[libssl API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Examples]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Documentation Index|Index of all API functions]]</TD>
</TR>
<TR>
<TD>[[License]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Command Line Utilities]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Related Links]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Binaries]]</TD>
</TR>
<TR>
<TD>[[SSL and TLS Protocols]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[1.1 API Changes]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[FIPS modules]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[TLS1.3]]</TD>
</TR>
</TABLE>

== Administrivia ==
Site guidelines, legal and admininstrative issues.
:* [[Basic rules]], [[Commercial Product Disclaimer]], [[Contributions]], [[Copyright]], [[License]]
:* Using This Wiki
:: [http://meta.wikimedia.org/wiki/Help:Contents Wiki User's Guide], [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list], [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ], [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki Mailing List]

== Reference ==
This section contains the automagically generated man pages from the OpenSSL git repository, and similar "man" style reference documentation. The man pages are automatically imported from the OpenSSL git repository and local wiki modifications are submitted as patches.
:* [https://www.openssl.org/docs/manpages.html OpenSSL Manual Pages]
:* [[API]], [[Libcrypto API]], [[Libssl API]]
:* [[FIPS mode()]], [[FIPS_mode_set()]]

== Usage and Programming ==
This section has discussions of practical issues in using OpenSSL
:* Building from Source
:: Where to find it, the different versions, how to build and install it.
:* [[OpenSSL Overview]]
:* [[Versioning]]
:* [[Compilation and Installation]]
:* [[EVP]]
:: Programming techniques and example code
:: Use of EVP is preferred for most applications and circumstances
::* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
::* [[EVP Authenticated Encryption and Decryption]]
::* [[EVP Symmetric Encryption and Decryption]]
::* [[EVP Key and Parameter Generation]]
::* [[EVP Key Agreement]]
::* [[EVP Message Digests]]
::* [[EVP Key Derivation]]
::* [[EVP Signing and Verifying|EVP Signing and Verifying (including MAC codes)]]
:* [[STACK API]]
:* [[List of SSL OP Flags]]
:* Low Level APIs
::[[Creating an OpenSSL Engine to use indigenous ECDH ECDSA and HASH Algorithms]]
:: More specialized non-EVP usage
::* [[Diffie-Hellman parameters]]
:* [[FIPS Mode]]
:* [[Simple TLS Server]]

== Concepts and Theory ==
Discussions of basic cryptographic theory and concepts
Discussions of common operational issues
:* [[Base64]]
:* [http://wiki.openssl.org/index.php/Category:FIPS_140 FIPS 140-2]
:* [[Random Numbers]]
:* [[Diffie Hellman]]
:* [[Elliptic Curve Diffie Hellman]]
:* [[Elliptic Curve Cryptography]]

== Security Advisories ==
:* [https://www.openssl.org/policies/secpolicy.html OpenSSL Security Policy]
:* [https://www.openssl.org/news/vulnerabilities.html OpenSSL Vulnerabilities List]
:* [[Security_Advisories|Security Advisories Additional Information]]

== Feedback and Contributions ==
:* [https://www.openssl.org/news/vulnerabilities.html How to notify us of suspected security vulnerabilities]
:* [https://www.openssl.org/community/#bugs How to report bugs, other than for suspected vulnerabilities]
:* [[Contributions|General background on source and documentation contributions - '''must read''']]
:* Contributing code fixes, other than for suspected vulnerabilities, as well as fixes and other improvements to manual pages:
::* If you are unsure as to whether a feature will be useful for the general OpenSSL community please discuss it on the [https://www.openssl.org/community/ openssl-users mailing list] first. Someone may be already working on the same thing or there may be a good reason as to why that feature isn't implemented.
::* Follow the [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|instructions for accessing source code]] in the appropriate branches. Note that manual pages and the FAQ are maintained with the source code.
::* Submit a pull request for each separate fix (also documented [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|there]])
::* Submit a bug report (see second bullet, above) and reference the pull request. Or you can attach the patch to the ticket.
:* Contributing fixes and other improvements to the web site
::* Follow the [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|instructions for accessing web site sources]]
::* Create a patch (also documented [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|there]])
::* Submit a bug report and add the patch as an attachment
:* [[Developing For OpenSSL]]
:* [[KnownPatches|Known patches not part of OpenSSL]]
:* [[Welcome|Contributing to this wiki]]

== Internals and Development ==
This section is for internal details of primary interest to OpenSSL maintainers and power users
:* [[Code reformatting]]

:* [[Internals]]
:* [[Code Quality]]
:* [[Static and Dynamic Analysis]]
:* [[OCB|OCB Licence details]]
:* [[Defect and Feature Review Process]]
:* [[Unit Testing]] (includes other automated testing information)
:* [[How to Integrate a Symmetric Cipher]]

TLS1.3

2018-04-20T08:09:12Z

Kurt: Import from blog

OpenSSL 1.1.0 Changes

2016-11-04T15:48:25Z

Kurt: /* Adding forward-compatible code to older versions */

This is a parent page for discussion about API changes being done for OpenSSL version 1.1

The overall goal of this project is to make most data structures opaque to applications. This provides us with a number of benefits:
* We can add fields without breaking [[Binary_Compatibility|binary compatibility]]
* Applications are more robust and can be more assured about correctness
* It helps us determine which (new) accessors and settors, for example, are needed

Please add sub-pages to discuss particular parts of the library as work progresses.

== Major Changes so far ==

* All structures in libssl public header files have been removed so that they are "opaque" to library users. You should use the provided accessor functions instead
* The old DES API has been removed
* bn, a sub library in libcrypto, has been made opaque
* Access to deprecated functions/macros has been removed by default. To enable access you must do two things. 1) Build OpenSSL with deprecation support (pass "enable-deprecated" as an argument to config) 2) Applications must define "OPENSSL_USE_DEPRECATED" before including OpenSSL header files
* HMAC_Init and HMAC_cleanup were previously stated in the docs and header files as being deprecated - but were not flagged in previous versions with OPENSSL_NO_DEPRECATED. This has been corrected in 1.1.0. Access to these functions/macros will be off by default in 1.1.0 as per the note above about deprecation.

== OPENSSL_API_COMPAT ==

Various functions get deprecated as other interfaces get added, but are still available in a default build.
The include files support setting the OPENSSL_API_COMPAT define that will hide functions that are deprecated in the selected version.
To select the 1.1.0 version use -DOPENSSL_API_COMPAT=0x10100000L.

== Backward compatibility ==

Since some structures have become opaque you can't directly access the member any more. You might need to create backward compatible macros or functions if you still want to support older versions of OpenSSL. A suggested way of doing that is:

<code>
#if OPENSSL_VERSION_NUMBER < 0x10100000L
#define OBJ_get0_data(o) ((o)->data)
#define OBJ_length(o) ((o)->length)
#endif
</code>

== Adding forward-compatible code to older versions ==

Application code now has to use pointers, and cannot allocate objects directly on the stack. For instance if the old code did:

<code>
BN_CTX ctx;
</code>

You now have to do:
<code>
BN_CTX *ctx;

ctx = BN_CTX_new();
[...]
BN_CTX_free(ctx);
</code>

If you want to access rsa->n you now have to do something like:
<code>
const BIGNUM *n;

RSA_get0_key(rsa, &n, NULL, NULL);
</code>

There are new functions available for to get and set such variables that are not available in older versions. The suggested way to solve this is add your own copy of the new functions based on the one in OpenSSL 1.1.0. Here is an overview of most of them and how they could look like:
<code>
#if OPENSSL_VERSION_NUMBER < 0x10100000L

#include <string.h>
#include <openssl/engine.h>

static void *OPENSSL_zalloc(size_t num)
{
void *ret = OPENSSL_malloc(num);

if (ret != NULL)
memset(ret, 0, num);
return ret;
}

int RSA_set0_key(RSA *r, BIGNUM *n, BIGNUM *e, BIGNUM *d)
{
/* If the fields n and e in r are NULL, the corresponding input
* parameters MUST be non-NULL for n and e. d may be
* left NULL (in case only the public key is used).
*/
if ((r->n == NULL && n == NULL)
|| (r->e == NULL && e == NULL))
return 0;

if (n != NULL) {
BN_free(r->n);
r->n = n;
}
if (e != NULL) {
BN_free(r->e);
r->e = e;
}
if (d != NULL) {
BN_free(r->d);
r->d = d;
}

return 1;
}

int RSA_set0_factors(RSA *r, BIGNUM *p, BIGNUM *q)
{
/* If the fields p and q in r are NULL, the corresponding input
* parameters MUST be non-NULL.
*/
if ((r->p == NULL && p == NULL)
|| (r->q == NULL && q == NULL))
return 0;

if (p != NULL) {
BN_free(r->p);
r->p = p;
}
if (q != NULL) {
BN_free(r->q);
r->q = q;
}

return 1;
}

int RSA_set0_crt_params(RSA *r, BIGNUM *dmp1, BIGNUM *dmq1, BIGNUM *iqmp)
{
/* If the fields dmp1, dmq1 and iqmp in r are NULL, the corresponding input
* parameters MUST be non-NULL.
*/
if ((r->dmp1 == NULL && dmp1 == NULL)
|| (r->dmq1 == NULL && dmq1 == NULL)
|| (r->iqmp == NULL && iqmp == NULL))
return 0;

if (dmp1 != NULL) {
BN_free(r->dmp1);
r->dmp1 = dmp1;
}
if (dmq1 != NULL) {
BN_free(r->dmq1);
r->dmq1 = dmq1;
}
if (iqmp != NULL) {
BN_free(r->iqmp);
r->iqmp = iqmp;
}

return 1;
}

void RSA_get0_key(const RSA *r,
const BIGNUM **n, const BIGNUM **e, const BIGNUM **d)
{
if (n != NULL)
*n = r->n;
if (e != NULL)
*e = r->e;
if (d != NULL)
*d = r->d;
}

void RSA_get0_factors(const RSA *r, const BIGNUM **p, const BIGNUM **q)
{
if (p != NULL)
*p = r->p;
if (q != NULL)
*q = r->q;
}

void RSA_get0_crt_params(const RSA *r,
const BIGNUM **dmp1, const BIGNUM **dmq1,
const BIGNUM **iqmp)
{
if (dmp1 != NULL)
*dmp1 = r->dmp1;
if (dmq1 != NULL)
*dmq1 = r->dmq1;
if (iqmp != NULL)
*iqmp = r->iqmp;
}

void DSA_get0_pqg(const DSA *d,
const BIGNUM **p, const BIGNUM **q, const BIGNUM **g)
{
if (p != NULL)
*p = d->p;
if (q != NULL)
*q = d->q;
if (g != NULL)
*g = d->g;
}

int DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g)
{
/* If the fields p, q and g in d are NULL, the corresponding input
* parameters MUST be non-NULL.
*/
if ((d->p == NULL && p == NULL)
|| (d->q == NULL && q == NULL)
|| (d->g == NULL && g == NULL))
return 0;

if (p != NULL) {
BN_free(d->p);
d->p = p;
}
if (q != NULL) {
BN_free(d->q);
d->q = q;
}
if (g != NULL) {
BN_free(d->g);
d->g = g;
}

return 1;
}

void DSA_get0_key(const DSA *d,
const BIGNUM **pub_key, const BIGNUM **priv_key)
{
if (pub_key != NULL)
*pub_key = d->pub_key;
if (priv_key != NULL)
*priv_key = d->priv_key;
}

int DSA_set0_key(DSA *d, BIGNUM *pub_key, BIGNUM *priv_key)
{
/* If the field pub_key in d is NULL, the corresponding input
* parameters MUST be non-NULL. The priv_key field may
* be left NULL.
*/
if (d->pub_key == NULL && pub_key == NULL)
return 0;

if (pub_key != NULL) {
BN_free(d->pub_key);
d->pub_key = pub_key;
}
if (priv_key != NULL) {
BN_free(d->priv_key);
d->priv_key = priv_key;
}

return 1;
}

void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps)
{
if (pr != NULL)
*pr = sig->r;
if (ps != NULL)
*ps = sig->s;
}

int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s)
{
if (r == NULL || s == NULL)
return 0;
BN_clear_free(sig->r);
BN_clear_free(sig->s);
sig->r = r;
sig->s = s;
return 1;
}

void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps)
{
if (pr != NULL)
*pr = sig->r;
if (ps != NULL)
*ps = sig->s;
}

int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s)
{
if (r == NULL || s == NULL)
return 0;
BN_clear_free(sig->r);
BN_clear_free(sig->s);
sig->r = r;
sig->s = s;
return 1;
}

void DH_get0_pqg(const DH *dh,
const BIGNUM **p, const BIGNUM **q, const BIGNUM **g)
{
if (p != NULL)
*p = dh->p;
if (q != NULL)
*q = dh->q;
if (g != NULL)
*g = dh->g;
}

int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g)
{
/* If the fields p and g in d are NULL, the corresponding input
* parameters MUST be non-NULL. q may remain NULL.
*/
if ((dh->p == NULL && p == NULL)
|| (dh->g == NULL && g == NULL))
return 0;

if (p != NULL) {
BN_free(dh->p);
dh->p = p;
}
if (q != NULL) {
BN_free(dh->q);
dh->q = q;
}
if (g != NULL) {
BN_free(dh->g);
dh->g = g;
}

if (q != NULL) {
dh->length = BN_num_bits(q);
}

return 1;
}

void DH_get0_key(const DH *dh, const BIGNUM **pub_key, const BIGNUM **priv_key)
{
if (pub_key != NULL)
*pub_key = dh->pub_key;
if (priv_key != NULL)
*priv_key = dh->priv_key;
}

int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key)
{
/* If the field pub_key in dh is NULL, the corresponding input
* parameters MUST be non-NULL. The priv_key field may
* be left NULL.
*/
if (dh->pub_key == NULL && pub_key == NULL)
return 0;

if (pub_key != NULL) {
BN_free(dh->pub_key);
dh->pub_key = pub_key;
}
if (priv_key != NULL) {
BN_free(dh->priv_key);
dh->priv_key = priv_key;
}

return 1;
}

int DH_set_length(DH *dh, long length)
{
dh->length = length;
return 1;
}

const unsigned char *EVP_CIPHER_CTX_iv(const EVP_CIPHER_CTX *ctx)
{
return ctx->iv;
}

unsigned char *EVP_CIPHER_CTX_iv_noconst(EVP_CIPHER_CTX *ctx)
{
return ctx->iv;
}

EVP_MD_CTX *EVP_MD_CTX_new(void)
{
return OPENSSL_zalloc(sizeof(EVP_MD_CTX));
}

void EVP_MD_CTX_free(EVP_MD_CTX *ctx)
{
EVP_MD_CTX_cleanup(ctx);
OPENSSL_free(ctx);
}

RSA_METHOD *RSA_meth_dup(const RSA_METHOD *meth)
{
RSA_METHOD *ret;

ret = OPENSSL_malloc(sizeof(RSA_METHOD));

if (ret != NULL) {
memcpy(ret, meth, sizeof(*meth));
ret->name = OPENSSL_strdup(meth->name);
if (ret->name == NULL) {
OPENSSL_free(ret);
return NULL;
}
}

return ret;
}

int RSA_meth_set1_name(RSA_METHOD *meth, const char *name)
{
char *tmpname;

tmpname = OPENSSL_strdup(name);
if (tmpname == NULL) {
return 0;
}

OPENSSL_free((char *)meth->name);
meth->name = tmpname;

return 1;
}

int RSA_meth_set_priv_enc(RSA_METHOD *meth,
int (*priv_enc) (int flen, const unsigned char *from,
unsigned char *to, RSA *rsa,
int padding))
{
meth->rsa_priv_enc = priv_enc;
return 1;
}

int RSA_meth_set_priv_dec(RSA_METHOD *meth,
int (*priv_dec) (int flen, const unsigned char *from,
unsigned char *to, RSA *rsa,
int padding))
{
meth->rsa_priv_dec = priv_dec;
return 1;
}

int RSA_meth_set_finish(RSA_METHOD *meth, int (*finish) (RSA *rsa))
{
meth->finish = finish;
return 1;
}

void RSA_meth_free(RSA_METHOD *meth)
{
if (meth != NULL) {
OPENSSL_free((char *)meth->name);
OPENSSL_free(meth);
}
}

int RSA_bits(const RSA *r)
{
return (BN_num_bits(r->n));
}

RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey)
{
if (pkey->type != EVP_PKEY_RSA) {
return NULL;
}
return pkey->pkey.rsa;
}

HMAC_CTX *HMAC_CTX_new(void)
{
HMAC_CTX *ctx = OPENSSL_malloc(sizeof(*ctx));
if (ctx != NULL) {
if (!HMAC_CTX_reset(ctx)) {
HMAC_CTX_free(ctx);
return NULL;
}
}
return ctx;
}

void HMAC_CTX_free(HMAC_CTX *ctx)
{
if (ctx != NULL) {
hmac_ctx_cleanup(ctx);
EVP_MD_CTX_free(ctx->i_ctx);
EVP_MD_CTX_free(ctx->o_ctx);
EVP_MD_CTX_free(ctx->md_ctx);
OPENSSL_free(ctx);
}
}
#endif
</code>

== Things that Broke in Qt ==

Here's what's broken in the dev branch of Qt when building openssl master as of 6 Feb 2015.

* DH - we were directly accessing p and q to set the DH params to primes embedded in Qt. We can probably replace this with SSL_CTX_set_dh_auto(ctx, 1). Another option suggested by Steve Henson is to save the DHparams we're using at the moment then use d2i_DHparams to load them in. This is compatible with openssl versions that don't have the dh_auto option.

* ctx->cert_store - we were directly accessing the cert_store field of SSL_CTX. We can probably replace this with X509_STORE *SSL_CTX_get_cert_store(SSL_CTX *ctx) [Fixed in dev]

* session->tlsext_tick_lifetime_hint - we were directly accessing the lifetime hint of the session. [A new API to access this field has been added]

* cipher->valid - we were directly accessing the valid field of SSL_CIPHER. No replacement found. [This turned out not to be needed and so will be removed].

== Things that Broke in Curl ==

* SSL_SESSION->ssl_version. Replaced with SSL_version(SSL *)

== Things that Broke in wget ==

* SSL->state. Replaced with SSL_state(SSL *)

== Things that Broke in Apache Traffic Manager ==

* Setting SSL->rbio without setting SSL->wbio. New function introduction in 1.1.0 to handle this: SSL_set_rbio()

== Things that Broke in OpenConnect ==

In order to simulate "resume" of a DTLS session which never really existed but which was actually negotiated over the VPN control connection, [http://git.infradead.org/users/dwmw2/openconnect.git/blob/fa5cea08:/dtls.c#l147 this code] in the [http://www.infradead.org/openconnect/ OpenConnect VPN client] needs to set the following fields in a new <tt>SSL_SESSION</tt>:
* <tt>->ssl_version</tt>
* <tt>->cipher{,_id}</tt>
* <tt>->master_key{,_length}</tt>
* <tt>->session_id{,_length}</tt>

This was fixed with [http://git.infradead.org/users/dwmw2/openconnect.git/commitdiff/5abb133f this OpenConnect commit] which makes it create the ASN.1 representation of the session and import it with <tt>d2i_SSL_SESSION()</tt>. This is done conditionally in the above patch because it depends on the [http://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff;h=af674d4e20a82c2a98767b837072d7093c70b1cf fix in openssl HEAD] for <tt>d2i_SSL_SESSION()</tt> to make it cope with <tt>DTLS1_BAD_VER</tt> <i>([http://rt.openssl.org/Ticket/Display.html?id=3704 RT#3704])</i>.

Other simpler things which broke:
* <tt>SSL_CIPHER->id</tt>. Replaced with <tt>SSL_CIPHER_get_id()</tt>
* <tt>SSL_CTX->extra_certs</tt>. Replaced with <tt>SSL_CTX_get_extra_chain_certs_only()</tt>

== Things that Broke in TianoCore/EDKII ==

EDKII is the reference implementation of UEFI firmware.

* Various implicit inclusions of <tt><openssl/bn.h></tt> and <tt><openssl/rsa.h></tt> needed to be made explicit. ''[http://git.infradead.org/users/dwmw2/edk2.git/commitdiff/8d7d32c1 (commit)]''
* <tt>X509_NAME->bytes->{data,length}</tt>. Replaced with <tt>i2d_X509_NAME()</tt> ''[http://git.infradead.org/users/dwmw2/edk2.git/commitdiff/e192c51b (commit)]''
* <tt>X509_ATTRIBUTE->{object,value}</tt>. Replaced with <tt>X509_ATTRIBUTE_get0_object()</tt> and <tt>X509_ATTRIBUTE_get0_type()</tt> ''[http://git.infradead.org/users/dwmw2/edk2.git/commitdiff/1bd8ee96 (commit)]''
* <tt>ASN1_OBJECT->{length,data}</tt>. Replaced with <tt>OBJ_get0_data()</tt> and <tt>OBJ_length()</tt>. With backward-compatibility <tt>#define</tt> of same. ''[http://git.infradead.org/users/dwmw2/edk2.git/commitdiff/6a7a36edc (commit)]''

OpenSSL 1.1.0 Changes

2016-06-15T20:24:05Z

Kurt: Add example of backward compatible macro

OpenSSL 1.1.0 Changes

2016-06-15T20:02:00Z

Kurt: Add OPENSSL_API_COMPAT