Mule Credentials Vault

Use the Mule Credentials Vault to encrypt data in a .properties file. (In the context of this document, we refer to the .properties file simply as the properties file.)

The properties file in Mule stores data as key-value pairs which may contain information such as usernames, first and last names, and credit card numbers. A Mule application may access this data as it processes messages, for example, to acquire login credentials for an external Web service. However, though this sensitive, private data must be stored in a properties file for Mule to access, it must also be protected against unauthorized – and potentially malicious – use by anyone with access to the Mule application. How do you protect the data in a properties file while still making it available to Mule?

If you have installed Anypoint Enterprise Security you can secure your information using these three ingredients:

Mule Credentials Vault
Global Secure Property Placeholder element
Key to unlock the vault

In the context of Anypoint Enterprise Security, the properties file which stores encrypted properties is called the Mule Credentials Vault.

Also note that the uniquepassword value in this document refers to a unique password that the person using your application supplies when the application runs.

How It Works

Imagine a situation in which you are tasked with designing a Mule application for the Human Resources department that must access a secure database of private employee information. An HR employee – an authorized end user of the Mule application – submits a request for information, say, an employee’s base salary, and the Mule application must access a secure database to retrieve the information. One cannot access this HR database without valid login credentials, so you need to design the Mule application to access the database, yet keep the database login credentials secret.

First, you need to design the application to process HR end user requests, which includes a call to the secure database. Then create a Mule Credentials Vault to store the database login credentials, or properties. In the context of Anypoint Enterprise Security, the properties file which stores encrypted properties is the Credentials Vault. When you add data to the properties file, Mule gives you the option to encrypt the data. You then choose an encryption algorithm (of the 19 available), and enter an encryption key. That encryption key is the only way to decrypt the properties in the properties file. In other words, the encryption key is the only thing that unlocks the Credentials Vault.

Next, create a global Secure Property Placeholder element which locates the Credentials Vault (that is, the properties file), and retrieve encrypted properties. However, the Secure Property Placeholder can only access the Credentials Vault (that is, to decrypt the data) if it has the key.

Now you have the data in a vault and a mechanism to request the data, but where is the key to unlock the vault (that is, to decrypt the data)? And how do you ensure that the key is not accessible by everyone with access to the application? If you simply hard code the key into the configuration of the global Secure Property Placeholder, any colleague with access to the application can read the key and unlock the vault. Therefore, you need to configure the Secure Property Placeholder to use the key that Mule collects from the user at runtime (see code below). In this context, the key to decrypt the properties becomes a runtime password.

<secure-property-placeholder:config key="${prod.key}" location="test.${env}.properties"/>

At runtime (that is, when you run the Mule application on premises or in the cloud), Mule demands that the user (for example, an Operations Administrator) enter a key, which Mule stores in-memory. Recall that the key that Mule demands at runtime is the same key you use to encrypt the properties in the Credentials Vault; you in this scenario had to have manually give the key to the person who is responsible for running the application, such as an Ops Admin. Whenever a Secure Property Placeholder within a Mule application must unlock the Credentials Vault to retrieve HR database login credentials, it uses the key that the Ops Admin entered at runtime. Conveniently, Mule remembers the key for the duration of the Ops Admin’s session so as to avoid demanding a key each time a Mule decrypts a property in the vault. However, when the Ops Admin ends the Mule session (that is, terminates the application), Mule discards the key.

To configure Mule to demand that a user enter a password key at runtime, you need to include the following in the system properties (the mule-app.properties file in the src/main/app folder):

-M-Dprod.key=uniquepassword -M-Denv=prod

When it needs the key to decrypt the contents of the properties file, the secure properties placeholder asks Mule’s system properties file, which uses the in-memory key as entered by the Ops Admin.

Placeholders, Keys, and Vaults

In Mule, you can set up several variations of of the Placeholder-Vault-Key relationship.

This topic introduces the idea of Global Elements; if you are unfamiliar with this functionality, access Understand Global Mule Elements to learn more before proceeding.

One-to-One-to-One Relationship

The first variation is a simple one-to-one-to-one relationship, as illustrated in the graphic below. The configuration of one global secure property placeholder demands that it use one key to unlock one Credentials Vault. (In other words, one key decrypts the properties in one properties file.) Unlocked and decrypted at runtime with the key, any flow which must access the data in the properties file can do so.

One-to-One-to-Many Relationship

The second variation is a one-to-one-to-many relationship, as illustrated in the graphic below. The configuration of one global secure property placeholder demands that it use one key to unlock many Credentials Vaults. (In other words, one key decrypts the properties in many properties files.) Unlocked and decrypted at runtime with the key, any flow which must access the data in any of the properties file can do so.

Multiple One-to-One-to-One Relationships

As soon as you assign a different key to each property file, you create a situation that requires multiple one-to-one-to-one relationships. As illustrated in the graphic below, each global secure property placeholder uses only one key which, in turn, unlocks only one Credentials Vault. (In other words, each key decrypts the properties in only one properties file.) Unlocked and decrypted at runtime with multiple keys, any flow which must access the data in any of the properties file can do so.

Use Mule Credentials Vault

To use the Mule Credentials Vault, you must perform three tasks:

Encrypt properties in a properties file.
Create a global secure property placeholder in your Mule application to use the encryption key Mule collects at runtime.
Configure Mule’s system properties file to demand the key at runtime.

The following sections describe how to complete these three tasks.

Encrypt Properties

Studio Visual Editor

In Studio, right-click the src/main/resources folder, then select New > File.
In the New File wizard, enter a Filename, including the .properties extension. For example, test.properties.
Click Finish. Studio saves the new, blank file in your project and opens a new window in a Properties File Editor window.
Click the in the .properties tab to close the Properties File Editor window.
In the Package Explorer, right-click the .properties file, then select Open With > Mule Properties Editor.
Click the green icon in the Studio toolbar (see the image below) to open the Add a new property dialog.
Add the key-value pair (property) you wish to record in the properties file.
If you want to save the property as an unencrypted key-value pair, simply click OK to add the new property to the properties file. Essentially, this produces an unencrypted properties file. However, if you wish to encrypt the properties file (that is, creates a Credentials Vault), click the Encrypt button.

Studio opens a Setup encryption information dialog, in which you:

Select the type of algorithm you wish to use to encrypt the value.

Enter the key that Mule requires when asked to decrypt the value.

Don’t Forget the Key!

The key that you enter to encrypt the properties file is the same key that the administrator enters at runtime. Be sure to keep this key secure and pass it to the administrator(s) who deploys and runs your Mule application.

Click OK to complete the encryption.
In the Add a new property dialog, Studio displays the encrypted value in the Value field (see below). Click OK to save the property.

Repeat steps 6 - 11 to add many properties to your Credentials Vault.

Note that the first time you add an encrypted a property to a properties file, Mule demands that you enter the key. The next time you add an encrypted property to the same properties file, Mule uses the key you entered and does not demand it again. Mule remembers the key (in-memory store) for the duration of your Studio session; when you end your session (that is, closes Studio), Mule "forgets" the key.

You can add unencrypted properties to a properties file. In the properties file, an encrypted property is indecipherable, but recognizable by its wrapper.

encrypted property

Username=![r8weir09458riwe0r9484oi]

unencrypted property

Username=Aaron Martinez

XML Editor or Standalone

Encrypt the properties in your .properties file.

Don’t Forget the Key!

The key that you use to encrypt the properties file is the same key that the administrator enters at runtime. Be sure to keep this key secure and pass it to the administrator(s) who deploys and runs your Mule application.

Set Global Secure Property Placeholder

Studio Visual Editor

In Studio, create a new global Secure Property Placeholder element.

Configure the field values of the global element according to the table below.

Field Req’d Value

Name

A unique name for your global secure property placeholder.

Key

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

Location

The name of the properties file that the key unlocks.

Encryption Algorithm

The type of algorithm you used to encrypt the content of the Credentials Vault.

The algorithms supported are:

AES
Blowfish
Camelia
CAST5
CAST6
DES
DESede
Noekeon
RC3
RC5
RC6
Rijndael
RSA
SEED
Serpent
Skipjack
TEA
Twofish
XT

Encryption Mode

The procedure that allows Mule to repeatedly use a block cipher with a single key.

The modes supported are:

XML Editor or Standalone

Create a new global secure-property-placeholder:config element in your config file, set above all the flows in the application.

Configure the attributes of the global element according to the table below.

<secure-property-placeholder:config name="Secure_Property_Placeholder" key="${production.myproperty}" location="test.properties" encryptionAlgorithm="Blowfish" doc:name="Secure Property Placeholder"/>

Attribute Req’d Value

name

A unique name for your global secure property placeholder.

key

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

location

The name of the properties file that the key unlocks.

encryptionAlgorithm

The type of algorithm you used to encrypt the content of the Credentials Vault.

The algorithms supported are:

AES
Blowfish
Camelia
CAST5
CAST6
DES
DESede
Noekeon
RC3
RC5
RC6
Rijndael
RSA
SEED
Serpent
Skipjack
TEA
Twofish
XT

encryptionMode

The procedure that allows Mule to repeatedly use a block cipher with a single key.

The modes supported are:

doc:name

A display name for the element in Studio’s Visual Editor. Not applicable for Standalone.

Configure Mule to Demand the Key

It is recommended to never store the secret encryption key value to disk in any file. Instead, an Operations Administrator should manually enter these secret properties to the command line command when starting the Mule runtime into which the application is deployed.

./mule -M-Dprod.key=uniquepassword -M-Denv=prod

In CloudHub, the Operations Administrator can enter each environment name/value pair into the Properties tab of the application’s deployment configuration.

Studio Visual Editor

During development time, for testing purposes, you can store the following values in the application configuration. In Studio, access the src/main/app folder, then double-click the mule-app.properties file to open it.
Add the following Java system environment properties to this configuration file:
```
prod.key=uniquepassword
env=prod
```
Save your changes to the file, then close.

XML Editor or Standalone

Open your project’s mule-app.properties file.
To this system properties file, add the following properties.
Save your changes to the file, then close.
Alternatively, instead of changing this file you can add these properties to your command line command when executing Mule.

./mule -M-Dprod.key=uniquepassword -M-Denv=prod

By default, the Secure Property Placeholder module sets the encryption key as a JVM parameter.

When you include the secret encryption key as a JVM argument, the value is stored in the $MULE_HOME/conf/wrapper-additional.conf file. Be sure to protect access to this file to avoid compromising your encrypted secure properties. If you use MMC, the secret encryption key value is also displayed in several places in the server’s Properties tab, so be sure to also secure access to this MMC view.

Administrative commands such as the ps command in UN*X or the tasklist command in Windows list all the JVM arguments used to start a Mule runtime, including the secret encryption key value, so access to these commands should also be restricted to trusted administrators.

Though the scenarios just mentioned satisfy most of the use cases, there are situations where you need to hide the secret encryption key value from other users of the operating system, that is, you must not show the secret encryption key as a JVM parameter, since it is visible to anyone having access to the process.

One way to secure the secret encryption key value is to implement a custom secure property placeholder that can read the encryption key in a different way: for example, from a file located in a protected folder. This custom implementation must extend org.mule.modules.security.placeholder.SecurePropertyPlaceholderModule.

Another solution is to set the mule.runtime.verbose flag to false at Mule startup, so that encryption keys are not logged with the system properties. ./mule -M-Dmule.key=mykey -M-Dmule.runtime.verbose=false

Using a Custom Secure Property Placeholder

The following example shows a custom implementation of SecurePropertyPlaceholderModule that fetches the encryption key from a file named keyfile.properties that is part of the class path of the application, for simplicity. This can be easily adapted to read the file from anywhere in the file system, in particular from a well protected folder.

package com.mulesoft.training.esbops.security;

import java.io.IOException;
import java.util.Properties;

import org.mule.modules.security.placeholder.SecurePropertyPlaceholderModule;
import org.mule.util.IOUtils;

public class CustomSecurePropertyPlaceholderModule extends SecurePropertyPlaceholderModule {

	public void setKeyFilePath(String keyFilePath) throws IOException {
		Properties prop = new Properties();
		prop.load(IOUtils.getResourceAsStream(keyFilePath, this.getClass()));
		super.setKey(prop.getProperty("secure.key"));
	}

}

Next, add a spring:bean element to your project to instantiate this custom secure property placeholder module. Notice the additional element <spring:property name="keyFilePath" value="keyfile.properties" /> tells this custom secure property placeholder where to look for the secure.key value.

<spring:beans>
    <spring:bean id="secure-property-placeholder" class="security.CustomSecurePropertyPlaceholderModule">
       <spring:property name="encryptionAlgorithm" value="Blowfish" />
       <spring:property name="encryptionMode" value="CBC" />
       <spring:property name="keyFilePath" value="keyfile.properties" />
       <spring:property name="location" value="secure.properties" />
       <spring:property name="ignoreUnresolvablePlaceholders" value="true" />
   </spring:bean>
</spring:beans>

Notice the code line prop.load(IOUtils.getResourceAsStream(keyFilePath, this.getClass())); in this custom secure property placeholder sets its keyFilePath to the value set in the <spring:property name="keyFilePath" value="keyfile.properties" /> element. In this example the file keyfile.properties must be located in the Mule server’s classpath. Alternatively the value can be an absolute path to a protected folder on the Mule runtime’s machine.

The code line super.setKey(prop.getProperty("secure.key")); looks for a property named secure.key inside the first matching file discovered in the keyFilePath.

Use Case Example

A company has built a Mule application which connects to the Salesforce API. The application stores Salesforce login credentials for all its users. Developers who work on the application must be able to test Salesforce connection functionality, but must not be able to access the users’ Salesforce account information. Therefore, the application has two properties files, one for the production environment of the application, and one that the developers can use to test functionality.

test.prod.properties (Salesforce key to production environment)
test.dev.properties (sandbox environment)

The test.prod.properties file stores encrypted contents in the Mule Credentials Vault; the test.dev.properties file stores unencrypted information inside properties file. Because ${env} is part of the name of the property, you need to assign a value to it when running Mule, this determines which property to read.
At runtime in production, the Mule application uses the key that was defined in the system properties to unlock the Credentials vault. This allows the Mule flows in the application to utilize the properties in the Credentials Vault to log in to Salesforce (refer to secure property placeholder configuration below). The secure-property-placeholder element automatically identifies the environment (${env}) and accesses the Mule Credentials Vault (test.prod.properties file) for genuine credentials.
```
<secure-property-placeholder:config key="${prod.key}" location="test.${env}.properties"/>
```
The names of the properties used here (for example, the ${prod.key} and test.${env}.properties) are used here as examples, you could use any other property name you choose.
At runtime in the sandbox, no key needs to be provided in the system properties, as test.dev.properties file is not encrypted. The secure-property-placeholder element automatically identifies which properties aren’t encrypted, and returns them in plain text.

Because the developers do not have the prod.key value (that is, the runtime password, which is also the key to access the Credentials Vault), they cannot access the secure Salesforce login credentials in the test.prod.properties file. The only one who knows the prod.key is the Operations Team Lead who deploys the application into production.

When the Ops Team Lead starts the Mule runtime, the lead must provide a value for prod.key for the Credentials Vault (see command below). Mule accepts the prod.key as valid for the duration of the Ops Team Lead’s Mule session. This value is not persisted anywhere on disk, so the prod.key is not available the next time the application is run; instead the prod.key must again be manually entered into memory.

./mule -M-Dprod.key=uniquepassword -M-Denv=prod

Mule Credentials Vault

How It Works

Placeholders, Keys, and Vaults

One-to-One-to-One Relationship

One-to-One-to-Many Relationship

Multiple One-to-One-to-One Relationships

Use Mule Credentials Vault

Encrypt Properties

Studio Visual Editor

XML Editor or Standalone

Set Global Secure Property Placeholder

Studio Visual Editor

XML Editor or Standalone

Configure Mule to Demand the Key

Studio Visual Editor

XML Editor or Standalone

Using a Custom Secure Property Placeholder

Use Case Example

See Also