---
schema_version: "1"
id: 7ab8c15e46d06e069cf85b5d22b95e7cf445b9275566aeda48a515fbf861ac35
title: Gateway Startup Encryption in Mule 4
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-gateway/mule-gateway-encryption-mule4.md
canonical_url: https://docs.mulesoft.com/mule-gateway/mule-gateway-encryption-mule4
source_site: docs.mulesoft.com
content_type: documentation
content_hash: ec0d6f665d435c5bb965fa22b3fef1c4f8993f93b080691580e1a4aebb27ff10
description: MuleSoft Documentation Site
latest: true
---
---
product: Mule Gateway
---

# Gateway Startup Encryption in Mule 4

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

Mule Gateway startup encryption enables you to encrypt sensitive information stored by Mule runtime
engine (Mule), such as policies, contracts, and the credentials required to configure the connection
between your Mule application and Anypoint Platform.

This feature is supported in Mule 4.2.0 and later. If a
[policy that supports encryption](#policies-that-support-encryption), such as Basic Authentication
1.2.0, is applied to an API that is running in Mule versions earlier than 4.2.0, the policy
configuration is not encrypted.

## Encrypting Your Anypoint Platform Credentials Using the Agent

Configuring encryption through Anypoint Runtime Manager agent is the fastest way to secure your
client credentials. You add the encryption key when creating an agent server. The agent then
encrypts the properties encryption for you.  
To learn how to configure encryption through the agent, see
[Install and Configure the Runtime Manager Agent](https://docs.mulesoft.com/runtime-manager/installing-and-configuring-runtime-manager-agent).

## Encrypting the Client ID and Client Secret

You can manually encrypt your properties even though you are using an agent. The most common way is
using the
[secure properties tools](https://docs.mulesoft.com/mule-runtime/latest/secure-configuration-properties#secure-properties-tool).  
When
you use encrypted properties, Mule Gateway assumes that you are using the AES algorithm in CBC Mode.

### Example

Let us assume that your client ID is `bb458e566cba4e2ea5a826d27b46031a`, and you choose the
encryption key to be the 128 bits string `MyEncryptionKey1`. To encrypt these properties, you must
run the following command:

```console
> java -jar secure-properties-tool.jar \
string \ (1)
encrypt \ (2)
AES \ (3)
CBC \
MyEncryptionKey1 \ (4)
bb458e566cba4e2ea5a826d27b46031a
```

<table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>Use the string parameter to encrypt a single value.</td></tr><tr><td><i data-value="2"></i><b>2</b></td><td>Set the tool to encrypt the value.</td></tr><tr><td><i data-value="3"></i><b>3</b></td><td>Use AES with CBC Mode.<br>This is important because Mule uses this configuration to decrypt the value later.</td></tr><tr><td><i data-value="4"></i><b>4</b></td><td>And finally, specify the encryption key-value pair that you want to encrypt.</td></tr></tbody></table>

This command outputs your encrypted client ID:

```none
> smzbg+aV2HbiC9Fv8KBsZpD5PlXiplsfhZ42RWNEbHhUeZ9ZIDftljUx6sYpuQ+b
```

## Passing Your Encrypted Client ID and Client Secret

After encrypting your credentials, you must configure your encrypted values in your `wrapper.conf`
file, which is located inside the `conf` directory in the root folder of your Mule environment:

```none
wrapper.java.additional.<n>=-Danypoint.platform.client_id=![_encrypted client ID_]
wrapper.java.additional.<n>=-Danypoint.platform.anypoint.platform.client_secret=![_encryptedclient secret_]
wrapper.java.additional.<n>=-Danypoint.platform.proxy_password=![_encrypted password_]
```

Replace <n> with the unique number within the property `wrapper.java.additional` file.

> [!CAUTION] If you add `wrapper.java.additional.n` entries to the configuration file, you must
> change each instance of `<n>` to a consecutive number. otherwise, Java does not parse the
> properties correctly.

Based on this example, your `client_id` would appear as:

```none
wrapper.java.additional.100=-Danypoint.platform.client_id=![smzbg+aV2HbiC9Fv8KBsZpD5PlXiplsfhZ42RWNEbHhUeZ9ZIDftljUx6sYpuQ+b]
```

> [!NOTE] The required `![` prefix and `]` suffix indicate to Mule runtime that the enclosed value
> is encrypted.

When starting Mule runtime, you must pass your secret key, using the
`anypoint.platform.encryption_key` property:

```none
$MULE_HOME/bin/mule start -M-Danypoint.platform.encryption_key=MyEncryptionKey1
```

Mule runtime uses the encryption key passed in the `anypoint.platform.encryption_key` property to
decrypt the properties.

### How It Works

You can encrypt your Anypoint Platform credentials (client ID, client secret, and your proxy
password) and add those encrypted values, along with your encryption key to the `wrapper.conf` file
of your Mule environment.

When Mule Gateway capability starts, it checks for an encryption key. The client ID and client
secret values are then obtained from its `wrapper.conf` file. If any of the values in that file are
enclosed within encryption indicators (`![` and `]`), Mule runtime uses the encryption key that it
loaded earlier to decrypt the values and use its original content.

## Debugging Startup Encryption

You can configure your runtime Log4J logger to display information about the encryption mechanism
during startup.

In `$MULE_HOME/conf/log4j2.xml`, set up an asynchronous logger for your gateway deployment:

```XML
...
  <AsyncLogger name="com.mulesoft.mule.runtime.gw.deployment" level="DEBUG" />
...
```

When you provide a key, the Mule environment displays the following message:

An encryption key is present. Policies and API contracts will be encrypted.

If not, Mule runtime starts with:

No encryption key provided. Policies and API contracts will not be encrypted.

If the decryption process fails, the Mule environment displays an error:

Client ID cannot be decrypted

If your credentials cannot be decrypted, you cannot establish a connection with Anypoint Platform,
nor can you subsequently download policies or contracts or generate analytics information for
tracked APIs.

## Troubleshooting Credentials

If you encounter issues when passing your encrypted credentials to Anypoint Platform, MuleSoft
recommends you verify that the provided credentials are valid. You can use the Secure Properties
Tool to decrypt the values back to the original and compare them with the ones displayed in Anypoint
Platform:

1.  Run the Secure Properties Tool to decrypt your credentials:

    ```none
    > java -jar secure-properties-tool.jar string decrypt AES CBC <yourEncryptionKey>
    ```

2.  Compare the decrypted value with the one in Anypoint Platform.  
    See [Obtaining Credentials](https://docs.mulesoft.com/mule-gateway/mule-gateway-org-credentials-mule4#obtaining-credentials) for
    information on how to verify your Anypoint Platform’s credentials.

## Supported Properties

The following `wrapper.conf` properties support encryption:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Property</th><th>Property Key</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Client ID</p></div></div></td><td><div><div><p><code>anypoint.platform.client_id</code></p></div></div></td><td><div><div><p>Your Anypoint Platform client ID</p></div></div></td></tr><tr><td><div><div><p>Client secret</p></div></div></td><td><div><div><p><code>anypoint.platform.client_secret</code></p></div></div></td><td><div><div><p>Your Anypoint Platform client secret</p></div></div></td></tr><tr><td><div><div><p>Proxy password</p></div></div></td><td><div><div><p><code>anypoint.platform.proxy_password</code></p></div></div></td><td><div><div><p>Password of the proxy configuration to connect to Anypoint Platform</p></div></div></td></tr></tbody></table>

## Policies Encryption

The configuration for your API policies is stored in the `policies` directory. Some policies may
contain sensitive information that you want to hide from unauthorized parties, such as the password
field for the `Basic Authentication` header.

Sensitive values in your provided API policies are marked as such in the API Manager UI for policy
configuration. When creating a custom policy, you can define which values are sensitive.

## Configuring Policy Encryption

To enable encryption in policies, you must provide two system properties in your `wrapper.conf`
file:

- `anypoint.platform.encryption_key`  
  The encryption key for your policy.

  > [!CAUTION] If you restart Mule runtime without an encryption key, all policies are downloaded
  > again, and sensitive information is not encrypted.

- `anypoint.platform.policy_encryption_mode`  
  This property key can take two values:

  <table><colgroup><col> <col></colgroup><tbody><tr><td><div><div><p><code>FULL</code></p></div></div></td><td><div><div><p>All values are encrypted.</p></div></div></td></tr><tr><td><div><div><p><code>SENSITIVE_ONLY</code></p></div></div></td><td><div><div><p>Only values that you marked as <code>sensitive</code> are encrypted.<br>This is the default encryption mode.</p></div></div></td></tr></tbody></table>

  If you have not configured this property, the default `SENSITIVE_ONLY` encryption mode is used.  
  You can change the encryption mode after applying one. The files in your `policies` directory
  regenerates according to your new encryption mode.

  > [!CAUTION] If you are changing from `FULL` to `SENSITIVE_ONLY`, any parameter not marked as
  > `sensitive` is shown as plain text in your file system.

## Policies That Support Encryption

The following list describes all policies that support encryption in their values, along with their
minimum required version to support this feature.

Earlier versions of these policies and policies that are not listed below will not encrypt the
policy values even when the gateway capability detects an encryption key in its configuration.

<table><colgroup><col> <col></colgroup><thead><tr><th>Policy</th><th>Version</th></tr></thead><tbody><tr><td><div><div><p>Basic Authentication</p></div></div></td><td><div><div><p>1.2.0 and later.</p></div></div></td></tr><tr><td><div><div><p>Client ID Enforcement</p></div></div></td><td><div><div><p>1.2.0 and later.</p></div></div></td></tr><tr><td><div><div><p>Header Injection</p></div></div></td><td><div><div><p>1.1.0 and later.</p></div></div></td></tr><tr><td><div><div><p>IP Allowlist</p></div></div></td><td><div><div><p>1.0.0 and later.</p></div></div></td></tr><tr><td><div><div><p>IP Blocklist</p></div></div></td><td><div><div><p>1.0.0 and later.</p></div></div></td></tr><tr><td><div><div><p>JWT Validation</p></div></div></td><td><div><div><p>1.1.0 and later.</p></div></div></td></tr><tr><td><div><div><p>Open AM</p></div></div></td><td><div><div><p>1.2.0 and later.</p></div></div></td></tr><tr><td><div><div><p>Open ID</p></div></div></td><td><div><div><p>1.2.0 and later.</p></div></div></td></tr><tr><td><div><div><p>OAuth 2.0</p></div></div></td><td><div><div><p>1.2.0 and later.</p></div></div></td></tr><tr><td><div><div><p>Ping Federate</p></div></div></td><td><div><div><p>1.2.0 and later.</p></div></div></td></tr></tbody></table>

## Custom Policy Encryption

The recommended way to create a new custom policy project is using the Maven archetype.  
When creating a new custom policy project using the archetype, you can pass the
`-DencryptionSupported=true` property to enable encryption in your custom policy.  
See [Setting up a project with the archetype](https://docs.mulesoft.com/mule-gateway/policies-custom-getting-started#setting-up-a-project-with-the-archetype)
for more detailed steps to do this. If you are developing a custom policy manually, or want to add
encryption to an existing policy, perform the following steps:

1.  Add the required dependencies in the policy `pom.xml` file.  
    You must add the **Secure Configuration Property Module** dependency in your `pom.xml` file:

    ```XML
    <dependency>
       <groupId>com.mulesoft.modules</groupId>
       <artifactId>mule-secure-configuration-property-module</artifactId>
       <version>${securePropertyModuleVersion}</version>
       <classifier>mule-plugin</classifier>
    </dependency>
    ```

2.  Add the **Secure Properties Element** to your policy’s template file.  
    Paste the following snippet in your policy’s XML template file, after your `<mule …​>` element:

    ```XML
    {{#if encrypted}}
    <secure-properties:config key="${anypoint.platform.encryption_key}" file="${encryptedPropertiesFile}" name="encryptionConfiguration">
       <secure-properties:encrypt algorithm="AES" mode="CBC"/>
    </secure-properties:config>
    {{/if}}
    ```

    This feature supports only the AES Algorithm in CBC mode.  
    The gateway capability takes the `anypoint.platform.encryption_key` and
    `encryptedPropertiesFile` values from the system properties that you set at startup time for the
    gateway.

3.  Define the sensitive values in the policy’s YAML file.  
    By default, the values in a custom policy are not sensitive. To specify that a value is
    sensitive, use the `sensitive` element.

    ```YAML
      configuration:
       - propertyName: username
         type: string
         sensitive: false
       - propertyName: password
         type: string
         sensitive: true (1)
    ```

    <table><tbody><tr><td><i data-value="1"></i><b>1</b></td><td>The <code>password</code> value in your policy is now considered sensitive.</td></tr></tbody></table>

## Offline Policies Encryption

You can encrypt the configuration of your offline policies by encrypting their values using the
[Secure Properties Tools](https://docs.mulesoft.com/mule-runtime/latest/secure-configuration-properties#secure-properties-tool).

\> java -jar secure-properties-tool.jar \\ string \\ **(1)** encrypt \\ **(2)** AES \\ **(3)** CBC
\\ MyEncryptionKey1 \\ **(4)** bb458e566cba4e2ea5a826d27b46031a

1.  Use the string parameter to encrypt a single value.

2.  Set the tool to encrypt the value.

3.  Use AES with CBC Mode. This is important because Mule runtime uses this configuration to decrypt
    the value later.

4.  And finally, specify the encryption key-value pair that you want to encrypt.

See [Applying an Offline Policy](https://docs.mulesoft.com/mule-gateway/policies-custom-offline-apply) for more information.

## Contracts Encryption

If your Mule Gateway is configured with encryption, then contracts associated with the contract
enforcement policies will also be encrypted.

## Scope and Considerations

In a cluster scenario, you must set the encryption properties for each node. Otherwise, you may
leave some of your nodes unprotected.