Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.6)
  3. Securing
  4. Anypoint Enterprise Security

  5. Mule Credentials Vault

Mule Credentials Vault

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

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? Use three ingredients:

  1. Mule Credentials Vault

  2. Global Secure Property Placeholder element

  3. 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.

How It Works

Imagine a situation in which a developer is tasked with designing a Mule application for the Human Resources department which 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 the developer must design the Mule application to access the database, yet keep the database login credentials secret.

First, the developer designs the application to process HR end user requests, which includes a call to the secure database. She then creates 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 she adds data to the properties file, Mule gives her the option to encrypt the data. She chooses an encryption algorithm (of the 19 available), then enters 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, the creates a global Secure Property Placeholder element which locates the Credentials Vault (i.e. properties file), then retrieves encrypted properties. However, the Secure Property Placeholder can only access the Credentials Vault (i.e. decrypt the data) if it has the key.

Now she has data in a vault and a mechanism to request the data, but where is the key to unlock the vault (i.e. decrypt the data)? And how does the developer ensure that the key is not accessible by everyone with access to the application? If she were to simply hardcode the key into the configuration of the global Secure Property Placeholder, any colleague with access to the application could simply read the key and unlock the vault. The developer, therefore, configures 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 (i.e. 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 the developer used to encrypt the properties in the Credentials Vault; the developer in this scenario had to have manually given the key to the person who is responsible for running the application, such as an Ops Admin. Whenever a Secure Property Placeholder within the Mule application must unlock the Credentials Vault to retrieve HR database login credentials, it uses the key 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 (i.e. terminates the application), Mule discards the key.

To configure Mule to demand that the user enter a key at runtime, the developer includes 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 one one

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.

one one many

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.

multiple one one

Use Mule Credentials Vault

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

  1. Encrypt properties in a properties file

  2. Create a global secure property placeholder in your Mule application to use the encryption key Mule collects at runtime

  3. 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

  1. In Anypoint Studio, right click the src/main/resources folder, then select New > File.

  2. In the New File wizard, enter a Filename, including the .properties extension. For example, test.properties.

  3. Click Finish. Studio saves the new, blank file in your project and opens a new window in a Properties File Editor window.

    test_properties2

  4. Click the (error) in the .properties tab to close the Properties File Editor window.

  5. In the Package Explorer, right-click the .properties file, then select Open With > Mule Properties Editor.

  6. Click the green (plus) icon in the Studio toolbar (see image below) to open the Add a new property dialog.

    add_new_prop

  7. Add the key-value pair (property) you wish to record in the properties file.

    add_key-value

  8. 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 (i.e. create a Credentials Vault), click the Encrypt button.

  9. 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.
      setup_encryption

  10. Click OK to complete the encryption.

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

    encrypted_value

  12. 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 (i.e. close 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

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

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

    global_secure
Field Req’d Value

Name

x

A unique name for your global secure property placeholder.

Key

x

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.

Encryption Mode

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

XML Editor or Standalone

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

  2. 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

    x

    A unique name for your global secure property placeholder.

    key

    x

    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:

    • CBC

    • CFB

    • ECB

    • OFB

    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’s name/value pair into the Properties tab of the application’s deployment configuration.

Studio Visual Editor

  1. During development time, for testing purposes, you can store these values in the application configuration. In Studio, access the src/main/app folder, then double-click the mule-app.properties file to open it.

  2. Add the following Java system environment properties to this configuration file:

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

  3. Save your changes to the file, then close.

  4. When you start Mule, provide the key to decrypt the properties file.

    ./mule -M-Dprod.key.property=uniquePassword

XML Editor or Standalone

  1. Open your project’s mule-app.properties file.

  2. To this system properties file, add code which instructs Mule to demand that the user enter a key at runtime, and store that key in-memory (see sample code below).

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

  3. Save your changes to the file, then close.

  4. When you start Mule, provide the key to decrypt the properties file.

    ./mule -M-Dprod.key.property=uniquePassword
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 reveal 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.

Although 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’s visible to anyone having access to the process.

A solution for this 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.

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" /> is added to tell this custom secure property placeholder where it should 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, locate the keyfile.properties file 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. At runtime, Mule behavior differs according to environment.

  • At runtime in production, the Mule application demands a key which it uses to unlock the Credentials vault so that the Mule flows in the application can 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"/>

  • At runtime in the sandbox, the Mule application demands no key because the test.dev.properties file is not encrypted. The secure-property-placeholder element automatically identifies the environment (env) and accesses the test.dev.properties file for fake credentials

Because the developers do not have the prod.key value (i.e. 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

See Also