---
schema_version: "1"
id: d48715192cac6ed3fabfe915bd370b0841ec559c0d087219387b451bd04088f3
title: Transport Layer Security Policy - Inbound
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-tls.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-tls
source_site: docs.mulesoft.com
content_type: documentation
content_hash: a455cad3743c11075bebd0832355b58a445c06bd20590feb65ca2e86b897e06c
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: tls, mtls, transport layer security, inbound tls, api gateway, flex gateway, gateway, policy
---

# Transport Layer Security Policy - Inbound

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><div><div><p>Transport Layer Security (TLS) - Inbound</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables authentication between a client and the API proxy</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0 (inbound mTLS: v1.3.0)</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/tls-release-notes">Transport Layer Security (TLS) - Inbound</a></p></div></div></td></tr><tr><td rowspan="4"><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy.</p></div></div></td></tr><tr><td><div></div></td></tr></tbody></table>

> [!NOTE] The following document applies only to Omni Gateway running in Local Mode. To configure
> TLS in Connected Mode, see
> [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config).

## Summary

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

To apply inbound TLS in Local Mode, use the
[Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config) tutorial and refer to the
following configuration files in this documentation.

You can configure an inbound TLS context to enable authentication between a client and the API
instance (HTTPS) by binding the TLS policy to your API instance or to all instances in your Omni
Gateway.

Omni Gateway implements port-level inbound TLS, meaning if you apply an inbound TLS to an API
instance that shares a port with other instances, the same inbound TLS context is applied to all
instances sharing the port. Omni Gateway supports multiple TLS certificates on a single gateway, but
you must apply the certificates to unique ports. If you apply inbound TLS to one API instance, you
do not need to apply the same inbound TLS context to instances that share that port. Consequently,
you cannot apply different inbound TLS contexts to API instances that share the same port.

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

> [!NOTE] TLS policies do not support policy ordering.

## Configuring Policy Parameters

To use HTTPS as your schema when creating an API instance using Omni 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 config: requireClientCertificate: <boolean> // OPTIONAL trustedCA: <string>
// OPTIONAL 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, see [TLS Cipher Support on Omni Gateway](#local-support)
for the supported ciphers.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>requireClientCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>false</p></div></div></td><td><div><div><p>Enables/disables inbound mTLS.</p></div></div></td></tr><tr><td><div><div><p><code>trustedCA</code></p></div></div></td><td><div><div><p>Optional, unless <code>requireClientCertificate</code> is true</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The CA used to validate the client certificate. If no trusted CA is provided, the policy uses the default OS CA.</p></div></div></td></tr><tr><td><div><div><p><code>certificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A TLS certificate key pair. To comply with security standards, all certificates must be 2048 bits or longer.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The private key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>certificate.crt</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>The public key part of the certificate.</p></div></div></td></tr><tr><td><div><div><p><code>alpn</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>h2</code> and <code>http/1.1</code></p></div></div></td><td><div><div><p>A prioritized list of supported application level protocols; for example, h2, http/1.1, and so forth.</p></div></div></td></tr><tr><td><div><div><p><code>minversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.2</code></p></div></div></td><td><div><div><p>The minimum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>maxversion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>1.3</code></p></div></div></td><td><div><div><p>The maximum TLS version allowed.</p></div></div></td></tr><tr><td><div><div><p><code>ciphers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>For the default and other supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td><td><div><div><p>A list of supported TLS ciphers (IANA format). For the supported ciphers, see <a href="#local-support">TLS Cipher Support on Omni Gateway</a>.</p></div></div></td></tr></tbody></table>

### Resource Configuration Examples

You can format the YAML file to configure TLS or mTLS either for a specific API instance or for all
API instances running on your Omni Gateway.

#### Apply TLS Configuration to All API Instances

**Sample configuration for adding inbound TLS context for all API instances running on this Omni
Gateway:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: ingress-https-tls
spec:
  targetRef:
    kind: Selector
    selector:
      kind: ApiInstance
  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
```

#### Apply TLS Configuration to a Specific API Instance

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

```yaml
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
```

#### Apply mTLS Inbound Configuration to a Specific API Instance

**Sample configuration for adding an inbound mTLS context for a specific API instance:**

```yaml
apiVersion: gateway.mulesoft.com/v1alpha1
kind: PolicyBinding
metadata:
  name: mtls
spec:
  targetRef:
    name: ingress-https
  policyRef:
    name: tls
  config:
    requireClientCertificate: true
    trustedCA: |
      # -----BEGIN CERTIFICATE-----
      # insert certificate
      # -----END CERTIFICATE-----
    certificate:
      key: |
        # -----BEGIN RSA PRIVATE KEY-----
        # insert private key
        # -----END RSA PRIVATE KEY-----
      crt: |
        # -----BEGIN CERTIFICATE-----
        # insert certificate
        # -----END CERTIFICATE-----
```

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

## TLS Cipher Support on Omni Gateway

Omni can support a range of TLS Versions from TLS 1.2 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.

### Omni Gateway Supported Ciphers

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

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Cipher</th><th>TLS Version</th><th>Default</th><th>Advice</th></tr></thead><tbody><tr><td><div><div><p>TLS_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.3</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Recommended</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Secure</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_GCM_SHA256</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_GCM_SHA384</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr><tr><td><div><div><p>TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA</p></div></div></td><td><div><div><p>1.2</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Weak</p></div></div></td></tr></tbody></table>

## See Also

- [Configuring TLS Context for Omni Gateway in Connected Mode](https://docs.mulesoft.com/gateway/1.13/conn-tls-config)

- [Configuring TLS Context for Omni Gateway in Local Mode](https://docs.mulesoft.com/gateway/1.13/local-tls-config)

- [Transport Layer Security Policy - Outbound](https://docs.mulesoft.com/gateway/1.13/policies-included-tls-outbound)