Merge pull request Mbed-TLS#8 from hanno-arm/tls13-prototype_doc

Enhance documentation of cTLS and TLS 1.3 compatibility mode configuration options

include/mbedtls/check_config.h

@@ -807,13 +807,27 @@
 #endif /* MBEDTLS_SSL_HW_RECORD_ACCEL */
 
 
-#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_ZERO_RTT) && ( !defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED) || !defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED))
+#if defined(MBEDTLS_SSL_PROTO_TLS1_3) &&                        \
+    defined(MBEDTLS_ZERO_RTT)         &&                        \
+    ( !defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED) ||             \
+      !defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED) )
 #error "ZeroRTT requires MBEDTLS_ZERO_RTT and MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED to be defined."
 #endif
 
-#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_COMPATIBILITY_MODE) && defined(MBEDTLS_CTLS)
+#if defined(MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE) && \
+    defined(MBEDTLS_SSL_TLS13_CTLS)
 #error "cTLS cannot be used in combination with the TLS 1.3 compatibility mode."
-#endif 
+#endif
+
+#if defined(MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE) && \
+    !defined(MBEDTLS_SSL_PROTO_TLS1_3)
+#error "MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE defined, but not all prerequesites."
+#endif
+
+#if defined(MBEDTLS_SSL_TLS13_CTLS) && \
+    !defined(MBEDTLS_SSL_PROTO_TLS1_3)
+#error "MBEDTLS_SSL_TLS13_CTLS defined, but not all prerequesites."
+#endif
 
 /*
  * The following extensions are no longer applicable to TLS 1.3,
@@ -893,7 +907,7 @@
  /* Caching in TLS 1.3 works differently than in TLS 1.2
   * Hence, SSL Cache MUST NOT be enabled.
  */
-#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_CACHE_C) 
+#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_CACHE_C)
 #error "SSL Caching not supported with TLS 1.3"
 #endif
 
@@ -902,17 +916,17 @@
 #error "The new session ticket concept is only available with TLS 1.3 and is not compatible with RFC 5077-style session tickets."
 #endif
 
-#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_PROTO_DTLS) && !defined(MBEDTLS_SSL_COOKIE_C) 
+#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_PROTO_DTLS) && !defined(MBEDTLS_SSL_COOKIE_C)
 #error "Cookie functionality needs to be enabled for DTLS 1.3"
 #endif
 
-#if defined(MBEDTLS_CTLS) && !defined(MBEDTLS_SSL_PROTO_TLS1_3)
+#if defined(MBEDTLS_SSL_TLS13_CTLS) && !defined(MBEDTLS_SSL_PROTO_TLS1_3)
 #error "cTLS can only be used in context with TLS and/or DTLS 1.3"
-#endif 
+#endif
 
-#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_CTLS) && !defined(MBEDTLS_CTLS_RANDOM_MAX_LENGTH)
-#define MBEDTLS_CTLS_RANDOM_MAX_LENGTH 32
-#endif 
+#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_TLS13_CTLS) && !defined(MBEDTLS_CTLS_RANDOM_MAX_LENGTH)
+#define MBEDTLS_SSL_TLS13_CTLS_RANDOM_MAX_LENGTH 32
+#endif
 
  /* Either SHA-256 or SHA-512 must be enabled.
   *
@@ -926,13 +940,13 @@
 #endif
 
 #if !defined(MBEDTLS_SSL_MAX_KEY_SHARES) && defined(MBEDTLS_ECDH_C) && defined(MBEDTLS_SSL_PROTO_TLS1_3)
-#define MBEDTLS_SSL_MAX_KEY_SHARES 1 
-#endif  
+#define MBEDTLS_SSL_MAX_KEY_SHARES 1
+#endif
 
 
 #if defined(MBEDTLS_SSL_PROTO_TLS1_3) && !defined(MBEDTLS_HKDF_C)
 #error "MBEDTLS_HKDF_C is required for TLS 1_3 to work. "
-#endif 
+#endif
 
 /*
  * Avoid warning from -pedantic. This is a convenient place for this

include/mbedtls/config.h

@@ -36,24 +36,33 @@
 
 
  /**
- * \def MBEDTLS_CTLS_RANDOM_MAX_LENGTH
+ * \def MBEDTLS_SSL_TLS13_CTLS_RANDOM_MAX_LENGTH
  *
  * Sets the maximum length for the random
  * in the ClientHello and the ServerHello.
  * (in bytes). This value MUST NOT be larger
- * than 32 bytes. 
+ * than 32 bytes.
  *
  */
-#define MBEDTLS_CTLS_RANDOM_MAX_LENGTH 32
+#define MBEDTLS_SSL_TLS13_CTLS_RANDOM_MAX_LENGTH 32
 
 
  /**
- * \def MBEDTLS_CTLS
+ * \def MBEDTLS_SSL_TLS13_CTLS
  *
- * Enables support for CTLS.
+ * Enable support for Compact TLS (cTLS).
+ *
+ * Compact TLS (cTLS) is a non-interoperable variant of the TLS 1.3 protocol
+ * that keeps the handshake logic of TLS 1.3 but applies compression techniques
+ * to reduce the transmission bandwidth of a handshake.
+ *
+ * \warning cTLS is _not_ interoperable with native TLS 1.3. If you want to use it,
+ *          you need to make sure out-of-band that the peer supports it.
+ *
+ * Uncomment to use the cTLS variant of TLS 1.3.
  *
  */
-//#define MBEDTLS_CTLS
+//#define MBEDTLS_SSL_TLS13_CTLS
 
 /**
 * \name SECTION: System support
@@ -89,9 +98,9 @@
  * Comment if you do not need the connection ID mechanism.
  */
 
-/* The old CID implementation has to be removed since 
- * CID functionality has been incorporated into the code 
- * already. 
+/* The old CID implementation has to be removed since
+ * CID functionality has been incorporated into the code
+ * already.
  */
  //#define MBEDTLS_CID
 
@@ -417,7 +426,7 @@
 * Enable the support for the ECDSA_SECP256r1_SHA256
 * signature scheme
 *
-* Requires: MBEDTLS_ECP_DP_SECP256R1_ENABLED, ... 
+* Requires: MBEDTLS_ECP_DP_SECP256R1_ENABLED, ...
 *
 * Comment this macro to disable the MBEDTLS_ECDSA_SECP256r1_SHA256 signature algo
 */
@@ -652,11 +661,11 @@
 *
 * Enables debug functions for the HKDF functions
 *
-* Requires: 
+* Requires:
 *
 * Uncomment this macro to include HKDF debug information
 */
-//#define HKDF_DEBUG 
+//#define HKDF_DEBUG
 
 /**
 * \def MBEDTLS_SSL_DEBUG_HANDSHAKE_HASHES
@@ -667,7 +676,7 @@
 *
 * Uncomment this macro to print handshake hash information
 */
-//#define MBEDTLS_SSL_DEBUG_HANDSHAKE_HASHES 
+//#define MBEDTLS_SSL_DEBUG_HANDSHAKE_HASHES
 
 
 /**
@@ -803,7 +812,7 @@
 *
 * Allows adjusting the length of the nonce field in the ticket.
 *
-* The default value is 32 bytes. 
+* The default value is 32 bytes.
 */
 #define MBEDTLS_SSL_TICKET_NONCE_LENGTH 32
 
@@ -822,7 +831,8 @@
 /**
 * \def MBEDTLS_SSL_PROTO_TLS1_3
 *
-* Enable support for TLS 1.3 (and DTLS 1.3 if DTLS is enabled).
+* Enable support for TLS 1.3 (and DTLS 1.3 if DTLS is enabled
+* via MBEDTLS_SSL_PROTO_DTLS).
 *
 * Requires: MBEDTLS_SHA1_C or MBEDTLS_SHA256_C or MBEDTLS_SHA512_C
 *           (Depends on ciphersuites)
@@ -831,25 +841,25 @@
 */
 #define MBEDTLS_SSL_PROTO_TLS1_3
 
-/* This is necessary to get the ECDH functions working because 
- * the new data structures expose different members. The code 
+/* This is necessary to get the ECDH functions working because
+ * the new data structures expose different members. The code
  * needs to be adjusted. */
-#define MBEDTLS_ECDH_LEGACY_CONTEXT 
+#define MBEDTLS_ECDH_LEGACY_CONTEXT
 
-/* Constant to the messaging layer working. Note: The messaging layer 
+/* Constant to the messaging layer working. Note: The messaging layer
  * will change with MPS in the future. */
 #define MBEDTLS_SSL_BUFFER_LEN 4096
 
 
-/* This declaration is needed currently because the code makes access 
+/* This declaration is needed currently because the code makes access
  * to the peer certificate. Ideally, it should be made optional. */
-#define MBEDTLS_SSL_KEEP_PEER_CERTIFICATE 
+#define MBEDTLS_SSL_KEEP_PEER_CERTIFICATE
 
 /**
 *  \def MBEDTLS_SSL_EARLY_DATA_MAX_DELAY
 *
 * Tolerance window for ticket age value.
-* Outside this tolerance window, 0-RTT mode will be disabled. 
+* Outside this tolerance window, 0-RTT mode will be disabled.
 *
 */
 
@@ -858,22 +868,22 @@
 /**
 *  \def MBEDTLS_SSL_MAX_KEY_SHARES
 *
-* Defines the maximum number of key share entires in a 
-* key share extension advertised as part of the ClientHello. 
-* 
-* The impact of increasing the number of key shares is that 
-* a client needs to store more ECDHE key pairs and the 
-* transmission size of the ClientHello is increased as well. 
+* Defines the maximum number of key share entires in a
+* key share extension advertised as part of the ClientHello.
+*
+* The impact of increasing the number of key shares is that
+* a client needs to store more ECDHE key pairs and the
+* transmission size of the ClientHello is increased as well.
 * On the positive side this allows more rapid session
 * establishment in case there is no prior knowledge between
-* the client and the server about the supported algorithms 
-* and curves. 
+* the client and the server about the supported algorithms
+* and curves.
 *
 */
 
 #define MBEDTLS_SSL_MAX_KEY_SHARES 1
 
-/** 
+/**
 *  \def MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN
 *  \def MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX
 *
@@ -887,7 +897,7 @@
 //#define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN   600000
 //#define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX  1800000
 
-// These values represent resonable settings. 
+// These values represent resonable settings.
 /*
 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN   1000
 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX  60000
@@ -1003,8 +1013,8 @@
 * tickets, including authenticated encryption and key management. Example
 * callbacks are provided by MBEDTLS_SSL_TICKET_C.
 *
-* Comment this macro to 
-*  - be able to issue tickets by TLS 1.3 servers, and 
+* Comment this macro to
+*  - be able to issue tickets by TLS 1.3 servers, and
 *  - use them in TLS 1.3 clients.
 */
 #define MBEDTLS_SSL_NEW_SESSION_TICKET
@@ -1828,14 +1838,26 @@
 //#define MBEDTLS_THREADING_C
 
 /**
-* \def MBEDTLS_COMPATIBILITY_MODE
+* \def MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE
+*
+* Enable TLS 1.3 middlebox compatibility mode.
+*
+* As specified in Section D.4 of RFC 8449, TLS 1.3 offers a compatibility
+* mode to make a TLS 1.3 connection more likely to pass through middle boxes
+* expecting TLS 1.2 traffic.
+*
+* Turning on the compatibility mode comes at the cost of a few added bytes
+* on the wire, but it doesn't affect compatibility with TLS 1.3 implementations
+* that don't use it. Therefore, unless transmission bandwidth is critical and
+* you know that middlebox compatibility issues won't occur, it is therefore
+* recommended to set this option.
 *
-* Enable the compatibility mode for TLS 1.3.
+* Comment to disable compatibility mode for TLS 1.3.
 *
 * Requires: MBEDTLS_SSL_PROTO_TLS1_3
 *
 */
-//#define MBEDTLS_COMPATIBILITY_MODE
+//#define MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE
 
 #define MBEDTLS_HKDF_C
 

include/mbedtls/ssl.h

@@ -598,14 +598,14 @@ extern "C" {
         MBEDTLS_SSL_HANDSHAKE_FINISH_ACK,
         MBEDTLS_SSL_HANDSHAKE_OVER,
         MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET,
-#if defined(MBEDTLS_COMPATIBILITY_MODE)
+#if defined(MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE)
         MBEDTLS_SSL_CLIENT_CCS_BEFORE_2ND_CLIENT_HELLO,
         MBEDTLS_SSL_CLIENT_CCS_BEFORE_CERTIFICATE_REQUEST,
         MBEDTLS_SSL_CLIENT_CCS_BEFORE_FINISHED,
         MBEDTLS_SSL_CLIENT_CCS_AFTER_CLIENT_HELLO,
         MBEDTLS_SSL_SERVER_CCS_AFTER_SERVER_HELLO,
         MBEDTLS_SSL_SERVER_CCS_AFTER_HRR,
-#endif /* MBEDTLS_COMPATIBILITY_MODE */
+#endif /* MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE */
         MBEDTLS_SSL_EARLY_APP_DATA
     }
     mbedtls_ssl_states;

include/mbedtls/ssl_internal.h

@@ -136,8 +136,8 @@
 
 
 /* For use with cTLS only */
-#define MBEDTLS_CTLS_DO_NOT_USE         0
-#define MBEDTLS_CTLS_USE                1
+#define MBEDTLS_SSL_TLS13_CTLS_DO_NOT_USE         0
+#define MBEDTLS_SSL_TLS13_CTLS_USE                1
 
 // Constants for use with varint data type introduced by cTLS
 #define MBEDTLS_VARINT_HDR_1 128
@@ -341,9 +341,9 @@ struct mbedtls_ssl_handshake_params
 #if defined(MBEDTLS_SSL_SRV_C)
     int hello_retry_requests_sent; /*!<  Number of Hello Retry Request messages sent by the server.  */
 #endif /* MBEDTLS_SSL_SRV_C */
-#if defined(MBEDTLS_COMPATIBILITY_MODE)
+#if defined(MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE)
     int ccs_sent; /* Number of CCS messages sent */
-#endif /* MBEDTLS_COMPATIBILITY_MODE */
+#endif /* MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE */
 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
 
 #if defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
@@ -667,9 +667,9 @@ struct mbedtls_ssl_handshake_params
     int extensions_present;             /*!< which extension were present; the */
 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
 
-#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_CTLS)
+#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_TLS13_CTLS)
     uint8_t ctls; /* value of 1 indicates we are using ctls */
-#endif /* MBEDTLS_SSL_PROTO_TLS1_3 && MBEDTLS_CTLS */
+#endif /* MBEDTLS_SSL_PROTO_TLS1_3 && MBEDTLS_SSL_TLS13_CTLS */
 #if (defined(MBEDTLS_SSL_SESSION_TICKETS) || (defined(MBEDTLS_SSL_NEW_SESSION_TICKET) && defined(MBEDTLS_SSL_PROTO_TLS1_3)))
     int new_session_ticket;             /*!< use NewSessionTicket?    */
 #endif /* MBEDTLS_SSL_SESSION_TICKETS || ( MBEDTLS_SSL_NEW_SESSION_TICKET && MBEDTLS_SSL_PROTO_TLS1_3 ) */
@@ -1133,11 +1133,11 @@ int ssl_parse_new_session_ticket(mbedtls_ssl_context* ssl);
 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
 
 
-#if defined(MBEDTLS_CTLS)
+#if defined(MBEDTLS_SSL_TLS13_CTLS)
 static enum varint_length_enum set_varint_length(uint32_t input, uint32_t* output);
 static uint8_t get_varint_length(const uint8_t input);
 static uint32_t get_varint_value(const uint32_t input);
-#endif /* MBEDTLS_CTLS */
+#endif /* MBEDTLS_SSL_TLS13_CTLS */
 
 
 int mbedtls_ssl_key_derivation(mbedtls_ssl_context* ssl, KeySet* traffic_keys);
@@ -1155,9 +1155,9 @@ int ssl_write_encrypted_extension(mbedtls_ssl_context* ssl);
 int mbedtls_ssl_derive_traffic_keys(mbedtls_ssl_context* ssl, KeySet* traffic_keys);
 int incrementSequenceNumber(unsigned char* sequenceNumber, unsigned char* nonce, size_t ivlen);
 
-#if defined(MBEDTLS_COMPATIBILITY_MODE)
+#if defined(MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE)
 int mbedtls_ssl_write_change_cipher_spec(mbedtls_ssl_context* ssl);
-#endif /* MBEDTLS_COMPATIBILITY_MODE */
+#endif /* MBEDTLS_SSL_TLS13_COMPATIBILITY_MODE */
 
 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
 int ssl_write_pre_shared_key_ext(mbedtls_ssl_context* ssl, unsigned char* buf, unsigned char* end, size_t* olen, int dummy_run);