...
🤔 Description
To ensure a higher level of credential security that may be required in specific industries, ACLI 11.0 .0 with the intent of helping to better secure the credentials required to access the products and systems on which ACLI actions operate.
🤔 Problem
ACLI loads the necessary system credentials it needs to do its work from configuration found in acli.properties. These credentials have historically been stored either directly in this file as plain text, or indirectly provided to the configuration by environment variable references. While indirection via the environment can help protect credentials, better solutions exist.
Despite the fact that ACLI sets restrictive file permissions on the acli.properties configuration file (since version 10.6.0), some customers want a higher level of credential security than this can provide since escape of the configuration file could result in direct compromise of the credentials it contains.
🌱 Solution
ACLI 11.0.0 introduces a new feature known as Secure Properties that 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 utilized is the UBER format, provided by the excellent Bouncy Castle provided UBER format. The use of secure properties is optional!The intent of the secure properties key store is to protect 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, but it can store any values you wish.
Creating a key store
A new key store is created when the action setSecureProperty is run for the first time. For .
| Info |
|---|
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 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.
| Note |
|---|
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 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:
other properties defined in
acli.propertiesJava system properties
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
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:
First prompts for the value of the secret to be stored.
Prompts for the new key store file password (with confirmation).
To create your key store, run the action setSecureProperty, as shown in the example:
| Code Block | ||
|---|---|---|
| ||
$ acli system setSecureProperty --name my.secret --secret - Enter secure value: <secret value prompt> Secure properties file does not yet exist. Creating... Enter new secure properties password: <new password prompt> Confirm secure properties password: <new password prompt> Remember your password, it cannot be recovered! Secure properties file created. Value for key 'foo' set in secure properties file. |
The value for the --secret parameter, provided in this the example is provided as - which , is - The value set to - indicates that the value should be obtain obtained via an interactive prompt (or read from stdin if not connected to a tty).
We strongly recommend providing sensitive values this way so that they are not that you use this method to provide sensitive values to avoid them being accidentally recorded in your shell history, where they would could end up existing in plain text anyway!
...
| Note |
|---|
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 |
...
Once created, the key store file (named .acli.keystore) can be found in your home directory. Each ACLI user on a given system has their own such file (because of other ACLI limitations, it is still necessary on a multi-user system for each user 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
. |
Referencing secrets in acli.properties
When in use, the key store file can be used to provide values to acli.propertiesby way of substitution variables similar to the current method of referring to environment variables or other properties (i.e., using ${my.variable} syntax). In ACLI 11.0.0, the default
The syntax for referring to key store values is with a variation of that the syntax of the form ${secret:my.secret} (note the addition of the secret: prefix).
Because the key store is password-protected, we require the secret: prefix in order allows you to only consult the key store only when necessary. This requirement can be disabled by setting 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 will be is consulted for any variable names that are not found in the acli.properties itself file or the environment, but this may result in an interactive prompt requesting to supply a password!
Unlocking the key store
Once your When the ACLI configuration refers to secure property values (i.e., using ${secret:...} style variables in acli.properties) then you will be prompted to unlock the key store , 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 will prompt prompts you interactively for your key store password before it continues (or read reads it from stdin when not connected to a tty). At your discretion, you may optionally To short-circuit this the prompting behavior by setting , set the environment variable ACLI_SECURE_PROPERTIES_PASSWORD with your password as a value.
| Note |
|---|
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 , but one that comes at a cost of reduced security. You still have the advantage that if Advantage: Disadvantage: Whether you decide this is an acceptable risk is entirely at your discretion, and depends on considerations on the threat modeling under consideration by that you and your organization use. Use this method at your own risk. |
Actions
Use ACLI actions can be used , part of the ACLI system client, to create, update, read, and delete key-value pairs stored in the secure properties Secure Properties key store. These actions are all part of the ACLI system client:
To use a secure property in acli.properties, follow the example as illustrated here:
| Code Block | ||||
|---|---|---|---|---|
| ||||
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 | |
|---|---|
| |
...
are prompted to confirm that you wish to overwrite the value. Use |
getSecureProperty
This action will get a secure property from the key store. By default it will only report whether or not the property was found in the key store. To also return the value, use --outputFormat 2.
removeSecureProperty
...
Example: Set Secure Property
|
|
...
accidentally removed |
...
, you |
...
are prompted for confirmation |
...
. If you |
...
add the
|
...
getSecurePropertyList
...
Example: Clear all Secure Properties
| ||||||
|
...
only indicates whether the named entry exists in the key store. To retrieve the property value as well, use: |
...
clearSecureProperties
This action clears the entire secure properties key store file. In order to ensure you don’t casually destroy the file, you will be prompted for confirmation unless you also add the --force parameter.
...
Example: Get Secure Property
Example: Get Secure Property with value
|
|
...
To do so, you need the password for both the source and destination key stores. |
...
|
...
|
...
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.
|
...
|
...
|
...
exportSecureProperties
...
|
...
Examples
Set a secure property
The following examples assume that both Example: Import Secure Properties
|
...
|
...
|
...
|
...
|
...
|
...
Get a secure property
| Code Block | ||
|---|---|---|
| ||
$ acli system -a getSecureProperty --name my-jira.token
Enter secure properties password: <password prompt>
Secure property 'foo' exists in the secure properties file. |
...
Example: Import select Secure Properties (via inclusion) with replacement
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
Get secure property list with values
| Code Block | ||
|---|---|---|
| ||
$ acli system -a getSecurePropertyList --outputFormat 2
Enter secure properties password:
2 secure properties in list
"Name","Value"
"buz","qux"
"foo","foo" |
Use a secure property in acli.properties
| Code Block | ||
|---|---|---|
| ||
my-jira = jiracloud -s https://myjira.atlassian.net -u me@example.com -t ${secret:my-jira.token} |
...
| |||||
|
| Code Block | ||
|---|---|---|
| ||
$ acli system -a removeSecureProperty --name my-jira.token
Enter secure properties password: <password prompt>
Enter CONFIRM to permanently remove the secure property 'my-jira.token': CONFIRM
Removed value for key 'my-jira.token' from secure properties file. |
...
Clear all secure properties
...
| language | none |
|---|
Example: Force remove a Secure Property (with deletion of empty key store)
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
Import secure properties
|
|
| Code Block | ||
|---|---|---|
| ||
$ acli system -a |
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
| |||||
|
| Code Block | ||
|---|---|---|
| ||
$ acli system -a |
...
|
...
|
...
|
...
|
...
|
...
|
...
Example: Get Secure Property list with values
|
...
| Locating your Secure Properties key store Your key store is normally located in your home directory and is named Example: Display key store file path
|
...
|