Encryption Key

Connect uses a secret encryption key to encrypt sensitive data at rest, including certain configuration properties and application environment variables. By default, Connect creates and manages this key automatically, and no action or configuration is required.

In some cases a Connect administrator may wish to create and manage the key directly. For example, when provisioning a new Connect environment, you may want to encrypt sensitive configuration properties before launching Connect for the first time. This requires access in advance to the key Connect will use. Or, you may want to manage the encryption key with an existing secrets management tool rather than in a file on-disk managed by Connect.

Configuration properties

Connect supports two configuration properties for managing the encryption key. They are mutually exclusive, meaning only one or the other should be used. (If both are configured, Connect will report an error and will fail to start.) If either property is configured, Connect will use the provided key rather than create one.

EncryptionKeyFile is the path to a file containing the encryption key. The file must have 0600 file mode permissions and contain a valid key (see Creating a key). If multiple instances of Connect will share the same database in a High Availability configuration, every instance of Connect must have access to the same key file.

EncryptionKey is the raw encryption key. Use this property if you wish to configure the encryption key as an environment variable rather than write it to disk, by setting the CONNECT_SERVER_ENCRYPTIONKEY environment variable.

The Connect server log will indicate at startup which source was used to load the encryption key.

Creating a key

If you are provisioning a new Connect environment and wish to create an encryption key rather than let Connect create it automatically, use the rskey CLI to generate the key:

# Generate an encryption key file. 0600 file mode permissions are automatically configured.
$ rskey generate -o secret.key

# Or, print the encryption key to stdout.
$ rskey generate

Then provide the generated key to Connect using one of the configuration properties described above.

Managing an existing key

If you have an existing Connect environment and wish to take over management of the encryption key, you must use the existing key that was created by Connect. The automatically-created key is stored in a file named secret.key in the Database directory. You may move that file to another location specified by Server.EncryptionKeyFile, or remove the file and provide its contents to Connect via the Server.EncryptionKey property.

Encrypting values

Use the rskey CLI to encrypt string values with an externally-managed key.

(The rscadmin encrypt-config-value command can only work with the default encryption key managed by Connect.)

You can use this utility to produce encrypted, Base64-encoded values for any configuration property that has the encrypted-string type.

Encryption uses the NaCl library, which in turn uses the Salsa20 cipher and Poly1305 MAC, by default. The AES-256-GCM algorithm is also available.

The key file prohibits access by unprivileged users, so the rskey command must be run as root or using sudo.

Encrypt a configuration value:

# rskey will prompt you to enter the plain text value to encrypt
sudo rskey encrypt -f /path/to/secret.key

Encrypt multiple configuration values at once:

# rskey will read line-separated values from standard input
cat passwords.txt | sudo rskey encrypt -f /path/to/secret.key

FIPS mode

rskey and Connect support an alternative encryption algorithm, AES-256-GCM. This algorithm is an Approved Security Function under Federal Information Processing Standard 140 (FIPS). To encrypt a value using FIPS mode, pass the --mode=fips flag to the encrypt command:

sudo rskey encrypt -f /path/to/secret.key --mode=fips

See UseFIPSEncryption for configuring Connect to use FIPS mode when encrypting sensitive data. This configuration property, and the --mode=fips flag, control encryption; Connect will automatically decrypt FIPS-mode encrypted values correctly whether or not this configuration property is enabled.

Troubleshooting key mismatch error

If the value of the encryption key changes, or if Connect loses access to the key, Connect will log a warning and fail to start:

Secret key mismatch between database and configuration; the database was previously used with a different secret key. Replace previous key or run `rscadmin reset-secret-key`.

This may happen if:

  • Connect cannot read the file containing the key.
  • The contents of the file (or environment variable) containing the key have changed.
  • Connect was previously configured with the EncryptionKeyFile or EncryptionKey property, but is no longer, causing Connect to fall back to generating a new key in the default location.

To resolve this issue, ensure that Connect has access to the correct key.

Configuration Change

Confirm that your Connect configuration has not changed unexpectedly. If you previously configured the EncryptionKey or EncryptionKeyFile property, is it still configured with the correct value?

Data Directory

If your encryption key is stored in a file, whether configured with EncryptionKeyFile or in the default location (a file named secret.key in the Database.Dir directory), is the file available from all Connect nodes?

Are the file permissions correct? (The file mode should be 0600.)

NFS

If you are using NFS, ensure that your NFS service starts before the Posit Connect service.

To do this, you can override the systemd service unit by running sudo systemctl edit rstudio-connect.service, and adding the following lines (in this example, Server.DataDir is set to /networkstorage/rstudio-connect; edit that value to match your configured DataDir):

[Unit]
Description=Posit Connect
After=network-online.target
Wants=network-online.target
RequiresMountsFor=/networkstorage/rstudio-connect

Then run systemctl daemon-reload to read the change, then restart the Connect service with sudo systemctl restart rstudio-connect.

Resetting

If the encryption key is lost and cannot be recovered, you will need to reset it in order to start Connect successfully.

Please note that any encrypted data (configuration property values, content environment variables, etc.) will be lost.

First, ensure that your configuration reflects the state you wish to reset to. (Either managing the key yourself through one of the documented properties, or leaving them unconfigured to allow Connect to manage the key automatically.) Any encrypted configuration properties will need to be replaced with plaintext values, or reencrypted using the new key. (See Encrypting values for more information.)

See the appendix for the commands to reset the secret encryption key.

After resetting the key and starting Connect, any existing content environment variables will be undecryptable. Content relying on environment variables will have to be reconfigured with the correct environment variable values before they will be able to run or render again.