-
Notifications
You must be signed in to change notification settings - Fork 10
/
README.Rmd
203 lines (138 loc) · 9.58 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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
```{r, setup, echo = FALSE, message = FALSE}
knitr::opts_chunk$set(
tidy = FALSE,
error = FALSE,
fig.width = 8,
fig.height = 8)
```
# cyphr
<!-- badges: start -->
[](https://www.repostatus.org/#active)
[](https://github.com/ropensci/cyphr/actions)
[](https://app.codecov.io/github/ropensci/cyphr?branch=master)
[](https://cran.r-project.org/package=cyphr)
[](https://github.com/ropensci/software-review/issues/114)
<!-- badges: end -->
High-level functions for supporting encryption and decryption of data from R. This allows secure storage and exchange of information, while trying to keep the encryption/decryption code from taking over your analyses. `cyphr` wraps the lower-level support from [`sodium`](https://github.com/r-lib/sodium) and [`openssl`](https://github.com/jeroen/openssl). This package is designed to be easy to use, rather than the most secure thing (you're using R, remember - for examples of what `cyphr` can't protect against see [`jammr`](https://github.com/Ironholds/jammr), [`rpwnd`](https://github.com/hrbrmstr/rpwnd) and [`evil.R`](https://github.com/romainfrancois/evil.R).)
`cyphr` provides high level functions to:
* Encrypt and decrypt
* **strings**: `encrypt_string` / `decrypt_string`
* **objects**: `encrypt_object` / `decrypt_object`
* **raw data**: `encrypt_data` / `decrypt_data`
* **files**: `encrypt_file` / `decrypt_file`
* User-friendly wrappers (`encrypt` and `decrypt`) around R's file reading and writing functions that enable transparent encryption (support included for `readRDS`/`writeRDS`, `read.csv`/`write.csv`, etc).
The package aims to make encrypting and decrypting as easy as
```{r, eval = FALSE}
cyphr::encrypt(save.csv(dat, "file.csv"), key)
```
and
```{r, eval = FALSE}
dat <- cyphr::decrypt(read.csv("file.csv", stringsAsFactors = FALSE), key)
```
In addition, the package implements a workflow that allows a group to securely share data by encrypting it with a shared ("symmetric") key that is in turn encrypted with each users ssh keys. The use case is a group of researchers who are collaborating on a dataset that cannot be made public, for example containing sensitive data. However, they have decided or need to store it in a setting that they are not 100% confident about the security of the data. So encrypt the data at each read/write.
## Installation
Install `cyphr` from CRAN with
```{r, eval = FALSE}
install.packages("cyphr")
```
To install a development version from github, you can use `remotes`
To install `cyphr` from github:
```{r, eval = FALSE}
remotes::install_github("ropensci/cyphr", upgrade = FALSE)
```
## Scope
The scope of the package is to protect data that has been saved to disk. It is not designed to stop an attacker targeting the R process itself to determine the contents of sensitive data. The package does try to prevent you accidentally saving to disk the contents of sensitive information, including the keys that could decrypt such information.
## Objects to handle keys:
Decide on a style of encryption and create a key object
* `key_sodium`: Symmetric encryption, using [sodium](https://cran.r-project.org/package=sodium) -- everyone shares the same key (which must be kept secret!) and can encrypt and decrypt data with it. This is used as a building block but is inflexible because of the need to keep the key secret.
* `key_openssl`: Symmetric encryption using [openssl](https://cran.r-project.org/package=openssl)
* `keypair_sodium`: Public key encryption with [sodium](https://cran.r-project.org/package=sodium) -- this lets people encrypt messages using your public key that only you can read using your private key.
* `keypair_openssl`: Public key encryption, using [openssl](https://cran.r-project.org/package=openssl), which has the big advantage that many people already have compatible (ssh) keys in standard places with standard file formats (see `?encrypt_envelope` in the the `openssl` package).
`cyphr` does not include wrappers for key generation for sodium - sodium keys do not have a file format: So a secret symmetric key in `sodium` might be:
```{r}
k <- sodium::keygen()
k
```
With this key we can create the `key_sodium` object:
```{r}
key <- cyphr::key_sodium(k)
key
```
If the key was saved to file that would work too:
If you load a password protected ssh key you will be prompted for your passphrase. `cyphr` will ensure that this is not echoed onto the console.
```{r, eval = FALSE}
key <- cyphr::key_openssl()
## Please enter private key passphrase:
key
```
## Encrypt / decrypt a file
If you have files that already exist and you want to encrypt or decrypt, the functions `cyphr::encrypt_file` and `cyphr::decrypt_file` will do that (these are workhorse functions that are used internally throughout the package)
```{r}
saveRDS(iris, "myfile")
cyphr::encrypt_file("myfile", key, "myfile.encrypted")
```
The file is encrypted now:
```{r, error = TRUE}
readRDS("myfile.encrypted")
```
Decrypt the file and read it:
```{r}
cyphr::decrypt_file("myfile.encrypted", key, "myfile.clear")
identical(readRDS("myfile.clear"), iris)
```
```{r, echo = FALSE, results = "hide"}
file.remove("myfile", "myfile.encrypted", "myfile.clear")
```
## Wrappers around R's file functions
Encrypting files like the above risks leaving a cleartext (i.e., unencrypted) version around. If you want to wrap the output of something like `write.csv` or `saveRDS` you really have no choice but to write out the file first, encrypt it, and delete the clear version. Making sure that this happens even if a step fails is error prone and takes a surprising number of repetitive lines of code.
Alternatively, to encrypt the output of a file producing command, just wrap it in `cyphr::encrypt`
```{r}
cyphr::encrypt(saveRDS(iris, "myfile.rds"), key)
```
Then to decrypt the a file to feed into a file consuming command, wrap it in `cyphr::decrypt`
```{r}
dat <- cyphr::decrypt(readRDS("myfile.rds"), key)
```
The round-trip preserves the data:
```{r}
identical(dat, iris) # yay
```
But without the key, it cannot be read:
```{r, error = TRUE}
readRDS("myfile.rds")
```
```{r, echo = FALSE, results = "hide"}
file.remove("myfile.rds")
```
The above commands work through computing on the language, rewriting the `readRDS` and `saveRDS` commands. Commands for reading and writing tabular and plain text files (`read.csv`, `readLines`, etc) are also supported, and the way the rewriting is done is designed to be extensible.
The argument to the wrapped functions can be connection objects. In this case the *actual* command is written to a file and the contents of that file are encrypted and written to the connection. When reading/writing multiple objects from/to a single connection though, this is likely to go very badly.
### Supporting additional functions
The functions supported so far are:
* `readLines` / `writeLines`
* `readRDS` / `writeRDS`
* `read` / `save`
* `read.table` / `write.table`
* `read.csv` / `read.csv2` / `write.csv`
* `read.delim` / `read.delim2`
However, there are bound to be more functions that could be useful to add here (e.g., `readxl::read_excel`). Either pass the name of the file argument to `cyphr::encrypt` / `cyphr::decrypt` as
```r
cyphr::decrypt(readxl::read_excel("myfile.xlsx"), key, file_arg = "path")
```
or *register* the function with the package using `rewrite_register`:
```r
cyphr::rewrite_register("readxl", "read_excel", "path")
```
Then you can use
```r
cyphr::decrypt(readxl::read_excel("myfile.xlsx"), key)
```
to decrypt the file (these are equivalent, but the former will likely be more convenient if you're only dealing with a couple of files, the latter will be more convenient if you are dealing with many).
## Collaborating with encrypted data
Even with high-level functions to ease encrypting and decrypting things given a key, there is some work to be done to distribute a set of keys across a group of people who are working together so that everyone can encrypt and decrypt the data but so that the keys themselves are not compromised.
The package contains support for a group of people are working on a sensitive data set. The data will be stored with a symmetric key. However, we never actually store the key directly, instead we'll store a copy for each user that is encrypted with the user's key. Any user with access to the data can authorise another user to access the data. This is described in more detail in the [vignette](https://docs.ropensci.org/cyphr/articles/data.html) (in R: `vignette("data", package = "cyphr")`).
## Why are wrappers needed?
The low level functions in `sodium` and `openssl` work with raw data, for generality. Few users encounter raw vectors in their typical use of R, so these require serialisation. Most of the encryption involves a little extra random data (the "nonce" in `sodium` and similar additional pieces with `openssl`). These need storing with the data, and then separating from the data when decryption happens.
## Licence
MIT © [Rich FitzJohn](https://github.com/richfitz).
Please note that this project is released with a [Contributor Code of Conduct](https://github.com/ropensci/cyphr/blob/master/CONDUCT.md). By participating in this project you agree to abide by its terms.
[](https://ropensci.org)