--- schema_version: "1" id: 56b93b05091df1675df6d19721853e6f786e360438f95a3be18692598bebc784 title: Secure Configuration Properties collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-runtime/4.4/secure-configuration-properties.md canonical_url: https://docs.mulesoft.com/mule-runtime/4.4/secure-configuration-properties source_site: docs.mulesoft.com content_type: documentation content_hash: eec656c0b4cba8862721cbb7f54b31f7ca1cdf1f6e080cee8310a65e40bce010 description: MuleSoft Documentation Site release: "4.4" latest: false --- --- product: Mule Runtime version: 4.4 --- # Secure Configuration Properties > For the full documentation index, see: https://docs.mulesoft.com/llms.txt 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 NameDescription

Name

A unique name for your global secure configuration properties.

Key

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.

File

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 NameDescription

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 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. > [!CAUTION] 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" > [!NOTE] 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. Download link: [Secure Properties Tool Jar file](https://docs.mulesoft.com/mule-runtime/4.4/_attachments/secure-properties-tool.jar). Latest release: 09/14/2022. Note that the syntax has changed from earlier versions. To avoid issues, use the syntax and the JAR file provided in this article. See [Parameters Reference](#parameter-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: ```console.linenums java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \ \ \ \ \ \ \ --use-random-iv [optional] ``` - Set `` 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: ```console.linenums java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \ string \ encrypt \ Blowfish \ CBC \ mulesoft \ "some value to encrypt" ``` The tool returns: ```console.linenums 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: ```console.linenums java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \ \ \ \ \ \ \ \ --use-random-iv [optional] ``` - Set `` to `file`. - Set `` to the properties file to process. - Set `` 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: ```yaml properties: example1: value: "Muleman is here" example2: "Max the mule" ``` If you run: ```console.linenums 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: ```yaml 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: ```console.linenums java -cp secure-properties-tool.jar com.mulesoft.tools.SecurePropertiesTool \ \ \ \ \ \ \ --use-random-iv [optional] ``` - Set `` to `file-level`. - Set `` to the properties file to process. - Set `` 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: ```yaml properties: example1: value: "Muleman is here" example2: "Max the mule" ``` If you run: ```console.linenums 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: ```txt k/J1EHyxJagOcyQELoaqIDCzzKc1bLGJiHY2dv6jzuhtVpP1LTlgK3y8EH7OkK5iuuu8kik3P5dCDMixZXwn/EV6xbUwLFKnEb4x1pUX6aopLP/KULm0pQ== ``` ### Parameters Reference
ParameterDescription

<method>

Sets the encryption or decryption method. Accepted values are:

string

Encrypts a single text string provided as parameter <value>.

file

Encrypts the value of each property set in the properties file provided as parameter <input file>.

file-level

Encrypts all the content of the properties file provided as parameter <input file>.

<operation>

Sets the operation to perform. Accepted values are:

encrypt

Sets the operation to encryption.

decrypt

Sets the operation to decryption.

<algorithm>

Specifies the algorithm to use during the operation.
See Supported Algorithms for a complete list.

<mode>

Specifies the mode to use during the operation.
See Supported Modes for a full list.

<key>

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 8 Update 161 (JRE 1.8.0_161), the Unlimited Strength Jurisdiction Policy is enabled by default. This allows the use of AES-256 (32-byte keys) without additional JVM configuration. Ensure your key length (16, 24, or 32 bytes which typically equates to the same number of standard text characters) exactly matches the requirements of your chosen encryption algorithm (AES-128, AES-192, or AES-256 respectively).

<value>

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](https://anypoint.mulesoft.com/exchange/com.mulesoft.modules/mule-secure-configuration-property-module/). ### Configure the File with the Extension Module in XML In your XML flow, use the module `` to configure the file. Review the following example: **Secure Configuration Properties with Default Values** ```xml ``` - The `` tag is required even when using the default values. - The prefix `secure::` is required for loading the key. > [!NOTE] 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 `` tag: **Secure Configuration Properties with Custom Values** ```xml ``` In the previous example, the `` tag uses the `AES` algorithm with `CBC` mode and `random IV`. > [!NOTE] The `key`, `algorithm`, `mode` and `useRandomIVs` values set in > `` 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**. ![config extension](/mulesoft/current/en-us/mule-runtime/4.4/_images/mruntime-secure-config-properties-studio.png) > [!NOTE] 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: ![config extension2](/mulesoft/current/en-us/mule-runtime/4.4/_images/mruntime-secure-config-properties-studio2.png) 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`: ```xml ``` In Studio, in Secure Configuration Properties window, select **True** for the **File level encryption**: ![config extension3](/mulesoft/current/en-us/mule-runtime/4.4/_images/mruntime-secure-config-properties-studio3.png) ## 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. ```xml ``` The following example shows how a flow uses a nonencrypted value from the same secure properties file: ```xml ``` ### 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** ```xml ``` 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** ```xml ``` 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 `` 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: ```xml ``` ## Supported Configuration File Types - Spring-formatted properties: `.properties` - YAML: `.yaml` ## Supported Algorithms and Modes ### Supported Algorithms - AES (default) - Blowfish - DES - DESede - RC2 - RCA The following algorithms can be used only if you configure a [Java Cryptography Extension (JCE) Provider](https://docs.oracle.com/cd/E19830-01/819-4712/ablsc/index.html) that adds support for them: - Camellia - CAST5 - CAST6 - Noekeon - Rijndael - SEED - Serpent - Skipjack - TEA - Twofish - XTEA - RC5 - RC6 ### Supported Modes - CBC (default) - CFB - ECB - OFB ## 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](https://docs.mulesoft.com/mule-runtime/4.4/configuring-properties) - [Define and Secure Properties for a Mule Application in Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/int-create-secure-configs)