Raw System Credential Store Access from R
Install the package from CRAN:
install.packages("oskeyring")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.
oskeyring uses the API defined in wincred.h
on Windows. The Windows credential store contains various credential
types. The ones supported by oskeyring are:
windows_item_types()#> [1] "generic" "domain_password"
#> [3] "domain_certificate" "domain_visible_password"windows_item_write() adds or updates a credential in the
credential store. It takes objects created with
windows_item() :
it <- windows_item("secret", "my-host-password")
it#> <oskeyring_windows_item: generic>
#> target_name: my-host-password
#> persist: local_machine
#> credential_blob: <-- hidden -->windows_item_write(it)windows_item_read() reads a credential from the
credential store, the return value includes the secret as well:
windows_item_read("my-host-password")#> <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.
oskeyring uses the Keychain API on macOS. macOS keychains can store various classes of items. The item classes supported by oskeyring are:
macos_item_classes()#> [1] "generic_password" "internet_password"macos_item_add() adds a new item to a keychain. It takes
objects created with macos_item():
it <- macos_item(
"secret",
list(service = "My service", account = "Gabor"),
class = "generic_password"
)
it#> <oskeyring_macos_item: generic_password>
#> account: Gabor
#> service: My service
#> value: <-- hidden -->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.
macos_item_add(it)macos_item_search() searches for a keychain item:
macos_item_search(attributes = list(service = "My service"))#> [[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 serviceIt 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.
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.
Please note that the oskeyring project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
MIT © RStudio