feat(translator): client tls session resumption

api/v1alpha1/tls_types.go

@@ -15,6 +15,20 @@ type ClientTLSSettings struct {
 	// +optional
 	ClientValidation *ClientValidationContext `json:"clientValidation,omitempty"`
 	TLSSettings      `json:",inline"`
+
+	// SessionTimeout determines the maximum lifetime of a TLS session.
+	// https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_DEFAULT_SESSION_TIMEOUT
+	// Default: 7200s
+	// +optional
+	SessionTimeout *gwapiv1.Duration `json:"sessionTimeout,omitempty"`
+
+	// SessionResumptionSettings determine 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
+	SessionResumptionSettings *SessionResumption `json:"sessionResumption,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 +147,29 @@ type ClientValidationContext struct {
 	// +optional
 	CACertificateRefs []gwapiv1.SecretObjectReference `json:"caCertificateRefs,omitempty"`
 }
+
+// SessionResumption defines supported tls session resumption methods and their associated configuration.
+type SessionResumption struct {
+	// StatelessSessionResumption defines setting for stateless (session-ticket based) session resumption
+	// +optional
+	StatelessSessionResumption *StatelessTLSSessionResumption `json:"statelessSessionResumption,omitempty"`
+
+	// StatefulSessionResumption defines setting for stateful (session-id based) session resumption
+	// +optional
+	StatefulSessionResumption *StatefulTLSSessionResumption `json:"statefulSessionResumption,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,30 @@ spec:
                     - "1.2"
                     - "1.3"
                     type: string
+                  sessionResumption:
+                    description: |-
+                      SessionResumptionSettings determine 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:
+                      statefulSessionResumption:
+                        description: StatefulSessionResumption defines setting for
+                          stateful (session-id based) session resumption
+                        type: object
+                      statelessSessionResumption:
+                        description: StatelessSessionResumption defines setting for
+                          stateless (session-ticket based) session resumption
+                        type: object
+                    type: object
+                  sessionTimeout:
+                    description: |-
+                      SessionTimeout determines the maximum lifetime of a TLS session.
+                      https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_DEFAULT_SESSION_TIMEOUT
+                      Default: 7200s
+                    pattern: ^([0-9]{1,5}(h|m|s|ms)){1,4}$
+                    type: string
                   signatureAlgorithms:
                     description: |-
                       SignatureAlgorithms specifies which signature algorithms the listener should

internal/gatewayapi/clienttrafficpolicy.go

@@ -864,6 +864,23 @@
 		}
 	}
 
+	if tlsParams.SessionResumptionSettings != nil {
+		if tlsParams.SessionResumptionSettings.StatelessSessionResumption != nil {
+			irTLSConfig.StatelessSessionResumption = true
+		}
+		if tlsParams.SessionResumptionSettings.StatefulSessionResumption != nil {
+			irTLSConfig.StatefulSessionResumption = true
+		}
+	}
+
+	if tlsParams.SessionTimeout != nil {
+		d, err := time.ParseDuration(string(*tlsParams.SessionTimeout))
+		if err != nil {
+			return nil, fmt.Errorf("invalid TLS SessionTimeout value %s", *tlsParams.SessionTimeout)
+		}
+		irTLSConfig.SessionTimeout = ptr.To(metav1.Duration{Duration: d})
+	}
+
 	return irTLSConfig, nil
 }
 

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

@@ -22,6 +22,10 @@ clientTrafficPolicies:
       signatureAlgorithms:
       - sig1
       - sig2
+      sessionTimeout: 30s
+      sessionResumption:
+        statelessSessionResumption: {}
+        statefulSessionResumption: {}
 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"
+      sessionResumption:
+        statefulSessionResumption: {}
+        statelessSessionResumption: {}
+      sessionTimeout: 30s
       signatureAlgorithms:
       - sig1
       - sig2
@@ -171,9 +175,12 @@ xdsIR:
         - curve1
         maxVersion: "1.3"
         minVersion: "1.0"
+        sessionTimeout: 30s
         signatureAlgorithms:
         - sig1
         - sig2
+        statefulSessionResumption: true
+        statelessSessionResumption: true
     - address: 0.0.0.0
       hostnames:
       - '*'

internal/ir/xds.go

@@ -350,6 +350,12 @@ type TLSConfig struct {
 	SignatureAlgorithms []string `json:"signatureAlgorithms,omitempty" yaml:"signatureAlgorithms,omitempty"`
 	// ALPNProtocols exposed by this listener
 	ALPNProtocols []string `json:"alpnProtocols,omitempty" yaml:"alpnProtocols,omitempty"`
+	// SessionTimeout determines the maximum lifetime of a TLS session
+	SessionTimeout *metav1.Duration `json:"sessionTimeout,omitempty" yaml:"sessionTimeout,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,22 @@ func buildXdsDownstreamTLSSocket(tlsConfig *ir.TLSConfig) (*corev3.TransportSock
 	}, nil
 }
 
+func setDownstreamTLSSessionSettings(tlsConfig *ir.TLSConfig, tlsCtx *tlsv3.DownstreamTlsContext) {
+	if tlsConfig.SessionTimeout != nil {
+		tlsCtx.SessionTimeout = durationpb.New(tlsConfig.SessionTimeout.Duration)
+	}
+
+	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,8 @@ http:
     minVersion: "1.0"
     alpnProtocols:
     - some-other-protocol
+    sessionTimeout: 30s
+    statefulSessionResumption: true
     certificates:
     - name: secret-1
       # byte slice representation of "key-data"
@@ -107,6 +109,8 @@ tcp:
         minVersion: "1.0"
         alpnProtocols:
         - some-other-protocol
+        sessionTimeout: 60s
+        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