Configuring TLS Context for Flex Gateway in Local Mode

Using encryption, Transport Layer Security (TLS) policies protect communication between clients, API instances, and upstream services. To use TLS when creating an API instance using Flex Gateway in Local Mode as your runtime, you must configure the TLS context in a PolicyBinding YAML configuration file.

When you add a TLS context, you can also select the ciphers to use with the TLS context and configure different inbound and outbound validation settings.

Flex Gateway supports the following:

Regular TLS between a client and the API instance (HTTPS), referred to as inbound TLS
Regular TLS between an API instance and an upstream service, referred to as outbound TLS
Mutual authentication TLS (mTLS) in both the inbound and outbound direction

By default, Flex Gateway supports outbound TLS to communicate with upstream services that require a secure communication channel. For default outbound communication, Flex Gateway uses only TLS 1.2. To find the default TLS 1.2 ciphers, see Flex Gateway Supported Ciphers. To find the ciphers, see Flex Gateway Supported Ciphers. Applying a TLS context to an upstream overrides the default TLS context for that upstream. Because the default ciphers may change for later Flex Gateway versions, you can apply a TLS context to an upstream to ensure it remains the same.

The following tutorials demonstrate how to apply a configured PolicyBinding resource. For how to configure the resource, see the policy configuration pages:

For inbound TLS, you bind the policy resource to the API instance. For outbound TLS, you bind the policy resource to the upstream service.

You can configure the TLS context for a Flex Gateway running in a Docker container, as a Linux Service, or in a Kubernetes cluster.

Configure TLS Context for Flex Gateway as a Linux Service

Configure TLS Context for Flex Gateway in a Docker Container

Configure TLS Context for Flex Gateway in a Kubernetes Cluster

Before You Begin

Before configuring the TLS context for a Flex Gateway, you must complete the following tasks:

Configure TLS Context for Flex Gateway as a Linux Service

Create a YAML configuration file in the Flex Gateway configuration directory:
```
sudo touch /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml
```

Update the file with your TLS context configuration details. For example:

sudo vi /usr/local/share/mulesoft/flex-gateway/conf.d/tls-config.yaml

The following configuration file only applies inbound TLS to one API instance. For all configuration file options, such as mTLS and outbound TLS, see:

Transport Layer Security Policy - Inbound

Transport Layer Security Policy - Outbound

Sample configuration for adding inbound TLS context for a specific API instance:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: ApiInstance
    name: ingress-https
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA

To comply with security standards, all certificates must be 2048 bits or longer.

Verify that the policy was correctly applied.

The following example curl command tests an HTTPS endpoint with a certificate that matches the certificate specified in the policy binding configuration resource.

curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v

The command should return information on the TLS handshake, as well as an HTTP status of 200 for the endpoint:

* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-RSA-CHACHA20-POLY1305
* ALPN, server did not agree to a protocol
...
> HTTP/1.1 200 OK

For inbound mTLS, the following example curl command requests an API proxy whose basepath is /.

curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
--cert <CLIENTAPP_CERT_FILE> \
--key <CLIENTAPP_KEY_FILE> \
--cacert <SERVER_CERT_FILE> \
--resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v

The configuration key and crt values must be correctly indented, otherwise curl returns the following error when attempting to test the endpoint:

curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number

Configure TLS Context for Flex Gateway in a Docker Container

If you have already added volume for a folder with your Flex Gateway configuration files, skip to the last step.

Press Ctrl+C to stop your Flex Gateway and any replicas.
Create a folder named app in the directory with your Flex Gateway configuration files.
Restart your Flex Gateway with an additional volume for the new app directory:
```
docker run --rm \
-v "$(pwd)":/usr/local/share/mulesoft/flex-gateway/conf.d \
-p 8080:8080 \
mulesoft/flex-gateway
```
Specify an optional name you want to assign to your Flex Replica by including the following: -e FLEX_NAME=<name-for-flex-replica> \.

Create and save a YAML configuration file in your app folder with your TLS context details.

The following configuration file only applies inbound TLS to one API instance. For all configuration file options, such as mTLS and outbound TLS, see:

Transport Layer Security Policy - Inbound

Transport Layer Security Policy - Outbound

Sample configuration for adding inbound TLS context for a specific API instance:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: ApiInstance
    name: ingress-https
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA

To comply with security standards, all certificates must be 2048 bits or longer.

Verify that the policy was correctly applied.

The following example curl command tests an HTTPS endpoint with a certificate that matches the certificate specified in the policy binding configuration resource.

curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get --cacert <SERVER_CERT_FILE> -v

The command should return information on the TLS handshake, as well as an HTTP status of 200 for the endpoint:

* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-RSA-CHACHA20-POLY1305
* ALPN, server did not agree to a protocol
...
> HTTP/1.1 200 OK

For inbound mTLS, the following example curl command requests an API proxy whose basepath is /.

curl https://<SERVER_DOMAIN>:<SERVER_PORT>/get \
--cert <CLIENTAPP_CERT_FILE> \
--key <CLIENTAPP_KEY_FILE> \
--cacert <SERVER_CERT_FILE> \
--resolve <SERVER_DOMAIN>:<SERVER_PORT>:127.0.0.1 -v

The configuration key and crt values must be correctly indented, otherwise curl returns the following error when attempting to test the endpoint:

curl: (35) error:1408F10B:SSL routines:ssl3_get_record:wrong version number

Configure TLS Context for Flex Gateway in a Kubernetes Cluster

To configure the TLS context for Flex Gateway, create a new resource using a YAML configuration file with your TLS context details.

The following configuration file only applies inbound TLS to one API instance. For all configuration file options, such as mTLS and outbound TLS, see:

Transport Layer Security Policy - Inbound

Transport Layer Security Policy - Outbound

Sample configuration for adding inbound TLS context for a specific API instance:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: ApiInstance
    name: ingress-https
  policyRef:
    name: tls
  config:
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
    alpn:
      - http/1.1
      - h2
    minversion: "1.1"
    maxversion: "1.3"
    ciphers:
      - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      - TLS_RSA_WITH_AES_128_GCM_SHA256
      - TLS_RSA_WITH_AES_128_CBC_SHA
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      - TLS_RSA_WITH_AES_256_GCM_SHA384
      - TLS_RSA_WITH_AES_256_CBC_SHA

To comply with security standards, all certificates must be 2048 bits or longer.

TLS Cipher Support on Flex Gateway

Flex can support a range of TLS Versions from TLS 1.1 to TLS 1.3, and you can also customize some of the ciphers to support.

You cannot customize the list of TLS 1.3 Ciphers. If you support TLS 1.3, the TLS 1.3 default ciphers are all supported regardless of the ciphers listed in the configuration file. If you don’t support TLS 1.3, these ciphers are not included.

For TLS 1.2, listing any ciphers overides the TLS 1.2 default ciphers. If you want to list ciphers besides the default TLS 1.2 Ciphers, you must list every cipher to support including the default ciphers you want to support. Excluding default ciphers from your list of supported ciphers means you do not support those ciphers. If you wish to only support the default ciphers, you can leave the cipher list blank. Listing ciphers does not affect the default TLS 1.3 cipher.

There are no default ciphers for TLS 1.1. To support TLS 1.1, you must list the ciphers to support. If you support TLS 1.1 and TLS 1.2, listing TLS 1.1 ciphers overides the TLS 1.2 defaults. To support both these versions, list all ciphers you want to support.

For outbound TLS Context, ensure that your upstream service supports the selected ciphers and versions.

Flex Gateway Supported Ciphers

Flex Gateway supports the following TLS Ciphers in Connected Mode and Local Mode:

Cipher	TLS Version	Default	Advice
TLS_AES_128_GCM_SHA256	1.3	Yes	Secure
TLS_AES_256_GCM_SHA384	1.3	Yes	Secure
TLS_CHACHA20_POLY1305_SHA256	1.3	Yes	Secure
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256	1.2	Yes	Recommended
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384	1.2	Yes	Recommended
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256	1.2	Yes	Recommended
TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256	1.2	No	Recommended
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256	1.2	Yes	Secure
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384	1.2	Yes	Secure
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256	1.2	Yes	Secure
TLS_RSA_WITH_AES_128_GCM_SHA256	1.2	No	Weak
TLS_RSA_WITH_AES_256_GCM_SHA384	1.2	No	Weak
TLS_RSA_WITH_AES_128_CBC_SHA	1.1, 1.2	No	Weak
TLS_RSA_WITH_AES_256_CBC_SHA	1.1, 1.2	No	Weak
TLS_PSK_WITH_AES_128_CBC_SHA	1.1, 1.2	No	Weak
TLS_PSK_WITH_AES_256_CBC_SHA	1.1, 1.2	No	Weak
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA	1.1, 1.2	No	Weak
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA	1.1, 1.2	No	Weak
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA	1.1, 1.2	No	Weak
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA	1.1, 1.2	No	Weak
TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA	1.1, 1.2	No	Weak
TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA	1.1, 1.2	No	Weak
TLS_RSA_WITH_3DES_EDE_CBC_SHA	1.1	No	Weak

Cipher

TLS Version

Default

Advice

TLS_AES_128_GCM_SHA256

1.3

Yes

Secure

TLS_AES_256_GCM_SHA384

1.3

Yes

Secure

TLS_CHACHA20_POLY1305_SHA256

1.3

Yes

Secure

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

1.2

Yes

Recommended

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

1.2

Yes

Recommended

TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

1.2

Yes

Recommended

TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256

1.2

Recommended

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

1.2

Yes

Secure

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

1.2

Yes

Secure

TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

1.2

Yes

Secure

TLS_RSA_WITH_AES_128_GCM_SHA256

1.2

Weak

TLS_RSA_WITH_AES_256_GCM_SHA384

1.2

Weak

TLS_RSA_WITH_AES_128_CBC_SHA

1.1, 1.2

Weak

TLS_RSA_WITH_AES_256_CBC_SHA

1.1, 1.2

Weak

TLS_PSK_WITH_AES_128_CBC_SHA

1.1, 1.2

Weak

TLS_PSK_WITH_AES_256_CBC_SHA

1.1, 1.2

Weak

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

1.1, 1.2

Weak

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

1.1, 1.2

Weak

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

1.1, 1.2

Weak

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

1.1, 1.2

Weak

TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA

1.1, 1.2

Weak

TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA

1.1, 1.2

Weak

TLS_RSA_WITH_3DES_EDE_CBC_SHA

1.1

Weak

Configuring TLS Context for Flex Gateway in Local Mode

Before You Begin

Configure TLS Context for Flex Gateway as a Linux Service

Configure TLS Context for Flex Gateway in a Docker Container

Configure TLS Context for Flex Gateway in a Kubernetes Cluster

TLS Cipher Support on Flex Gateway

Flex Gateway Supported Ciphers

See Also