keyring v1.1.0


Monthly downloads



Access the System Credential Store from R

Platform independent 'API' to access the operating system's credential store. Currently supports: 'Keychain' on 'macOS', Credential Store on 'Windows', the Secret Service 'API' on 'Linux', and a simple, platform independent store implemented with environment variables. Additional storage back-ends can be added easily.



Access the System Credential Store from R

Linux Build Status Windows Build status CRAN RStudio mirror downloads Coverage Status

Platform independent API to access the operating systems credential store. Currently supports:

  • Keychain on macOS (backend_macos),
  • Credential Store on Windows (backend_wincred),
  • the Secret Service API on Linux (backend_secret_service),
  • encrypted files (backend_file), and
  • environment variables (backend_env). The last two are available on all platforms. Additional storage backends can be added easily.



Install the libsecret library, at least version 0.16.

  • Debian/Ubuntu: libsecret-1-dev
  • Recent RedHat, Fedora and CentOS systems: libsecret-devel

The file backend uses the sodium package:

  • Debian/Ubuntu: libsodium-dev
  • Fedora, EPEL: libsodium-devel

OS X and Windows

No additional software needed

R package

Install the package from CRAN:



Configuring an OS-specific backend:

  • The default is operating system specific, and is described in manual page of default_backend(). In most cases you don't have to configure this.
  • MacOS: backend_macos
  • Linux: backend_secret_service, if build with libsecret
  • Windows: backend_wincred
  • Or store the secrets in environment variables on other operating systems: backend_env

Should you need to change the default backend, set the R_KEYRING_BACKEND environment variable or the keyring_backend R option to the backend's name (e.g. env, file, etc.).

Query secret keys in a keyring:

Each keyring can contain one or many secrets (keys). A key is defined by a service name and a password. Once a key is defined, it persists in the keyring store of the operating system. This means the keys persist beyond the termination of and R session. Specifically, you can define a key once, and then read the key value in completely independent R sessions.

  • Setting a secret interactively: key_set()
  • Setting a secret from a script, i.e. non-interactively: key_set_with_value()
  • Reading a secret: key_get()
  • Listing secrets: key_list()
  • Deleting a secret: key_delete()

Managing keyrings:

A keyring is a collection of keys that can be treated as a unit. A keyring typically has a name and a password to unlock it. See keyring_create(), keyring_delete(), keyring_list(), keyring_lock(), keyring_unlock(), keyring_is_locked().

Note that all platforms have a default keyring, and key_get(), etc. will use that automatically. The default keyring is also convenient, because the OS unlocks it automatically when you log in, so secrets are available immediately.

You only need to explicitly deal with keyrings and the keyring_* functions if you want to use a different keyring.

Development documentation

Please see our writeup of some keyring internals, and as always, use the source code.


MIT © RStudio

Functions in keyring

Name Description
backend_macos Create a macOS Keychain backend
backends Select the default backend and default keyring
backend_wincred Create a Windows Credential Store keyring backend
backend_env Store secrets in environment variables
b_wincred_get Get a key from a Wincred keyring
backend Abstract class of a minimal keyring backend
b_wincred_set_with_raw_value Set a key on a Wincred keyring
has_keyring_support Manage keyrings
keyring Access the System Credential Store from R
backend_secret_service Create a Secret Service keyring backend
key_get Query, set, delete list keys in a keyring
backend_file Store secrets in encrypted files
backend_keyrings Abstract class of a backend that supports multiple keyrings
No Results!

Last month downloads


License MIT + file LICENSE
LazyData true
RoxygenNote 6.0.1
Encoding UTF-8
SystemRequirements Optional: libsecret on Linux (libsecret-1-dev on Debian/Ubuntu, libsecret-devel on Fedora/CentOS)
Collate 'api.R' 'assertions.R' 'backend-class.R' 'backend-env.R' 'backend-file.R' 'backend-macos.R' 'backend-secret-service.R' 'backend-wincred.R' 'default_backend.R' 'package.R' 'pass.R' 'utils.R'
NeedsCompilation yes
Packaged 2018-07-16 11:55:49 UTC; gaborcsardi
Repository CRAN
Date/Publication 2018-07-16 12:20:03 UTC

Include our badge in your README