Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rstudio/rskey/llms.txt

Use this file to discover all available pages before exploring further.

rskey uses two distinct key file formats depending on the target product. Connect and Package Manager share a 512-byte random key stored as hex, while Workbench accepts any opaque byte sequence of at least 32 bytes — traditionally a UUID.

​
Connect & Package Manager key format

Connect and Package Manager keys are 512 bytes of cryptographically secure random data. On disk, the key is stored as 1024 hex characters — each byte encoded as two lowercase hexadecimal characters. This is exactly equivalent to the output of: 
openssl rand -hex 512
Reading keys: NewKeyFromBytes and NewKeyFromReader accept both hex and base64-encoded key files. The function first attempts hex decoding; if that fails it falls back to standard base64. In both cases the decoded output must be exactly 512 bytes or ErrInvalidKeyLength is returned. Writing keys: (*Key).HexString() always produces hex output. Use this when writing a key to disk to ensure compatibility with Connect and Package Manager. Generating a key: 
# Write directly to disk
rskey generate -o /var/lib/rstudio-pm/rstudio-pm.key

# Print to stdout
rskey generate
Programmatically: 
key, err := crypt.NewKey()
if err != nil {
    panic(err)
}
err = os.WriteFile("connect.key", []byte(key.HexString()), 0600)
Key length constant: crypt.KeyLength = 512 (bytes, not encoded characters).
Protect key files with 0600 permissions. Anyone in possession of the key file can decrypt every secret encrypted with it. Never commit key files to version control and never pass key content directly in environment variables — pass the file path instead.

​
Workbench key format

Workbench keys are 32 or more opaque bytes. The workbench package imposes no structure on the content beyond the minimum length: minKeyLength = 32. Traditionally, Workbench keys are a UUID literal generated by the uuid command: 
echo $(uuid) > /etc/rstudio/secure-cookie-key
chmod 0600 /etc/rstudio/secure-cookie-key
A UUID string such as 550e8400-e29b-41d4-a716-446655440000\n is 37 bytes (including the trailing newline), which satisfies the 32-byte minimum. rskey-generated keys (512 bytes of hex) also satisfy the minimum length requirement and are accepted by workbench.NewKeyFromBytes. You can therefore use a single key file for both Workbench and Connect/Package Manager if needed: 
rskey generate -o /etc/rstudio/secure-cookie-key
rskey encrypt --mode=workbench -f /etc/rstudio/secure-cookie-key
Fingerprint: The Workbench fingerprint is the CRC32 (IEEE polynomial) checksum of the raw key bytes before rotation, formatted as an 8-character uppercase hex string. This matches the hash reported by rstudio-server encrypt-password. 
rskey fingerprint --mode=workbench -f /etc/rstudio/secure-cookie-key

​
Key rotation

Rotating a key requires re-encrypting every secret that was encrypted with the old key before replacing the key file.
1

Identify the current key in use

Use the rskey fingerprint command to record the fingerprint of the current key. Posit products log this fingerprint, which helps you confirm which key was active when a secret was encrypted.
rskey fingerprint -f /var/lib/rstudio-pm/rstudio-pm.key
2

Generate a new key

rskey generate -o /var/lib/rstudio-pm/rstudio-pm-new.key
chmod 0600 /var/lib/rstudio-pm/rstudio-pm-new.key
3

Re-encrypt all secrets

Decrypt each secret with the old key, then encrypt with the new key.
# Decrypt with old key
echo "$OLD_CIPHER" | rskey decrypt -f /var/lib/rstudio-pm/rstudio-pm.key

# Re-encrypt with new key
echo "$PLAINTEXT" | rskey encrypt -f /var/lib/rstudio-pm/rstudio-pm-new.key
Update all product configuration files with the newly encrypted values.
4

Replace the key file

Once all secrets have been re-encrypted and configuration files updated, replace the old key file:
mv /var/lib/rstudio-pm/rstudio-pm-new.key /var/lib/rstudio-pm/rstudio-pm.key
Restart the product to pick up the new key and updated configuration.
The old key file should be securely deleted after confirming the new key works correctly. Until that point, keep it in a safe location in case a rollback is needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us