Middlebox compatibility mode

TLSv1.3 RFC 8446 Appendix D defines an optional Middlebox Compatibility Mode applications can use to mitigate middlebox issues in the network.

The TLSv1.3 protocol significantly altered existing handshake message formats, and added and removed other handshake messages. Early TLSv1.3 adopters encountered handshake failures as a result of middleboxes on the network between the client and server not understanding the new protocol. The problem middleboxes didn’t adhere to previous TLS protocol versions’ specifications making them brittle to the new protocol.

Middlebox Compatibility Mode makes the TLSv1.3 handshake flow look more like a TLSv1.2 handshake. This is accomplished by filling in legacy fields in handshake messages and by sending a TLSv1.2 handshake message eliminated from the pure TLSv1.3 implementation. These changes make the TLSv1.3 handshake appear similar to a TLSv1.2 session resumption which misbehaving middleboxes understand and generally allow through.

System TLS does not initiate middlebox compatibility mode by default. If needed in your network, this mode can be turned on globally for System TLS using TLSCONFIG option middleboxCompatibilityMode. Individual GSKit applications can enable this mode with gsk_attribute_set_enum(). System TLS always responds with middlebox compatibility mode processing when a peer is detected using this mode.