diff --git a/DESCRIPTION b/DESCRIPTION index 46c827e..ab9fc40 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -49,3 +49,4 @@ Collate: 'package.R' 'pass.R' 'utils.R' +Config/Needs/website: tidyverse/tidytemplate diff --git a/README.Rmd b/README.Rmd index 42e0f81..608e6be 100644 --- a/README.Rmd +++ b/README.Rmd @@ -13,108 +13,88 @@ knitr::opts_chunk$set( # keyring -> Access the System Credential Store from R - -[![R-CMD-check](https://github.com/r-lib/keyring/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/keyring/actions/workflows/R-CMD-check.yaml) -[![](https://www.r-pkg.org/badges/version/keyring)](https://www.r-pkg.org/pkg/keyring) -[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/keyring)](https://www.r-pkg.org/pkg/keyring) -[![Codecov test coverage](https://codecov.io/gh/r-lib/keyring/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/keyring?branch=main) - - -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. +[![R-CMD-check](https://github.com/r-lib/keyring/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/keyring/actions/workflows/R-CMD-check.yaml) [![](https://www.r-pkg.org/badges/version/keyring)](https://www.r-pkg.org/pkg/keyring) [![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/keyring)](https://www.r-pkg.org/pkg/keyring) [![Codecov test coverage](https://codecov.io/gh/r-lib/keyring/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/keyring?branch=main) -## Installation - -### Linux - -For the Secret Service backend install the `libsecret` library, at least -version 0.16. This is typically the best keyring for a Linux desktop. -Install these packages: + -- Debian/Ubuntu: `libsecret-1-dev` -- Recent RedHat, Fedora and CentOS systems: `libsecret-devel` +keyring provides a way to securely manage secrets using your operating system's credential store. +Once a secret is defined, it persists in the keyring across multiple R sessions. +keyring is an alternative to using env vars that's a bit more secure because your secret is never stored in plain text, meaning that you can (e.g.) never accidentally upload it to GitHub. +For more security, you can also store secrets in a custom keyring that always requires a password to unlock. -The file backend uses the sodium package, which needs the sodium library. -This backend works best on Linux servers. Install these packages: +keyring currently supports: -- Debian/Ubuntu: `libsodium-dev` -- Fedora, EPEL: `libsodium-devel` +- The macOS Keychain (`backend_macos`). +- The Windows Credential Store (`backend_wincred`). +- The Linux Secret Service API (`backend_secret_service`). -### OS X and Windows +It also provides two backends that are available on all platforms: -No additional software is needed. +- Encrypted files (`backend_file`) +- Environment variables (`backend_env`). -### R package +## Installation Install the package from CRAN: ```{r eval = FALSE} -install.packages("keyring") +# install.packages("pak") +pak::pak("keyring") ``` +We recommend using pak to install keyring as it will ensure that Linux system requirements are automatically installed (e.g. Ubuntu requires `libsecret-1-dev`, `libssl-dev`, and `libsodium-dev`). + ## Usage -### Query secret keys in a keyring: +The simplest usage only requires `key_set()` and `key_get()`: + +```{r} +#| eval: false + +# Interactively save a secret. This avoids typing the value of the secret +# into the console as this will be recorded in your `.Rhistory` +key_set("secret-name") -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. +# Later retrieve that secret +key_get("secret-name") +``` -- 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()` +Each secret is associated with a keyring. +By default, keyring will use the OS keyring (see `default_backend()` for details), which is automatically unlocked when you log in. +That means while the secret is stored securely, it can be accessed by other processes. -### Configure an OS-specific backend: +If you want greater security you can create a custom keyring that you manually lock and unlock. +That will require you to enter a custom password every time you want to access your secret. -- 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 encrypted files: `backend_file`. +```{r} +#| eval: FALSE +keyring_create("mypackage") +key_set("secret-name", keyring = "mypackage") +key_get("secret-name", keyring = "mypackage") +``` -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.). +Accessing the key unlocks the keyring, so if you're being really careful, you might want to lock it after you've retrieved the value with `keyring_lock()`. -### Manage keyrings: +### GitHub -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()`. +When you use keyring on GitHub, it will fall back to the environment variable backend. +That means if you want to use `key_get("mysecret")` you need to do two things: -Note that all platforms have a default keyring, and `key_get()`, etc. -will use that automatically. The default keyring is also convenient, -because usually the OS unlocks it automatically when you log in, so secrets -are available immediately. But note that the file backend does not currently -unlock its default keyring. +- Add a [new action secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) to your repository. -You only need to explicitly deal with keyrings and the `keyring_*` -functions if you want to use a different keyring. +- Make the secret available in your workflow `.yml`, e.g. -## Development documentation + ``` yaml + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + R_KEEP_PKG_SOURCE: yes + MY_SECRET: ${{ secrets.my_secret }} + ``` -Please see our [writeup of some `keyring` internals](https://github.com/r-lib/keyring/blob/main/inst/development-notes.md), -and as always, use the source code. +The envvar backend doesn't support custom keyrings, so if you're using one locally you'll need to use the default keyring on GitHub. -## License +## Development documentation -MIT © RStudio +Please see our [writeup of some `keyring` internals](https://github.com/r-lib/keyring/blob/main/inst/development-notes.md), and as always, use the source code. diff --git a/README.md b/README.md index 549b971..05e9fb5 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # keyring -> Access the System Credential Store from R - [![R-CMD-check](https://github.com/r-lib/keyring/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/keyring/actions/workflows/R-CMD-check.yaml) @@ -11,104 +9,73 @@ downloads](https://cranlogs.r-pkg.org/badges/keyring)](https://www.r-pkg.org/pkg/keyring) [![Codecov test coverage](https://codecov.io/gh/r-lib/keyring/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/keyring?branch=main) - - -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. -## Installation - -### Linux - -For the Secret Service backend install the `libsecret` library, at least -version 0.16. This is typically the best keyring for a Linux desktop. -Install these packages: + -- Debian/Ubuntu: `libsecret-1-dev` -- Recent RedHat, Fedora and CentOS systems: `libsecret-devel` +keyring provides a way to securely manage secrets using your operating +system’s credential store. Once a secret is defined, it persists in the +keyring across multiple R sessions. keyring is an alternative to using +env vars that’s a bit more secure because your secret is never stored in +plain text, meaning that you can (e.g.) never accidentally upload it to +GitHub. -The file backend uses the sodium package, which needs the sodium -library. This backend works best on Linux servers. Install these -packages: +keyring currently supports: -- Debian/Ubuntu: `libsodium-dev` -- Fedora, EPEL: `libsodium-devel` +- The macOS Keychain (`backend_macos`). +- The Windows Credential Store (`backend_wincred`). +- The Linux Secret Service API (`backend_secret_service`). -### OS X and Windows +It also provides two backends that are available on all platforms: -No additional software is needed. +- Encrypted files (`backend_file`) +- Environment variables (`backend_env`). -### R package +## Installation Install the package from CRAN: ``` r -install.packages("keyring") +# install.packages("pak") +pak::pak("keyring") ``` -## Usage - -### 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. +We recommend using pak to install keyring as it will ensure that Linux +system requirements are automatically installed (e.g. Ubuntu requires +`libsecret-1-dev`, `libssl-dev`, and `libsodium-dev`). -- 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()` +## Usage -### Configure an OS-specific backend: +The simplest usage only requires `key_set()` and `key_get()`: -- 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 encrypted files: `backend_file`. +``` r +# Interactively save a secret. This avoids typing the value of the secret +# into the console as this will be recorded in your `.Rhistory` +key_set("secret-name") -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.). +# Later retrieve that secret +key_get("secret-name") +``` -### Manage keyrings: +Each secret is associated with a keyring. By default, keyring will use +the OS keyring (see `default_backend()` for details), which is +automatically unlocked when you log in. That means while the secret is +stored securely, it can be accessed by other processes. -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()`. +If you want greater security you can create a custom keyring that you +manually lock and unlock. That will require you to enter a custom +password every time you want to access your secret. -Note that all platforms have a default keyring, and `key_get()`, etc. -will use that automatically. The default keyring is also convenient, -because usually the OS unlocks it automatically when you log in, so -secrets are available immediately. But note that the file backend does -not currently unlock its default keyring. +``` r +keyring_create("mypackage") +key_set("secret-name", keyring = "mypackage") +key_get("secret-name", keyring = "mypackage") +``` -You only need to explicitly deal with keyrings and the `keyring_*` -functions if you want to use a different keyring. +Accessing the key unlocks the keyring, so if you’re being really +careful, you might want to lock it again with `keyring_lock()`. ## Development documentation Please see our [writeup of some `keyring` internals](https://github.com/r-lib/keyring/blob/main/inst/development-notes.md), and as always, use the source code. - -## License - -MIT © RStudio diff --git a/_pkgdown.yml b/_pkgdown.yml index aac6138..6f99188 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,6 +1,7 @@ -url: https://r-lib.github.io/keyring +url: https://keyring.r-lib.org template: bootstrap: 5 + package: tidytemplate destination: docs development: