Managing secrets

Ask each time

For scripts that you only use every now and then, a simple solution is to simply ask for the password each time the script is run. If you use RStudio an easy and secure way to request a password is with the rstudioapi package:

password <- rstudioapi::askForPassword()

If you don’t use RStudio, use a more general solution like the getPass package.

You should never type your password into the R console: this will typically be stored in the .Rhistory file, and it’s easy to accidentally share without realising it.

Environment variables

Asking each time is a hassle, so you might want to store the secret across sessions. One easy way to do that is with environment variables. Environment variables, or envvars for short, are a cross platform way of passing information to processes.

For passing envvars to R, you can list name-value pairs in a file called .Renviron in your home directory. The easiest way to edit it is to run:

file.edit("~/.Renviron")

The file looks something like

VAR1 = value1
VAR2 = value2

And you can access the values in R using Sys.getenv():

Sys.getenv("VAR1")
#> [1] "value1"

Note that .Renviron is only processed on startup, so you’ll need to restart R to see changes.

These environment variables will be available in every running R process, and can easily be read by any other program on your computer to access that file directly. For more security, use the keyring package.

Keyring

The keyring package provides a way to store (and retrieve) data in your OS’s secure secret store. Keyring has a simple API:

keyring::key_set("MY_SECRET")
keyring::key_get("MY_SECRET")

By default, keyring will use the system keyring. This is unlocked by default when you log in, which means while the password is stored securely pretty much any process can access it.

If you want to be even more secure, you can create custom keyring and keep it locked. That will require you to enter a password every time you want to access your secret.

keyring::keyring_create("httr")
keyring::key_set("MY_SECRET", keyring = "httr")

Note that accessing the key always unlocks the keyring, so if you’re being really careful, make sure to lock it again afterwards.

keyring::keyring_lock("httr")

You might wonder if we’ve actually achieved anything here because we still need to enter a password! However, that one password lets you access every secret, and you can control how often you need to re-enter it by manually locking and unlocking the keyring.

Reprexes

The most common place you might need to share a secret is to generate a reprex. First, do everything you can do eliminate the need to share a secret:

• If it is an http problem, make sure to run all requests with verbose().
• If you get an R error, make sure to include traceback().

If you’re lucky, that will be sufficient information to fix the problem.

Otherwise, you’ll need to encrypt the secret so you can share it with me. The easiest way to do so is with the following snippet:

library(openssl)
library(jsonlite)
library(curl)

encrypt <- function(secret, username) {
  url <- paste("https://api.github.com/users", username, "keys", sep = "/")

  resp <- httr::GET(url)
  httr::stop_for_status(resp)
  pubkey <- httr::content(resp)[[1]]$key

  opubkey <- openssl::read_pubkey(pubkey)
  cipher <- openssl::rsa_encrypt(charToRaw(secret), opubkey)
  jsonlite::base64_enc(cipher)
}
  
cipher <- encrypt("<username>\n<password>", "hadley")
cat(cipher)

Then I can run the following code on my computer to access it:

decrypt <- function(cipher, key = openssl::my_key()) {
  cipherraw <- jsonlite::base64_dec(cipher)
  rawToChar(openssl::rsa_decrypt(cipherraw, key = key))
}

decrypt(cipher)
#> username
#> password

Change your password before and after you share it with me or anyone else.

GitHub

If you want to share secrets with a group of other people on GitHub, use the secret or cyphr packages.

Travis

The easiest way to handle short secrets is to use environment variables. You’ll set in your .Renviron locally and in the settings pane on travis. That way you can use Sys.getenv() to access in both places. It’s also possible to set encrypted env vars in your .travis.yml: see the documentation for details.

Regardless of how you set it, make sure you have a helper to retrieve the value. A good error message will save you a lot of time when debugging problems!

my_secret <- function() {
  val <- Sys.getenv("SECRET")
  if (identical(val, "")) {
    stop("`SECRET` env var has not been set")
  }
  val
}

Note that encrypted data is not available in pull requests in forks. Typically you’ll need to check PRs locally once you’ve confirmed that the code isn’t actively malicious.

To share secret files on travis, see https://docs.travis-ci.com/user/encrypting-files/. Basically you will encrypt the file locally and check it in to git. Then you’ll add a decryption step to your .travis.yml which makes it decrypts it for each run.

Be careful to not accidentally expose the secret on travis. An easy way to accidentally expose the secret is to print it out so that it’s captured in the log. Don’t do that!

Documentation

Like any R package, an API client needs clear and complete documentation of all functions. Examples are particularly useful but may need to be wrapped in \donttest{} to avoid challenges of authentication, rate limiting, lack of network access, or occasional API server down time.

Vignettes

Vignettes pose additional challenges when an API requires authentication, because you don’t want to bundle your own credentials with the package! However, you can take advantage of the fact that the vignette is built locally, and only checked by CRAN. In a setup chunk, do:

NOT_CRAN <- identical(tolower(Sys.getenv("NOT_CRAN")), "true")
knitr::opts_chunk$set(purl = NOT_CRAN)

And then use eval = NOT_CRAN in any chunk that requires access to a secret.

Testing

Use testthat::skip() to automatically skip tests that require authentication. I typically will wrap this into a little helper function that I call at the start of every test requiring auth.

skip_if_no_auth <- function() {
  if (identical(Sys.getenv("MY_SECRET"), "")) {
    skip("No authentication available")
  }
}