Configuration Encryption

Package Manager supports the encryption of sensitive configuration options. For example, the Postgres.Password, Proxy.Password, and Manifest.Password settings all support plain text or encrypted values.

Generate an Encryption Key

Although Package Manager automatically generates an encryption key if one does not exist, there are situations where you might need to create a key manually before starting the application. To generate an encryption key, run the following command in your terminal

Terminal
$ rspm encrypt generate
0616a5a7445f4c0b8b9f31a840f22a152f7621c5c9cc1febcb9f647183193c8e9f60...

This can be stored in the PACKAGEMANAGER_ENCRYPTION_KEY environment variable or written to the persistent storage location (either file or s3).

If [Storage].Persistent is set to s3, the key needs to be manually uploaded to the correct location in the S3 bucket. This process looks like the following:

Terminal
# generate the encryption key locally
rspm encrypt generate > rstudio-pm.key

# push it to S3 in the `/persistent/encryption` directory.
aws s3 cp rstudio-pm.key s3://<s3_bucket_name>/persistent/encryption/rstudio-pm.key

Now when Package Manager starts, it will read the encryption key from the S3 bucket.

Encrypt a setting

To encrypt a sensitive configuration setting, use the rspm encrypt command. For example:

Terminal
$ rspm encrypt
Encryption: Enter the plain text value below.
Qu0lI/gridhu85sqChwFtP2wFkqCcWt9owBpxFjAhKFaU2ZraBB2LM62Ieo=
Note

Only settings that have the type of encrypted-string support encryption.

Note

If [Storage].Persistent is set to s3, the key file must be present in the S3 bucket at the location /persistent/encryption/rstudio-pm.key and your AWS credentials must be configured correctly to access the key.

Key file

The rspm encrypt command creates a key file called rstudio-pm.key. This should be placed on [Storage].Persistent location at /persistent/encryption/rstudio-pm.key. This key must not be deleted for the Package Manager server to properly read the configuration file.

Note that the PACKAGEMANAGER_ENCRYPTION_KEY environment variable can be used to specify the encryption key to rspm encrypt in place of the key file, which may be preferable to managing the file directly in some cases.

Encryption Key Rotation

Warning

Be sure to backup your data before initiating a key rotation. If the key rotation fails in an incomplete state, you will need to restore the server from a backup to recover.

Overview

Package Manager uses an encryption key to encrypt sensitive data like config values and Git credentials. The encryption key is stored in the rstudio-pm.key file in the /persistent/encryption directory, on S3 or disk depending on your storage configuration. The encryption key is generated on the first start-up of Package Manager and is used to encrypt sensitive data. Package Manager encrypts the following data:

  • Encrypted configuration values:
    • Postgres.Password
    • Postgres.UsageDataPassword
    • Proxy.Password
    • Manifest.Password
  • Encrypted database values:
    • git_credentials
    • key_rotations
Warning

The encryption key is also used to sign and verify API tokens. If the encryption key is rotated, all existing API tokens will be invalidated as they can only be verified with the old key. Admins will need to generate new API tokens for all users.

Key Rotation

To initiate an encryption key rotation, run the following command:

Terminal
rspm encrypt rotate
Warning

Using the PACKAGEMANAGER_ENCRYPTION_KEY environment variable is not supported for encryption key rotation. If you are using this environment variable, you must store the key at /persistent/encryption/rstudio-pm.key before initiating a rotation. This is so Package Manager owns the lifecycle of the old and new key during the rotation. After the rotation is complete, you may set the new key as the PACKAGEMANAGER_ENCRYPTION_KEY environment variable. If you try to rotate the key while using the PACKAGEMANAGER_ENCRYPTION_KEY environment variable, the command will return an error:

Terminal
encryption key rotation is prohibited for keys defined via the PACKAGEMANAGER_ENCRYPTION_KEY environment variable, only keys stored on persistent storage may be rotated

The rspm encrypt rotate command will generate a new encryption key and return which values need to be updated in the configuration file. The command output will look like this:

Terminal
Key rotation with ID '1' in progress. The following values are encrypted in the server's configuration and have been re-encrypted with the new encryption key:

Postgres.Password = jW1dMjLZuZMwQz7gBD01i7m8XZBlQUSt2qjRiCQm17kKogEJqNFFvzDc1Ho=
Postgres.UsageDataPassword = dznNHxRYtSlel1nUe2kCMWlVUBLDWQbF1gxiSWmmdUPTDOUQ5ahjgIwBUdQ=
Manifest.Password = /xssgdd3z5icZFXGWNlOnEfhAK445+donSMiHK56Pk8Y73q3xuMR+9SM7EU=
Proxy.Password = ntmE57lm4olrnWKmcU7G1u0s5TIERfQWyVUw6F4bdayqXRlq2PiOYewvPHI=

Please update these configuration values wherever they are stored and restart the server. Restarting the server will verify the new encryption key against the encrypted configuration values and rotate any encrypted database values.

The command output will list only the configuration values that it detects are currently encrypted with the old key. If they are stored in plain-text or are not set at all, it will not list them. If no values are currently encrypted in the configuration file, the command will return the following message:

Terminal
Key rotation with ID '1' in progress. No encrypted configuration values were found, nothing to manually rotate. Please restart the server. Restarting the server will rotate any encrypted database values.

After initiating a key rotation, you must update any encrypted configuration settings manually because Package Manager doesn’t control where these settings are defined. They can be stored:

  • In the .gcfg file,
  • As environment variables,
  • In a values.yaml file, or
  • In a combination of the above items.

After updating the configuration, restart the server to automatically verify the new encryption key against the encrypted configuration values and rotate any encrypted database values.

Only one key rotation can be in progress at a time. If you try to rotate the key while another rotation is in progress, the command will return the following error:

Terminal
an encryption key rotation is already in-progress

If Package Manager starts successfully after restarting the server, the key rotation is complete. If the server fails to start, you can restore the server from a backup to recover.

Back to top