Skip to content

Commit

Permalink
Tweak the readme to be more user facing (#138)
Browse files Browse the repository at this point in the history
  • Loading branch information
@hadley
hadley authored Oct 19, 2023
1 parent 83bf966 commit e8d88e2
Show file tree
Hide file tree
Showing 4 changed files with 101 additions and 152 deletions.
1 change: 1 addition & 0 deletions DESCRIPTION
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,3 +49,4 @@ Collate:
'package.R'
'pass.R'
'utils.R'
Config/Needs/website: tidyverse/tidytemplate
130 changes: 55 additions & 75 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,108 +13,88 @@ knitr::opts_chunk$set(

# keyring

> Access the System Credential Store from R
<!-- badges: start -->
[![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)
<!-- badges: end -->

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:
<!-- badges: end -->

- 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.
119 changes: 43 additions & 76 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@

# keyring

> Access the System Credential Store from R
<!-- badges: start -->

[![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)
Expand All @@ -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)
<!-- badges: end -->

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:
<!-- badges: end -->

- 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
3 changes: 2 additions & 1 deletion _pkgdown.yml
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand Down

0 comments on commit e8d88e2

Please sign in to comment.