Transport Layer Security Policy - Outbound

Policy Name

Transport Layer Security (TLS) - Outbound

Summary

Enables two-way authentication between the API proxy and an upstream service

Category

Security

First Flex version available

v1.4.0

Returned Status Codes

No return codes exist for this policy.

The following document applies only to Flex Gateway running in Local Mode. To configure TLS in Connected Mode, see Configuring TLS Context for Flex Gateway in Connected Mode.

Summary

Flex Gateway supports outbound Transport Layer Security (TLS) and outbound mutual authentication TLS (mTLS) in Local Mode.

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.

To apply outbound TLS in Local Mode, use the Configuring TLS Context for Flex Gateway in Local Mode tutorial and refer to the following configuration files in this documentation.

You can configure an outbound TLS context to enable authentication between an API instance and an upstream service by binding the TLS policy to the upstream service.

Unlike inbound TLS, it is not suggested to apply the same outbound TLS context to all API instances in your Flex Gateway because your API upstream services might come from different providers. Therefore, no configuration example for outbound TLS on all instances is provided.

Port sharing is not a concern for outbound TLS. You can apply an outbound TLS context for each individual upstream service.

TLS policies do not support policy ordering.

Upstream certificates must include the Subject Alternative Name (SAN) extension. The Common Name (CN) field is deprecated.

Flex Gateway supports the SAN extension of type dNSName.

The Authority Information Access (AIA) certificate extension is not supported when configuring outbound TLS contexts.

Configuring Policy Parameters

To enable outbound TLS between an API instance and an upstream service when using Flex Gateway as your runtime, you must manually configure the TLS context in a YAML configuration file.

Refer to the following policy definition and table of parameters:

- policyRef:
    name: tls-outbound
  config:
    skipValidation: <boolean> // REQUIRED
    certificate: // OPTIONAL
        key: <string> // OPTIONAL
        crt: <string> // OPTIONAL
    alpn: <array> // OPTIONAL
    minversion: <string> // OPTIONAL
    maxversion: <string> // OPTIONAL
    ciphers: <array> // OPTIONAL

Not including optional parameters in your configuration file applies the parameters default values to your TLS context.

When configuring the ciphers parameter, ensure that your API upstream supports the listed ciphers. For the supported ciphers, see TLS Cipher Support on Flex Gateway.

Parameter Required or Optional Default Value Description

Parameter	Required or Optional	Default Value	Description
`skipValidation`	Required	false	Skipping validation disables outbound mTLS
`trustedCA`	Optional, unless `skipValidation` is false	N/A	The client certificate used in mTLS
`certificate`	Optional	N/A	A TLS certificate key pair. To comply with security standards, all certificates must be 2048 bits or longer.
`certificate.key`	Optional	N/A	The private key part of the certificate
`certificate.crt`	Optional	N/A	The public key part of the certificate
`alpn`	Optional	`h2` and `http/1.1`	A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.
`minversion`	Optional	`1.2`	The minimum TLS version allowed
`maxversion`	Optional	`1.3`	The maximum TLS version allowed
`ciphers`	Optional	For the default and other supported ciphers, see TLS Cipher Support on Flex Gateway.	A list of supported TLS ciphers (IANA format).

skipValidation

Required

false

Skipping validation disables outbound mTLS

trustedCA

Optional, unless skipValidation is false

N/A

The client certificate used in mTLS

certificate

Optional

N/A

A TLS certificate key pair. To comply with security standards, all certificates must be 2048 bits or longer.

certificate.key

Optional

N/A

The private key part of the certificate

certificate.crt

Optional

N/A

The public key part of the certificate

alpn

Optional

h2 and http/1.1

A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.

minversion

Optional

1.2

The minimum TLS version allowed

maxversion

Optional

1.3

The maximum TLS version allowed

ciphers

Optional

For the default and other supported ciphers, see TLS Cipher Support on Flex Gateway.

A list of supported TLS ciphers (IANA format).

Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS for a upstream service.

Sample configuration for adding outbound TLS context for a specific upstream service:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: tls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: true
    certificate:
      key: |
        # -----BEGIN PRIVATE KEY-----
        # insert certificate key
        # -----END PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----

This example uses the default values for alpn, minversion, maxversion, and ciphers.

Sample configuration for adding outbound mTLS context for a specific upstream service:

apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls-outbound
spec:
  targetRef:
    kind: Service
    name: ingress-test-outbound-upstream
  policyRef:
    name: tls-outbound
  config:
    skipValidation: false
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    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_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

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

Transport Layer Security Policy - Outbound

Summary

Configuring Policy Parameters

Resource Configuration Examples

TLS Cipher Support on Flex Gateway

Flex Gateway Supported Ciphers

See Also