diff --git a/posts/2024-03-12-storing-secrets-with-the-renviron-file/2024-03-12-storing-secrets-with-the-renviron-file.qmd b/posts/2024-03-12-storing-secrets-with-the-renviron-file/2024-03-12-storing-secrets-with-the-renviron-file.qmd new file mode 100644 index 0000000..9ea1f74 --- /dev/null +++ b/posts/2024-03-12-storing-secrets-with-the-renviron-file/2024-03-12-storing-secrets-with-the-renviron-file.qmd @@ -0,0 +1,121 @@ +--- +title: "Storing secrets with the .Renviron file" +author: "Nicolas Casajus" +date: "2024-03-12" +categories: [r, secret, .renviron, security] +image: "logo-r.png" +toc: true +draft: true +--- + + +## Introduction + +What is a secret? It is usually a password, an username or an API token (key) required by services. For instance, some {{< fa brands r-project >}} packages require an authentication method: + +- [`usethis`](https://usethis.r-lib.org/) requires a token to control the [GitHub API](https://docs.github.com/en/rest) +- [`taxize`](https://docs.ropensci.org/taxize/) requires tokens to query API provided by several taxonomic databases +- [`rwosstarter`](https://frbcesab.github.io/rwosstarter/) requires a token to access the [Web of Science API](https://developer.clarivate.com/apis/wos-starter) +- [`rgbif`](https://docs.ropensci.org/rgbif/) requires an username and a password associated by a [GBIF](https://www.gbif.org/) account + +It's tempting to record secrets as variables in R scripts. But keep this in mind:
+**Never share your secrets with anyone** (this also includes GitHub). + +According to the [documentation of the `httr`](https://httr.r-lib.org/articles/secrets.html) package, there is three secure ways to store your secrets: + +- Ask for the secret each time (no permanent storage). +- Store the secret as an environment variable. +- Use the [`keyring`](https://keyring.r-lib.org/) package and the operating system’s credential store. + +Here we will see how to easily **store secret as an environment variable**. + + +::: {.callout-tip} +## Environment variable + +According to [Wikipedia](https://en.wikipedia.org/wiki/Environment_variable), + +> An _environment variable_ is a user-definable value that can affect the way running processes will behave on a computer. + +In short, it is a way to pass information to a program. Environment variable are used by many programs and operating systems and are made up of a **name-value pair**. +::: + + +## The .Renviron file + +The [{{< fa brands r-project >}} startup process](https://rstats.wtf/r-startup.html) is complex but one special {{< fa brands r-project >}} file is interesting for our purpose: the `.Renviron` file. This file does not contain {{< fa brands r-project >}} code: it only contains environment variables that will be pass to {{< fa brands r-project >}} at startup. It looks like: + +```txt +NAME1=value1 +NAME2=value2 +``` + +We can use this file to store our secrets. To open (and create) this `.Renviron` file, run this command: + +```{r} +#| eval: false + +## Create (if required) and open ~/.Renviron file ---- +utils::file.edit("~/.Renviron") + +## Alternatively, +usethis::edit_r_environ() +``` + +This command will create an `.Renviron` file at the user level (i.e. in his/her `HOME` directory) and all environment variables defined inside will be available for all his/her projects. + +To store a new secret, just add a new line. For instance: + +```txt +GITHUB_PAT='ghp_9999zzz9999zzz' +``` + +**N.B.** add a new empty line at the end of this file otherwise {{< fa brands r-project >}} will ignore it. + + +## Accessing secrets + +To retrieve the value of a secret (and any environment variable), just use the function [`Sys.getenv()`](https://stat.ethz.ch/R-manual/R-patched/library/base/html/Sys.getenv.html). + +```{r} +#| eval: false + +## Get secret value ---- +Sys.getenv("GITHUB_PAT") + +## Handle this secret securely ---- +github_pat <- Sys.getenv("GITHUB_PAT") +``` + +**N.B.** by running `Sys.getenv()` without argument you will print all available envrionment variables. + + +## To go further + +A `.Renviron` file can be created at three different levels: + +- at the system level (named `.Renviron.site`) +- at the user level (`~/.Renviron`) +- at the project level (`.Renviron`) + +At startup {{< fa brands r-project >}} will first read `.Renviron.site`, then `~/.Renviron` and finally the `.Renviron` of the project. +This means that if the same environment variable is defined in `~/.Renviron` (user level) and in the `.Renviron` of the project, the value defined in the `.Renviron` of the project will overwrite the one defined at the user level. + +- If you want to store a secret that be shared among projects, store it in the `~/.Renviron` (user level) +- If you want to store a secret specific to a project, store it in the `.Renviron` (project level) + + +::: {.callout-important} +## `git` and `.Renviron` + +If you create a `.Renviron` file at the project level, **do not forget** to add this file to the `.gitignore`. Otherwise your secret will be published on GitHub. +::: + + +## Resources + +
+
+
+ + diff --git a/posts/2024-03-12-storing-secrets-with-the-renviron-file/logo-r.png b/posts/2024-03-12-storing-secrets-with-the-renviron-file/logo-r.png new file mode 100644 index 0000000..eee17dd Binary files /dev/null and b/posts/2024-03-12-storing-secrets-with-the-renviron-file/logo-r.png differ