tls: introduce mode and sni to cert matching behavior

This patch adds a `mode` property to TLSConfig which determines the TLS behavior for each listener.
kubernetes-sigs · Aug 12, 2020 · 08f2d69 · 08f2d69
1 parent 35c3604
commit 08f2d69
Show file tree

Hide file tree

Showing 8 changed files with 377 additions and 231 deletions.
diff --git a/apis/v1alpha1/gateway_types.go b/apis/v1alpha1/gateway_types.go
@@ -249,6 +249,16 @@ type Listener struct {
 	// is required if the Protocol field is "HTTPS" or "TLS" and
 	// ignored otherwise.
 	//
+	// The association of SNIs to Certificate defined in TLSConfig is
+	// defined based on the value of HostnameMatchType for this listener:
+	// - "Domain": Certificate should be used used for the domain and its
+	//   first-level subdomains.
+	// - "Exact": Certificate should be used for the domain only.
+	// - "Any": Certificate in TLSConfig is the default certificate to use.
+	//
+	// The GatewayClass MUST use the longest matching SNI out of all
+	// available certificate for any TLS handshake.
+	//
 	// Support: Core
 	//
 	// +optional

diff --git a/apis/v1alpha1/generated.pb.go b/apis/v1alpha1/generated.pb.go
diff --git a/apis/v1alpha1/generated.proto b/apis/v1alpha1/generated.proto
diff --git a/apis/v1alpha1/tlsconfig_types.go b/apis/v1alpha1/tlsconfig_types.go
@@ -15,6 +15,18 @@ limitations under the License.
 
 package v1alpha1
 
+// TLSMode type defines behavior of gateway with TLS protocol.
+// +kubebuilder:validation:Enum=Terminate;Passthrough
+// +kubebuilder:default=Terminate
+type TLSMode string
+
+const (
+	// TLSModeTerminate represents the Terminate mode.
+	TLSModeTerminate TLSMode = "Terminate"
+	// TLSModePassthrough represents the Passthrough mode.
+	TLSModePassthrough TLSMode = "Passthrough"
+)
+
 // TLSConfig describes a TLS configuration.
 //
 // References
@@ -25,20 +37,28 @@ package v1alpha1
 // - aws: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html#describe-ssl-policies
 // - azure: https://docs.microsoft.com/en-us/azure/app-service/configure-ssl-bindings#enforce-tls-1112
 type TLSConfig struct {
-	// CertificateRefs is a list of references to Kubernetes objects that each
-	// contain an identity certificate.  The host name in a TLS SNI client hello
-	// message is used for certificate matching and route host name selection.
-	// The SNI server_name must match a route host name for the Gateway to route
-	// the TLS request.  If an entry in this list omits or specifies the empty
+	// Mode defines the TLS behavior for the TLS session initiated by the client.
+	// There are two possible modes:
+	// - Terminate: The TLS session between the downstream client
+	//   and the Gateway is terminated at the Gateway.
+	// - Passthrough: The TLS session NOT terminated by the Gateway. This
+	//   implies that the Gateway can't decipher the TLS stream except for
+	//   the ClientHello message of the TLS protocol.
+	Mode TLSMode `json:"mode,omitempty" protobuf:"bytes,1,opt,name=mode"`
+
+	// CertificateRef is the reference to Kubernetes object that
+	// contain an identity certificate.
+	// This certificate MUST be used for TLS handshakes for the domain
+	// this TLSConfig is associated with.
+	// If an entry in this list omits or specifies the empty
 	// string for both the group and the resource, the resource defaults to "secrets".
 	// An implementation may support other resources (for example, resource
 	// "mycertificates" in group "networking.acme.io").
-	//
 	// Support: Core (Kubernetes Secrets)
 	// Support: Implementation-specific (Other resource types)
 	//
 	// +required
-	CertificateRefs []CertificateObjectReference `json:"certificateRefs,omitempty" protobuf:"bytes,1,rep,name=certificateRefs"`
+	CertificateRef CertificateObjectReference `json:"certificateRef,omitempty" protobuf:"bytes,2,opt,name=certificateRef"`
 	// Options are a list of key/value pairs to give extended options
 	// to the provider.
 	//

diff --git a/apis/v1alpha1/zz_generated.deepcopy.go b/apis/v1alpha1/zz_generated.deepcopy.go
diff --git a/config/crd/bases/networking.x-k8s.io_gateways.yaml b/config/crd/bases/networking.x-k8s.io_gateways.yaml
@@ -176,28 +176,31 @@ spec:
                       - resource
                       type: object
                     tls:
-                      description: "TLS is the TLS configuration for the Listener. This field is required if the Protocol field is \"HTTPS\" or \"TLS\" and ignored otherwise. \n Support: Core"
+                      description: "TLS is the TLS configuration for the Listener. This field is required if the Protocol field is \"HTTPS\" or \"TLS\" and ignored otherwise. \n The association of SNIs to Certificate defined in TLSConfig is defined based on the value of HostnameMatchType for this listener: - \"Domain\": Certificate should be used used for the domain and its   first-level subdomains. - \"Exact\": Certificate should be used for the domain only. - \"Any\": Certificate in TLSConfig is the default certificate to use. \n The GatewayClass MUST use the longest matching SNI out of all available certificate for any TLS handshake. \n Support: Core"
                       properties:
-                        certificateRefs:
-                          description: "CertificateRefs is a list of references to Kubernetes objects that each contain an identity certificate.  The host name in a TLS SNI client hello message is used for certificate matching and route host name selection. The SNI server_name must match a route host name for the Gateway to route the TLS request.  If an entry in this list omits or specifies the empty string for both the group and the resource, the resource defaults to \"secrets\". An implementation may support other resources (for example, resource \"mycertificates\" in group \"networking.acme.io\"). \n Support: Core (Kubernetes Secrets) Support: Implementation-specific (Other resource types)"
-                          items:
-                            description: SecretsDefaultLocalObjectReference identifies an API object within a known namespace that defaults group to core and resource to secrets if unspecified.
-                            properties:
-                              group:
-                                default: core
-                                description: "Group is the group of the referent.  Omitting the value or specifying the empty string indicates the core API group.  For example, use the following to specify a secrets resource: \n fooRef:   resource: secrets   name: mysecret \n Otherwise, if the core API group is not desired, specify the desired group: \n fooRef:   group: acme.io   resource: foos   name: myfoo"
-                                type: string
-                              name:
-                                description: Name is the name of the referent.
-                                type: string
-                              resource:
-                                default: secrets
-                                description: "Resource is the API resource name of the referent. Omitting the value or specifying the empty string indicates the secrets resource. For example, use the following to specify a secrets resource: \n fooRef:   name: mysecret \n Otherwise, if the secrets resource is not desired, specify the desired group: \n fooRef:   group: acme.io   resource: foos   name: myfoo"
-                                type: string
-                            required:
-                            - name
-                            type: object
-                          type: array
+                        certificateRef:
+                          description: 'CertificateRef is the reference to Kubernetes object that contain an identity certificate. This certificate MUST be used for TLS handshakes for the domain this TLSConfig is associated with. If an entry in this list omits or specifies the empty string for both the group and the resource, the resource defaults to "secrets". An implementation may support other resources (for example, resource "mycertificates" in group "networking.acme.io"). Support: Core (Kubernetes Secrets) Support: Implementation-specific (Other resource types)'
+                          properties:
+                            group:
+                              default: core
+                              description: "Group is the group of the referent.  Omitting the value or specifying the empty string indicates the core API group.  For example, use the following to specify a secrets resource: \n fooRef:   resource: secrets   name: mysecret \n Otherwise, if the core API group is not desired, specify the desired group: \n fooRef:   group: acme.io   resource: foos   name: myfoo"
+                              type: string
+                            name:
+                              description: Name is the name of the referent.
+                              type: string
+                            resource:
+                              default: secrets
+                              description: "Resource is the API resource name of the referent. Omitting the value or specifying the empty string indicates the secrets resource. For example, use the following to specify a secrets resource: \n fooRef:   name: mysecret \n Otherwise, if the secrets resource is not desired, specify the desired group: \n fooRef:   group: acme.io   resource: foos   name: myfoo"
+                              type: string
+                          required:
+                          - name
+                          type: object
+                        mode:
+                          description: 'Mode defines the TLS behavior for the TLS session initiated by the client. There are two possible modes: - Terminate: The TLS session between the downstream client   and the Gateway is terminated at the Gateway. - Passthrough: The TLS session NOT terminated by the Gateway. This   implies that the Gateway can''t decipher the TLS stream except for   the ClientHello message of the TLS protocol.'
+                          enum:
+                          - Terminate
+                          - Passthrough
+                          type: string
                         options:
                           additionalProperties:
                             type: string

diff --git a/docs-src/spec.md b/docs-src/spec.md
@@ -1969,6 +1969,14 @@ TLSConfig
 <p>TLS is the TLS configuration for the Listener. This field
 is required if the Protocol field is &ldquo;HTTPS&rdquo; or &ldquo;TLS&rdquo; and
 ignored otherwise.</p>
+<p>The association of SNIs to Certificate defined in TLSConfig is
+defined based on the value of HostnameMatchType for this listener:
+- &ldquo;Domain&rdquo;: Certificate should be used used for the domain and its
+first-level subdomains.
+- &ldquo;Exact&rdquo;: Certificate should be used for the domain only.
+- &ldquo;Any&rdquo;: Certificate in TLSConfig is the default certificate to use.</p>
+<p>The GatewayClass MUST use the longest matching SNI out of all
+available certificate for any TLS handshake.</p>
 <p>Support: Core</p>
 </td>
 </tr>
@@ -2724,23 +2732,42 @@ TCPRouteAction
 <tbody>
 <tr>
 <td>
-<code>certificateRefs</code></br>
+<code>mode</code></br>
+<em>
+<a href="#networking.x-k8s.io/v1alpha1.TLSMode">
+TLSMode
+</a>
+</em>
+</td>
+<td>
+<p>Mode defines the TLS behavior for the TLS session initiated by the client.
+There are two possible modes:
+- Terminate: The TLS session between the downstream client
+and the Gateway is terminated at the Gateway.
+- Passthrough: The TLS session NOT terminated by the Gateway. This
+implies that the Gateway can&rsquo;t decipher the TLS stream except for
+the ClientHello message of the TLS protocol.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>certificateRef</code></br>
 <em>
 <a href="#networking.x-k8s.io/v1alpha1.SecretsDefaultLocalObjectReference">
-[]SecretsDefaultLocalObjectReference
+SecretsDefaultLocalObjectReference
 </a>
 </em>
 </td>
 <td>
-<p>CertificateRefs is a list of references to Kubernetes objects that each
-contain an identity certificate.  The host name in a TLS SNI client hello
-message is used for certificate matching and route host name selection.
-The SNI server_name must match a route host name for the Gateway to route
-the TLS request.  If an entry in this list omits or specifies the empty
+<p>CertificateRef is the reference to Kubernetes object that
+contain an identity certificate.
+This certificate MUST be used for TLS handshakes for the domain
+this TLSConfig is associated with.
+If an entry in this list omits or specifies the empty
 string for both the group and the resource, the resource defaults to &ldquo;secrets&rdquo;.
 An implementation may support other resources (for example, resource
-&ldquo;mycertificates&rdquo; in group &ldquo;networking.acme.io&rdquo;).</p>
-<p>Support: Core (Kubernetes Secrets)
+&ldquo;mycertificates&rdquo; in group &ldquo;networking.acme.io&rdquo;).
+Support: Core (Kubernetes Secrets)
 Support: Implementation-specific (Other resource types)</p>
 </td>
 </tr>
@@ -2763,6 +2790,15 @@ construct.</p>
 </tr>
 </tbody>
 </table>
+<h3 id="networking.x-k8s.io/v1alpha1.TLSMode">TLSMode
+(<code>string</code> alias)</p></h3>
+<p>
+(<em>Appears on:</em>
+<a href="#networking.x-k8s.io/v1alpha1.TLSConfig">TLSConfig</a>)
+</p>
+<p>
+<p>TLSMode type defines behavior of gateway with TLS protocol.</p>
+</p>
 <h3 id="networking.x-k8s.io/v1alpha1.TargetPort">TargetPort
 (<code>int32</code> alias)</p></h3>
 <p>

diff --git a/docs/spec/index.html b/docs/spec/index.html
@@ -2294,6 +2294,14 @@ <h3 id="networking.x-k8s.io/v1alpha1.Listener">Listener
 <p>TLS is the TLS configuration for the Listener. This field
 is required if the Protocol field is &ldquo;HTTPS&rdquo; or &ldquo;TLS&rdquo; and
 ignored otherwise.</p>
+<p>The association of SNIs to Certificate defined in TLSConfig is
+defined based on the value of HostnameMatchType for this listener:
+- &ldquo;Domain&rdquo;: Certificate should be used used for the domain and its
+first-level subdomains.
+- &ldquo;Exact&rdquo;: Certificate should be used for the domain only.
+- &ldquo;Any&rdquo;: Certificate in TLSConfig is the default certificate to use.</p>
+<p>The GatewayClass MUST use the longest matching SNI out of all
+available certificate for any TLS handshake.</p>
 <p>Support: Core</p>
 </td>
 </tr>
@@ -3049,23 +3057,42 @@ <h3 id="networking.x-k8s.io/v1alpha1.TLSConfig">TLSConfig
 <tbody>
 <tr>
 <td>
-<code>certificateRefs</code></br>
+<code>mode</code></br>
+<em>
+<a href="#networking.x-k8s.io/v1alpha1.TLSMode">
+TLSMode
+</a>
+</em>
+</td>
+<td>
+<p>Mode defines the TLS behavior for the TLS session initiated by the client.
+There are two possible modes:
+- Terminate: The TLS session between the downstream client
+and the Gateway is terminated at the Gateway.
+- Passthrough: The TLS session NOT terminated by the Gateway. This
+implies that the Gateway can&rsquo;t decipher the TLS stream except for
+the ClientHello message of the TLS protocol.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>certificateRef</code></br>
 <em>
 <a href="#networking.x-k8s.io/v1alpha1.SecretsDefaultLocalObjectReference">
-[]SecretsDefaultLocalObjectReference
+SecretsDefaultLocalObjectReference
 </a>
 </em>
 </td>
 <td>
-<p>CertificateRefs is a list of references to Kubernetes objects that each
-contain an identity certificate.  The host name in a TLS SNI client hello
-message is used for certificate matching and route host name selection.
-The SNI server_name must match a route host name for the Gateway to route
-the TLS request.  If an entry in this list omits or specifies the empty
+<p>CertificateRef is the reference to Kubernetes object that
+contain an identity certificate.
+This certificate MUST be used for TLS handshakes for the domain
+this TLSConfig is associated with.
+If an entry in this list omits or specifies the empty
 string for both the group and the resource, the resource defaults to &ldquo;secrets&rdquo;.
 An implementation may support other resources (for example, resource
-&ldquo;mycertificates&rdquo; in group &ldquo;networking.acme.io&rdquo;).</p>
-<p>Support: Core (Kubernetes Secrets)
+&ldquo;mycertificates&rdquo; in group &ldquo;networking.acme.io&rdquo;).
+Support: Core (Kubernetes Secrets)
 Support: Implementation-specific (Other resource types)</p>
 </td>
 </tr>
@@ -3088,6 +3115,15 @@ <h3 id="networking.x-k8s.io/v1alpha1.TLSConfig">TLSConfig
 </tr>
 </tbody>
 </table>
+<h3 id="networking.x-k8s.io/v1alpha1.TLSMode">TLSMode
+(<code>string</code> alias)</p></h3>
+<p>
+(<em>Appears on:</em>
+<a href="#networking.x-k8s.io/v1alpha1.TLSConfig">TLSConfig</a>)
+</p>
+<p>
+<p>TLSMode type defines behavior of gateway with TLS protocol.</p>
+</p>
 <h3 id="networking.x-k8s.io/v1alpha1.TargetPort">TargetPort
 (<code>int32</code> alias)</p></h3>
 <p>