api: client tls session resumption

Signed-off-by: Guy Daich <[email protected]>
envoyproxy · Sep 20, 2024 · e6d9813 · e6d9813
1 parent 91bea68
commit e6d9813
Show file tree

Hide file tree

Showing 5 changed files with 273 additions and 0 deletions.
diff --git a/api/v1alpha1/tls_types.go b/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"`
+
+	// StatelessSessionResumption defines setting for stateless (session-ticket based) session resumption
+	// +optional
+	StatelessSessionResumption *StatelessSessionResumptionSettings `json:"statelessSessionResumption,omitempty"`
+
+	// StatefulSessionResumption defines setting for stateful (session-id based) session resumption
+	// +optional
+	StatefulSessionResumption *StatefulSessionResumptionSettings `json:"statefulSessionResumptionSettings,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,36 @@ type ClientValidationContext struct {
 	// +optional
 	CACertificateRefs []gwapiv1.SecretObjectReference `json:"caCertificateRefs,omitempty"`
 }
+
+// StatelessSessionResumptionSettings defines setting for stateless (session-ticket based) session resumption
+// +kubebuilder:validation:XValidation:rule="(self.enabled == false && self.sessionTicketKeysRef.size() > 0)",message="sessionTicketKeysRef can only be set when enabled is true"
+type StatelessSessionResumptionSettings struct {
+	// Enabled determines if stateless session resumption is supported. When Envoy Proxy is deployed with more than
+	// one replica, session ticket encryption keys are not synchronized between instances, possibly leading to resumption
+	// failures. Users can synchronize session ticket encryption keys be storing them in a secret and using the
+	// sessionTicketKeysRef option.
+	// Note that improper handling of session ticket encryption keys may result in loss of secrecy.
+	// https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlssessionticketkeys
+	// Default: true
+	Enabled *bool `json:"enabled,omitempty"`
+
+	// SessionTicketKeysRef is a reference to the secret containing the keys to use for encryption and decryption
+	// of session tickets. The first keys is used for encryption and all keys are candidate for decryption.
+	// Users are responsible for securely generating, storing and rotating keys.
+	// If empty, each Envoy Proxy instance will use local in-memory keys.
+	// https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlssessionticketkeys
+	// +kubebuilder:validation:MaxItems=16
+	// +optional
+	SessionTicketKeysRef []gwapiv1.SecretObjectReference `json:"sessionTicketKeysRef,omitempty"`
+}
+
+// StatefulSessionResumptionSettings defines setting for stateful (session-id based) session resumption
+type StatefulSessionResumptionSettings struct {
+	// Enabled determines if stateful session resumption is supported. When Envoy Proxy is deployed with more than
+	// one replica, session caches are not synchronized between instances, possibly leading to resumption failures.
+	// Note that 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
+	// Default: true
+	// +optional
+	Enabled *bool `json:"enabled,omitempty"`
+}
diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go
diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_clienttrafficpolicies.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_clienttrafficpolicies.yaml
@@ -808,13 +808,113 @@ spec:
                     - "1.2"
                     - "1.3"
                     type: string
+                  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
                       support.
                     items:
                       type: string
                     type: array
+                  statefulSessionResumptionSettings:
+                    description: StatefulSessionResumption defines setting for stateful
+                      (session-id based) session resumption
+                    properties:
+                      enabled:
+                        description: |-
+                          Enabled determines if stateful session resumption is supported. When Envoy Proxy is deployed with more than
+                          one replica, session caches are not synchronized between instances, possibly leading to resumption failures.
+                          Note that 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
+                          Default: true
+                        type: boolean
+                    type: object
+                  statelessSessionResumption:
+                    description: StatelessSessionResumption defines setting for stateless
+                      (session-ticket based) session resumption
+                    properties:
+                      enabled:
+                        description: |-
+                          Enabled determines if stateless session resumption is supported. When Envoy Proxy is deployed with more than
+                          one replica, session ticket encryption keys are not synchronized between instances, possibly leading to resumption
+                          failures. Users can synchronize session ticket encryption keys be storing them in a secret and using the
+                          sessionTicketKeysRef option.
+                          Note that improper handling of session ticket encryption keys may result in loss of secrecy.
+                          https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlssessionticketkeys
+                          Default: true
+                        type: boolean
+                      sessionTicketKeysRef:
+                        description: |-
+                          SessionTicketKeysRef is a reference to the secret containing the keys to use for encryption and decryption
+                          of session tickets. The first keys is used for encryption and all keys are candidate for decryption.
+                          Users are responsible for securely generating, storing and rotating keys.
+                          If empty, each Envoy Proxy instance will use local in-memory keys.
+                          https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlssessionticketkeys
+                        items:
+                          description: |-
+                            SecretObjectReference identifies an API object including its namespace,
+                            defaulting to Secret.
+
+                            The API object must be valid in the cluster; the Group and Kind must
+                            be registered in the cluster for this reference to be valid.
+
+                            References to objects with invalid Group and Kind are not valid, and must
+                            be rejected by the implementation, with appropriate Conditions set
+                            on the containing object.
+                          properties:
+                            group:
+                              default: ""
+                              description: |-
+                                Group is the group of the referent. For example, "gateway.networking.k8s.io".
+                                When unspecified or empty string, core API group is inferred.
+                              maxLength: 253
+                              pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
+                              type: string
+                            kind:
+                              default: Secret
+                              description: Kind is kind of the referent. For example
+                                "Secret".
+                              maxLength: 63
+                              minLength: 1
+                              pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
+                              type: string
+                            name:
+                              description: Name is the name of the referent.
+                              maxLength: 253
+                              minLength: 1
+                              type: string
+                            namespace:
+                              description: |-
+                                Namespace is the namespace of the referenced object. When unspecified, the local
+                                namespace is inferred.
+
+                                Note that when a namespace different than the local namespace is specified,
+                                a ReferenceGrant object is required in the referent namespace to allow that
+                                namespace's owner to accept the reference. See the ReferenceGrant
+                                documentation for details.
+
+                                Support: Core
+                              maxLength: 63
+                              minLength: 1
+                              pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
+                              type: string
+                          required:
+                          - name
+                          type: object
+                        maxItems: 16
+                        type: array
+                    type: object
+                    x-kubernetes-validations:
+                    - message: sessionTicketKeysRef can only be set when enabled is
+                        true
+                      rule: (self.enabled == false && self.sessionTicketKeysRef.size()
+                        > 0)
                 type: object
                 x-kubernetes-validations:
                 - message: setting ciphers has no effect if the minimum possible TLS

diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md
@@ -610,6 +610,9 @@ _Appears in:_
 | `ecdhCurves` | _string array_ |  false  | ECDHCurves specifies the set of supported ECDH curves.<br />In non-FIPS Envoy Proxy builds the default curves are:<br />- X25519<br />- P-256<br />In builds using BoringSSL FIPS the default curve is:<br />- P-256 |
 | `signatureAlgorithms` | _string array_ |  false  | SignatureAlgorithms specifies which signature algorithms the listener should<br />support. |
 | `alpnProtocols` | _[ALPNProtocol](#alpnprotocol) array_ |  false  | ALPNProtocols supplies the list of ALPN protocols that should be<br />exposed by the listener. By default h2 and http/1.1 are enabled.<br />Supported values are:<br />- http/1.0<br />- http/1.1<br />- h2 |
+| `sessionTimeout` | _[Duration](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Duration)_ |  false  | SessionTimeout determines the maximum lifetime of a TLS session.<br />https://commondatastorage.googleapis.com/chromium-boringssl-docs/ssl.h.html#SSL_DEFAULT_SESSION_TIMEOUT<br />Default: 7200s |
+| `statelessSessionResumption` | _[StatelessSessionResumptionSettings](#statelesssessionresumptionsettings)_ |  false  | StatelessSessionResumption defines setting for stateless (session-ticket based) session resumption |
+| `statefulSessionResumptionSettings` | _[StatefulSessionResumptionSettings](#statefulsessionresumptionsettings)_ |  false  | StatefulSessionResumption defines setting for stateful (session-id based) session resumption |
 
 
 #### ClientTimeout
@@ -3608,6 +3611,35 @@ _Appears in:_
 | `Distinct` | SourceMatchDistinct Each IP Address within the specified Source IP CIDR is treated as a distinct client selector<br />and uses a separate rate limit bucket/counter.<br />Note: This is only supported for Global Rate Limits.<br /> | 
 
 
+#### StatefulSessionResumptionSettings
+
+
+
+StatefulSessionResumptionSettings defines setting for stateful (session-id based) session resumption
+
+_Appears in:_
+- [ClientTLSSettings](#clienttlssettings)
+
+| Field | Type | Required | Description |
+| ---   | ---  | ---      | ---         |
+| `enabled` | _boolean_ |  false  | Enabled determines if stateful session resumption is supported. When Envoy Proxy is deployed with more than<br />one replica, session caches are not synchronized between instances, possibly leading to resumption failures.<br />Note that envoy does not re-validate client certificates upon session resumption.<br />https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#config-route-v3-routematch-tlscontextmatchoptions<br />Default: true |
+
+
+#### StatelessSessionResumptionSettings
+
+
+
+StatelessSessionResumptionSettings defines setting for stateless (session-ticket based) session resumption
+
+_Appears in:_
+- [ClientTLSSettings](#clienttlssettings)
+
+| Field | Type | Required | Description |
+| ---   | ---  | ---      | ---         |
+| `enabled` | _boolean_ |  true  | Enabled determines if stateless session resumption is supported. When Envoy Proxy is deployed with more than<br />one replica, session ticket encryption keys are not synchronized between instances, possibly leading to resumption<br />failures. Users can synchronize session ticket encryption keys be storing them in a secret and using the<br />sessionTicketKeysRef option.<br />Note that improper handling of session ticket encryption keys may result in loss of secrecy.<br />https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlssessionticketkeys<br />Default: true |
+| `sessionTicketKeysRef` | _[SecretObjectReference](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.SecretObjectReference) array_ |  false  | SessionTicketKeysRef is a reference to the secret containing the keys to use for encryption and decryption<br />of session tickets. The first keys is used for encryption and all keys are candidate for decryption.<br />Users are responsible for securely generating, storing and rotating keys.<br />If empty, each Envoy Proxy instance will use local in-memory keys.<br />https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#extensions-transport-sockets-tls-v3-tlssessionticketkeys |
+
+
 #### StringMatch