Encryption
Posit Workbench uses AES for encryption to safeguard its internal data. You can configure Workbench to use different AES sizes as described below.
The encryption discussed in this section applies only to metadata internally generated by Workbench or encrypted configuration items (like the encrypted OpenID secret, if used) that are necessary to manage and provide IDE sessions for users.
In order to protect the integrity of the sessions it provides, Workbench encrypts the data it uses internally and when communicating with IDE sessions (i.e., encrypted SSL communication between Workbench and a client browser, if configured). However, Workbench does not attempt to encrypt data it does not own, such as data stored in a user’s home directory. Protection of that data is provided by whatever security policies have been implemented for the storage location and the system(s) on which Workbench and its IDE sessions run.
Versioned encryption
Workbench tracks different AES key lengths via encryption versions.
| Version | Encryption Algorithm | Notes |
|---|---|---|
| 0 (default)* | AES 128 | Legacy encryption version. Will be deprecated in future releases. |
| 1 | AES 128 | Not compatible with version 0, despite using the same algorithm. |
| 2 | AES 256 |
* The default encryption version is currently version 0. Posit increments the default encryption version over time in future releases, and in a manner that won’t negatively affect pre-existing user IDE sessions.
Manually configure encryption version
Posit recommends leaving encryption versions at their default values. However, if your security requires it Workbench can be manually configured to use a different version than the default by defining environment variables that define the minimum and maximum versions allowed. These environment variables are read by Workbench on startup.
Changing the encryption version used by Workbench can cause sessions using a different encryption version to become inaccessible.
Maximum encryption version (encryption)
The maximum encryption version defines the version at which any newly generated data is encrypted. Workbench always encrypts at the highest version allowed. For example, setting the maximum encryption version to 2 results in Workbench always creating data encrypted with version 2 encryption, and never version 0 or 1.
Encryption version of previous Workbench releases
Setting a high maximum encryption version impacts the ability to downgrade to older versions of Workbench. Prior to 2024.09, all Workbench releases use version 0 encryption and decryption. Setting a higher maximum encryption version, and then the downgrading to a version prior to 2024.09 results in the older version of Workbench not being able to decrypt any of the data created by the newer version. This may put the downgraded installation of Workbench in a unpredictable state that is difficult to diagnose.
Minimum encryption version (decryption)
The minimum encryption version defines the lowest version that Workbench decrypts. The minimum encryption version is a lower bound, so Workbench decrypts any version greater than or equal to the minimum encryption version. For example, setting the minimum encryption version to 0 means that Workbench will decrypt and use any version of encrypted data it comes across. A minimum version of 1 means that Workbench will refuse to decrypt any version 0 data, but versions 1 and 2 will be decrypted.
Setting a higher minimum encryption version impacts the ability to resume pre-existing sessions that were created with a lower encryption version. For this reason, the recommended minimum encryption version is currently 0. This allows Workbench to continue to interact with sessions that were created with versions 0-2 while it gradually phases them out with new sessions using higher maximum encryption versions as described above.
Incompatable encryption versions
If the minimum encryption version is set to a value higher than the maximum encryption value, Workbench won’t be able to decrypt any of the data it encrypted. If this case happens, Workbench emits an error and refuses to startup.
Setting encryption versions
Before changing the default encryption versions, be sure to carefully consider the impact it will have on:
- Resuming pre-existing sessions that were created prior to changing the default encryption version, and
- The ability to effectively downgrade to a version of Workbench older than 2024.09.
On startup, Workbench reads the two environment variables POSIT_MINIMUM_ENCRYPTION_VERSION and POSIT_MAXIMUM_ENCRYPTION_VERSION once, and sets its minimum and maximum encryption versions to match for the lifetime of the process. To set these environments follow the steps below.
1. Stop all sessions and take Workbench offline
Prepare Workbench as though you are going through the first 3 steps of the upgrade procedure. Namely:
- (Optional) Notify users of impending restart
- Suspend any active sessions (if you are setting a high minimum encryption version, notify users that suspended sessions may not be able to resume after)
- Take Workbench offline
2. Set encryption version environment variables
The environment variables can be set using systemctl. In the terminal, run both commands:
sudo systemctl edit rstudio-server
sudo systemctl edit rstudio-launcherIn the text editor that opens, add the following lines, then set the desired encryption versions, save, and quit. For example:
[Service]
Environment=POSIT_ENCRYPTION_MINIMUM_VERSION=0
Environment=POSIT_ENCRYPTION_MAXIMUM_VERSION=2Reload the systemd manager configuration:
sudo systemctl daemon-reloadVerify the environment variables were successfully applied by checking if they now exist in their respective override.conf files:
sudo cat /etc/systemd/system/rstudio-server.service.d/override.confThe output should contain the POSIT_ENCRYPTION_MINIMUM_VERSION and POSIT_ENCRYPTION_MAXIMUM_VERSION variables you defined above.
If your Linux distribution does not use the systemd init system, consult the documentation for your distribution to learn which init system it uses and the appropriate method for setting environment variables for Workbench’s rstudio-server and rstudio-launcher services.
3. Re-encrypt configuration values
If you are using encrypted values in your configuration for the internal database password or the OpenID client secret, you need to re-encrypt each of them using the encrypt-password command:
sudo rstudio-server encrypt-passwordVerify that the correct encryption version was used by looking for the text Using encryption version: in the output:
$ sudo rstudio-server encrypt-password
Using encryption version: 2
Encrypting with key from /var/lib/rstudio-server/secure-cookie-key key hash: (Hash Redacted)
Enter the password to be encrypted:
Enter the password again:
[Password Output Redacted]Copy the password output over the old password value in the corresponding configuration file.
4. Update configuration to other load balanced servers
If you are running Workbench with multiple load balanced servers, repeat step 2 above on each server. If you completed step 3, you should copy any conf files with newly encrypted passwords rather than re-running the encrypt-password on each server again.
5. Restart Workbench
Finally, restart Workbench and the launcher (restarting the services on all load balanced servers):
sudo rstudio-server restart && sudo rstudio-launcher restartBring Workbench back online if you set it offline in step 1
sudo rstudio-server online