Enhance credential security

Starting with ACLI 11.0 introduces secure properties to enhance credential security.

Secure properties improve the security of ACLI configuration files by storing sensitive information like passwords in an encrypted format.

How secure properties work

Secure properties use a key-store solution with password-based encryption (PBE). Your credentials are stored securely and cannot be accessed as plain text.

Using secure properties is optional. However, once enabled, ACLI requires the password before running any actions.

You can add secure properties when creating a site connection with the /sites add command in the ACLI Shell.

Appfire Support cannot recover data from secure properties files. If you forget the password to a file, you must manually rename or delete it in your user home directory.

Before secure properties

Previously, ACLI resolved variables in the acli.properties file by searching other property values, Java system properties, and runtime environment variables.

Secure properties add a fourth location for variable resolution, primarily used for values with a variable name containing the secret: prefix such as ${secret:myJiraPassword}.

How to use secure properties

To start using secure properties, follow these steps:

Create a secure properties file: Start by creating a secure properties file.

Reference secrets in the acli.properties file: Incorporate secrets (like passwords) into the acli.properties file.

Unlock the secure properties file.

Create a secure properties file

When you create the secure properties file (named .acli.keystore), this is stored in your home directory. Each ACLI user on a given system has their own secure properties file.

On a multi-user system, you must maintain your own ACLI installation.

Customize the secure properties file path

Use the environment variable ACLI_SECURE_PROPERTIES to change the secure properties file path. This is helpful if you have multiple installations of ACLI or need to work with multiple secure properties files.

When adding a secure property for the first time, ACLI asks for the secret's value to be stored. Then, it asks for a new password for the secure properties file.

To create your secure properties file, use the setSecureProperty action, as in the example below:

$ 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>
Secure properties file created.
Value for key 'foo' set in secure properties file.

The value of the --secret parameter is set to -. This means the value is obtained through an interactive prompt, keeping it secure.

The secure properties file requires a non-blank password.

If your password is ever compromised, you should consider the contents of the secure properties file to also be compromised. Rotate any secrets it contains accordingly.

Reference secrets in the acli.properties file

When the secure properties file is used, it can provide values to acli.properties using substitution variables. These variables are similar to how you refer to environment variables or other properties, using the ${my.variable} syntax.

To refer to secure properties file values, use a syntax such as ${secret:my.secret}. Note the addition of the secret: prefix.

The secure properties file is password-protected. The secret: prefix allows you to access only the secure properties file for secure properties key variables.

To remove this requirement, set the environment variable ACLI_SECURE_PROPERTIES_SAFE_MODE to false.

When disabled, if a variable name isn't found in acli.properties or the environment, the secure properties file is consulted. This might trigger an interactive prompt requesting a password.

Unlock the secure properties file

If a secure properties file exists and acli.properties contains variables using the secret: prefix, you must enter your password to unlock the file each time you run an ACLI command. This includes when you start the ACLI Shell.

Usually, this means ACLI requests your secure properties file password before proceeding (or reads it from stdin if you are not connected to a terminal).

To bypass this prompt, set the environment variable ACLI_SECURE_PROPERTIES_PASSWORD with your password as the value.

Setting your secure properties file password as an environment variable involves reduced security. Storing your secure properties file password as an environment variable could expose your secure properties file to a sophisticated attack. Deciding whether to take this risk is entirely up to you and your organization's threat modeling considerations.