feat(translator): client tls session resumption

api/v1alpha1/tls_types.go

@@ -15,6 +15,10 @@ type ClientTLSSettings struct {
 	// +optional
 	ClientValidation *ClientValidationContext `json:"clientValidation,omitempty"`
 	TLSSettings      `json:",inline"`
+
+	// Session defines settings related to TLS session management.
+	// +optional
+	Session *Session `json:"session,omitempty"`
 }
 
 // +kubebuilder:validation:XValidation:rule="has(self.minVersion) && self.minVersion == '1.3' ? !has(self.ciphers) : true", message="setting ciphers has no effect if the minimum possible TLS version is 1.3"
@@ -133,3 +137,40 @@ type ClientValidationContext struct {
 	// +optional
 	CACertificateRefs []gwapiv1.SecretObjectReference `json:"caCertificateRefs,omitempty"`
 }
+
+// Session defines settings related to TLS session management.
+type Session struct {
+	// Resumption determines the proxy's supported TLS session resumption option.
+	// By default, Envoy Gateway does not enable session resumption. Use sessionResumption to
+	// enable stateful and stateless session resumption. Users should consider security impacts
+	// of different resumption methods. Performance gains from resumption are diminished when
+	// Envoy proxy is deployed with more than one replica.
+	// +optional
+	Resumption *SessionResumption `json:"resumption,omitempty"`
+}
+
+// SessionResumption defines supported tls session resumption methods and their associated configuration.
+type SessionResumption struct {
+	// Stateless defines setting for stateless (session-ticket based) session resumption
+	// +optional
+	Stateless *StatelessTLSSessionResumption `json:"stateless,omitempty"`
+
+	// Stateful defines setting for stateful (session-id based) session resumption
+	// +optional
+	Stateful *StatefulTLSSessionResumption `json:"stateful,omitempty"`
+}
+
+// StatefulTLSSessionResumption defines the stateful (session-id based) type of TLS session resumption.
+// Note: When Envoy Proxy is deployed with more than one replica, session caches are not synchronized
+// between instances, possibly leading to resumption failures.
+// Envoy does not re-validate client certificates upon session resumption.
+// https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#config-route-v3-routematch-tlscontextmatchoptions
+type StatefulTLSSessionResumption struct{}
+
+// StatelessTLSSessionResumption defines the stateless (session-ticket based) type of TLS session resumption.
+// Note: When Envoy Proxy is deployed with more than one replica, session ticket encryption keys are not
+// synchronized between instances, possibly leading to resumption failures.
+// In-memory session ticket encryption keys are rotated every 48 hours.
+// https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlssessionticketkeys
+// https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#Session-tickets
+type StatelessTLSSessionResumption struct{}

charts/gateway-helm/crds/generated/gateway.envoyproxy.io_clienttrafficpolicies.yaml

@@ -808,6 +808,27 @@ spec:
                     - "1.2"
                     - "1.3"
                     type: string
+                  session:
+                    description: Session defines settings related to TLS session management.
+                    properties:
+                      resumption:
+                        description: |-
+                          Resumption determines the proxy's supported TLS session resumption option.
+                          By default, Envoy Gateway does not enable session resumption. Use sessionResumption to
+                          enable stateful and stateless session resumption. Users should consider security impacts
+                          of different resumption methods. Performance gains from resumption are diminished when
+                          Envoy proxy is deployed with more than one replica.
+                        properties:
+                          stateful:
+                            description: Stateful defines setting for stateful (session-id
+                              based) session resumption
+                            type: object
+                          stateless:
+                            description: Stateless defines setting for stateless (session-ticket
+                              based) session resumption
+                            type: object
+                        type: object
+                    type: object
                   signatureAlgorithms:
                     description: |-
                       SignatureAlgorithms specifies which signature algorithms the listener should

internal/gatewayapi/clienttrafficpolicy.go

@@ -864,6 +864,15 @@ func (t *Translator) buildListenerTLSParameters(policy *egv1a1.ClientTrafficPoli
 		}
 	}
 
+	if tlsParams.Session != nil && tlsParams.Session.Resumption != nil {
+		if tlsParams.Session.Resumption.Stateless != nil {
+			irTLSConfig.StatelessSessionResumption = true
+		}
+		if tlsParams.Session.Resumption.Stateful != nil {
+			irTLSConfig.StatefulSessionResumption = true
+		}
+	}
+
 	return irTLSConfig, nil
 }
 

internal/gatewayapi/testdata/clienttrafficpolicy-tls-settings.in.yaml

@@ -22,6 +22,10 @@ clientTrafficPolicies:
       signatureAlgorithms:
       - sig1
       - sig2
+      session:
+        resumption:
+          stateless: {}
+          stateful: {}
 gateways:
 - apiVersion: gateway.networking.k8s.io/v1
   kind: Gateway

internal/gatewayapi/testdata/clienttrafficpolicy-tls-settings.out.yaml

@@ -20,6 +20,10 @@ clientTrafficPolicies:
       - curve1
       maxVersion: "1.3"
       minVersion: "1.0"
+      session:
+        resumption:
+          stateful: {}
+          stateless: {}
       signatureAlgorithms:
       - sig1
       - sig2
@@ -174,6 +178,8 @@ xdsIR:
         signatureAlgorithms:
         - sig1
         - sig2
+        statefulSessionResumption: true
+        statelessSessionResumption: true
     - address: 0.0.0.0
       hostnames:
       - '*'

internal/ir/xds.go

@@ -351,6 +351,10 @@ type TLSConfig struct {
 	SignatureAlgorithms []string `json:"signatureAlgorithms,omitempty" yaml:"signatureAlgorithms,omitempty"`
 	// ALPNProtocols exposed by this listener
 	ALPNProtocols []string `json:"alpnProtocols,omitempty" yaml:"alpnProtocols,omitempty"`
+	// StatelessSessionResumption determines if stateless (session-ticket based) session resumption is enabled
+	StatelessSessionResumption bool `json:"statelessSessionResumption,omitempty" yaml:"statelessSessionResumption,omitempty"`
+	// StatefulSessionResumption determines if stateful (session-id based) session resumption is enabled
+	StatefulSessionResumption bool `json:"statefulSessionResumption,omitempty" yaml:"statefulSessionResumption,omitempty"`
 }
 
 // TLSCertificate holds a single certificate's details

internal/xds/translator/listener.go

@@ -624,6 +624,8 @@ func buildDownstreamQUICTransportSocket(tlsConfig *ir.TLSConfig) (*corev3.Transp
 		}
 	}
 
+	setDownstreamTLSSessionSettings(tlsConfig, tlsCtx.DownstreamTlsContext)
+
 	tlsCtxAny, err := anypb.New(tlsCtx)
 	if err != nil {
 		return nil, err
@@ -664,6 +666,8 @@ func buildXdsDownstreamTLSSocket(tlsConfig *ir.TLSConfig) (*corev3.TransportSock
 		}
 	}
 
+	setDownstreamTLSSessionSettings(tlsConfig, tlsCtx)
+
 	tlsCtxAny, err := anypb.New(tlsCtx)
 	if err != nil {
 		return nil, err
@@ -677,6 +681,18 @@ func buildXdsDownstreamTLSSocket(tlsConfig *ir.TLSConfig) (*corev3.TransportSock
 	}, nil
 }
 
+func setDownstreamTLSSessionSettings(tlsConfig *ir.TLSConfig, tlsCtx *tlsv3.DownstreamTlsContext) {
+	if !tlsConfig.StatefulSessionResumption {
+		tlsCtx.DisableStatefulSessionResumption = true
+	}
+
+	if !tlsConfig.StatelessSessionResumption {
+		tlsCtx.SessionTicketKeysType = &tlsv3.DownstreamTlsContext_DisableStatelessSessionResumption{
+			DisableStatelessSessionResumption: true,
+		}
+	}
+}
+
 func buildTLSParams(tlsConfig *ir.TLSConfig) *tlsv3.TlsParameters {
 	p := &tlsv3.TlsParameters{}
 	isEmpty := true

internal/xds/translator/testdata/in/xds-ir/tls-with-ciphers-versions-alpn.yaml

@@ -30,6 +30,7 @@ http:
     minVersion: "1.0"
     alpnProtocols:
     - some-other-protocol
+    statefulSessionResumption: true
     certificates:
     - name: secret-1
       # byte slice representation of "key-data"
@@ -107,6 +108,7 @@ tcp:
         minVersion: "1.0"
         alpnProtocols:
         - some-other-protocol
+        statelessSessionResumption: true
         certificates:
         - name: secret-3
           # byte slice representation of "key-data"

internal/xds/translator/testdata/out/xds-ir/http3.listeners.yaml

@@ -47,6 +47,8 @@
               sdsConfig:
                 ads: {}
                 resourceApiVersion: V3
+          disableStatefulSessionResumption: true
+          disableStatelessSessionResumption: true
   name: envoy-gateway/gateway-1/tls-quic
   udpListenerConfig:
     downstreamSocketConfig: {}
@@ -96,5 +98,7 @@
             sdsConfig:
               ads: {}
               resourceApiVersion: V3
+        disableStatefulSessionResumption: true
+        disableStatelessSessionResumption: true
   name: envoy-gateway/gateway-1/tls
   perConnectionBufferLimitBytes: 32768

internal/xds/translator/testdata/out/xds-ir/jsonpatch-with-jsonpath.listeners.yaml

@@ -59,5 +59,7 @@
             sdsConfig:
               ads: {}
               resourceApiVersion: V3
+        disableStatefulSessionResumption: true
+        disableStatelessSessionResumption: true
   name: first-listener
   perConnectionBufferLimitBytes: 32768

internal/xds/translator/testdata/out/xds-ir/jsonpatch.listeners.yaml

@@ -59,5 +59,7 @@
             sdsConfig:
               ads: {}
               resourceApiVersion: V3
+        disableStatefulSessionResumption: true
+        disableStatelessSessionResumption: true
   name: first-listener
   perConnectionBufferLimitBytes: 32768

internal/xds/translator/testdata/out/xds-ir/listener-proxy-protocol.listeners.yaml

@@ -50,6 +50,8 @@
             sdsConfig:
               ads: {}
               resourceApiVersion: V3
+        disableStatefulSessionResumption: true
+        disableStatelessSessionResumption: true
   listenerFilters:
   - name: envoy.filters.listener.proxy_protocol
     typedConfig:

internal/xds/translator/testdata/out/xds-ir/mixed-tls-jwt-authn.listeners.yaml

@@ -43,5 +43,7 @@
             sdsConfig:
               ads: {}
               resourceApiVersion: V3
+        disableStatefulSessionResumption: true
+        disableStatelessSessionResumption: true
   name: first-listener
   perConnectionBufferLimitBytes: 32768

internal/xds/translator/testdata/out/xds-ir/multiple-listeners-same-port.listeners.yaml

@@ -74,6 +74,8 @@
             sdsConfig:
               ads: {}
               resourceApiVersion: V3
+        disableStatefulSessionResumption: true
+        disableStatelessSessionResumption: true
   - filterChainMatch:
       serverNames:
       - foo.net
@@ -117,6 +119,8 @@
             sdsConfig:
               ads: {}
               resourceApiVersion: V3
+        disableStatefulSessionResumption: true
+        disableStatelessSessionResumption: true
   - filterChainMatch:
       serverNames:
       - bar.com