From bedddd707a0a36b4052e48be2abffdb6c3c44c45 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 27 Aug 2024 14:18:50 +0200 Subject: [PATCH 01/16] Add mbedtls_ssl_conf_enable_new_session_tickets() API Add mbedtls_ssl_conf_enable_new_session_tickets() API to be able to enable and disable the handling of TLS 1.3 NewSessionTicket messages. The TLS 1.2 equivalent function is named mbedtls_ssl_conf_session_tickets() thus the most natural name would have been mbedtls_ssl_conf_new_session_tickets() but it is already used on server side thus rather mbedtls_ssl_conf_enable_new_session_tickets(). Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 23 +++++++++++++++++++++++ library/ssl_tls.c | 12 +++++++++++- 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 466c734d37..1f07fb3b7d 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -324,6 +324,9 @@ #define MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0 #define MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1 +#define MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_DISABLED 0 +#define MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED 1 + #define MBEDTLS_SSL_PRESET_DEFAULT 0 #define MBEDTLS_SSL_PRESET_SUITEB 2 @@ -1447,6 +1450,12 @@ struct mbedtls_ssl_config { #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \ defined(MBEDTLS_SSL_CLI_C) uint8_t MBEDTLS_PRIVATE(session_tickets); /*!< use session tickets? */ +#if defined(MBEDTLS_SSL_PROTO_TLS1_3) + /** Whether we handle NewSessionTicket TLS 1.3 messages (<>0) or just ignore them (==0) + * They are ignored by default. + */ + uint8_t MBEDTLS_PRIVATE(new_session_tickets_enabled); +#endif #endif #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \ @@ -4478,6 +4487,20 @@ void mbedtls_ssl_conf_preference_order(mbedtls_ssl_config *conf, int order); * MBEDTLS_SSL_SESSION_TICKETS_DISABLED) */ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets); + +#if defined(MBEDTLS_SSL_PROTO_TLS1_3) +/** + * \brief Enable / Disable TLS 1.3 handling of NewSessionTicket messages (client and TLS 1.3 only). + * (Default: MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_DISABLED) + * + * \param conf SSL configuration + * \param new_session_tickets_enabled Enable or disable + * (MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED or + * MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_DISABLED) + */ +void mbedtls_ssl_conf_enable_new_session_tickets(mbedtls_ssl_config *conf, + int new_session_tickets_enabled); +#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ diff --git a/library/ssl_tls.c b/library/ssl_tls.c index d6077a2baa..21d70af772 100644 --- a/library/ssl_tls.c +++ b/library/ssl_tls.c @@ -3013,7 +3013,14 @@ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets) { conf->session_tickets = use_tickets; } -#endif +#if defined(MBEDTLS_SSL_PROTO_TLS1_3) +void mbedtls_ssl_conf_enable_new_session_tickets(mbedtls_ssl_config *conf, + int new_session_tickets_enabled) +{ + conf->new_session_tickets_enabled = new_session_tickets_enabled; +} +#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ +#endif /* MBEDTLS_SSL_CLI_C */ #if defined(MBEDTLS_SSL_SRV_C) @@ -5879,6 +5886,9 @@ int mbedtls_ssl_config_defaults(mbedtls_ssl_config *conf, conf->authmode = MBEDTLS_SSL_VERIFY_REQUIRED; #if defined(MBEDTLS_SSL_SESSION_TICKETS) conf->session_tickets = MBEDTLS_SSL_SESSION_TICKETS_ENABLED; +#if defined(MBEDTLS_SSL_PROTO_TLS1_3) + conf->new_session_tickets_enabled = MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_DISABLED; +#endif #endif } #endif From b675b2ba5dfc9223b610d066557bf81db077b479 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 27 Aug 2024 09:19:40 +0200 Subject: [PATCH 02/16] TLS 1.3: Ignore tickets if disabled at runtime Signed-off-by: Ronald Cron --- library/ssl_msg.c | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/library/ssl_msg.c b/library/ssl_msg.c index 2bdad848a9..65ad324337 100644 --- a/library/ssl_msg.c +++ b/library/ssl_msg.c @@ -5595,11 +5595,17 @@ static int ssl_tls13_handle_hs_message_post_handshake(mbedtls_ssl_context *ssl) if (ssl_tls13_is_new_session_ticket(ssl)) { #if defined(MBEDTLS_SSL_SESSION_TICKETS) MBEDTLS_SSL_DEBUG_MSG(3, ("NewSessionTicket received")); - ssl->keep_current_message = 1; + if (ssl->conf->new_session_tickets_enabled == + MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED) { + ssl->keep_current_message = 1; - mbedtls_ssl_handshake_set_state(ssl, - MBEDTLS_SSL_TLS1_3_NEW_SESSION_TICKET); - return MBEDTLS_ERR_SSL_WANT_READ; + mbedtls_ssl_handshake_set_state(ssl, + MBEDTLS_SSL_TLS1_3_NEW_SESSION_TICKET); + return MBEDTLS_ERR_SSL_WANT_READ; + } else { + MBEDTLS_SSL_DEBUG_MSG(3, ("Ignore NewSessionTicket, disabled.")); + return 0; + } #else MBEDTLS_SSL_DEBUG_MSG(3, ("Ignore NewSessionTicket, not supported.")); return 0; From 23303a47f4f02fb4ff71aa2b006a83383901aebd Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 27 Aug 2024 09:27:28 +0200 Subject: [PATCH 03/16] Enable TLS 1.3 ticket handling in resumption tests Signed-off-by: Ronald Cron --- programs/ssl/ssl_client2.c | 18 +++++++++++++++--- tests/src/test_helpers/ssl_helpers.c | 3 +++ 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/programs/ssl/ssl_client2.c b/programs/ssl/ssl_client2.c index cd839c1610..cf21569697 100644 --- a/programs/ssl/ssl_client2.c +++ b/programs/ssl/ssl_client2.c @@ -82,6 +82,7 @@ int main(void) #define DFL_CID_VALUE_RENEGO NULL #define DFL_RECONNECT_HARD 0 #define DFL_TICKETS MBEDTLS_SSL_SESSION_TICKETS_ENABLED +#define DFL_NEW_SESSION_TICKETS MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED #define DFL_ALPN_STRING NULL #define DFL_GROUPS NULL #define DFL_SIG_ALGS NULL @@ -198,7 +199,8 @@ int main(void) #if defined(MBEDTLS_SSL_SESSION_TICKETS) #define USAGE_TICKETS \ - " tickets=%%d default: 1 (enabled)\n" + " tickets=%%d default: 1 (enabled)\n" \ + " new_session_tickets=%%d default: 1 (enabled)\n" #else #define USAGE_TICKETS "" #endif /* MBEDTLS_SSL_SESSION_TICKETS */ @@ -514,7 +516,8 @@ struct options { int reco_delay; /* delay in seconds before resuming session */ int reco_mode; /* how to keep the session around */ int reconnect_hard; /* unexpectedly reconnect from the same port */ - int tickets; /* enable / disable session tickets */ + int tickets; /* enable / disable session tickets (TLS 1.2) */ + int new_session_tickets; /* enable / disable new session tickets (TLS 1.3) */ const char *groups; /* list of supported groups */ const char *sig_algs; /* supported TLS 1.3 signature algorithms */ const char *alpn_string; /* ALPN supported protocols */ @@ -969,6 +972,7 @@ int main(int argc, char *argv[]) opt.reco_mode = DFL_RECO_MODE; opt.reconnect_hard = DFL_RECONNECT_HARD; opt.tickets = DFL_TICKETS; + opt.new_session_tickets = DFL_NEW_SESSION_TICKETS; opt.alpn_string = DFL_ALPN_STRING; opt.groups = DFL_GROUPS; opt.sig_algs = DFL_SIG_ALGS; @@ -1226,6 +1230,11 @@ usage: if (opt.tickets < 0) { goto usage; } + } else if (strcmp(p, "new_session_tickets") == 0) { + opt.tickets = atoi(q); + if (opt.new_session_tickets < 0) { + goto usage; + } } else if (strcmp(p, "alpn") == 0) { opt.alpn_string = q; } else if (strcmp(p, "extended_ms") == 0) { @@ -1936,7 +1945,10 @@ usage: #if defined(MBEDTLS_SSL_SESSION_TICKETS) mbedtls_ssl_conf_session_tickets(&conf, opt.tickets); -#endif +#if defined(MBEDTLS_SSL_PROTO_TLS1_3) + mbedtls_ssl_conf_enable_new_session_tickets(&conf, opt.new_session_tickets); +#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ +#endif /* MBEDTLS_SSL_SESSION_TICKETS */ if (opt.force_ciphersuite[0] != DFL_FORCE_CIPHER) { mbedtls_ssl_conf_ciphersuites(&conf, opt.force_ciphersuite); diff --git a/tests/src/test_helpers/ssl_helpers.c b/tests/src/test_helpers/ssl_helpers.c index f546e76021..7d5d889ce3 100644 --- a/tests/src/test_helpers/ssl_helpers.c +++ b/tests/src/test_helpers/ssl_helpers.c @@ -2543,6 +2543,9 @@ int mbedtls_test_get_tls13_ticket( server_options, NULL, NULL, NULL); TEST_EQUAL(ret, 0); + mbedtls_ssl_conf_enable_new_session_tickets( + &client_ep.conf, MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED); + mbedtls_ssl_conf_session_tickets_cb(&server_ep.conf, mbedtls_test_ticket_write, mbedtls_test_ticket_parse, From 0e5d4fdfc56540ecc23809f006e83f5cea3c26a5 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 27 Aug 2024 14:29:55 +0200 Subject: [PATCH 04/16] Document MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET. Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 1f07fb3b7d..ae70f8adb2 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -84,8 +84,13 @@ #define MBEDTLS_ERR_SSL_BAD_CERTIFICATE -0x7A00 /* Error space gap */ /** - * Received NewSessionTicket Post Handshake Message. - * This error code is experimental and may be changed or removed without notice. + * A TLS 1.3 NewSessionTicket message has been received. + * This error code can be returned only on client side if and only if handling + * of TLS 1.3 NewSessionTicket messages has been enabled through the + * mbedtls_ssl_conf_enable_new_session_tickets() API. This error + * code can then be returned by mbedtls_ssl_handshake(), + * mbedtls_ssl_handshake_step(), mbedtls_ssl_read(), mbedtls_ssl_write() and + * mbedtls_ssl_write_early_data(). */ #define MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET -0x7B00 /** Not possible to read early data */ @@ -4910,6 +4915,13 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl, * \return #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED if DTLS is in use * and the client did not demonstrate reachability yet - in * this case you must stop using the context (see below). + * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 + * NewSessionTicket message has been received. This is client + * specific and may occur only if the handling of + * NewSessionTicket message has been enabled (see + * mbedtls_ssl_conf_enable_new_session_tickets() documentation). + * You may call mbedtls_ssl_get_session() to retrieve the + * ticket data. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific @@ -4926,6 +4938,7 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl, * #MBEDTLS_ERR_SSL_WANT_WRITE, * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, * you must stop using the SSL context for reading or writing, * and either free it or call \c mbedtls_ssl_session_reset() @@ -5000,6 +5013,7 @@ static inline int mbedtls_ssl_is_handshake_over(mbedtls_ssl_context *ssl) * #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using * the SSL context for reading or writing, and either free it * or call \c mbedtls_ssl_session_reset() on it before @@ -5068,6 +5082,13 @@ int mbedtls_ssl_renegotiate(mbedtls_ssl_context *ssl); * \return #MBEDTLS_ERR_SSL_CLIENT_RECONNECT if we're at the server * side of a DTLS connection and the client is initiating a * new connection using the same source port. See below. + * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 + * NewSessionTicket message has been received. This is client + * specific and may occur only if the handling of + * NewSessionTicket message has been enabled (see + * mbedtls_ssl_conf_enable_new_session_tickets() documentation). + * You may call mbedtls_ssl_get_session() to retrieve the + * ticket data. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific @@ -5085,6 +5106,7 @@ int mbedtls_ssl_renegotiate(mbedtls_ssl_context *ssl); * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, * #MBEDTLS_ERR_SSL_CLIENT_RECONNECT or + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, * you must stop using the SSL context for reading or writing, * and either free it or call \c mbedtls_ssl_session_reset() @@ -5150,6 +5172,13 @@ int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len); * operation is in progress (see mbedtls_ecp_set_max_ops()) - * in this case you must call this function again to complete * the handshake when you're done attending other tasks. + * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 + * NewSessionTicket message has been received. This is client + * specific and may occur only if the handling of + * NewSessionTicket message has been enabled (see + * mbedtls_ssl_conf_enable_new_session_tickets() documentation). + * You may call mbedtls_ssl_get_session() to retrieve the + * ticket data. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific @@ -5166,6 +5195,7 @@ int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len); * #MBEDTLS_ERR_SSL_WANT_WRITE, * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET or * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, * you must stop using the SSL context for reading or writing, * and either free it or call \c mbedtls_ssl_session_reset() From 9df056390ae7ff70560b0e3c47f167495df71aab Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 27 Aug 2024 18:04:44 +0200 Subject: [PATCH 05/16] Improve MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET documentation Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 32 +++++++++++++------------------- 1 file changed, 13 insertions(+), 19 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index ae70f8adb2..d4ab7d1c1b 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -90,7 +90,10 @@ * mbedtls_ssl_conf_enable_new_session_tickets() API. This error * code can then be returned by mbedtls_ssl_handshake(), * mbedtls_ssl_handshake_step(), mbedtls_ssl_read(), mbedtls_ssl_write() and - * mbedtls_ssl_write_early_data(). + * mbedtls_ssl_write_early_data(). A TLS 1.3 NewSessionTicket message has been + * received and parsed successfully by the client. Ticket data is available + * in the SSL context and may be retrieved through the + * mbedtls_ssl_get_session() API. */ #define MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET -0x7B00 /** Not possible to read early data */ @@ -4916,12 +4919,9 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl, * and the client did not demonstrate reachability yet - in * this case you must stop using the context (see below). * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 - * NewSessionTicket message has been received. This is client - * specific and may occur only if the handling of - * NewSessionTicket message has been enabled (see - * mbedtls_ssl_conf_enable_new_session_tickets() documentation). - * You may call mbedtls_ssl_get_session() to retrieve the - * ticket data. + * NewSessionTicket message has been received. See + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET documentation + * for more information. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific @@ -5083,12 +5083,9 @@ int mbedtls_ssl_renegotiate(mbedtls_ssl_context *ssl); * side of a DTLS connection and the client is initiating a * new connection using the same source port. See below. * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 - * NewSessionTicket message has been received. This is client - * specific and may occur only if the handling of - * NewSessionTicket message has been enabled (see - * mbedtls_ssl_conf_enable_new_session_tickets() documentation). - * You may call mbedtls_ssl_get_session() to retrieve the - * ticket data. + * NewSessionTicket message has been received. See + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET documentation + * for more information. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific @@ -5173,12 +5170,9 @@ int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len); * in this case you must call this function again to complete * the handshake when you're done attending other tasks. * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 - * NewSessionTicket message has been received. This is client - * specific and may occur only if the handling of - * NewSessionTicket message has been enabled (see - * mbedtls_ssl_conf_enable_new_session_tickets() documentation). - * You may call mbedtls_ssl_get_session() to retrieve the - * ticket data. + * NewSessionTicket message has been received. See + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET documentation + * for more information. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific From e55659d5769572be84e4850de4dfcdf2b67555af Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 27 Aug 2024 19:23:51 +0200 Subject: [PATCH 06/16] Document NewSessionTicket handling being disabled by default Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index d4ab7d1c1b..ed3489fa88 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -4498,8 +4498,31 @@ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets) #if defined(MBEDTLS_SSL_PROTO_TLS1_3) /** - * \brief Enable / Disable TLS 1.3 handling of NewSessionTicket messages (client and TLS 1.3 only). - * (Default: MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_DISABLED) + * \brief Enable / Disable handling of TLS 1.3 NewSessionTicket messages (client and TLS 1.3 only). + * + * The handling of TLS 1.3 NewSessionTicket messages is disabled by + * default. + * + * Contrary to TLS 1.2 tickets, the default value is disabled in Mbed TLS + * 3.6.x for backward compatibility with applications based on the Mbed TLS + * client in the default configuration connecting to TLS 1.3 servers + * supporting NewSessionTicket messages. + * + * Up to Mbed TLS 3.5, in the default configuration TLS 1.3 was + * disabled, and an Mbed TLS client in the default configuration would + * establish a TLS 1.2 connection with a TLS 1.2 and TLS 1.3 capable + * server. + * + * Starting with Mbed TLS 3.6.0, TLS 1.3 is enabled by default, and thus + * an Mbed TLS client in the default configuration establishes a TLS 1.3 + * connection with a TLS 1.2 and TLS 1.3 capable server. If following + * the handshake the TLS 1.3 server sends NewSessionTicket messages and + * the Mbed TLS client processes them, this results in Mbed TLS high + * level APIs (mbedtls_ssl_read(), mbedtls_ssl_handshake(), ...) to + * eventually return an #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET non + * fatal error code (see the documentation of that error code for more + * information). Applications unaware of that TLS 1.3 specific non fatal + * error code are then failing. * * \param conf SSL configuration * \param new_session_tickets_enabled Enable or disable From 57ad182644bbfb26248c0a639619dbed7d8da927 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 27 Aug 2024 19:38:41 +0200 Subject: [PATCH 07/16] ssl_client2: Fix new_session_tickets option parsing Signed-off-by: Ronald Cron --- programs/ssl/ssl_client2.c | 2 +- tests/opt-testcases/tls13-misc.sh | 28 ++++++++++++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/programs/ssl/ssl_client2.c b/programs/ssl/ssl_client2.c index cf21569697..2ae715b4b4 100644 --- a/programs/ssl/ssl_client2.c +++ b/programs/ssl/ssl_client2.c @@ -1231,7 +1231,7 @@ usage: goto usage; } } else if (strcmp(p, "new_session_tickets") == 0) { - opt.tickets = atoi(q); + opt.new_session_tickets = atoi(q); if (opt.new_session_tickets < 0) { goto usage; } diff --git a/tests/opt-testcases/tls13-misc.sh b/tests/opt-testcases/tls13-misc.sh index 9d5870da65..17beab67a1 100755 --- a/tests/opt-testcases/tls13-misc.sh +++ b/tests/opt-testcases/tls13-misc.sh @@ -841,6 +841,20 @@ run_test "TLS 1.3 m->O: resumption fails, no ticket support" \ -C "Reconnecting with saved session... ok" \ -c "Ignore NewSessionTicket, not supported." +requires_openssl_tls1_3_with_compatible_ephemeral +requires_all_configs_enabled MBEDTLS_SSL_CLI_C \ + MBEDTLS_SSL_SESSION_TICKETS \ + MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE \ + MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED +run_test "TLS 1.3 m->O: resumption fails, ticket handling disabled" \ + "$O_NEXT_SRV -msg -tls1_3 -no_resume_ephemeral -no_cache --num_tickets 1" \ + "$P_CLI debug_level=3 new_session_tickets=0 reco_mode=1 reconnect=1" \ + 1 \ + -c "Protocol is TLSv1.3" \ + -C "Saving session for reuse... ok" \ + -C "Reconnecting with saved session... ok" \ + -c "Ignore NewSessionTicket, disabled." + # No early data m->O tests for the time being. The option -early_data is needed # to enable early data on OpenSSL server and it is not compatible with the # -www option we usually use for testing with OpenSSL server (see @@ -901,6 +915,20 @@ run_test "TLS 1.3 m->G: resumption fails, no ticket support" \ -C "Reconnecting with saved session... ok" \ -c "Ignore NewSessionTicket, not supported." +requires_gnutls_tls1_3 +requires_all_configs_enabled MBEDTLS_SSL_CLI_C \ + MBEDTLS_SSL_SESSION_TICKETS \ + MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE \ + MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED +run_test "TLS 1.3 m->G: resumption fails, ticket handling disabled" \ + "$G_NEXT_SRV -d 5 --priority=NORMAL:-VERS-ALL:+VERS-TLS1.3 --disable-client-cert" \ + "$P_CLI debug_level=3 new_session_tickets=0 reco_mode=1 reconnect=1" \ + 1 \ + -c "Protocol is TLSv1.3" \ + -C "Saving session for reuse... ok" \ + -C "Reconnecting with saved session... ok" \ + -c "Ignore NewSessionTicket, disabled." + requires_gnutls_tls1_3 requires_all_configs_enabled MBEDTLS_SSL_CLI_C \ MBEDTLS_SSL_SESSION_TICKETS MBEDTLS_HAVE_TIME \ From d67f801c63977dcd1f5876615f46d8f59ba51eff Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 28 Aug 2024 07:45:57 +0200 Subject: [PATCH 08/16] Do not add a new field in the SSL config We cannot add a new field in SSL config in an LTS. Use `session_tickets` field instead. Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 43 +++++++++++++++++++--------- library/ssl_msg.c | 4 +-- library/ssl_tls.c | 38 ++++++++++++++++++++---- library/ssl_tls12_client.c | 6 ++-- programs/ssl/ssl_client2.c | 2 +- tests/src/test_helpers/ssl_helpers.c | 2 +- 6 files changed, 70 insertions(+), 25 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index ed3489fa88..2eb4f9cd53 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -332,8 +332,8 @@ #define MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0 #define MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1 -#define MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_DISABLED 0 -#define MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED 1 +#define MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED 0 +#define MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED 1 #define MBEDTLS_SSL_PRESET_DEFAULT 0 #define MBEDTLS_SSL_PRESET_SUITEB 2 @@ -1458,12 +1458,6 @@ struct mbedtls_ssl_config { #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \ defined(MBEDTLS_SSL_CLI_C) uint8_t MBEDTLS_PRIVATE(session_tickets); /*!< use session tickets? */ -#if defined(MBEDTLS_SSL_PROTO_TLS1_3) - /** Whether we handle NewSessionTicket TLS 1.3 messages (<>0) or just ignore them (==0) - * They are ignored by default. - */ - uint8_t MBEDTLS_PRIVATE(new_session_tickets_enabled); -#endif #endif #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \ @@ -4485,8 +4479,8 @@ void mbedtls_ssl_conf_preference_order(mbedtls_ssl_config *conf, int order); #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \ defined(MBEDTLS_SSL_CLI_C) /** - * \brief Enable / Disable session tickets (client only). - * (Default: MBEDTLS_SSL_SESSION_TICKETS_ENABLED.) + * \brief Enable / Disable TLS 1.2 session tickets (client and TLS 1.2 only). + * Disabled by default. * * \note On server, use \c mbedtls_ssl_conf_session_tickets_cb(). * @@ -4496,6 +4490,16 @@ void mbedtls_ssl_conf_preference_order(mbedtls_ssl_config *conf, int order); */ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets); +/** + * \brief Get if TLS 1.2 session tickets usage is enabled or not + * + * \param conf SSL configuration + * + * \return MBEDTLS_SSL_SESSION_TICKETS_ENABLED or + * MBEDTLS_SSL_SESSION_TICKETS_DISABLED + */ +int mbedtls_ssl_conf_get_session_tickets(const mbedtls_ssl_config *conf); + #if defined(MBEDTLS_SSL_PROTO_TLS1_3) /** * \brief Enable / Disable handling of TLS 1.3 NewSessionTicket messages (client and TLS 1.3 only). @@ -4525,12 +4529,23 @@ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets) * error code are then failing. * * \param conf SSL configuration - * \param new_session_tickets_enabled Enable or disable - * (MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED or - * MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_DISABLED) + * \param use_new_session_tickets Enable or disable + * (MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED or + * MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED) */ void mbedtls_ssl_conf_enable_new_session_tickets(mbedtls_ssl_config *conf, - int new_session_tickets_enabled); + int use_new_session_tickets); + +/** + * \brief Get if usage of TLS 1.3 NewSessionTicket messages is enabled or not + * + * \param conf SSL configuration + * + * \return MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED or + * MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED + */ +int mbedtls_ssl_conf_is_new_session_tickets_enabled(const mbedtls_ssl_config *conf); + #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ diff --git a/library/ssl_msg.c b/library/ssl_msg.c index 65ad324337..58063c7f11 100644 --- a/library/ssl_msg.c +++ b/library/ssl_msg.c @@ -5595,8 +5595,8 @@ static int ssl_tls13_handle_hs_message_post_handshake(mbedtls_ssl_context *ssl) if (ssl_tls13_is_new_session_ticket(ssl)) { #if defined(MBEDTLS_SSL_SESSION_TICKETS) MBEDTLS_SSL_DEBUG_MSG(3, ("NewSessionTicket received")); - if (ssl->conf->new_session_tickets_enabled == - MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED) { + if (mbedtls_ssl_conf_is_new_session_tickets_enabled(ssl->conf) == + MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED) { ssl->keep_current_message = 1; mbedtls_ssl_handshake_set_state(ssl, diff --git a/library/ssl_tls.c b/library/ssl_tls.c index 21d70af772..89588a4787 100644 --- a/library/ssl_tls.c +++ b/library/ssl_tls.c @@ -3009,15 +3009,43 @@ void mbedtls_ssl_conf_renegotiation_period(mbedtls_ssl_config *conf, #if defined(MBEDTLS_SSL_SESSION_TICKETS) #if defined(MBEDTLS_SSL_CLI_C) + +#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_BIT 0 +#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_BIT 1 + +#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_MASK \ + (1 << MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_BIT) +#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_MASK \ + (1 << MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_BIT) + void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets) { - conf->session_tickets = use_tickets; + conf->session_tickets &= ~MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_MASK; + conf->session_tickets |= (use_tickets != 0) << + MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_BIT; } + +int mbedtls_ssl_conf_get_session_tickets(const mbedtls_ssl_config *conf) +{ + return conf->session_tickets & MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_MASK ? + MBEDTLS_SSL_SESSION_TICKETS_ENABLED : + MBEDTLS_SSL_SESSION_TICKETS_DISABLED; +} + #if defined(MBEDTLS_SSL_PROTO_TLS1_3) void mbedtls_ssl_conf_enable_new_session_tickets(mbedtls_ssl_config *conf, - int new_session_tickets_enabled) + int use_new_session_tickets) { - conf->new_session_tickets_enabled = new_session_tickets_enabled; + conf->session_tickets &= ~MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_MASK; + conf->session_tickets |= (use_new_session_tickets != 0) << + MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_BIT; +} + +int mbedtls_ssl_conf_is_new_session_tickets_enabled(const mbedtls_ssl_config *conf) +{ + return conf->session_tickets & MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_MASK ? + MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED : + MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED; } #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ #endif /* MBEDTLS_SSL_CLI_C */ @@ -5885,9 +5913,9 @@ int mbedtls_ssl_config_defaults(mbedtls_ssl_config *conf, if (endpoint == MBEDTLS_SSL_IS_CLIENT) { conf->authmode = MBEDTLS_SSL_VERIFY_REQUIRED; #if defined(MBEDTLS_SSL_SESSION_TICKETS) - conf->session_tickets = MBEDTLS_SSL_SESSION_TICKETS_ENABLED; + mbedtls_ssl_conf_session_tickets(conf, MBEDTLS_SSL_SESSION_TICKETS_ENABLED); #if defined(MBEDTLS_SSL_PROTO_TLS1_3) - conf->new_session_tickets_enabled = MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_DISABLED; + mbedtls_ssl_conf_enable_new_session_tickets(conf, MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED); #endif #endif } diff --git a/library/ssl_tls12_client.c b/library/ssl_tls12_client.c index eac6a3aadd..9b2da5a39d 100644 --- a/library/ssl_tls12_client.c +++ b/library/ssl_tls12_client.c @@ -364,7 +364,8 @@ static int ssl_write_session_ticket_ext(mbedtls_ssl_context *ssl, *olen = 0; - if (ssl->conf->session_tickets == MBEDTLS_SSL_SESSION_TICKETS_DISABLED) { + if (mbedtls_ssl_conf_get_session_tickets(ssl->conf) == + MBEDTLS_SSL_SESSION_TICKETS_DISABLED) { return 0; } @@ -787,7 +788,8 @@ static int ssl_parse_session_ticket_ext(mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len) { - if (ssl->conf->session_tickets == MBEDTLS_SSL_SESSION_TICKETS_DISABLED || + if ((mbedtls_ssl_conf_get_session_tickets(ssl->conf) == + MBEDTLS_SSL_SESSION_TICKETS_DISABLED) || len != 0) { MBEDTLS_SSL_DEBUG_MSG(1, ("non-matching session ticket extension")); diff --git a/programs/ssl/ssl_client2.c b/programs/ssl/ssl_client2.c index 2ae715b4b4..7029e2677a 100644 --- a/programs/ssl/ssl_client2.c +++ b/programs/ssl/ssl_client2.c @@ -82,7 +82,7 @@ int main(void) #define DFL_CID_VALUE_RENEGO NULL #define DFL_RECONNECT_HARD 0 #define DFL_TICKETS MBEDTLS_SSL_SESSION_TICKETS_ENABLED -#define DFL_NEW_SESSION_TICKETS MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED +#define DFL_NEW_SESSION_TICKETS MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED #define DFL_ALPN_STRING NULL #define DFL_GROUPS NULL #define DFL_SIG_ALGS NULL diff --git a/tests/src/test_helpers/ssl_helpers.c b/tests/src/test_helpers/ssl_helpers.c index 7d5d889ce3..b0fe2bdf1e 100644 --- a/tests/src/test_helpers/ssl_helpers.c +++ b/tests/src/test_helpers/ssl_helpers.c @@ -2544,7 +2544,7 @@ int mbedtls_test_get_tls13_ticket( TEST_EQUAL(ret, 0); mbedtls_ssl_conf_enable_new_session_tickets( - &client_ep.conf, MBEDTLS_SSL_ENABLE_NEW_SESSION_TICKETS_ENABLED); + &client_ep.conf, MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED); mbedtls_ssl_conf_session_tickets_cb(&server_ep.conf, mbedtls_test_ticket_write, From fc76718dcd745bc5ba9f610e6f5563feb1174f97 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 28 Aug 2024 09:46:44 +0200 Subject: [PATCH 09/16] Move MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET doc Move MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET error code documentation to the documentation of mbedtls_ssl_read() as we cannot have long error descriptions because of a limitation in generate_errors.pl. Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 44 ++++++++++++++++++++----------------------- 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 2eb4f9cd53..8c7b7281db 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -83,18 +83,7 @@ /** Processing of the Certificate handshake message failed. */ #define MBEDTLS_ERR_SSL_BAD_CERTIFICATE -0x7A00 /* Error space gap */ -/** - * A TLS 1.3 NewSessionTicket message has been received. - * This error code can be returned only on client side if and only if handling - * of TLS 1.3 NewSessionTicket messages has been enabled through the - * mbedtls_ssl_conf_enable_new_session_tickets() API. This error - * code can then be returned by mbedtls_ssl_handshake(), - * mbedtls_ssl_handshake_step(), mbedtls_ssl_read(), mbedtls_ssl_write() and - * mbedtls_ssl_write_early_data(). A TLS 1.3 NewSessionTicket message has been - * received and parsed successfully by the client. Ticket data is available - * in the SSL context and may be retrieved through the - * mbedtls_ssl_get_session() API. - */ +/** A TLS 1.3 NewSessionTicket message has been received. */ #define MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET -0x7B00 /** Not possible to read early data */ #define MBEDTLS_ERR_SSL_CANNOT_READ_EARLY_DATA -0x7B80 @@ -4524,9 +4513,9 @@ int mbedtls_ssl_conf_get_session_tickets(const mbedtls_ssl_config *conf); * the Mbed TLS client processes them, this results in Mbed TLS high * level APIs (mbedtls_ssl_read(), mbedtls_ssl_handshake(), ...) to * eventually return an #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET non - * fatal error code (see the documentation of that error code for more - * information). Applications unaware of that TLS 1.3 specific non fatal - * error code are then failing. + * fatal error code (see the documentation of mbedtls_ssl_read() for + * more information on that error code). Applications unaware of that + * TLS 1.3 specific non fatal error code are then failing. * * \param conf SSL configuration * \param use_new_session_tickets Enable or disable @@ -4957,9 +4946,9 @@ int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl, * and the client did not demonstrate reachability yet - in * this case you must stop using the context (see below). * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 - * NewSessionTicket message has been received. See - * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET documentation - * for more information. + * NewSessionTicket message has been received. See the + * documentation of mbedtls_ssl_read() for more information + * about this error code. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific @@ -5121,9 +5110,16 @@ int mbedtls_ssl_renegotiate(mbedtls_ssl_context *ssl); * side of a DTLS connection and the client is initiating a * new connection using the same source port. See below. * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 - * NewSessionTicket message has been received. See - * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET documentation - * for more information. + * NewSessionTicket message has been received. + * This error code can be returned only on client side if and + * only if handling of TLS 1.3 NewSessionTicket messages has + * been enabled through the + * mbedtls_ssl_conf_enable_new_session_tickets() API. A TLS 1.3 + * NewSessionTicket message has been received and parsed + * successfully by the client. Ticket data is available in the + * SSL context and remain available as long as the client does + * not receive a new NewSessionTicket message. Ticket data may + * be retrieved through the mbedtls_ssl_get_session() API. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific @@ -5208,9 +5204,9 @@ int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len); * in this case you must call this function again to complete * the handshake when you're done attending other tasks. * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 - * NewSessionTicket message has been received. See - * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET documentation - * for more information. + * NewSessionTicket message has been received. See the + * documentation of mbedtls_ssl_read() for more information + * about this error code. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific From 97dc5832c5e70b4553ec8958f4fe40dccd2823f6 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 28 Aug 2024 09:34:34 +0200 Subject: [PATCH 10/16] Improve debug logs Signed-off-by: Ronald Cron --- library/ssl_msg.c | 4 ++-- tests/opt-testcases/tls13-misc.sh | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/library/ssl_msg.c b/library/ssl_msg.c index 58063c7f11..f7c12a85dc 100644 --- a/library/ssl_msg.c +++ b/library/ssl_msg.c @@ -5603,11 +5603,11 @@ static int ssl_tls13_handle_hs_message_post_handshake(mbedtls_ssl_context *ssl) MBEDTLS_SSL_TLS1_3_NEW_SESSION_TICKET); return MBEDTLS_ERR_SSL_WANT_READ; } else { - MBEDTLS_SSL_DEBUG_MSG(3, ("Ignore NewSessionTicket, disabled.")); + MBEDTLS_SSL_DEBUG_MSG(3, ("Ignoring NewSessionTicket, handling disabled.")); return 0; } #else - MBEDTLS_SSL_DEBUG_MSG(3, ("Ignore NewSessionTicket, not supported.")); + MBEDTLS_SSL_DEBUG_MSG(3, ("Ignoring NewSessionTicket, not supported.")); return 0; #endif } diff --git a/tests/opt-testcases/tls13-misc.sh b/tests/opt-testcases/tls13-misc.sh index 17beab67a1..90ae3b2b57 100755 --- a/tests/opt-testcases/tls13-misc.sh +++ b/tests/opt-testcases/tls13-misc.sh @@ -839,7 +839,7 @@ run_test "TLS 1.3 m->O: resumption fails, no ticket support" \ -c "Protocol is TLSv1.3" \ -C "Saving session for reuse... ok" \ -C "Reconnecting with saved session... ok" \ - -c "Ignore NewSessionTicket, not supported." + -c "Ignoring NewSessionTicket, not supported." requires_openssl_tls1_3_with_compatible_ephemeral requires_all_configs_enabled MBEDTLS_SSL_CLI_C \ @@ -853,7 +853,7 @@ run_test "TLS 1.3 m->O: resumption fails, ticket handling disabled" \ -c "Protocol is TLSv1.3" \ -C "Saving session for reuse... ok" \ -C "Reconnecting with saved session... ok" \ - -c "Ignore NewSessionTicket, disabled." + -c "Ignoring NewSessionTicket, handling disabled." # No early data m->O tests for the time being. The option -early_data is needed # to enable early data on OpenSSL server and it is not compatible with the @@ -913,7 +913,7 @@ run_test "TLS 1.3 m->G: resumption fails, no ticket support" \ -c "Protocol is TLSv1.3" \ -C "Saving session for reuse... ok" \ -C "Reconnecting with saved session... ok" \ - -c "Ignore NewSessionTicket, not supported." + -c "Ignoring NewSessionTicket, not supported." requires_gnutls_tls1_3 requires_all_configs_enabled MBEDTLS_SSL_CLI_C \ @@ -927,7 +927,7 @@ run_test "TLS 1.3 m->G: resumption fails, ticket handling disabled" \ -c "Protocol is TLSv1.3" \ -C "Saving session for reuse... ok" \ -C "Reconnecting with saved session... ok" \ - -c "Ignore NewSessionTicket, disabled." + -c "Ignoring NewSessionTicket, handling disabled." requires_gnutls_tls1_3 requires_all_configs_enabled MBEDTLS_SSL_CLI_C \ From 31b40b3600eced75c5e8d7585d8ad510d770b26f Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 28 Aug 2024 09:31:06 +0200 Subject: [PATCH 11/16] Add change logs Signed-off-by: Ronald Cron --- ChangeLog.d/disable-new-session-tickets.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 ChangeLog.d/disable-new-session-tickets.txt diff --git a/ChangeLog.d/disable-new-session-tickets.txt b/ChangeLog.d/disable-new-session-tickets.txt new file mode 100644 index 0000000000..664240b065 --- /dev/null +++ b/ChangeLog.d/disable-new-session-tickets.txt @@ -0,0 +1,13 @@ +Bugfix + * Fix TLS connection abortion in applications using an Mbed TLS client in + the default configuration connecting to a TLS 1.3 server sending tickets. + See the documentation of mbedtls_ssl_conf_enable_new_session_tickets() + for more information. + Fixes #8749. + +Changes + * By default, the handling of TLS 1.3 tickets by the Mbed TLS client is now + disabled at runtime. Applications that were using TLS 1.3 tickets + signalled by MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET return values now + need to enable the handling of TLS 1.3 tickets through the new + mbedtls_ssl_conf_enable_new_session_tickets() API. From ba45a44f1332bb1a1c7fed6d6881ec86a33cfc88 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 28 Aug 2024 13:20:56 +0200 Subject: [PATCH 12/16] Move session tickets getter functions to ssl_misc.h Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 26 ++------------------------ library/ssl_misc.h | 29 +++++++++++++++++++++++++++++ library/ssl_tls.c | 22 ---------------------- 3 files changed, 31 insertions(+), 46 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 8c7b7281db..1fe1ac5e3b 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -4465,8 +4465,7 @@ int mbedtls_ssl_conf_max_frag_len(mbedtls_ssl_config *conf, unsigned char mfl_co void mbedtls_ssl_conf_preference_order(mbedtls_ssl_config *conf, int order); #endif /* MBEDTLS_SSL_SRV_C */ -#if defined(MBEDTLS_SSL_SESSION_TICKETS) && \ - defined(MBEDTLS_SSL_CLI_C) +#if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C) /** * \brief Enable / Disable TLS 1.2 session tickets (client and TLS 1.2 only). * Disabled by default. @@ -4479,16 +4478,6 @@ void mbedtls_ssl_conf_preference_order(mbedtls_ssl_config *conf, int order); */ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets); -/** - * \brief Get if TLS 1.2 session tickets usage is enabled or not - * - * \param conf SSL configuration - * - * \return MBEDTLS_SSL_SESSION_TICKETS_ENABLED or - * MBEDTLS_SSL_SESSION_TICKETS_DISABLED - */ -int mbedtls_ssl_conf_get_session_tickets(const mbedtls_ssl_config *conf); - #if defined(MBEDTLS_SSL_PROTO_TLS1_3) /** * \brief Enable / Disable handling of TLS 1.3 NewSessionTicket messages (client and TLS 1.3 only). @@ -4525,19 +4514,8 @@ int mbedtls_ssl_conf_get_session_tickets(const mbedtls_ssl_config *conf); void mbedtls_ssl_conf_enable_new_session_tickets(mbedtls_ssl_config *conf, int use_new_session_tickets); -/** - * \brief Get if usage of TLS 1.3 NewSessionTicket messages is enabled or not - * - * \param conf SSL configuration - * - * \return MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED or - * MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED - */ -int mbedtls_ssl_conf_is_new_session_tickets_enabled(const mbedtls_ssl_config *conf); - #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ -#endif /* MBEDTLS_SSL_SESSION_TICKETS && - MBEDTLS_SSL_CLI_C */ +#endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \ defined(MBEDTLS_SSL_SRV_C) && \ diff --git a/library/ssl_misc.h b/library/ssl_misc.h index 082bc9bd93..10cb68456d 100644 --- a/library/ssl_misc.h +++ b/library/ssl_misc.h @@ -2934,8 +2934,37 @@ static inline void mbedtls_ssl_tls13_session_clear_ticket_flags( { session->ticket_flags &= ~(flags & MBEDTLS_SSL_TLS1_3_TICKET_FLAGS_MASK); } + #endif /* MBEDTLS_SSL_PROTO_TLS1_3 && MBEDTLS_SSL_SESSION_TICKETS */ +#if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C) +#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_BIT 0 +#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_BIT 1 + +#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_MASK \ + (1 << MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_BIT) +#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_MASK \ + (1 << MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_BIT) + +static inline int mbedtls_ssl_conf_get_session_tickets( + const mbedtls_ssl_config *conf) +{ + return conf->session_tickets & MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_MASK ? + MBEDTLS_SSL_SESSION_TICKETS_ENABLED : + MBEDTLS_SSL_SESSION_TICKETS_DISABLED; +} + +#if defined(MBEDTLS_SSL_PROTO_TLS1_3) +static inline int mbedtls_ssl_conf_is_new_session_tickets_enabled( + const mbedtls_ssl_config *conf) +{ + return conf->session_tickets & MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_MASK ? + MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED : + MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED; +} +#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ +#endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ + #if defined(MBEDTLS_SSL_CLI_C) && defined(MBEDTLS_SSL_PROTO_TLS1_3) int mbedtls_ssl_tls13_finalize_client_hello(mbedtls_ssl_context *ssl); #endif diff --git a/library/ssl_tls.c b/library/ssl_tls.c index 89588a4787..fe1a1efa99 100644 --- a/library/ssl_tls.c +++ b/library/ssl_tls.c @@ -3010,14 +3010,6 @@ void mbedtls_ssl_conf_renegotiation_period(mbedtls_ssl_config *conf, #if defined(MBEDTLS_SSL_SESSION_TICKETS) #if defined(MBEDTLS_SSL_CLI_C) -#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_BIT 0 -#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_BIT 1 - -#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_MASK \ - (1 << MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_BIT) -#define MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_MASK \ - (1 << MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_BIT) - void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets) { conf->session_tickets &= ~MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_MASK; @@ -3025,13 +3017,6 @@ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets) MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_BIT; } -int mbedtls_ssl_conf_get_session_tickets(const mbedtls_ssl_config *conf) -{ - return conf->session_tickets & MBEDTLS_SSL_SESSION_TICKETS_TLS1_2_MASK ? - MBEDTLS_SSL_SESSION_TICKETS_ENABLED : - MBEDTLS_SSL_SESSION_TICKETS_DISABLED; -} - #if defined(MBEDTLS_SSL_PROTO_TLS1_3) void mbedtls_ssl_conf_enable_new_session_tickets(mbedtls_ssl_config *conf, int use_new_session_tickets) @@ -3040,13 +3025,6 @@ void mbedtls_ssl_conf_enable_new_session_tickets(mbedtls_ssl_config *conf, conf->session_tickets |= (use_new_session_tickets != 0) << MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_BIT; } - -int mbedtls_ssl_conf_is_new_session_tickets_enabled(const mbedtls_ssl_config *conf) -{ - return conf->session_tickets & MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_MASK ? - MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED : - MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED; -} #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ #endif /* MBEDTLS_SSL_CLI_C */ From 48a9f562ba9a172961af05146039d33e4e14689a Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 28 Aug 2024 13:36:43 +0200 Subject: [PATCH 13/16] Improve documentation Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 1fe1ac5e3b..8ba7ef8f17 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -4485,26 +4485,27 @@ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets) * The handling of TLS 1.3 NewSessionTicket messages is disabled by * default. * - * Contrary to TLS 1.2 tickets, the default value is disabled in Mbed TLS - * 3.6.x for backward compatibility with applications based on the Mbed TLS - * client in the default configuration connecting to TLS 1.3 servers - * supporting NewSessionTicket messages. + * Contrary to TLS 1.2 tickets, the default value is disabled in + * Mbed TLS 3.6.x for backward compatibility with client applications + * developed using Mbed TLS 3.5 or earlier with the default + * configuration. * * Up to Mbed TLS 3.5, in the default configuration TLS 1.3 was - * disabled, and an Mbed TLS client in the default configuration would + * disabled, and a Mbed TLS client with the default configuration would * establish a TLS 1.2 connection with a TLS 1.2 and TLS 1.3 capable * server. * * Starting with Mbed TLS 3.6.0, TLS 1.3 is enabled by default, and thus - * an Mbed TLS client in the default configuration establishes a TLS 1.3 - * connection with a TLS 1.2 and TLS 1.3 capable server. If following - * the handshake the TLS 1.3 server sends NewSessionTicket messages and - * the Mbed TLS client processes them, this results in Mbed TLS high - * level APIs (mbedtls_ssl_read(), mbedtls_ssl_handshake(), ...) to - * eventually return an #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET non - * fatal error code (see the documentation of mbedtls_ssl_read() for - * more information on that error code). Applications unaware of that - * TLS 1.3 specific non fatal error code are then failing. + * an Mbed TLS client with the default configuration establishes a + * TLS 1.3 connection with a TLS 1.2 and TLS 1.3 capable server. If + * following the handshake the TLS 1.3 server sends NewSessionTicket + * messages and the Mbed TLS client processes them, this results in + * Mbed TLS high level APIs (mbedtls_ssl_read(), + * mbedtls_ssl_handshake(), ...) to eventually return an + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET non fatal error code + * (see the documentation of mbedtls_ssl_read() for more information on + * that error code). Applications unaware of that TLS 1.3 specific non + * fatal error code are then failing. * * \param conf SSL configuration * \param use_new_session_tickets Enable or disable @@ -5095,7 +5096,7 @@ int mbedtls_ssl_renegotiate(mbedtls_ssl_context *ssl); * mbedtls_ssl_conf_enable_new_session_tickets() API. A TLS 1.3 * NewSessionTicket message has been received and parsed * successfully by the client. Ticket data is available in the - * SSL context and remain available as long as the client does + * SSL context and remain available as long as the client will * not receive a new NewSessionTicket message. Ticket data may * be retrieved through the mbedtls_ssl_get_session() API. * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as From c9884b04add0bc1e392c985b8ee200bc5ee9bba9 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 28 Aug 2024 16:36:07 +0200 Subject: [PATCH 14/16] Fix change log Signed-off-by: Ronald Cron --- ChangeLog.d/disable-new-session-tickets.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ChangeLog.d/disable-new-session-tickets.txt b/ChangeLog.d/disable-new-session-tickets.txt index 664240b065..1fd112ff15 100644 --- a/ChangeLog.d/disable-new-session-tickets.txt +++ b/ChangeLog.d/disable-new-session-tickets.txt @@ -1,5 +1,5 @@ Bugfix - * Fix TLS connection abortion in applications using an Mbed TLS client in + * Fix TLS connection failure in applications using an Mbed TLS client in the default configuration connecting to a TLS 1.3 server sending tickets. See the documentation of mbedtls_ssl_conf_enable_new_session_tickets() for more information. From 9f44c883f4d4970221ae711ae1f7b597768435d9 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 28 Aug 2024 16:44:10 +0200 Subject: [PATCH 15/16] Rename some "new_session_tickets" symbols Signed-off-by: Ronald Cron --- ChangeLog.d/disable-new-session-tickets.txt | 7 ++++--- include/mbedtls/ssl.h | 18 +++++++++--------- library/ssl_misc.h | 6 +++--- library/ssl_msg.c | 4 ++-- library/ssl_tls.c | 9 +++++---- programs/ssl/ssl_client2.c | 5 +++-- tests/src/test_helpers/ssl_helpers.c | 4 ++-- 7 files changed, 28 insertions(+), 25 deletions(-) diff --git a/ChangeLog.d/disable-new-session-tickets.txt b/ChangeLog.d/disable-new-session-tickets.txt index 1fd112ff15..bb13b4b2b4 100644 --- a/ChangeLog.d/disable-new-session-tickets.txt +++ b/ChangeLog.d/disable-new-session-tickets.txt @@ -1,8 +1,9 @@ Bugfix * Fix TLS connection failure in applications using an Mbed TLS client in the default configuration connecting to a TLS 1.3 server sending tickets. - See the documentation of mbedtls_ssl_conf_enable_new_session_tickets() - for more information. + See the documentation of + mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets() for more + information. Fixes #8749. Changes @@ -10,4 +11,4 @@ Changes disabled at runtime. Applications that were using TLS 1.3 tickets signalled by MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET return values now need to enable the handling of TLS 1.3 tickets through the new - mbedtls_ssl_conf_enable_new_session_tickets() API. + mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets() API. diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index 8ba7ef8f17..afd4129d7a 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -321,8 +321,8 @@ #define MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0 #define MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1 -#define MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED 0 -#define MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED 1 +#define MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_DISABLED 0 +#define MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED 1 #define MBEDTLS_SSL_PRESET_DEFAULT 0 #define MBEDTLS_SSL_PRESET_SUITEB 2 @@ -4508,12 +4508,12 @@ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets) * fatal error code are then failing. * * \param conf SSL configuration - * \param use_new_session_tickets Enable or disable - * (MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED or - * MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED) + * \param signal_new_session_tickets Enable or disable + * (MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED or + * MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_DISABLED) */ -void mbedtls_ssl_conf_enable_new_session_tickets(mbedtls_ssl_config *conf, - int use_new_session_tickets); +void mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets( + mbedtls_ssl_config *conf, int signal_new_session_tickets); #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ @@ -5093,8 +5093,8 @@ int mbedtls_ssl_renegotiate(mbedtls_ssl_context *ssl); * This error code can be returned only on client side if and * only if handling of TLS 1.3 NewSessionTicket messages has * been enabled through the - * mbedtls_ssl_conf_enable_new_session_tickets() API. A TLS 1.3 - * NewSessionTicket message has been received and parsed + * mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets() API. + * A TLS 1.3 NewSessionTicket message has been received and parsed * successfully by the client. Ticket data is available in the * SSL context and remain available as long as the client will * not receive a new NewSessionTicket message. Ticket data may diff --git a/library/ssl_misc.h b/library/ssl_misc.h index 10cb68456d..1e4c42c634 100644 --- a/library/ssl_misc.h +++ b/library/ssl_misc.h @@ -2955,12 +2955,12 @@ static inline int mbedtls_ssl_conf_get_session_tickets( } #if defined(MBEDTLS_SSL_PROTO_TLS1_3) -static inline int mbedtls_ssl_conf_is_new_session_tickets_enabled( +static inline int mbedtls_ssl_conf_is_signal_new_session_tickets_enabled( const mbedtls_ssl_config *conf) { return conf->session_tickets & MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_MASK ? - MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED : - MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED; + MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED : + MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_DISABLED; } #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ diff --git a/library/ssl_msg.c b/library/ssl_msg.c index f7c12a85dc..ef722d7bdc 100644 --- a/library/ssl_msg.c +++ b/library/ssl_msg.c @@ -5595,8 +5595,8 @@ static int ssl_tls13_handle_hs_message_post_handshake(mbedtls_ssl_context *ssl) if (ssl_tls13_is_new_session_ticket(ssl)) { #if defined(MBEDTLS_SSL_SESSION_TICKETS) MBEDTLS_SSL_DEBUG_MSG(3, ("NewSessionTicket received")); - if (mbedtls_ssl_conf_is_new_session_tickets_enabled(ssl->conf) == - MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED) { + if (mbedtls_ssl_conf_is_signal_new_session_tickets_enabled(ssl->conf) == + MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED) { ssl->keep_current_message = 1; mbedtls_ssl_handshake_set_state(ssl, diff --git a/library/ssl_tls.c b/library/ssl_tls.c index fe1a1efa99..07eee6bebb 100644 --- a/library/ssl_tls.c +++ b/library/ssl_tls.c @@ -3018,11 +3018,11 @@ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets) } #if defined(MBEDTLS_SSL_PROTO_TLS1_3) -void mbedtls_ssl_conf_enable_new_session_tickets(mbedtls_ssl_config *conf, - int use_new_session_tickets) +void mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets( + mbedtls_ssl_config *conf, int signal_new_session_tickets) { conf->session_tickets &= ~MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_MASK; - conf->session_tickets |= (use_new_session_tickets != 0) << + conf->session_tickets |= (signal_new_session_tickets != 0) << MBEDTLS_SSL_SESSION_TICKETS_TLS1_3_BIT; } #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ @@ -5893,7 +5893,8 @@ int mbedtls_ssl_config_defaults(mbedtls_ssl_config *conf, #if defined(MBEDTLS_SSL_SESSION_TICKETS) mbedtls_ssl_conf_session_tickets(conf, MBEDTLS_SSL_SESSION_TICKETS_ENABLED); #if defined(MBEDTLS_SSL_PROTO_TLS1_3) - mbedtls_ssl_conf_enable_new_session_tickets(conf, MBEDTLS_SSL_NEW_SESSION_TICKETS_DISABLED); + mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets( + conf, MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_DISABLED); #endif #endif } diff --git a/programs/ssl/ssl_client2.c b/programs/ssl/ssl_client2.c index 7029e2677a..7a48ab82f8 100644 --- a/programs/ssl/ssl_client2.c +++ b/programs/ssl/ssl_client2.c @@ -82,7 +82,7 @@ int main(void) #define DFL_CID_VALUE_RENEGO NULL #define DFL_RECONNECT_HARD 0 #define DFL_TICKETS MBEDTLS_SSL_SESSION_TICKETS_ENABLED -#define DFL_NEW_SESSION_TICKETS MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED +#define DFL_NEW_SESSION_TICKETS MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED #define DFL_ALPN_STRING NULL #define DFL_GROUPS NULL #define DFL_SIG_ALGS NULL @@ -1946,7 +1946,8 @@ usage: #if defined(MBEDTLS_SSL_SESSION_TICKETS) mbedtls_ssl_conf_session_tickets(&conf, opt.tickets); #if defined(MBEDTLS_SSL_PROTO_TLS1_3) - mbedtls_ssl_conf_enable_new_session_tickets(&conf, opt.new_session_tickets); + mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets( + &conf, opt.new_session_tickets); #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ #endif /* MBEDTLS_SSL_SESSION_TICKETS */ diff --git a/tests/src/test_helpers/ssl_helpers.c b/tests/src/test_helpers/ssl_helpers.c index b0fe2bdf1e..3cb6175b98 100644 --- a/tests/src/test_helpers/ssl_helpers.c +++ b/tests/src/test_helpers/ssl_helpers.c @@ -2543,8 +2543,8 @@ int mbedtls_test_get_tls13_ticket( server_options, NULL, NULL, NULL); TEST_EQUAL(ret, 0); - mbedtls_ssl_conf_enable_new_session_tickets( - &client_ep.conf, MBEDTLS_SSL_NEW_SESSION_TICKETS_ENABLED); + mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets( + &client_ep.conf, MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED); mbedtls_ssl_conf_session_tickets_cb(&server_ep.conf, mbedtls_test_ticket_write, From c46edd4423741ccf83f7d1bd9e15d62d43b66279 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Wed, 28 Aug 2024 16:54:42 +0200 Subject: [PATCH 16/16] Fix/Improve documentation Signed-off-by: Ronald Cron --- include/mbedtls/ssl.h | 70 +++++++++++++++++++++---------------------- library/ssl_tls.c | 22 ++++++++++++++ 2 files changed, 56 insertions(+), 36 deletions(-) diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h index afd4129d7a..42fffbf860 100644 --- a/include/mbedtls/ssl.h +++ b/include/mbedtls/ssl.h @@ -1446,6 +1446,12 @@ struct mbedtls_ssl_config { #endif #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \ defined(MBEDTLS_SSL_CLI_C) + /** Encodes two booleans, one stating whether TLS 1.2 session tickets are + * enabled or not, the other one whether the handling of TLS 1.3 + * NewSessionTicket messages is enabled or not. They are respectively set + * by mbedtls_ssl_conf_session_tickets() and + * mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets(). + */ uint8_t MBEDTLS_PRIVATE(session_tickets); /*!< use session tickets? */ #endif @@ -4467,50 +4473,42 @@ void mbedtls_ssl_conf_preference_order(mbedtls_ssl_config *conf, int order); #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C) /** - * \brief Enable / Disable TLS 1.2 session tickets (client and TLS 1.2 only). - * Disabled by default. + * \brief Enable / Disable TLS 1.2 session tickets (client only, + * TLS 1.2 only). Enabled by default. * * \note On server, use \c mbedtls_ssl_conf_session_tickets_cb(). * * \param conf SSL configuration - * \param use_tickets Enable or disable (MBEDTLS_SSL_SESSION_TICKETS_ENABLED or - * MBEDTLS_SSL_SESSION_TICKETS_DISABLED) + * \param use_tickets Enable or disable (#MBEDTLS_SSL_SESSION_TICKETS_ENABLED or + * #MBEDTLS_SSL_SESSION_TICKETS_DISABLED) */ void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets); #if defined(MBEDTLS_SSL_PROTO_TLS1_3) /** - * \brief Enable / Disable handling of TLS 1.3 NewSessionTicket messages (client and TLS 1.3 only). + * \brief Enable / Disable handling of TLS 1.3 NewSessionTicket messages + * (client only, TLS 1.3 only). * * The handling of TLS 1.3 NewSessionTicket messages is disabled by * default. * - * Contrary to TLS 1.2 tickets, the default value is disabled in - * Mbed TLS 3.6.x for backward compatibility with client applications - * developed using Mbed TLS 3.5 or earlier with the default - * configuration. + * In TLS 1.3, servers may send a NewSessionTicket message at any time, + * and may send multiple NewSessionTicket messages. By default, TLS 1.3 + * clients ignore NewSessionTicket messages. * - * Up to Mbed TLS 3.5, in the default configuration TLS 1.3 was - * disabled, and a Mbed TLS client with the default configuration would - * establish a TLS 1.2 connection with a TLS 1.2 and TLS 1.3 capable - * server. - * - * Starting with Mbed TLS 3.6.0, TLS 1.3 is enabled by default, and thus - * an Mbed TLS client with the default configuration establishes a - * TLS 1.3 connection with a TLS 1.2 and TLS 1.3 capable server. If - * following the handshake the TLS 1.3 server sends NewSessionTicket - * messages and the Mbed TLS client processes them, this results in - * Mbed TLS high level APIs (mbedtls_ssl_read(), - * mbedtls_ssl_handshake(), ...) to eventually return an - * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET non fatal error code - * (see the documentation of mbedtls_ssl_read() for more information on - * that error code). Applications unaware of that TLS 1.3 specific non - * fatal error code are then failing. + * To support session tickets in TLS 1.3 clients, call this function + * with #MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED. When + * this is enabled, when a client receives a NewSessionTicket message, + * the next call to a message processing functions (notably + * mbedtls_ssl_handshake() and mbedtls_ssl_read()) will return + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET. The client should then + * call mbedtls_ssl_get_session() to retrieve the session ticket before + * calling the same message processing function again. * * \param conf SSL configuration * \param signal_new_session_tickets Enable or disable - * (MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED or - * MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_DISABLED) + * (#MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_ENABLED or + * #MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_DISABLED) */ void mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets( mbedtls_ssl_config *conf, int signal_new_session_tickets); @@ -5090,15 +5088,15 @@ int mbedtls_ssl_renegotiate(mbedtls_ssl_context *ssl); * new connection using the same source port. See below. * \return #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET if a TLS 1.3 * NewSessionTicket message has been received. - * This error code can be returned only on client side if and - * only if handling of TLS 1.3 NewSessionTicket messages has - * been enabled through the - * mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets() API. - * A TLS 1.3 NewSessionTicket message has been received and parsed - * successfully by the client. Ticket data is available in the - * SSL context and remain available as long as the client will - * not receive a new NewSessionTicket message. Ticket data may - * be retrieved through the mbedtls_ssl_get_session() API. + * This error code is only returned on the client side. It is + * only returned if handling of TLS 1.3 NewSessionTicket + * messages has been enabled through + * mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets(). + * This error code indicates that a TLS 1.3 NewSessionTicket + * message has been received and parsed successfully by the + * client. The ticket data can be retrieved from the SSL + * context by calling mbedtls_ssl_get_session(). It remains + * available until the next call to mbedtls_ssl_read(). * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as * defined in RFC 8446 (TLS 1.3 specification), has been * received as part of the handshake. This is server specific diff --git a/library/ssl_tls.c b/library/ssl_tls.c index 07eee6bebb..62e9c954e9 100644 --- a/library/ssl_tls.c +++ b/library/ssl_tls.c @@ -5893,6 +5893,28 @@ int mbedtls_ssl_config_defaults(mbedtls_ssl_config *conf, #if defined(MBEDTLS_SSL_SESSION_TICKETS) mbedtls_ssl_conf_session_tickets(conf, MBEDTLS_SSL_SESSION_TICKETS_ENABLED); #if defined(MBEDTLS_SSL_PROTO_TLS1_3) + /* Contrary to TLS 1.2 tickets, TLS 1.3 NewSessionTicket message + * handling is disabled by default in Mbed TLS 3.6.x for backward + * compatibility with client applications developed using Mbed TLS 3.5 + * or earlier with the default configuration. + * + * Up to Mbed TLS 3.5, in the default configuration TLS 1.3 was + * disabled, and a Mbed TLS client with the default configuration would + * establish a TLS 1.2 connection with a TLS 1.2 and TLS 1.3 capable + * server. + * + * Starting with Mbed TLS 3.6.0, TLS 1.3 is enabled by default, and thus + * an Mbed TLS client with the default configuration establishes a + * TLS 1.3 connection with a TLS 1.2 and TLS 1.3 capable server. If + * following the handshake the TLS 1.3 server sends NewSessionTicket + * messages and the Mbed TLS client processes them, this results in + * Mbed TLS high level APIs (mbedtls_ssl_read(), + * mbedtls_ssl_handshake(), ...) to eventually return an + * #MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET non fatal error code + * (see the documentation of mbedtls_ssl_read() for more information on + * that error code). Applications unaware of that TLS 1.3 specific non + * fatal error code are then failing. + */ mbedtls_ssl_conf_tls13_enable_signal_new_session_tickets( conf, MBEDTLS_SSL_TLS1_3_SIGNAL_NEW_SESSION_TICKETS_DISABLED); #endif