github.com/projectcontour/contour@v1.28.2/site/content/docs/v1.10.0/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 contain keys named tls.crt and tls.key that contain the certificate and private key to use for TLS, e.g.:
    17  
    18  ```yaml
    19  # ingress-tls.secret.yaml
    20  apiVersion: v1
    21  data:
    22    tls.crt: base64 encoded cert
    23    tls.key: base64 encoded key
    24  kind: Secret
    25  metadata:
    26    name: testsecret
    27    namespace: default
    28  type: kubernetes.io/tls
    29  ```
    30  
    31  The HTTPProxy can be configured to use this secret using `tls.secretName` property:
    32  
    33  ```yaml
    34  # httpproxy-tls.yaml
    35  apiVersion: projectcontour.io/v1
    36  kind: HTTPProxy
    37  metadata:
    38    name: tls-example
    39    namespace: default
    40  spec:
    41    virtualhost:
    42      fqdn: foo2.bar.com
    43      tls:
    44        secretName: testsecret
    45    routes:
    46      - services:
    47          - name: s1
    48            port: 80
    49  ```
    50  
    51  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`.
    52  See TLS Certificate Delegation below for more information.
    53  
    54  The TLS **Minimum Protocol Version** a virtual host should negotiate can be specified by setting the `spec.virtualhost.tls.minimumProtocolVersion`:
    55  
    56  - 1.3
    57  - 1.2  (Default)
    58  - 1.1
    59  
    60  ## Fallback Certificate
    61  
    62  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.
    63  
    64  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.
    65  
    66  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.
    67  
    68  _**Note:**
    69  The minimum TLS protocol version for any fallback request is defined by the `minimum TLS protocol version` set in the Contour configuration file.
    70  Enabling the fallback certificate is not compatible with TLS client authentication._
    71  
    72  ### Fallback Certificate Configuration
    73  
    74  First define the `namespace/name` in the [Contour configuration file][1] of a Kubernetes secret which will be used as the fallback certificate.
    75  Any HTTPProxy which enables fallback certificate delegation must have the fallback certificate delegated to the namespace in which the HTTPProxy object resides.
    76  
    77  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.
    78  Finally, for each root HTTPProxy, set the `Spec.TLS.enableFallbackCertificate` parameter to allow that HTTPProxy to opt-in to the fallback certificate routing.
    79  
    80  ```yaml
    81  apiVersion: projectcontour.io/v1
    82  kind: HTTPProxy
    83  metadata:
    84    name: fallback-tls-example
    85    namespace: defaultub
    86  spec:
    87    virtualhost:
    88      fqdn: fallback.bar.com
    89      tls:
    90        secretName: testsecret
    91        enableFallbackCertificate: true
    92    routes:
    93      - services:
    94          - name: s1
    95            port: 80
    96  ---
    97  apiVersion: projectcontour.io/v1
    98  kind: TLSCertificateDelegation
    99  metadata:
   100    name: fallback-delegation
   101    namespace: www-admin
   102  spec:
   103    delegations:
   104      - secretName: fallback-secret-name
   105        targetNamespaces:
   106        - "*"
   107  ```
   108  
   109  ## Permitting Insecure Requests
   110  
   111  A HTTPProxy can be configured to permit insecure requests to specific Routes.
   112  In this example, any request to `foo2.bar.com/blog` will not receive a 301 redirect to HTTPS, but the `/` route will:
   113  
   114  ```yaml
   115  apiVersion: projectcontour.io/v1
   116  kind: HTTPProxy
   117  metadata:
   118    name: tls-example-insecure
   119    namespace: default
   120  spec:
   121    virtualhost:
   122      fqdn: foo2.bar.com
   123      tls:
   124        secretName: testsecret
   125    routes:
   126      - services:
   127          - name: s1
   128            port: 80
   129      - conditions:
   130        - prefix: /blog
   131        permitInsecure: true
   132        services:
   133          - name: s2
   134            port: 80
   135  ```
   136  
   137  ## Client Certificate Validation
   138  
   139  It is possible to protect the backend service from unauthorized external clients by requiring the client to present a valid TLS certificate.
   140  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.
   141  Only those requests with a valid client certificate will be accepted and forwarded to the backend service.
   142  
   143  ```yaml
   144  apiVersion: projectcontour.io/v1
   145  kind: HTTPProxy
   146  metadata:
   147    name: with-client-auth
   148  spec:
   149    virtualhost:
   150      fqdn: www.example.com
   151      tls:
   152        secretName: secret
   153        clientValidation:
   154          caSecret: client-root-ca
   155    routes:
   156      - services:
   157          - name: s1
   158            port: 80
   159  ```
   160  
   161  The preceding example enables validation by setting the optional `clientValidation` attribute.
   162  Its mandatory attribute `caSecret` contains a name of an existing Kubernetes Secret that must be of type "Opaque" and have a data key named `ca.crt`.
   163  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.
   164  
   165  ## TLS Session Proxying
   166  
   167  HTTPProxy supports proxying of TLS encapsulated TCP sessions.
   168  
   169  _Note_: The TCP session must be encrypted with TLS.
   170  This is necessary so that Envoy can use SNI to route the incoming request to the correct service.
   171  
   172  If `spec.virtualhost.tls.secretName` is present then that secret will be used to decrypt the TCP traffic at the edge.
   173  
   174  ```yaml
   175  # httpproxy-tls-termination.yaml
   176  apiVersion: projectcontour.io/v1
   177  kind: HTTPProxy
   178  metadata:
   179    name: example
   180    namespace: default
   181  spec:
   182    virtualhost:
   183      fqdn: tcp.example.com
   184      tls:
   185        secretName: secret
   186    tcpproxy:
   187      services:
   188      - name: tcpservice
   189        port: 8080
   190      - name: otherservice
   191        port: 9999
   192        weight: 20
   193  ```
   194  
   195  The `spec.tcpproxy` key indicates that this _root_ HTTPProxy will forward the de-encrypted TCP traffic to the backend service.
   196  
   197  ### TLS Session Passthrough
   198  
   199  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.
   200  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.
   201  
   202  ```yaml
   203  # httpproxy-tls-passthrough.yaml
   204  apiVersion: projectcontour.io/v1
   205  kind: HTTPProxy
   206  metadata:
   207    name: example
   208    namespace: default
   209  spec:
   210    virtualhost:
   211      fqdn: tcp.example.com
   212      tls:
   213        passthrough: true
   214    tcpproxy:
   215      services:
   216      - name: tcpservice
   217        port: 8080
   218      - name: otherservice
   219        port: 9999
   220        weight: 20
   221  ```
   222  
   223  [1]: ../configuration#fallback-certificate