rskey

rskey

rskey is a command-line tool (and bundled Go package) that generates secret keys interoperable with the format used by Posit's Workbench, Connect, and Package Manager products.

It can be used to help manage secrets without the need to install these products first, and is designed for use in Infrastructure-as-Code and containerised deployments of these products.

This tool can also serve as a drop-in replacement for:

• Posit Connect's rscadmin configure --encrypt-config-value command

• Package Manager's rspm encrypt command.

• Workbench's rstudio-server encrypt-password command.

No local license keys are required, either.

This is not a general-purpose encryption tool.

Installation

Binary releases for Windows, macOS, and Linux are available on GitHub.

If you have a local Go toolchain you can also install via go install:

$ go install github.com/rstudio/rskey@latest

Binary releases are signed with Sigstore. You can verify these signatures with their cosign tool, for example:

$ cosign verify-blob \
  --signature rskey_0.5.0_linux_amd64.tar.gz.sig \
  rskey_0.5.0_linux_amd64.tar.gz

We use Cosign's "keyless" mode, which uses the OpenID Connect tokens issued by GitHub for this repository and ephemeral certificates instead of private keys.

Usage

You can generate keys with rskey generate. For example:

$ rskey generate -o /var/lib/rstudio-pm/rstudio-pm.key
# Or, to simply echo the key to standard input:
$ rskey generate

You can then encrypt data (such as database passwords) interactively with rskey encrypt. For example:

$ rskey encrypt -f /var/lib/rstudio-pm/rstudio-pm.key

Line-separated entries can also be passed on standard input:

$ cat passwords.txt | rskey encrypt -f /var/lib/rstudio-pm/rstudio-pm.key

An rskey decrypt command is also provided.

The rskey fingerprint command prints a short fingerprint that helps identify keys in log messages and other output of Posit products. The default fingerprint algorithm is SHA-256; for historical reasons the Workbench algorithm is crc32.

FIPS Mode

Connect version 2022.03.0 and later and Package Manager version 2024.04.0 and later support an alternative encryption algorithm, AES-256-GCM. This algorithm is an Approved Security Function under Federal Information Processing Standard 140 (FIPS), unlike the default.

If you prefer to encrypt secrets using this algorithm and are using this version or later of Connect or Package Manager, pass the --mode=fips flag to the encrypt command:

$ rskey encrypt -f connect.key --mode=fips

rskey decrypt does not require this flag because the algorithm in use can be determined from the encrypted output.

Workbench

Secret keys for Workbench are traditionally generated by the uuid command, but there is no built-in support for this format in rskey generate.

To encrypt or decrypt secrets for use with Posit Workbench, pass the --mode=workbench flag to the appropriate command. Both key formats are acceptable:

$ rskey generate -o /etc/rstudio/secure-cookie-key
$ rskey encrypt --mode=workbench -f /etc/rstudio/secure-cookie-key
$ echo `uuid` > uuid.key
$ rskey encrypt --mode=workbench -f uuid.key

Details

• Secret key must be kept secret, and anyone in possession of that key can decrypt any data encrypted with it.

• Encryption for Connect and Package Manager uses the well-known NaCl Secretbox algorithm by default.

• Connect version 2022.03.0 and later supports an alternative encryption algorithm, AES-256-GCM. This algorithm is an Approved Security Function under Federal Information Processing Standard 140, and can be used by passing --mode=fips to the rskey encrypt command.

• Package Manager version 2024.04.0 and later supports an identical setting.

• Encryption for Workbench uses AES-128-CBC.

• Key files for Connect and Package Manager are a sequence of 512 hex-encoded, securely-generated random bytes. This means that rskey generate is analogous to openssl rand -hex 512.

• Key files for Workbench are 32 or more opaque bytes. Most often they are generated by the uuid command, but you can use the output of rskey generate as well.

API Stability and Versioning

rskey and its packages follow strict semantic versioning.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.