Data Encryption

The scenario:

A group of people are working on a sensitive data set that for practical reasons needs to be stored in a place that we’re not 100% happy with the security (e.g., Dropbox), or we’re concerned that files stored in plain text on users computers (e.g. laptops) may lead to the data being compromised.

If the data can be stored encrypted but everyone in the group can still read and write the data then we’ve improved the situation somewhat. But organising for everyone to get a copy of the key to decrypt the data files is non-trivial. The workflow described here aims to simplify this procedure using lower-level functions in the cyphr package.

The general procedure is this:

A person will set up a set of personal keys and a key for the data. The data key will be encrypted with their personal key so they have access to the data but nobody else does. At this point the data can be encrypted.
Additional users set up personal keys and request access to the data. Anyone with access to the data can grant access to anyone else.

Before doing any of this, everyone needs to have ssh keys set up. By default the package will use your ssh keys found at “~/.ssh”; see the main package vignette for how to use this.

For clarity here we will generate two sets of key pairs for two actors Alice and Bob:

path_key_alice <- cyphr::ssh_keygen(password = FALSE)
path_key_bob <- cyphr::ssh_keygen(password = FALSE)

These would ordinarily be on different machines (nobody has access to anyone else’s private key) and they would be password protected. In the function calls below, all the path_user arguments would be omitted.

We’ll store data in the directory data; at present there is nothing there (this is in a temporary directory for compliance with CRAN policies but would ordinarily be somewhere persistent and under version control ideally).

data_dir <- file.path(tempdir(), "data")
dir.create(data_dir)
dir(data_dir)

## character(0)

First, create a personal set of keys. These will be shared across all projects and stored away from the data. Ideally one would do this with ssh-keygen at the command line, following one of the many guides available. A utility function ssh_keygen (which simply calls ssh-keygen for you) is available in this package though. You will need to generate a key on each computer you want access from. Don’t copy the key around. If you lose your user key you will lose access to the data!

Second, create a key for the data and encrypt that key with your personal key. Note that the data key is never stored directly - it is always stored encrypted by a personal key.

cyphr::data_admin_init(data_dir, path_user = path_key_alice)

## Generating data key

## Authorising ourselves

## Adding key dc:de:6c:69:31:a1:58:47:62:45:21:da:f7:9e:d0:d6:fe:7a:61:de:33:85:f1:6f:08:a3:36:c7:40:74:dc:54
##   user: root
##   host: e704ed56b847
##   date: 2024-11-27 03:39:22.730339

## Verifying

The data key is very important. If it is deleted, then the data cannot be decrypted. So do not delete the directory data_dir/.cyphr! Ideally add it to your version control system so that it cannot be lost. Of course, if you’re working in a group, there are multiple copies of the data key (each encrypted with a different person’s personal key) which reduces the chance of total loss.

This command can be run multiple times safely; if it detects it has been rerun and the data key will not be regenerated.

cyphr::data_admin_init(data_dir, path_user = path_key_alice)

## Already set up at /tmp/RtmpamMGk4/data

## Verifying

Third, you can add encrypted data to the directory (or to anywhere really). When run, cyphr::config_data will verify that it can actually decrypt things.

key <- cyphr::data_key(data_dir, path_user = path_key_alice)

This object can be used with all the cyphr functions (see the “cyphr” vignette; vignette("cyphr"))

filename <- file.path(data_dir, "iris.rds")
cyphr::encrypt(saveRDS(iris, filename), key)
dir(data_dir)

## [1] "iris.rds"

The file is encrypted and so cannot be read with readRDS:

readRDS(filename)

## Error in readRDS(filename): unknown input format

But we can decrypt and read it:

head(cyphr::decrypt(readRDS(filename), key))

##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1          5.1         3.5          1.4         0.2  setosa
## 2          4.9         3.0          1.4         0.2  setosa
## 3          4.7         3.2          1.3         0.2  setosa
## 4          4.6         3.1          1.5         0.2  setosa
## 5          5.0         3.6          1.4         0.2  setosa
## 6          5.4         3.9          1.7         0.4  setosa

Fourth, have someone else join in. Recall that to simulate another person here, I’m going to pass an argument path_user = path_key_bob though to the functions. This contains the path to “Bob”’s ssh keypair. If run on an actually different computer this would not be needed; this is just to simulate two users in a single session for this vignette (see minimal example below where this is simulated). Again, typically this user would also not use the cyphr::ssh_keygen function but use the ssh-keygen command from their shell.

We’re going to assume that the user can read and write to the data. This is the case for my use case where the data are stored on dropbox and will be the case with GitHub based distribution, though there would be a pull request step in here.

This user cannot read the data, though trying to will print a message explaining how you might request access:

key_bob <- cyphr::data_key(data_dir, path_user = path_key_bob)

But bob is your collaborator and needs access! What they need to do is run:

cyphr::data_request_access(data_dir, path_user = path_key_bob)

## A request has been added

## Email someone with access to add you
## 
##     hash: 64:1f:e8:6a:45:7a:88:98:99:3d:f1:b9:f5:f2:c9:52:38:c5:85:a7:4d:71:09:c6:04:c7:9b:b7:fc:5c:be:a0
## 
## If you are using git, you will need to commit and push first:
## 
##     git add .cyphr
##     git commit -m "Please add me to the dataset"
##     git push

(again, ordinarily you would not need the bob bit here)

The user should the send an email to someone with access and quote the hash in the message above.

Fifth, back on the first computer we can authorise the second user. First, see who has requested access:

req <- cyphr::data_admin_list_requests(data_dir)
req

## 1 key:
##   64:1f:e8:6a:45:7a:88:98:99:3d:f1:b9:f5:f2:c9:52:38:c5:85:a7:4d:71:09:c6:04:c7:9b:b7:fc:5c:be:a0
##     user: root
##     host: e704ed56b847
##     date: 2024-11-27 03:39:22.840237

We can see the same hash here as above (641fe86a457a8898993df1b9f5f2c95238c585a74d7109c604c79bb7fc5cbea0)

…and then grant access to them with the cyphr::data_admin_authorise function.

cyphr::data_admin_authorise(data_dir, yes = TRUE, path_user = path_key_alice)

## There is 1 request for access

## Adding key 64:1f:e8:6a:45:7a:88:98:99:3d:f1:b9:f5:f2:c9:52:38:c5:85:a7:4d:71:09:c6:04:c7:9b:b7:fc:5c:be:a0
##   user: root
##   host: e704ed56b847
##   date: 2024-11-27 03:39:22.840237

## Added 1 key

## If you are using git, you will need to commit and push:
## 
##     git add .cyphr
##     git commit -m "Authorised root"
##     git push

If you do not specify yes = TRUE will prompt for confirmation at each key added.

This has cleared the request queue:

cyphr::data_admin_list_requests(data_dir)

## (empty)

and added it to our set of keys:

cyphr::data_admin_list_keys(data_dir)

## 2 keys:
##   64:1f:e8:6a:45:7a:88:98:99:3d:f1:b9:f5:f2:c9:52:38:c5:85:a7:4d:71:09:c6:04:c7:9b:b7:fc:5c:be:a0
##     user: root
##     host: e704ed56b847
##     date: 2024-11-27 03:39:22.840237
##   dc:de:6c:69:31:a1:58:47:62:45:21:da:f7:9e:d0:d6:fe:7a:61:de:33:85:f1:6f:08:a3:36:c7:40:74:dc:54
##     user: root
##     host: e704ed56b847
##     date: 2024-11-27 03:39:22.730339

Finally, as soon as the authorisation has happened, the user can encrypt and decrypt files:

key_bob <- cyphr::data_key(data_dir, path_user = path_key_bob)
head(cyphr::decrypt(readRDS(filename), key_bob))

##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1          5.1         3.5          1.4         0.2  setosa
## 2          4.9         3.0          1.4         0.2  setosa
## 3          4.7         3.2          1.3         0.2  setosa
## 4          4.6         3.1          1.5         0.2  setosa
## 5          5.0         3.6          1.4         0.2  setosa
## 6          5.4         3.9          1.7         0.4  setosa

Minimal example

As above, but with less discussion:

Setup, on Alice’s computer:

cyphr::data_admin_init(data_dir, path_user = path_key_alice)

## Generating data key

## Authorising ourselves

## Adding key dc:de:6c:69:31:a1:58:47:62:45:21:da:f7:9e:d0:d6:fe:7a:61:de:33:85:f1:6f:08:a3:36:c7:40:74:dc:54
##   user: root
##   host: e704ed56b847
##   date: 2024-11-27 03:39:22.944336

## Verifying

Get the data key key:

key <- cyphr::data_key(data_dir, path_user = path_key_alice)

Encrypt a file:

cyphr::encrypt(saveRDS(iris, filename), key)

Request access, on Bob’s computer:

hash <- cyphr::data_request_access(data_dir, path_user = path_key_bob)

## A request has been added

## Email someone with access to add you
## 
##     hash: 64:1f:e8:6a:45:7a:88:98:99:3d:f1:b9:f5:f2:c9:52:38:c5:85:a7:4d:71:09:c6:04:c7:9b:b7:fc:5c:be:a0
## 
## If you are using git, you will need to commit and push first:
## 
##     git add .cyphr
##     git commit -m "Please add me to the dataset"
##     git push

Alice authorises this request::

cyphr::data_admin_authorise(data_dir, yes = TRUE, path_user = path_key_alice)

## There is 1 request for access

## Adding key 64:1f:e8:6a:45:7a:88:98:99:3d:f1:b9:f5:f2:c9:52:38:c5:85:a7:4d:71:09:c6:04:c7:9b:b7:fc:5c:be:a0
##   user: root
##   host: e704ed56b847
##   date: 2024-11-27 03:39:22.989555

## Added 1 key

## If you are using git, you will need to commit and push:
## 
##     git add .cyphr
##     git commit -m "Authorised root"
##     git push

Bob can get the data key:

key <- cyphr::data_key(data_dir, path_user = path_key_bob)

Bob can read the secret data:

head(cyphr::decrypt(readRDS(filename), key))

##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1          5.1         3.5          1.4         0.2  setosa
## 2          4.9         3.0          1.4         0.2  setosa
## 3          4.7         3.2          1.3         0.2  setosa
## 4          4.6         3.1          1.5         0.2  setosa
## 5          5.0         3.6          1.4         0.2  setosa
## 6          5.4         3.9          1.7         0.4  setosa

Details & disclosure

Encryption does not work through security through obscurity; it works because we can rely on the underlying maths enough to be open about how things are stored and where.

Most encryption libraries require some degree of security in the underlying software. Because of the way R works this is very difficult to guarantee; it is trivial to rewrite code in running packages to skip past verification checks. So this package is not designed to (or able to) avoid exploits in your running code; an attacker could intercept your private keys, the private key to the data, or skip the verification checks that are used to make sure that the keys you load are what they say they are. However, the data are safe; only people who have keys to the data will be able to read it.

cyphr uses two different encryption algorithms; it uses RSA encryption via the openssl package for user keys, because there is a common file format for these keys so it makes user configuration easier. It uses the modern sodium package (and through that the libsodium library) for data encryption because it is very fast and simple to work with. This does leave two possible points of weakness as a vulnerability in either of these libraries could lead to an exploit that could allow decryption of your data.

Each user has a public/private key pair. Typically this is in ~/.ssh/id_rsa.pub and ~/.ssh/id_rsa, and if found these will be used. Alternatively the location of the keypair can be stored elsewhere and pointed at with the USER_KEY or USER_PUBKEY environment variables. The key may be password protected (and this is recommended!) and the password will be requested without ever echoing it to the terminal.

The data directory has a hidden directory .cyphr in it.

dir(data_dir, all.files = TRUE, no.. = TRUE)

## [1] ".cyphr"   "iris.rds"

This does not actually need to be stored with the data but it makes sense to (there are workflows where data is stored remotely where storing this directory might make sense). The “keys” directory contains a number of files; one for each person who has access to the data.

dir(file.path(data_dir, ".cyphr", "keys"))

## [1] "641fe86a457a8898993df1b9f5f2c95238c585a74d7109c604c79bb7fc5cbea0"
## [2] "dcde6c6931a15847624521daf79ed0d6fe7a61de3385f16f08a336c74074dc54"

names(cyphr::data_admin_list_keys(data_dir))

## [1] "641fe86a457a8898993df1b9f5f2c95238c585a74d7109c604c79bb7fc5cbea0"
## [2] "dcde6c6931a15847624521daf79ed0d6fe7a61de3385f16f08a336c74074dc54"

(the file test is a small file encrypted with the data key used to verify everything is working OK).

Each file is stored in RDS format and is a list with elements:

user: the reported user name of the person who created request for data
host: the reported computer name
date: the time the request was generated
pub: the RSA public key of the user
key: the data key, encrypted with the user key. Without the private key, this cannot be used. With the user’s private key this can be used to generate the symmetric key to the data.

h <- names(cyphr::data_admin_list_keys(data_dir))[[1]]
readRDS(file.path(data_dir, ".cyphr", "keys", h))

## $user
## [1] "root"
## 
## $host
## [1] "e704ed56b847"
## 
## $date
## [1] "2024-11-27 03:39:22 UTC"
## 
## $pub
## [2048-bit rsa public key]
## md5: 8c0076bb55123aa7f00583f9a0bcca7e
## sha256: 641fe86a457a8898993df1b9f5f2c95238c585a74d7109c604c79bb7fc5cbea0
## 
## $key
##   [1] 64 a8 66 15 f0 dc 05 c1 c1 2e a7 2e 93 82 7f d7 74 31 8a f0 9b 8c 6d 49 24
##  [26] 04 61 c6 35 ba a8 bb 36 db aa c0 24 a9 17 3e 47 84 d7 fb 94 68 47 af 17 53
##  [51] 38 99 40 bc 0d b9 61 e1 88 48 45 5a f0 7b 43 79 5e 60 17 c2 ba 63 24 b3 99
##  [76] df 98 35 9d 8f b8 d6 8b 35 59 42 98 f0 12 51 e0 51 c0 af fd a8 64 c2 87 76
## [101] f9 01 a6 7e 77 f7 02 83 da 58 cc 2a a5 3f b6 6d 9b d2 0a 39 7a 88 ce 62 4a
## [126] 41 44 c2 5d 3c e3 fa 46 73 7b a5 e2 73 fe ce 77 fe 9b 91 97 4d 89 54 e7 97
## [151] a1 c4 15 74 b5 0d 33 31 4f 75 d5 7f 1c 54 49 25 0c 84 28 de 91 a8 6a 38 9f
## [176] 8f 0c 1c c7 db ab 40 f1 e0 8f 74 a7 b2 da ec d9 66 ed 77 a1 5c 74 ae ec 1f
## [201] 72 0e d7 ec f3 4f ed 09 2d ec c9 27 42 32 7b ef a6 32 60 f6 02 01 a2 30 38
## [226] 7c 02 41 14 0b 4a 5f 61 06 f8 59 9f 58 13 08 10 43 ec e7 b9 6d e6 f1 6f a6
## [251] 64 aa 3f 71 4b e1

You can see that the hash of the public key is the same as name of the stored file here (which is used to prevent collisions when multiple people request access at the same time).

## [1] "641fe86a457a8898993df1b9f5f2c95238c585a74d7109c604c79bb7fc5cbea0"

When a request is posted it is an RDS file with all of the above except for the key element, which is added during authorisation.

(Note that the verification relies on the package code not being attacked, and given R’s highly dynamic nature an attacker could easily swap out the definition for the verification function with something that always returns TRUE.)

When an authorised user creates the data_key object (which allows decryption of the data) secret will:

read their private user key (probably from ~/.ssh/id_rsa)
read the encrypted data key from the data directory (the $key element from the list above).
decrypt this data key using their user key to yield the the data symmetric key.

Limitations

In the Dropbox scenario, non-password protected keys will afford only limited protection. This is because even though the keys and data are stored separately on Dropbox, they will be in the same place on a local computer; if that computer is lost then the only thing preventing an attacker recovering the data is security through obscurity (the data would appear to be random junk but they will be able to run your analysis scripts as easily as you can). Password protected keys will improve this situation considerably as without a password the data cannot be recovered.

The data is not encrypted during a running R session. R allows arbitrary modification of code at runtime so this package provides no security from the point where the data can be decrypted. If your computer was compromised then stealing the data while you are running R should be assumed to be straightforward.