-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
183 lines (130 loc) · 4.96 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
---
output: github_document
editor_options:
markdown:
wrap: sentence
canonical: true
---
```{r, setup, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
comment = "#>",
tidy = FALSE,
error = FALSE,
fig.width = 8,
fig.height = 8)
```
# oskeyring
> Raw System Credential Store Access from R
<!-- badges: start -->
[](https://github.com/r-lib/oskeyring/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/r-lib/oskeyring)
<!-- badges: end -->
## Features
- Windows and macOS support. Read, write, list and search the system credential store.
- Generic credentials, domain passwords, domain certificates on Windows.
- Generic passwords and internet passwords on macOS.
- Multiple keychains on macOS.
## Related
- The keyring R package provides a portable system keyring API for all platforms, and also supports multiple backends: <https://github.com/r-lib/keyring>
## Installation
Install the package from CRAN:
```{r eval = FALSE}
install.packages("oskeyring")
```
To install the development version from GitHub run:
```{r eval = FALSE}
pak::pak("r-lib/oskeyring")
```
## Usage
```{r}
library(oskeyring)
```
Most oskeyring functions are not portable, and only work on one operating system (OS).
The functions that do not use the system credential store can be used on all OSes.
E.g. `macos_item()` and `windows_item()` are portable.
Calling a function on the wrong OS will throw an `oskeyring_bad_os_error` error.
oskeyring follows the API of the OS closely, and it has a different set of functions on Windows and macOS.
E.g. the macOS API can search for keychain items based on item attributes, but there is no similar API on Windows, so oskeyring does not have a `windows_item_search()` function.
### Windows Credential Store
oskeyring uses the API defined in [`wincred.h`](https://learn.microsoft.com/en-us/windows/win32/api/wincred/) on Windows.
The Windows credential store contains various credential types.
The ones supported by oskeyring are:
```{r}
windows_item_types()
```
`windows_item_write()` adds or updates a credential in the credential store.
It takes objects created with `windows_item()` :
```{r}
it <- windows_item("secret", "my-host-password")
it
```
``` r
windows_item_write(it)
```
`windows_item_read()` reads a credential from the credential store, the return value includes the secret as well:
``` r
windows_item_read("my-host-password")
```
``` r
#> <oskeyring_windows_item: generic>
#> target_name: my-host-password
#> persist: local_machine
#> credential_blob: <-- hidden -->
```
`windows_item_enumerate()` lists all credentials that match a prefix.
`windows_item_delete()` deletes a credential.
See more in the manual: `?windows_credentials`.
### macOS Keychain Services
#### Keychain items
oskeyring uses the [Keychain API](https://developer.apple.com/documentation/security/keychain_services) on macOS.
macOS keychains can store various classes of items.
The item classes supported by oskeyring are:
```{r}
macos_item_classes()
```
`macos_item_add()` adds a new item to a keychain.
It takes objects created with `macos_item()`:
```{r}
it <- macos_item(
"secret",
list(service = "My service", account = "Gabor"),
class = "generic_password"
)
it
```
Items contain the secret itself, and a set of attributes, that depends on the item class.
See `?macos_keychain` for the list of attributes for each class.
``` r
macos_item_add(it)
```
`macos_item_search()` searches for a keychain item:
``` r
macos_item_search(attributes = list(service = "My service"))
```
``` r
#> [[1]]
#> <oskeyring_macos_item: generic_password>
#> account: Gabor
#> creation_date: 2020-10-21 10:01:44
#> label: My service
#> modification_date: 2020-10-21 10:01:44
#> service: My service
```
It does not return the secret itself, unless it is called with `return_data = TRUE`.
This possibly prompts the user for a password.
`macos_item_update()` updates the attributes of existing Keychain items.
`macos_item_delete()` deletes one or more Keychain items.
#### Keychains
macOS supports multiple keychains.
There is always a default keychain, and this is what oskeyring uses by default as well.
There is also a keychain search list, where secrets are looked up by default, and this can contain multiple keychains.
`macos_item_*()` functions have a `keychain` argument to direct or restrict the operation to a specific keychain.
`macos_keychain_create()` creates a new keychain.
`macos_keychain_list()` lists all keychains on the search list.
See more about macOS keychains in the manual: `?macos_keychain`.
## Code of Conduct
Please note that the oskeyring project is released with a
[Contributor Code of Conduct](https://r-lib.github.io/oskeyring/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.
## License
MIT © [RStudio](https://github.com/rstudio)