Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (4.8)
  3. Security

  4. Secure Configuration Properties

Secure Configuration Properties

You can encrypt configuration properties as another security level for your applications. To create secure configuration properties, review the following process:

  1. Create a secure configuration properties file.

  2. Define secure properties in the file by enclosing the encrypted values between the sequence ![value].

  3. Configure the file in the project with the Mule Secure Configuration Properties Extension module. The file must point to or include the decryption key.

Attributes

Before you create a secure properties file and define its properties, review the secure configuration properties attributes and encrypting attributes used in the process:

Table 1. Secure Configuration Properties Attributes
Attribute Name Description

Name

A unique name for your global secure configuration properties.

Key

A word or phrase that you specify to unlock the properties value. For example, ${production.myproperty} instructs the Mule runtime engine to demand the key at runtime.

File

The location of the file that the key unlocks.

Encoding

Encoding of the file that the key unlocks. The default value is UTF-8.

File Level Encryption

Set to true if the file itself is entirely encrypted. Default value is false.
Table 2. Secure Configuration Properties Encrypting Attributes
Attribute Name Description

Algorithm

The type of algorithm you use to encrypt the content of the property. See Supported Algorithms for a complete list.

Mode

The procedure that allows the Mule runtime engine to repeatedly use a block cipher with a single key. See Supported Modes for a full list.

Use random IVs

Set this attribute to true to use random initialization vectors (IVs). If this option is set to true, the decryption algorithm assumes IVs are prepended to the ciphertext during decryption operations.

Create a Secure Configuration Properties File

The first task in securing configuration properties is to create a YAML configuration file (.yaml) or a Spring-formatted Properties file (.properties), where you define the properties. The Mule Secure Configuration Properties Extension module enables you to configure YAML or Properties file types.

You can create secure configuration properties files either in src/main/resources in your Mule project, or by using absolute paths.

Define Secure Configuration Properties in the File

Define secure properties in the file by enclosing the encrypted values between the sequence ![value]. The file can contain both encrypted and nonencrypted values that could be used anywhere in the Mule application.

Secure access to the operating system. Anyone who can run a ps command or view a Java console will be able to see the decrypted values that are stored in the Mule app’s memory.

The following file1.yaml example contains both encrypted and nonencrypted configuration properties values:

encrypted:
    value1: "![nHWo5JhNAYM+TzxqeHdRDXx15Q5R56YVGiQgXCoBCew=]"
    value2: "![nHWo6XyCADP+TzxqeHdRDXx15Q5R56YVGiQgXCoDFaj=]"

testPropertyA: "testValueA"
testPropertyB: "testValueB"
The encrypted value must be enclosed in quotes so that it is read as a string.

The following file1.properties example contains the configuration properties used in the previous example but uses a Spring-formatted properties file:

encrypted.value1=![nHWo5JhNAYM+TzxqeHdRDXx15Q5R56YVGiQgXCoBCew=]
encrypted.value2=![nHWo6XyCADP+TzxqeHdRDXx15Q5R56YVGiQgXCoDFaj=]

testPropertyA=testValueA
testPropertyB=testValueB

Encrypt Properties Using the Secure Properties Tool

Use the Secure Properties Tool to encrypt or decrypt text strings, values inside a properties file, or all the contents of a properties file.

Ensure that you have the latest available version of this tool to use all the functions detailed in this article.

Secure Properties Tool Jar file - Supports Java 17.
Latest release: 11/22/2024.

Secure Properties Tool Jar file - Supports Java 8 and 11.
Latest release: 09/14/2022.

Note that the syntax has changed from earlier versions. To avoid issues, use the syntax and the JAR file provided in this article.

See Parameters Reference for a complete list and definition of all accepted parameters.

Encrypt Text Strings

Use the following syntax to encrypt or decrypt a text string provided as a parameter:

java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \
<method> \
<operation> \
<algorithm> \
<mode> \
<key> \
<value> \
--use-random-iv [optional]

  • Set <method> to string to configure the tool to process a text string.

  • Specify the other parameters to perform your desired operation.

For example, if you run:

java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \
string \
encrypt \
Blowfish \
CBC \
mulesoft \
"some value to encrypt"

The tool returns:

8q5e1+jy0cND2iV2WPThahmz6XsDwB6Z

Encrypt Files

In addition to processing strings, the encryption tool processes .yaml or .properties files. You can encrypt or decrypt the values inside a properties file, or all the file’s content.

Encrypt Properties Inside a File

Use the following syntax to encrypt or decrypt all values inside a properties file:

java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \
<method> \
<operation> \
<algorithm> \
<mode> \
<key> \
<input file> \
<output file> \
--use-random-iv [optional]

  • Set <method> to file.

  • Set <input file> to the properties file to process.

  • Set <output file> to the file that is generated after the process.

  • Specify the other parameters to perform your desired operation.

For example, consider the file example_in.yaml with the following content:

properties:
  example1:
    value: "Muleman is here"
  example2: "Max the mule"

If you run:

java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \
file \
encrypt \
Blowfish \
CBC \
mulesoft \
example_in.yaml \
example_out.yaml

The tool generates the file example_out.yaml with the following content:

properties:
  example1:
    value: "![qCReIPK3jcqD7WR84ISSIQ==]"
  example2: "![En8lII21ZHrdIaINw0+mSA==]"

Encrypt All the Content of a File

Use the following syntax to encrypt or decrypt all the content of a properties file:

java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \
<method> \
<operation> \
<algorithm> \
<mode> \
<key> \
<input file> \
<output file>
--use-random-iv [optional]

  • Set <method> to file-level.

  • Set <input file> to the properties file to process.

  • Set <output file> to the file that is generated after the process.

  • Specify the other parameters to perform your desired operation.

For example, consider the file example_in.yaml with the following content:

properties:
  example1:
    value: "Muleman is here"
  example2: "Max the mule"

If you run:

java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \
file-level \
encrypt \
Blowfish \
CBC \
mulesoft \
example_in.yaml \
example_out.yaml

The tool generates the file example_out.yaml with the following content:

k/J1EHyxJagOcyQELoaqIDCzzKc1bLGJiHY2dv6jzuhtVpP1LTlgK3y8EH7OkK5iuuu8kik3P5dCDMixZXwn/EV6xbUwLFKnEb4x1pUX6aopLP/KULm0pQ==

Parameters Reference

Parameter Description

<method>

Sets the encryption or decryption method. Accepted values are:

string

Encrypts a single text string provided as parameter <value>.

file

Encrypts the value of each property set in the properties file provided as parameter <input file>.

file-level

Encrypts all the content of the properties file provided as parameter <input file>.

<operation>

Sets the operation to perform. Accepted values are:

encrypt

Sets the operation to encryption.

decrypt

Sets the operation to decryption.

<algorithm>

Specifies the algorithm to use during the operation.
See Supported Algorithms for a complete list.

<mode>

Specifies the mode to use during the operation.
See Supported Modes for a full list.

<key>

Specifies the word used to lock or unlock the file or value during the operation.

  • If you use the $ character in your key, you must precede it with \. For example, to use key myKey#$%123, you must specify the <key> parameter as myKey#\$%123.

  • Beginning with Java Cryptography Extension (JCE) version 1.8.0_161, the AES key size must be of 32 characters (128 bits).

<value>

Specifies the string value that is encrypted or decrypted during the string operation.

<use random IV>

Specifies if random initialization vectors (IVs) are used during the operation.

<input file>

Specifies the properties file that is encrypted or decrypted during the file or file-level operation.

<output file>

Specifies the encrypted or decrypted properties file that is created after the file or file-level operation.

Configure the File in the Project

You can configure a secure properties file both in standalone XML or in Anypoint Studio, with the Mule Secure Configuration Properties Extension module available from Exchange.

Configure the File with the Extension Module in XML

In your XML flow, use the module <secure-properties:config> to configure the file. Review the following example:

Secure Configuration Properties with Default Values

<secure-properties:config key="${runtime.property}"
  file="file1.yaml" name="test">
    <secure-properties:encrypt/>
</secure-properties:config>

<global-property name="prop" value="my-${secure::property.key1}"/>

  • The <secure-properties:encrypt> tag is required even when using the default values.

  • The prefix secure:: is required for loading the key.

    You have to use the secure:: prefix to access all values inside a secure properties file, even if the values are not encrypted. Doing this enables you to switch between files (or environments) without changing the entire configuration.

  • At deployment time, a decryption key is passed into the Mule runtime engine as a system environment variable runtime.property. This property must be the exact key used to encrypt the values stored in the file1.yaml file.

  • The default encryption algorithm and mode is used.

  • If the actual (decrypted) value of the property property.key1 is, for example, "property", the value of the property prop is "my-property".

You can also change the encryption algorithm and crypto mode by setting additional attributes of the <secure-properties:encrypt> tag:

Secure Configuration Properties with Custom Values

<secure-properties:config key="${runtime.property}"
  file="file1.properties" name="test">
    <secure-properties:encrypt algorithm="AES" mode="CBC" useRandomIVs="true"/>
</secure-properties:config>

In the previous example, the <secure-properties:encrypt> tag uses the AES algorithm with CBC mode and random IV.

The key, algorithm, mode and useRandomIVs values set in <secure-properties:config> must match the values used to encrypt the properties files.

Configure the File with the Extension Module in Studio

If you are developing applications using Anypoint Studio, you can also create secure configuration properties using the module by adding it as a dependency in your Mule app.

Install the Extension Module

  1. Open your Mule project in Anypoint Studio.

  2. Go to the Mule Palette section.

  3. Click Search in Exchange.

  4. In the Add Module to Project window, search for Mule Secure Configuration Property Extension in the Type a search term to look up in Exchange box.

  5. Select the module name in the list.

  6. Click Add and then Finish.

Add and Configure Secure Configuration Properties to your App

  1. Go to your Mule app configuration file.

  2. Select Global Elements tab.

  3. Click Create.

  4. Select Secure Properties Config.

  5. Configure the global element with a File location, Key, Algorithm, Mode, Use random IV, File level encryption, and Encoding.

  6. Click OK.

config extension

The key, algorithm, mode and use random IV values set in the Secure Configuration Properties module must match the values used to encrypt the properties files.

Verify Secure Configuration Properties at Development Time

When you are developing applications in Studio, you can verify that secure configurations properties for a connector are set up correctly by testing the connector connection. The following example shows a Salesforce connector configuration with its secure properties (username, password, and token) encrypted in a .yaml file:

config extension2

The secure:: prefix is added before the property name definition, to enable access to all values inside a secure properties file, even if the values are not encrypted.

You can click Test Connection to verify that the connection is functioning as expected and assure that the secure properties are read successfully.

File-Level Encryption

Since version 1.1.0 of the Secure Configuration Properties module, you can encrypt an entire file rather than only individual properties values. You can encrypt a file both in XML or Anypoint Studio:

In your XML flow, add the fileLevelEncryption attribute and set it to true:

<secure-properties:config key="${runtime.property}" file="file1.yaml" fileLevelEncryption="true" name="test">
    <secure-properties:encrypt algorithm="AES" mode="CBC"/>
</secure-properties:config>

In Studio, in Secure Configuration Properties window, select True for the File level encryption:

config extension3

Secure Configuration Properties Use Cases

Review the following uses cases about secure configuration properties, where you can learn how a flow uses encrypted and nonencrypted values, set secure configuration properties files dynamically, and how you can work using more than one configuration file.

Encrypted and Nonencrypted Values

The following example shows how a flow uses the encrypted encrypted.value1 value to set the payload. At runtime, the decryption algorithm is used to store the decrypted value of encrypted.value1 into memory.

<flow name="main">
    <set-payload value="${secure::encrypted.value1}"/>
</flow>

The following example shows how a flow uses a nonencrypted value from the same secure properties file:

<flow name="mainNonEncrypted">
    <set-payload value="${secure::testPropertyA}"/>
</flow>

Set Secure Configuration Properties File Dynamically

A common configuration use case is to set the file to depend on a property (for example, env) to determine which file to use.
For example, to use a development-properties file during the development stage (which could not be encrypted) or a production file (with encrypted values).

Secure Configuration Properties with Environment File Defined

<secure-properties:config key="${runtime.property}" file="${env}-properties.yaml" name="test"/>

Using this method, the value of the property env determines which file to use to load the secure configuration properties. That env property could be set by a global property, system property, or environment property.

Secure Global Configuration Properties with Environment File Defined

<global-property name="env" value="dev"/>

<secure-properties:config key="${runtime.property}" file="${env}-properties.yaml" name="test"/>

Using this method, the default value for the env property is "dev", which can still be overridden with a system or environment property. Note that this is required for metadata resolution in Anypoint Studio. If you do not define default values for the properties that are passed through the command line, you receive an error when you create the application model for all message processors that depend on those properties.

Work with More Than One Configuration File

You can define more than one secure configuration properties file to read properties from. To do so, simply define a <secure-properties:config /> tag for each file you want to load. Each secure configuration properties file is independently configured with an encryption algorithm, cipher mode, and encryption/decryption key. These settings do not have to be the same among the files.
The following example shows how to use more than one configuration file:

<secure-properties:config key="${runtime.property}" file="file1.yaml" name="test">
    <secure-properties:encrypt algorithm="AES" mode="CBC"/>
</secure-properties:config>

<secure-properties:config key="${runtime.property}" file="file2.yaml" name="otherConfig">
    <secure-properties:encrypt algorithm="AES" mode="CBC"/>
</secure-properties:config>

Supported Configuration File Types

  • Spring-formatted properties: .properties

  • YAML: .yaml

Supported Algorithms and Modes

Supported Algorithms

  • AES (default)

  • Blowfish

  • DES

  • DESede

  • RC2

  • RCA

The following algorithms can be used only if you configure a Java Cryptography Extension (JCE) Provider that adds support for them:

  • Camellia

  • CAST5

  • CAST6

  • Noekeon

  • Rijndael

  • SEED

  • Serpent

  • Skipjack

  • TEA

  • Twofish

  • XTEA

  • RC5

  • RC6

Supported Modes

  • CBC (default)

  • CFB

  • ECB

  • OFB

Frequently Asked Questions

After you learn about, create, and use secure configuration properties files for a while, you might have additional questions about troubleshooting and maximizing their use. Following are some common questions and answers. Refer as well to the topics linked to in See Also.

What if a property is defined in multiple files?

In that case, the actual property’s value will be the one in which is first defined.

Can I define a secure property that depends on a previously defined secure property?

Yes. Just use the same syntax: property=My dependent ${secure::dependent.property} value.

Note that secure configuration properties can depend on other secure configuration properties, but not on other Mule configuration properties.

See Also