Secrets Management and Encryption
Provar needs to access various passwords and other secrets so that it can connect to the systems to be tested.
This document provides an overview of how Provar manages these secrets and how you can use Provar’s encryption features.
Use the following links to navigate to the relevant section:
- Secret Types
- Test Environments
- Secrets Password Entry in Desktop
- Secrets Password Entry under ANT
Provar honors the following principles with regard to passwords and secrets:
- Provar never exposes secrets in clear text in its UI or log files.
- Provar never transmits secrets in clear text over networks. This includes “localhost” connections.
- Provar does not rely on encryption keys that are built into the software (as these can be extracted by reverse compilation). These are always used in combination with a user-supplied secrets password that is used to “salt” the encryption. See this Wikipedia entry for additional information on encryption salting.
- Secrets passwords are never stored by Provar but instead supplied by the user when required.
Provar needs to store various secrets depending on the type of connection:
- Passwords are required for Salesforce, secured websites, Email and Database connections.
- Security Tokens and Client Secrets are required for certain types of Salesforce connection.
User account passwords are required to connect to third-party browser and mobile device hosting services such as Perfecto Mobile and SauceLabs.
Test Environments allow you to specify alternate details for connections in Provar:
- The “<default>” Test Environment is built into the tool.
- Additional Test Environments can be defined in the Test Settings view.
When a new connection is created, details are always supplied for the “<default>” Test Environment. Alternate details can then be supplied for specific Test Environments, if desired.
For example, a “SalesUser” connection can be defined that:
- Connects using “UatSalesUser / password1” for the “<default>” Test Environment
- Connects using “ProdSalesUser / password2” for the “PROD” Test Environment.
At runtime, Provar uses any specific connection details for the active Test Environment, failing which the “<default>” connection details are used.
Provar stores all secrets in centralized “.secrets” files. These are stored at the root of the Test Project and can either be encrypted or in plain text.
The main “.secrets” file contains all secrets for the “<default>” Test Environment and also the secrets for Test Environments that do not have their own encryption passwords.
Where Test Environments have been encrypted with their own passwords, their secrets are stored in a separate “.secrets” file.
External Secrets Management
Some customers would prefer not to store their “.secrets” files in their Source Control Repositories (e.g. GitHub).
To accommodate this, Provar’s ANT task allows secrets to be supplied via specially named environment variables. This allows the secrets to be managed outside of Provar, for example, by the password plugin for Jenkins.
Test Project vs. Test Environment encryption
Provar allows secrets to be encrypted for entire Test Projects and also for individual Test Environments. This allows a PROD Test Environment, for example, to have its own secrets password that is only known to selected Provar users.
These approaches can be mixed and matched as follows:
- All secrets can be unencrypted. This is the default state for newly created Test Projects.
- The main “.secrets” file can be unencrypted and selected Test Environments encrypted with their own secrets passwords.
- The main “.secrets” file can be encrypted with the “main” secrets password and selected Test Environments encrypted with their own secrets passwords.
The encryption is done via the Jasypt open-source library using the user-supplied secrets password as the “encryption salt”:
- If the Test Project is encrypted then all secrets for the “<default>”. Test Environment are encrypted in the main “.secrets” file together with the secrets for any unencrypted Test Environments.
- If a Test Environment is encrypted then its secrets are encrypted in a separate “<environmentName>.secrets” file.
Secrets Password Requirements
Secrets passwords need to meet the following requirements:
- Must be at least 8 characters long
- Must contain an uppercase character
- Must contain a lowercase character
- Must contain a numeric character
- May contain special characters.
Newly created (and pre-existing) Test Projects are not encrypted by default:
- The “Encrypt Secrets” context menu item against the Test Project’s entry in the Navigator view allows the Test Project to be encrypted.
- After successfully Encrypt .secrets file looks like this with encrypted format.
- The “Encrypt” context menu item against Test Environments in the Test Settings view allows individual Test Environments to be encrypted.
- An entry will be created under test project file with the name of ‘testenvironment.secrets’
Once encrypted, the following context menus are available against the Test Project’s entry in the Navigator view and Test Environments in the Test Settings view:
- Change Secrets Password
Change Secrets Password allows the secrets to be re-encrypted with a new password.
Change Secrets Password requires the existing password to be entered, as below:
- Unencrypt Secrets
For Test Environments, Unencrypt Secrets moves the secrets into the main “.secrets” file. For the main “.secrets” file, it decrypts the secrets and stores the “.secrets” file as plain text.
Unencrypt Secrets requires the existing password to be entered, as below:
Note that the .Secrets file comes in original format (un-encrypted format) with all the values except if there is any test environment encrypted value present.
Reset Secrets Encryption
For Test Environments, Reset Secrets Encryption moves all the secrets into the main “.secrets” file and sets them to empty values. For Test Projects, it removes the encryption and sets all secrets to empty values.
The existing password is not required for Reset Secrets Encryption:
Secrets Password Entry in Desktop
When a Test Project is opened in Provar desktop:
- The user is prompted for the main secrets password if the Test Project is encrypted. Provar shuts down if no valid password is supplied after 3 attempts.
- If the pre-selected Test Environment (in Provar’s Settings Toolbar) is encrypted, the user is then prompted for the Test Environment’s secrets password. The “<default>” Test Environment is automatically selected after 3 unsuccessful attempts.
Switching to encrypted Test Environments
The user is subsequently prompted for Test Environment passwords if:
- They select an encrypted Test Environment in the Settings Toolbar. The “<default>” Test Environment is automatically selected after 3 unsuccessful attempts.
- They attempt to edit the alternate connection details for an encrypted Test Environment. The edit dialog does not open after 3 unsuccessful attempts.
- When they change the Test Environment on for an alternate connection to an encrypted one.
Invalid Password attempts
Provar shuts down if the main secrets password is not supplied within 3 attempts.
- Provar automatically switches to the “<default>” Test Environment if the password for an encrypted Test Environment is not supplied within 3 attempts.
- Provar does not allow alternate connection details to be modified if the password for an encrypted Test Environment is not supplied within 3 attempts.
- Provar prevents the Test Environment for alternate connection details being modified if the password for an encrypted Test Environment is not supplied within 3 attempts.
- Because Provar has no reliable way of storing invalid password attempt counters, these counters are reset when Test Projects are re-opened.
- The number of unsuccessful password attempts is tracked independently for each Test Environment until the Test Project is reopened.
Secrets Password Entry under ANT
Main secrets password
The main secrets password can be supplied in two different ways when Provar is run via ANT:
- Via the “secretsPassword” property of the TestRunner task.
- Via the “ProvarSecretsPassword” environment variable.
Test Environment secrets passwords
The secrets passwords for Test Environments can be supplied:
- Via the “testEnvironmentSecretsPassword” property of the TestRunner task.
- Via the “ProvarSecretsPassword.” environment variable.
Invalid Password processing
Provar validates the main and Test Environment passwords when the ANT task starts. If either password is invalid then:
- No tests are run
- An error outcome is returned.