Secure Configuration Properties | MuleSoft Documentation
# 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  
---|---  
A unique name for your global secure configuration properties.  
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.  
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.  
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.
Note that the syntax has changed from earlier versions. To avoid issues, use the syntax and the JAR file provided in this article. Also, the tool doesn’t support the hash character `#` in the input text.git st
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  
---|---  
Sets the encryption or decryption method. Accepted values are: |  Encrypts a single text string provided as parameter `<value>`.  
---  
Encrypts the value of each property set in the properties file provided as parameter `<input file>`.  
Encrypts all the content of the properties file provided as parameter `<input file>`.  
Sets the operation to perform. Accepted values are: |  Sets the operation to encryption.  
---  
Sets the operation to decryption.  
Specifies the algorithm to use during the operation. See Supported Algorithms for a complete list.  
Specifies the mode to use during the operation. See Supported Modes for a full list.  
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).
### Parameters Reference
Parameter | Description  
---|---  
Sets the encryption or decryption method. Accepted values are: |  Encrypts a single text string provided as parameter `<value>`.  
---  
Encrypts the value of each property set in the properties file provided as parameter `<input file>`.  
Encrypts all the content of the properties file provided as parameter `<input file>`.  
Sets the operation to perform. Accepted values are: |  Sets the operation to encryption.  
---  
Sets the operation to decryption.  
Specifies the algorithm to use during the operation. See Supported Algorithms for a complete list.  
Specifies the mode to use during the operation. See Supported Modes for a full list.  
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).

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


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:
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** :
## 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>
```
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
  * DESede


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
  * Serpent
  * Skipjack
  * Twofish


### Supported Modes
  * CBC (default)


## 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
  * Configuring Properties
  * Define and Secure Properties for a Mule Application in Anypoint Code Builder