plumber uses the crypto R package sodium, to encrypt/decrypt req$session information for each server request.

sessionCookie(
  key,
  name = "plumber",
  expiration = FALSE,
  http = TRUE,
  secure = FALSE
)

Arguments

key

The secret key to use. This must be consistent across all R sessions where you want to save/restore encrypted cookies. It should be produced using randomCookieKey. Please see the "Storing secure keys" section for more details complex character string to bolster security.

name

The name of the cookie in the user's browser.

expiration

A number representing the number of seconds into the future before the cookie expires or a POSIXt date object of when the cookie expires. Defaults to the end of the user's browser session.

http

Boolean that adds the HttpOnly cookie flag that tells the browser to save the cookie and to NOT send it to client-side scripts. This mitigates cross-site scripting. Defaults to TRUE.

secure

Boolean that adds the Secure cookie flag. This should be set when the route is eventually delivered over HTTPS.

Details

The cookie's secret encryption key value must be consistent to maintain req$session information between server restarts.

Storing secure keys

While it is very quick to get started with user session cookies using plumber, please exercise precaution when storing secure key information. If a malicious person were to gain access to the secret key, they woud be able to eavesdrop on all req$session information and/or tamper with req$session information being processed.

Please:

  • Do NOT store keys in source control.

  • Do NOT store keys on disk with permissions that allow it to be accessed by everyone.

  • Do NOT store keys in databases which can be queried by everyone.

Instead, please:

  • Use a key management system, such as 'keyring' (preferred)

  • Store the secret in a file on disk with appropriately secure permissions, such as "user read only" (Sys.chmod("myfile.txt", mode = "0600")), to prevent others from reading it.

Examples of both of these solutions are done in the Examples section.

See also

  • 'sodium': R bindings to 'libsodium'

  • 'libsodium': A Modern and Easy-to-Use Crypto Library

  • 'keyring': Access the system credential store from R

  • Set-Cookie flags: Descriptions of different flags for Set-Cookie

  • Cross-site scripting: A security exploit which allows an attacker to inject into a website malicious client-side code

Examples

if (FALSE) { ## Set secret key using `keyring` (preferred method) keyring::key_set_with_value("plumber_api", plumber::randomCookieKey()) # Load a plumber API pr <- plumb(system.file(file.path("examples", "01-append", "plumber.R"), package = "plumber")) # Add cookie support and retrieve secret key using `keyring` pr$registerHooks( sessionCookie( keyring::key_get("plumber_api") ) ) pr$run() #### -------------------------------- ### ## Save key to a local file pswd_file <- "normal_file.txt" cat(plumber::randomCookieKey(), file = pswd_file) # Make file read-only Sys.chmod(pswd_file, mode = "0600") # Load a plumber API pr <- plumb(system.file(file.path("examples", "01-append", "plumber.R"), package = "plumber")) # Add cookie support and retrieve secret key from file pr$registerHooks( sessionCookie( readLines(pswd_file, warn = FALSE) ) ) pr$run() }