Contact Free trial Login

Secure Configuration Properties

Create secure configuration properties by encrypting them. To set up the encryption process:

  1. Obtain the Mule Secure Configuration Property Extension module from Exchange, as described in Adding the Secure Configuration Properties Module.

  2. Configure a secure properties file with this module. This file must point to or include the decryption key.

  3. Define secure properties in any properties configuration file. Enclose the secured properties between the sequence ![value], as described in Configuration Files Content. The same properties configuration file can include secured and non-secured properties.

Adding the Secure Configuration Properties Module

The Mule Secure Configuration Property Extension module is available from Exchange.

You can configure a secure properties file with this module (<secure-properties:config>), for example:

Example: Secure Configuration Properties with Default Values
<secure-properties:config key="${runtime.property}"
  file="file1.yaml" name="test">
    <secure-properties:encrypt/> (1)
</secure-properties:config>

<global-property name="prop" value="my-${secure::property.key1}"/> (2)
1 The <secure-properties:encrypt> tag is required even when using the default values.
2 The prefix secure:: is required for loading the key.

In the example above:

  • A decryption key is passed into the Mule runtime at deployment time 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 will be "my-property".

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

Example: Secure Configuration Properties with Custom Values
<secure-properties:config key="${runtime.property}"
  file="file1.properties" name="test">
    <secure-properties:encrypt algorithm="AES" mode="CBC"/> (1)
</secure-properties:config>
1 This uses the AES algorithm with CBC mode.

Attributes

Secure Configuration Properties Attributes

Name

A unique name for your global secure configuration properties.

Key

The word or phrase to unlock the properties value according to the system property that you define in this field. For example, ${production.myproperty} instructs the Mule runtime to demand the key at runtime.

File

The location of the file that the key unlocks. See Supported Files.

Secure Configuration Properties Encrypting Attributes

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 to repeatedly use a block cipher with a single key. See Supported Modes for a full list.

Supported Files

The Secure Configuration Properties module supports both YAML configuration files and Spring-formatted properties files, as shown in the examples below. The recommended approach is to use a YAML configuration file, because it allows the addition of type validations and autocompletion.

Configuration Files Content

Both encrypted and non-encrypted values can be used anywhere in the Mule app. Encrypted values should be defined between the sequence ![value], as shown in the example below. The file1.yaml file can also contain non-encrypted values, for example:

Example: file1.yaml
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.

Here is the same configuration as above using a Spring-formatted properties file:

Example: file1.properties
encrypted.value1=![nHWo5JhNAYM+TzxqeHdRDXx15Q5R56YVGiQgXCoBCew=]
encrypted.value2=![nHWo6XyCADP+TzxqeHdRDXx15Q5R56YVGiQgXCoDFaj=]

testPropertyA=testValueA
testPropertyB=testValueB

Usage

Here is a flow that uses the encrypted encrypted.value1 value to set the payload:

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

At runtime, the decryption algorithm is used to store the decrypted value of encrypted.value1 into memory.

Here is a flow that uses a non-encrypted value from the same secure properties file:

Example: Use of Non-encrypted Properties
<flow name="mainNonEncrypted">
    <set-payload value="${secure::testPropertyA}"/>
</flow>

Notice that you have to use the secure:: prefix to access all values inside a secure properties file, even if the values are non-encrypted. This behavior allows you to switch between files (or environments) without changing the entire configuration.

Setting the 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 in development stage (which could not be encrypted) or a production file (with encrypted values).

Example: Secure Configuration Properties with Environment File Defined
<secure-properties:config key="${runtime.property}" file="${env}-properties.yaml" name="test"/>

This way, 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 (see Configure Properties).

Example: Secure Configuration Properties with Environment File Defined
<global-property name="env" value="dev"/>

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

This way, the default value for the env property will be "dev", which can still be overriden with a system or environment property. Please note that this is required for metadata resolution in Anypoint Studio. If you do not define devault values for the properties that are passed through the command line you will receive an error while creating application model for all message processors that depend on them.

Working 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. None of these settings needs to be the same between secure configuration properties files.

Using More Than One Config 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>

Frequently Asked Questions

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.

What if I want to define a secure property to depend on a previously defined secure property?

It is possible to define a property to depend on a previously defined one, just using 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 Configure Properties).

Warning

When using encrypted properties, it is especially important to 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.

Supported Algorithms and Modes

Supported Algorithms

  • AES (default)

  • Blowfish

  • DES

  • DESede

  • Camellia

  • CAST5

  • CAST6

  • Noekeon

  • Rijndael

  • SEED

  • Serpent

  • Skipjack

  • TEA

  • Twofish

  • XTEA

  • RC2

  • RC5

  • RC6

  • RCA

Supported Modes

  • CBC (default)

  • CFB

  • ECB

  • OFB

Using the Extension in Anypoint Studio 7

You can use this extension by adding it as a dependency in your Mule app.

Installing the Extension

  1. Open your Mule project in Anypoint Studio.

  2. Go to the Mule Palette.

  3. Select Search in Exchange, and search for the Mule Secure Configuration Property Extension.

  4. Add the extension.

Adding Secure Configuration Properties to your App

  1. Go to your Mule app configuration file.

  2. Select the Global Elements tab.

  3. Click the Create button.

  4. From the search bar, select Secure Properties Config.

  5. Configure the global element with a File location, Key, Algorithm, and Mode:

config extension

Secure Properties Tool

You can download the JAR file for this tool so you can encrypt or decrypt single values, and complete files (both, YAML and Properties files). You can run it in the command line as follows:

Using the Secure Properties Tool
java -jar secure-properties-tool.jar string <encrypt|decrypt> <algorithm> <mode> <key> <value>

Or you can use a command like this:

java -jar secure-properties-tool.jar file <encrypt|decrypt> <algorithm> <mode> <key> <input file> <output file>

In the case of using the file mode, the output is a file with the same properties, but its values are encrypted. For example, assume that this is the input file:

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

If you run java -jar secure-properties-tool.jar file encrypt Blowfish CBC mulesoft example_in.yaml example_out.yaml, the output file will be:

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

Note that key sizes might depend on the Java Cryptography Extension (JCE) version. For example, since version 1.8.0_161, the AES key size should be of at least 32 characters (256 bytes), instead of 16 for previous versions.