Introduction

It is not good practice to store credentials in clear text as it is a security risk. The keyring package provides an approach to managing crendentials securely.

Example

The following will create a local keyring file using an approach compatible with all platform (macOS, Windows etc). The following command indicates that the backend to be used is a file. You can insert this command as a line in the .Rprofile file (which is located in your home directory) and this will ensure that all projects use a file version of the keyring.

options(keyring_backend=keyring::backend_file)

When you create a keyring, the keyring file will be stored in a platform-specific location on your drive. For macOS, this is in the user application data, typically found under ~/Library/Application Support/ in a directory called r-keyring. It is unclear to me where the file will be stored on other platforms.

You could create a new keyring that has the name foobar with the following command, noting that this will overwrite any existing keyring of that same name.

keyring::keyring_create("foobar")

In the event that there already exists a keyring file called foobar you will be prompted to see if you really want to overwrite the file. You will then be asked to provide a password for the new keyring store.

An alternative approach, is to instantiate a new backend_file object and call the keyring_create method on that. You will get the same prompts that did previously, namely you will be asked if you really want to overwrite and then to provide a password for the new file.

kb <- keyring::backend_file$new()
kb$keyring_create("foobar")

Once you have created the keyring, you can then add, update and delete new keys. Note that you have to specify a default keyring otherwise the API will ask you to create one every time you make call. Alternatively, you can just pass the name of the keyring into most of the methods below. When you try to unlock the keyring, you will be prompted to enter the password that you set up previously.

Once the keyring is unlocked, you can edit and retrieve from it until you restart your R session, clear the keyring from memory or lock the keyring with kb$keyring_lock(). However, note that you can still list the service and username contents of a locked keyring.

kb <- keyring_unlock("foobar")
# this just means that you don't have to pass the keyring name to all methods
kb$keyring_set_default("foobar")

Now you can add a key with the following command. The service_name is a service that the credentials pertain to. This might be a db that you have implemented, or website portal etc. The (optional) username is provided as is the password you want to store.

kb$set_with_value("service_name1", username = "fred", password = "secret1")
kb$set_with_value("service_name2", username = "billy", password = "secret2")
# Shows the status of the keyring store
kb$keyring_list()

The last command provides the following output

  keyring num_secrets locked
1  foobar           2  FALSE

To view the services and usernames stored in the keyring

kb$list()
        service username
1 service_name1     fred
2 service_name2    billy

and to get the username from a particular service:

kb$list()$username[kb$list()$service == "service_name1"]

To then access the secret for the service use

kb$get("service_name1")
[1] "secret1"

The secret can be updated at any time with

kb$set_with_value("service_name1", username = "fred", password = "secret1new")
kb$get("service_name1")
[1] "secret1new"

To delete a key from the keyring use the following command. Here I am passing in the name of the keyring, but technically, this is not required as I specified the default keyring earlier.

kb$delete("service_name1", username = "fred", keyring = "foobar")
kb$list()
        service username
1 service_name2    billy

If I want to remove the entire keyring store along with all its contents, I can use the following command. However, note that this may leave a zero-sized lockfile (*.lck extension) in the r-keyring folder, but it appears to be benign.

kb$keyring_lock()
keyring::keyring_delete(keyring = "foobar")

The above demonstrated the basic use of the keyring package using a file based backend.