Contact Free trial Login

Gateway Startup Encryption in Mule 4

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

Encrypting Your Anypoint Platform Credentials Using the Agent

Configuring encryption through the Runtime Manager Agent is the fastest way to secure your client credentials. You have to add the encryption key when creating an Agent server, and the agent will handle the properties encryption for you.
See Install and Configure the Runtime Manager Agent to learn how to configure the agent with encryption.

Encrypting the Client ID and Secret

If you are not using an agent, you can still manually encrypt your properties.

The most common way, is using the Secure Properties Tools.
When using encrypted properties, the API gateway assumes that you are using the AES algorithm in CBC Mode.

Example

Suppose that your client ID is bb458e566cba4e2ea5a826d27b46031a, and that you choose the encryption key to be the 128 bits string MyEncryptionKey1. To encrypt it, you need to run the following command:

> java -jar secure-properties-tool.jar \
string \ (1)
encrypt \ (2)
AES \ (3)
CBC \
MyEncryptionKey1 \ (4)
bb458e566cba4e2ea5a826d27b46031a
1 As you are trying to encrypt a single value, you need to specify it using the string parameter.
2 Set the tool to encrypt the value.
3 Use AES with CBC Mode.
This is important, as the Mule runtime engine only uses this configuration to decrypt the value later.
4 And finally, you write your encryption key and the value you want to encrypt.

This command outputs your encrypted client ID:

> smzbg+aV2HbiC9Fv8KBsZpD5PlXiplsfhZ42RWNEbHhUeZ9ZIDftljUx6sYpuQ+b

Passing your Encrypted Client ID and Secret

After encrypting your credentials, you need to configure your encrypted values in your wrapper.conf file located inside the conf directory in the root folder of your Mule runtime:

anypoint.platform.client_id.<n>
anypoint.platform.client_secret.<n>
anypoint.platform.proxy_password.<n>

+

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

In the example above, your client_id would look as below:

anypoint.platform.client_id.<n>=![smzbg+aV2HbiC9Fv8KBsZpD5PlXiplsfhZ42RWNEbHhUeZ9ZIDftljUx6sYpuQ+b]
The ![ prefix and ] suffix are required, as they indicate the Mule runtime engine that the enclosed value is encrypted.

For the Mule runtime engine to be able to decrypt your secured values, you need to pass your secret key when starting your Mule runtime using the anypoint.platform.encryption_key property:

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

the Mule runtime engine 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 your runtime’s wrapper.conf file.

While the Mule runtime engine is starting it checks for an encryption key. Then it gets the client ID and client secret values from its wrapper.conf file. If some of the values in that file are enclosed within the encryption indicators (![ and ]), the Mule runtime engine uses the encryption key it loaded earlier to decrypt the values and use its original content.

Debugging Startup Encrpytion

You can configure your gateway 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:

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

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

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

If not, the Mule runtime engine stars with:

No encryption key provided. Policies and API contracts won't be encrypted.

If the decryption process fails, the Mule runtime engine displays an error:

Client ID cannot be decrypted

If your credentials can’t be decrypted, you cannot establish a connection with Anypoint Platform, and won’t be able to download policies or contracts.

Troubleshooting Credentials

If you run into issues when passing your encrypted credentials to Anypoint Platform, it’s recommended to check that the provided credentials are valid. You can use the Secure Properties Tool described earlier to decrypt the values back to the originals and compare them with the ones displayed in Anypoint Platform:

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

    > 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 for information on how to verify your Anypoint Platform’s credentials.

Supported Properties

The following wrapper.conf properties support encryption:

Property Description

Client ID

anypoint.platform.client_id.<n>

Your Anypoint Platform Client ID

Client Secret

anypoint.platform.client_secret.<n>

Your Anypoint Platform Client Secret

Proxy Password

anypoint.platform.proxy_password.<n>

Password of the proxy configuration to connect to Anypoint Platform

Policies Encryption

The configuration for your API policies is stored in the policies directory, and 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 need to provide two system properties in your wrapper.conf file:

  • anypoint.platform.encryption_key.<n>.
    The encryption key for your policy.

    If you have all your policies encrypted, and then you restart the Mule runtime engine without an encryption key, all policies will be downloaded again, but all the sensitive information won’t be encrypted.

  • anypoint.platform.encryption_mode.<n>.
    This property can take two values:

    FULL

    All values are encrypted.

    SENSITIVE_ONLY

    Only values that you marked as sensitive are encrypted.
    This is the default encryption mode.

    If this property is not set in the wrapper.conf file, then the default SENSITIVE_ONLY encryption mode is used.
    You can change the encryption mode after applying one. The files in your policies directory will regenerate according to your new encryption mode.

    If you are changing from FULL to SENSITIVE_ONLY, any parameter not marked as sensitive will be shown as plain text in your filesystem.

Policies That Support Encryption

Below is a list of 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 not listed below will not encrypt the policies values even when the gateway capability detects an encryption key in its configuration.

Policy Version

Basic Authentication

1.2.0 and later.

Client ID Enforcement

1.2.0 and later.

Header Injection

1.1.0 and later.

IP Whitelist

1.2.0 and later.

IP Blacklist

1.2.0 and later.

JWT Validation

1.1.0 and later.

Open AM

1.2.0 and later.

Open ID

1.2.0 and later.

OAuth 2.0

1.2.0 and later.

Ping Federate

1.2.0 and later.

Custom Policy Encryption

The recommended way of creating 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 for more detailed steps to do this.

If you are developing a custom policy manually, or want to add encryption to an existing policy, follow the steps below:

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

    <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:

    {{#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. You can use the element sensitive to specify whether a value is sensitive or not.

      configuration:
       - propertyName: username
         type: string
         sensitive: false
       - propertyName: password
         type: string
         sensitive: true (1)
    1 The password value in your policy is now considered sensitive.

Offline Policies Encryption

You can encrypt the configuration of your offline policies by encrypting their values using the Secure Properties Tools as described in the above:

> java -jar secure-properties-tool.jar \
string \ (1)
encrypt \ (2)
AES \ (3)
CBC \
MyEncryptionKey1 \ (4)
bb458e566cba4e2ea5a826d27b46031a
1 As you are trying to encrypt a single value, you need to specify it using the string parameter.
2 Set the tool to encrypt the value.
3 Use AES with CBC Mode.
This is important, as the Mule runtime engine only uses this configuration to decrypt the value later.
4 And finally, you write your encryption key and the value you want to encrypt.

See Applying an Offline Policy for more information.

Contracts Encryption

If your 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.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub