Encrypted Configuration

Parts of the configuration are considered extra sensitive. When dumping the configuration to file, using version control systems to manage versions of the configuration or viewing the configuration using any interface it’s often desired to be able to lock certain parts.

The crypto subtree under /processing/crypto is therefore encrypted. By default it uses a known key by the system, but in production systems this should be replaced with a production key instead.

It is possible to setup different keys for different environments and using command line arguments when starting Curity to re-encrypt the data using new keys.

Important

When enabling encryption of the config it is not possible to retrieve the encrypted values if the key is lost.

Setup Encryption

In a default installation of Curity the encryption key is not set. This means that the sensitive parts of the data are encrypted using a default key, and should be considered non-encrypted.

Defining a key during installation

The first approach is to define a key when installing Curity. The installer.sh will ask if the configuration should be encrypted:

Listing 324 installer.sh
...
Would you like to protect sensitive parts of the configuration with a unique encryption key? [y/N]
y

If you have an existing encryption key you want to use, paste it here (may be a comma separated list of keys); press enter to generate a new key

If you answer y to the question about encryption you are prompted with a second question where two options are available:

  1. Leave blank (hit enter) and a new key will ge generated for you.
  2. Enter a plaintext key that should be used to encrypt the data.

The key will be placed in <IDSVR_HOME>/etc/startup.properties after the installer is done:

Listing 325 startup.properties
# Required: false
CONFIG_ENCRYPTION_KEY="02b891b3ec501cece86de216a6f6a15f585dddcbd56fe21b410233d78dfaa79e"

It can be removed from this file and placed on the command line when starting Curity. See Defining Encryption Key on Startup.

Tip

The encryption key can be removed from startup.properties and given as a command line argument or an environment variable (by the same name) when starting Curity

Whenever configuration is added using REST, CLI or the Admin UI it will be encrypted using the new encryption key.

Defining Encryption Key on Startup

Instead of giving the configuration key as a property in startup.properties it’s also possible to provide it directly on the command line. When doing so, the entry in startup.properties is ignored.

Listing 326 Providing key as startup argument
$ idsvr --config-encryption-key 02b891b3ec501cece86de216a6f6a15f585dddcbd56fe21b410233d78dfaa79e

It’s also possible to provide multiple keys comma separated. The first key is used as the encryption key and primary decryption key, and all consecutive keys are used as decryption keys. This is handy when rotating keys or when migrating config between environments.

Listing 327 Providing multiple keys as startup arguments (abbreviated for readability)
$ idsvr --config-encryption-key 02b891b3ec501cece86d,42b391bgecgg01cece

Change Encryption Key

When it’s time to move to a production configuration, or when rotating keys, the bin/reenc tool can be used to re-encrypt the configuration.

../_images/re-encrypt.png

Fig. 200 Re-encrypting configuration

Listing 328 Re-encrypting using reenc
$ ./bin/reenc config.xml NEW_KEY OLD_KEY1,OLD_KEY2 > new-config.xml

In the same way, multiple “old” description keys can be given comma separated. The first argument is the current configuration, the second argument is the new encryption key and the last argument is a comma separated list of all old decryption keys.

The last key in the list is implicit and is the built in key. So the same script can be used to encrypt configuration that previously only was encrypted with the default key.

Listing 329 Encrypting using reenc from default encryption
$ ./bin/reenc config.xml NEW_KEY > new-config.xml

Re-encrypting custom Plugin configuration

If a plugin uses the Curity SDK type EncryptedString, the plugin’s configuration secrets are not re-encrypted by default. However, reenc can load a file with the custom plugin configuration paths which should be encrypted.

The file must have the following format:

Listing 330 Plugin custom paths for encryption
    # namespace  namespace-url      custom-path
    myns         https://my-plugin  b:facilities/b:data-sources/b:data-source/myns:custom/myns:enc-string

Note

The b namespace shown above comes from the default XSLT file used by reenc, which you can find with the Curity distribution at lib/reenc.xslt. Many other namespaces are defined which may be useful.

Each non-blank line that does not start with # should contain the following components separated by whitespaces:

  • namespace to use for the plugin’s configuration
  • the namespace URL
  • a configuration path that needs to be encrypted.

If a namespace repeats, its URL must match the one from previous lines.

To tell reenc where to find the custom plugin paths file, set the environment variable called PLUGINS_ENCRYPTED_PATHS_FILE to the path of the file.

Listing 331 Encrypting using reenc with custom plugin paths
$ PLUGINS_ENCRYPTED_PATHS_FILE=my-plugin-paths.txt ./bin/reenc config.xml NEW_KEY > new-config.xml

If you place this file within the Curity folder, at etc/plugins/reenc.txt, then reenc will find it automatically and you do not need to set PLUGINS_ENCRYPTED_PATHS_FILE.