--- title: "How to use Secure Properties" canonical: "https://support.appfire.com/space/SUPPORT/349962465/How%20to%20use%20Secure%20Properties" format: markdown --- ## 🤔 Description To ensure a higher level of credential security that may be required in specific industries, ACLI 11.0 introduces the Secure Properties functionality. Secure Properties augments the `acli.properties` file, mitigating any breach of security that could occur if the ACLI configuration files were to escape your system. ## 🌱 Solution The Secure Properties in ACLI 11.0 provides a key-store-based credential storage solution using password based encryption (PBE). The specific key store format is the UBER format, provided by the excellent [Bouncy Castle](https://www.bouncycastle.org/java.html) cryptography library for Java. The Secure Properties key store can store any value, while it prevents sensitive credentials from being stored as plain text on disk. > ℹ️ The use of Secure Properties is *optional*. > ℹ️ > ℹ️ Once you have configured the use of Secure Properties, ACLI will require the password before executing any actions. The password can be [provided](https://appfire.atlassian.net/wiki/spaces/SUPPORT/pages/349962465/How+to+use+Secure+Properties#Unlocking-the-key-store) interactively each time ACLI is run, or via an environment variable. > 📝 The ACLI Shell can create Secure Properties entries as part of its guided site configuration functionality, which can be launched using the slash-command, `/sites add`. > ⚠️ If you forget the password to a Secure Properties key store, the only solution is to manually rename or delete the file (we recommend renaming if there’s any hope you will later remember the password). > ⚠️ > ⚠️ The key store file is named `.acli.keystore` and can be found in your user home directory. > ⚠️ > ⚠️ *Appfire support cannot recover data stored in these files if you forget your password!* ## Working with Secure Properties Secure Properties adds actions for creating, updating, reading, and deleting values in an encrypted key store. This key store can then act as a source of variable values that can be referenced in `acli.properties`. Prior to the introduction of secure properties, resolution of variables in the `acli.properties` configuration file included a search of these locations: 1. other properties defined in `acli.properties` 2. Java system properties 3. runtime environment variables The Secure Properties key store adds a 4th location from which variables may be resolved. By default, this location is only consulted for values if the variable name contains the `secret:` prefix. Using Secure Properties consists of three main steps: - [Creating a key store](https://appfire.atlassian.net/wiki/spaces/SUPPORT/pages/349962465/How+to+use+Secure+Properties#Creating-a-key-store) - [Referencing secrets in the acli.properties file](https://appfire.atlassian.net/wiki/spaces/SUPPORT/pages/349962465/How+to+use+Secure+Properties#Referencing-secrets-in-acli.properties) - [Unlocking the key store](https://appfire.atlassian.net/wiki/spaces/SUPPORT/pages/349962465/How+to+use+Secure+Properties#Unlocking-the-key-store) ### Creating a key store When you create the key store file (named `.acli.keystore`), it can be found in your home directory. Each ACLI user on a given system has their own such file. Note that on a multi-user system, each user is required to maintain their own ACLI installation. The key store file path can be overridden to point to an alternative location through the use of the environment variable `ACLI_SECURE_PROPERTIES`. This can be useful if you need to work with multiple key stores or multiple installations of ACLI. When a secure property is first added, ACLI: 1. First prompts for the value of the secret to be stored. 2. Prompts for the new key store file password (with confirmation). To create your key store, run the action `setSecureProperty`, as shown in the example: ```none $ acli system setSecureProperty --name my.secret --secret - Enter secure value: Secure properties file does not yet exist. Creating... Enter new secure properties password: Confirm secure properties password: Secure properties file created. Value for key 'foo' set in secure properties file. ``` > 📝 The value for the `--secret` parameter, provided in the example, is `-` The value set to `-` indicates that the value should be obtained via an interactive prompt (or read from `stdin` if not connected to a tty). > 📝 > 📝 We strongly recommend that you use this method to provide sensitive values to avoid them being accidentally recorded in your shell history, where they could end up existing in plain text anyway! > ⚠️ The key store requires a non-blank password. Once created, do not forget the password! > ⚠️ > ⚠️ *Key store passwords cannot be recovered by ACLI support.* > ⚠️ > ⚠️ If your password is ever compromised, you should consider the contents of the key store to also be compromised and rotate any secrets it contains accordingly. ### Referencing secrets in `acli.properties` When in use, the key store file can be used to provide values to `acli.properties`by way of substitution variables similar to the current method of referring to environment variables or other properties (i.e., using `${my.variable}` syntax). The syntax for referring to key store values is a variation of the syntax of the form `${secret:my.secret}` (note the addition of the `secret:` prefix). > 📝 Because the key store is password-protected, the `secret:` prefix allows you to only consult the key store for the Secure Properties key variables. To disable this requirement, set the environment variable `ACLI_SECURE_PROPERTIES_SAFE_MODE=false`. > 📝 > 📝 When disabled, the key store is consulted for variable names that are not found in the `acli.properties` file or the environment, this may result in an interactive prompt requesting to supply a password! ### Unlocking the key store When the ACLI configuration refers to secure property values (i.e., using `${secret:...}` style variables in `acli.properties`), each time that you run an ACLI command (including starting the ACLI Shell), you are prompted to unlock the key store. Normally, this means that ACLI prompts you for your key store password before it continues (or reads it from `stdin` when not connected to a tty). To short-circuit the prompting behavior, set the environment variable `ACLI_SECURE_PROPERTIES_PASSWORD` with your password as a value. > ⚠️ Setting your key store password as an environment variable may or may not be appropriate, depending on your risk tolerance. Doing so is a convenience that comes at a cost of reduced security. > ⚠️ > ⚠️ **Advantage**: > ⚠️ If your key store file escapes your system, it is strongly encrypted. > ⚠️ > ⚠️ **Disadvantage**: > ⚠️ Storing your key store password as an environment variable may allow a sophisticated attack to compromise your key store. > ⚠️ > ⚠️ Whether you decide this is an acceptable risk is entirely at your discretion, and depends on considerations on the threat modeling that you and your organization use. > ⚠️ > ⚠️ *Use this method at your own risk.* ### Actions Use ACLI actions, part of the ACLI `system` client, to create, update, read, and delete key-value pairs stored in the Secure Properties key store. To use a secure property in `acli.properties`, follow the example as illustrated here: ```none my-jira = jiracloud -s https://myjira.atlassian.net -u me@example.com -t ${secret:my-jira.token} ``` The **Actions and Examples** table shows how you can work with the secure properties and provides examples. | **Actions and Examples** | | --- | | #### `setSecureProperty`
This action sets or overwrites a secure property in the key store. If a property name already exists, you are prompted to confirm that you wish to overwrite the value. Use `--replace` to skip the confirmation prompt.
**Example: Set Secure Property**
``` $ acli system -a setSecureProperty --name my-jira.token --secret Enter secure properties password: Value for key 'my-jira.token' set in secure properties file. ``` | #### `clearSecureProperties`
This action clears the entire secure properties key store file. To ensure that a value is not accidentally removed, you are prompted for confirmation. If you add the `--force` parameter, the secure property file is removed without confirmation. To complete the action, you are prompted to insert the key store password.
> ⚠️ If you have forgotten the password, you must manually rename or delete the key store file (named `.acli.keystore`) in your home directory. > ⚠️ > ⚠️ We recommend *renaming* the file (rather than deleting it) if there’s any chance you might later remember the password and still need the contents of the file.
**Example: Clear all Secure Properties**
```none $ acli system -a clearSecureProperties Enter secure properties password: Enter CONFIRM to permanently clear all secure properties (CANNOT be undone): CONFIRM Secure properties cleared. ``` | | #### `getSecureProperty`
This action retrieves a secure property from the key store. By default, it only indicates whether the named entry exists in the key store. To retrieve the property value as well, use: `--outputFormat 2`.
**Example: Get Secure Property**
```none $ acli system -a getSecureProperty --name foo Enter secure properties password: Secure property 'foo' exists in the secure properties file. ```
**Example: Get Secure Property with value**
```none $ acli system -a getSecureProperty --name foo --outputFormat 2 Enter secure properties password: Value of secure property 'foo': bar ``` | #### `importSecureProperties`
This action allows you to import secure properties from another key store file to your default key store. To do so, you need the password for both the source and destination key stores. **OPTIONS**
- Use the `--replace` parameter to avoid being asked to confirm overwriting properties during import. - Use the `--include` and `--exclude` parameters to filter the properties being imported.
Note that each of the imported properties, take a regular expression value that is evaluated against the list of keys in the source key store.
> ⚠️ This can be useful for sharing selected secure properties, just ensure to not store or transmit the key store password with the key store file!
The following examples assume that both `.acli.keystore` and `import.keystore` contain entries for the keys `foo` and `bar`.
**Example: Import Secure Properties**
```none $ acli system -a importSecureProperties -f import.keystore Enter secure properties password: Enter inbound secure properties password: Imported 0 secure properties. Ignored: buz,foo. Use --replace to overwrite existing values. ```
**Example: Import select Secure Properties (via inclusion) with replacement**
```none $ acli system -a importSecureProperties -f import.keystore --include '(?i)^F' --replace Enter secure properties password: Enter inbound secure properties password: Imported 1 secure property: foo. ``` | | #### `removeSecureProperty`
This action removes a secure property from the key store. To ensure that a value is not accidentally removed, you are prompted for confirmation.
If you add the `--force` parameter, the secure property is removed without confirmation.
If after this operation the key store is empty, it is automatically removed.
**Example: Remove a Secure Property**
```none $ acli system -a removeSecureProperty --name my-jira.token Enter secure properties password: Enter CONFIRM to permanently remove the secure property 'my-jira.token': CONFIRM Removed value for key 'my-jira.token' from secure properties file. ```
**Example: Force remove a Secure Property (with deletion of empty key store)**
``` $ acli system -a removeSecureProperty --name my-jira.token --force Enter secure properties password: Removed value for key 'my-jira.token' from secure properties file. Deleted empty keystore file. ``` | #### `exportSecureProperties`
This action allows you to export secure properties from your default key store to another key store file. To do so, you need the password for both the source and destination key stores.
**OPTIONS**
- Use the `--replace` parameter to avoid being asked to confirm overwriting properties during export. - Use the `--include` and `--exclude` parameters to filter the properties being exported.
Note that each of the exported properties, take a regular expression value that is evaluated against the list of keys in the source key store.
The following examples assumes that both `.acli.keystore` and `import.keystore` contain entries for the keys `foo` and `bar`.
**Example: Export select Secure Properties (via exclusion) with replacement**
```none $ acli system -a exportSecureProperties -f export.keystore --exclude '(?i)^F' --replace Enter secure properties password: Enter outbound secure properties password: Exported 1 secure property: buz. ``` | | #### `getSecurePropertyList`
This action returns all secure properties from the key store. To retrieve the list of property values as well, use: `--outputFormat 2`.
**Example: Get Secure Property list**
```none $ acli system -a getSecurePropertyList Enter secure properties password: 2 secure properties in list "Name" "buz" "foo" ```
**Example: Get Secure Property list with values**
```none $ acli system -a getSecurePropertyList --outputFormat 2 Enter secure properties password: 2 secure properties in list "Name","Value" "buz","qux" "foo","bar" ``` | **Locating your Secure Properties key store**
Your key store is normally located in your home directory and is named `.acli.keystore`. ACLI displays the file path as part of the detailed `getClientInfo` output (if it exists).
**Example: Display key store file path**
``` $ acli -a getClientInfo --outputFormat 2 Enter secure properties password: Client information Client name . . . . . . . . . : cli Client version . . . . . . . : 11.0.0 ... Secure properties . . . . . . : File . . . . . . . . . . . : /Users/me/.acli.keystore ``` |