TLS1.3 - Revision history

Matt: /* Differences with TLS1.2 and below */ typo fix

2022-03-28T13:46:31Z

Differences with TLS1.2 and below: typo fix

Kurt: /* Non-application data records */

2018-10-07T16:47:40Z

Non-application data records

Matt: /* Ciphersuites */ Add note about the TLSv1.3 ciphersuite API functions

2018-09-12T15:14:25Z

Ciphersuites: Add note about the TLSv1.3 ciphersuite API functions

Kurt: /* Sessions */

2018-09-05T20:58:47Z

Sessions

Kurt: /* Sessions */

2018-09-05T20:50:16Z

Sessions

Kurt: /* Sessions */

2018-09-05T20:04:45Z

Sessions

Kurt at 19:54, 26 August 2018

2018-08-26T19:54:58Z

Kurt: /* Sessions */

2018-08-26T19:51:51Z

Sessions

Kurt: /* Non-application data records */

2018-08-26T11:28:20Z

Non-application data records

Kurt: Add section about non-application data

2018-08-26T10:48:30Z

Add section about non-application data

@@ Line 6: / Line 6: @@
 * 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.
+* 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 ECDHE). 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.

@@ Line 147: / Line 147: @@
 == 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.
+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.

← Older revision		Revision as of 15:14, 12 September 2018
Line 39:		Line 39:

	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.		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 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.

@@ Line 84: / Line 84: @@
 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.
+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 ==

@@ Line 84: / Line 84: @@
 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.
+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 ==

@@ Line 82: / Line 82: @@
 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.
+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.
 == Custom Extensions and Certificate Transparency ==

@@ Line 64: / Line 64: @@
 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]).
+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/man1.1.1/man3/SSL_get1_session.html SSL_get1_session()] function (or similar).
+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/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 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/man1.1.1/man3/SSL_SESSION_is_resumable.html SSL_SESSION_is_resumable()].
+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/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.
+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.
@@ Line 94: / Line 94: @@
 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 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/man1.1.1/man3/SSL_CTX_use_serverinfo.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 ==
@@ Line 102: / Line 102: @@
 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).
+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/man1.1.1/man3/SSL_verify_client_post_handshake.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 ==
@@ Line 114: / Line 114: @@
 == 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).
+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.
@@ Line 124: / Line 124: @@
 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]].
+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 ==
@@ Line 134: / Line 134: @@
 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.
+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.