github.com/projectcontour/contour@v1.28.2/site/content/docs/1.20/config/tls-termination.md (about)

     1  # TLS Termination
     2  
     3  HTTPProxy follows a similar pattern to Ingress for configuring TLS credentials.
     4  
     5  You can secure a HTTPProxy by specifying a Secret that contains TLS private key and certificate information.
     6  If multiple HTTPProxies utilize the same Secret, the certificate must include the necessary Subject Authority Name (SAN) for each fqdn.
     7  
     8  Contour (via Envoy) requires that clients send the Server Name Indication (SNI) TLS extension so that requests can be routed to the correct virtual host.
     9  Virtual hosts are strongly bound to SNI names.
    10  This means that the Host header in HTTP requests must match the SNI name that was sent at the start of the TLS session.
    11  
    12  Contour also follows a "secure first" approach.
    13  When TLS is enabled for a virtual host, any request to the insecure port is redirected to the secure interface with a 301 redirect.
    14  Specific routes can be configured to override this behavior and handle insecure requests by enabling the `spec.routes.permitInsecure` parameter on a Route.
    15  
    16  The TLS secret must:
    17  - be a Secret of type `kubernetes.io/tls`. This means that it must contain keys named `tls.crt` and `tls.key` that contain the certificate and private key to use for TLS, in PEM format.
    18  
    19  The TLS secret may also:
    20  - add any chain CA certificates required for validation into the `tls.crt` PEM bundle. If this is the case, the serving certificate must be the first certificate in the bundle and the intermediate CA certificates must be appended in issuing order.
    21  
    22  ```yaml
    23  # ingress-tls.secret.yaml
    24  apiVersion: v1
    25  data:
    26    tls.crt: base64 encoded cert
    27    tls.key: base64 encoded key
    28  kind: Secret
    29  metadata:
    30    name: testsecret
    31    namespace: default
    32  type: kubernetes.io/tls
    33  ```
    34  
    35  The HTTPProxy can be configured to use this secret using `tls.secretName` property:
    36  
    37  ```yaml
    38  # httpproxy-tls.yaml
    39  apiVersion: projectcontour.io/v1
    40  kind: HTTPProxy
    41  metadata:
    42    name: tls-example
    43    namespace: default
    44  spec:
    45    virtualhost:
    46      fqdn: foo2.bar.com
    47      tls:
    48        secretName: testsecret
    49    routes:
    50      - services:
    51          - name: s1
    52            port: 80
    53  ```
    54  
    55  If the `tls.secretName` property contains a slash, eg. `somenamespace/somesecret` then, subject to TLS Certificate Delegation, the TLS certificate will be read from `somesecret` in `somenamespace`.
    56  See TLS Certificate Delegation below for more information.
    57  
    58  The TLS **Minimum Protocol Version** a virtual host should negotiate can be specified by setting the `spec.virtualhost.tls.minimumProtocolVersion`:
    59  
    60  - 1.3
    61  - 1.2  (Default)
    62  
    63  ## Fallback Certificate
    64  
    65  Contour provides virtual host based routing, so that any TLS request is routed to the appropriate service based on both the server name requested by the TLS client and the HOST header in the HTTP request.
    66  
    67  Since the HOST Header is encrypted during TLS handshake, it can’t be used for virtual host based routing unless the client sends HTTPS requests specifying hostname using the TLS server name, or the request is first decrypted using a default TLS certificate.
    68  
    69  Some legacy TLS clients do not send the server name, so Envoy does not know how to select the right certificate. A fallback certificate is needed for these clients.
    70  
    71  _**Note:**
    72  The minimum TLS protocol version for any fallback request is defined by the `minimum TLS protocol version` set in the Contour configuration file.
    73  Enabling the fallback certificate is not compatible with TLS client authentication._
    74  
    75  ### Fallback Certificate Configuration
    76  
    77  First define the `namespace/name` in the [Contour configuration file][1] of a Kubernetes secret which will be used as the fallback certificate.
    78  Any HTTPProxy which enables fallback certificate delegation must have the fallback certificate delegated to the namespace in which the HTTPProxy object resides.
    79  
    80  To do that, configure `TLSCertificateDelegation` to delegate the fallback certificate to specific or all namespaces (e.g. `*`) which should be allowed to enable the fallback certificate.
    81  Finally, for each root HTTPProxy, set the `Spec.TLS.enableFallbackCertificate` parameter to allow that HTTPProxy to opt-in to the fallback certificate routing.
    82  
    83  ```yaml
    84  apiVersion: projectcontour.io/v1
    85  kind: HTTPProxy
    86  metadata:
    87    name: fallback-tls-example
    88    namespace: defaultub
    89  spec:
    90    virtualhost:
    91      fqdn: fallback.bar.com
    92      tls:
    93        secretName: testsecret
    94        enableFallbackCertificate: true
    95    routes:
    96      - services:
    97          - name: s1
    98            port: 80
    99  ---
   100  apiVersion: projectcontour.io/v1
   101  kind: TLSCertificateDelegation
   102  metadata:
   103    name: fallback-delegation
   104    namespace: www-admin
   105  spec:
   106    delegations:
   107      - secretName: fallback-secret-name
   108        targetNamespaces:
   109        - "*"
   110  ```
   111  
   112  ## Permitting Insecure Requests
   113  
   114  A HTTPProxy can be configured to permit insecure requests to specific Routes.
   115  In this example, any request to `foo2.bar.com/blog` will not receive a 301 redirect to HTTPS, but the `/` route will:
   116  
   117  ```yaml
   118  apiVersion: projectcontour.io/v1
   119  kind: HTTPProxy
   120  metadata:
   121    name: tls-example-insecure
   122    namespace: default
   123  spec:
   124    virtualhost:
   125      fqdn: foo2.bar.com
   126      tls:
   127        secretName: testsecret
   128    routes:
   129      - services:
   130          - name: s1
   131            port: 80
   132      - conditions:
   133        - prefix: /blog
   134        permitInsecure: true
   135        services:
   136          - name: s2
   137            port: 80
   138  ```
   139  
   140  ## Client Certificate Validation
   141  
   142  It is possible to protect the backend service from unauthorized external clients by requiring the client to present a valid TLS certificate.
   143  Envoy will validate the client certificate by verifying that it is not expired and that a chain of trust can be established to the configured trusted root CA certificate.
   144  Only those requests with a valid client certificate will be accepted and forwarded to the backend service.
   145  
   146  ```yaml
   147  apiVersion: projectcontour.io/v1
   148  kind: HTTPProxy
   149  metadata:
   150    name: with-client-auth
   151  spec:
   152    virtualhost:
   153      fqdn: www.example.com
   154      tls:
   155        secretName: secret
   156        clientValidation:
   157          caSecret: client-root-ca
   158    routes:
   159      - services:
   160          - name: s1
   161            port: 80
   162  ```
   163  
   164  The preceding example enables validation by setting the optional `clientValidation` attribute.
   165  Its mandatory attribute `caSecret` contains a name of an existing Kubernetes Secret that must be of type "Opaque" and have only a data key named `ca.crt`.
   166  The data value of the key `ca.crt` must be a PEM-encoded certificate bundle and it must contain all the trusted CA certificates that are to be used for validating the client certificate.
   167  If the Opaque Secret also contains one of either `tls.crt` or `tls.key` keys, it will be ignored.
   168  
   169  When using external authorization, it may be desirable to use an external authorization server to validate client certificates on requests, rather than the Envoy proxy.
   170  
   171  ```yaml
   172  apiVersion: projectcontour.io/v1
   173  kind: HTTPProxy
   174  metadata:
   175    name: with-client-auth-and-ext-authz
   176  spec:
   177    virtualhost:
   178      fqdn: www.example.com
   179      authorization:
   180        # external authorization server configuration
   181      tls:
   182        secretName: secret
   183        clientValidation:
   184          caSecret: client-root-ca
   185          skipClientCertValidation: true
   186    routes:
   187      - services:
   188          - name: s1
   189            port: 80
   190  ```
   191  
   192  In the above example, setting the `skipClientCertValidation` field to `true` will configure Envoy to require client certificates on requests and pass them along to a configured authorization server.
   193  Failed validation of client certificates by Envoy will be ignored and the `fail_verify_error` [Listener statistic][2] incremented.
   194  If the `caSecret` field is omitted, Envoy will request but not require client certificates to be present on requests.
   195  
   196  ## TLS Session Proxying
   197  
   198  HTTPProxy supports proxying of TLS encapsulated TCP sessions.
   199  
   200  _Note_: The TCP session must be encrypted with TLS.
   201  This is necessary so that Envoy can use SNI to route the incoming request to the correct service.
   202  
   203  If `spec.virtualhost.tls.secretName` is present then that secret will be used to decrypt the TCP traffic at the edge.
   204  
   205  ```yaml
   206  # httpproxy-tls-termination.yaml
   207  apiVersion: projectcontour.io/v1
   208  kind: HTTPProxy
   209  metadata:
   210    name: example
   211    namespace: default
   212  spec:
   213    virtualhost:
   214      fqdn: tcp.example.com
   215      tls:
   216        secretName: secret
   217    tcpproxy:
   218      services:
   219      - name: tcpservice
   220        port: 8080
   221      - name: otherservice
   222        port: 9999
   223        weight: 20
   224  ```
   225  
   226  The `spec.tcpproxy` key indicates that this _root_ HTTPProxy will forward the de-encrypted TCP traffic to the backend service.
   227  
   228  ### TLS Session Passthrough
   229  
   230  If you wish to handle the TLS handshake at the backend service set `spec.virtualhost.tls.passthrough: true` indicates that once SNI demuxing is performed, the encrypted connection will be forwarded to the backend service.
   231  The backend service is expected to have a key which matches the SNI header received at the edge, and be capable of completing the TLS handshake. This is called SSL/TLS Passthrough.
   232  
   233  ```yaml
   234  # httpproxy-tls-passthrough.yaml
   235  apiVersion: projectcontour.io/v1
   236  kind: HTTPProxy
   237  metadata:
   238    name: example
   239    namespace: default
   240  spec:
   241    virtualhost:
   242      fqdn: tcp.example.com
   243      tls:
   244        passthrough: true
   245    tcpproxy:
   246      services:
   247      - name: tcpservice
   248        port: 8080
   249      - name: otherservice
   250        port: 9999
   251        weight: 20
   252  ```
   253  
   254  [1]: ../configuration#fallback-certificate
   255  [2]: https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/stats#tls-statistics