Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.5)
  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. He 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 he adds data to the properties file, Mule gives him the option to encrypt the data. He 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 will unlock 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 he 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 he 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 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 (that is, to 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 will deploy and run 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 will deploy and run 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.
    [TIP] — 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.
    [TIP] — 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

Studio Visual Editor

  1. In Studio, access the src>main>app folder, then double-click the mule-app.properties file to open it.

  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

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

== 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 Mule, Mule demands that he enter the` 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. When he quits the application, Mule forgets the prod.key.

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

== See Also