Secure sensitive data with passwords and encrypted dictionary entries

This topic describes how password properties and encrypted dictionary entries combine to secure sensitive data in XL Deploy.

How it works

In XL Deploy’s type system, any property defined as password="true" is stored in the repository in encrypted form (AES-256) and is displayed as ****** in the GUI. The password="true" setting typically applies to properties called “password”, but you can define any property as secure in this way.

When you first establish a secret value such as a password or an encrypted dictionary entry in the GUI, you can visually validate what you typed or copy-pasted is correct before storing it. To view the value in plain text before you save it, click the “eye” icon to the right of the password field. Once the value is stored in encrypted form in the repository, it is displayed in the GUI as ******.

This behavior is also true if you delete an existing encrypted value and provide a new one. For example, if you have a password field for an Infrastructure CI that displays ****** and you delete it entirely and begin typing another password, you can use the “eye” icon to view it in plain text before saving it.

In the case of secure properties of deployable items (such as the password for a datasource spec or similar piece of configuration) the value is usually not set directly on the deployable, because it varies across target environments.

You can handle a secure property by setting the property on the deployable to a placeholder such as {{my.datasource.password}}. When the deployable is mapped to a specific target environment, XL Deploy resolves the placeholder using dictionaries that are linked to the environment. XL Deploy selects the first value that it finds for the my.datasource.password key.

In XL Deploy, a dictionary can contain:

  • “Regular” key/value pairs that are intended to store non-sensitive values
  • Encrypted key/value pairs that are intended to store sensitive data such as passwords

In a regular dictionary entry, the key and value are both stored in plain text and are visible anyone with read access to the dictionary configuration item.

In an encrypted dictionary entry, the key is treated as plain text, but the value is treated in the same way as password="true" properties: it is hidden in the UI and stored in encrypted form in the repository.

Common questions

This section describes some common questions you may have when working with password properties and encrypted dictionary entries.

How do properties and dictionaries work together?

There are four possible combinations of properties and dictionary entries. The following scenario examines what happens in each case. Assume that you have:

  • A deployable with two properties:

    • A normal property called username
    • A password property called password
  • Two entries in a dictionary:

    • The regular entry my.username = scott
    • The encrypted entry my.password = tiger

Normal property, regular dictionary entry

The deployable contains username = {{my.username}}. XL Deploy resolves this property, resulting in username = scott on the corresponding item to be deployed.

Secret property, encrypted dictionary entry

The deployable contains password = {{my.password}}. XL Deploy resolves this property, resulting in password = tiger. In the GUI, the value is displayed in encrypted form, so the user only sees password = *****.

Secret property, regular dictionary entry

The deployable contains password = {{my.username}}. XL Deploy resolves this property to password = scott, which is not a security problem (tiger was already a visible value because it is stored in a regular dictionary entry). However, it will fail, because the password is incorrect.

Normal property, encrypted dictionary entry

The deployable contains username = {{my.password}}. XL Deploy will not resolve this property, because that would expose the password. Instead, it will leave the username value blank. If username is a required property, this will cause an immediate validation error when XL Deploy attempts to generate the deployment plan.

Why don’t the values that I entered in an encrypted dictionary entry appear in normal properties?

As described above, XL Deploy will not resolve a normal property that is set to a placeholder stored in an encrypted dictionary entry. This protects the value of the placeholder, so it is not visible if someone attempts to reference them in a normal property of a deployable (accidentally or otherwise).

How can I prevent users from storing sensitive data where they shouldn’t?

XL Deploy cannot determine which key in a dictionary should have a secret value. Therefore, there is no default validation that attempts to prevent users from entering a value that should be secure into a regular dictionary; for example, entering my.password as a regular entry instead of an encrypted entry.

If there is a convention that you can follow in your organization—for example, all keys that contain “password” should have secret values and should not be stored in regular entries—then you can define a validation rule on regular dictionary entries to enforce this convention.

It is highly recommended that you set up roles and permissions in XL Deploy so that all dictionaries—regular and encrypted—can only be viewed by the relevant people and teams. This means that, even if you accidentally store a value that should be secret in a regular dictionary, the number of users who could see the value is limited.