Introduction

Rich FitzJohn

2025-02-07

This package tries to smooth over some of the differences in encryption approaches (symmetric vs. asymmetric, sodium vs. openssl) to provide a simple interface for users who just want to encrypt or decrypt things.

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.

This vignette works through the basic functionality of the package. It does not offer much in the way of an introduction to encryption itself; for that see the excellent vignettes in the openssl and sodium packages (see vignette("crypto101") and vignette("bignum") for information about how encryption works). This package is a wrapper around those packages in order to make them more accessible.

Keys and the like

To encrypt anything we need a key. There are two sorts of key “types” we will concern ourselves with here “symmetric” and “asymmetric”.

We support symmetric keys and asymmetric key pairs from the openssl and sodium packages (which wrap around industry-standard cryptographic libraries) - this vignette will show how to create and load keys of different types as they’re used.

The openssl keys have the advantage of a standard key format, and that many people (especially on Linux and macOS) have a keypair already (see below if you’re not sure if you do). The sodium keys have the advantage of being a new library, starting from a clean slate rather than carrying with it accumulated ideas from the last 20 years of development.

The idea in cyphr is that we can abstract away some differences in the types of keys and the functions that go with them to create a standardised interface to encrypting and decrypting strings, R objects, files and raw vectors. With that, we can then create wrappers around functions that create files and simplify the process of adding encryption into a data workflow.

Below, I’ll describe the sorts of keys that cyphr supports and in the sections following describe how these can be used to actually do some encryption.

Symmetric encryption

Illustration of Symmetric Encryption
Illustration of Symmetric Encryption

This is the simplest form of encryption because everyone has the same key (like a key to your house or a single password). This raises issues (like how do you store the key without other people reading it) but we can deal with that below.

openssl

To generate a key with openssl, you can use:

k <- openssl::aes_keygen()

which generates a raw vector

k
## aes 7f:ff:d5:4a:19:54:ea:a1:9e:72:ab:4d:d6:1b:c0:ea

(this prints nicely but it really is stored as a 16 byte raw vector).

The encryption functions that this key supports are openssl::aes_cbc_encrypt, openssl::aes_ctr_encrypt and openssl::aes_gcm_encrypt (along with the corresponding decryption functions). The cyphr package tries to abstract this away by using a wrapper `cyphr::key_openssl

key <- cyphr::key_openssl(k)
key
## <cyphr_key: openssl>

With this key, one can encrypt a string with cyphr::encrypt_string:

secret <- cyphr::encrypt_string("my secret string", key)

and decrypt it again with cyphr::decrypt_string:

cyphr::decrypt_string(secret, key)
## [1] "my secret string"

See below for more functions that use these key objects.

sodium

The interface is almost identical using sodium symmetric keys. To generate a symmetric key with libsodium you would use sodium::keygen

k <- sodium::keygen()

This is really just a raw vector of length 32, without even any class attribute!

The encryption functions that this key supports are sodium::data_encrypt and sodium::data_decrypt. To create a key for use with cyphr that knows this, use:

key <- cyphr::key_sodium(k)
key
## <cyphr_key: sodium>

This key can then be used with the high-level cyphr encryption functions described below.

Asymmetric encryption (“key pairs”)

Illustration of Asymmetric Encryption
Illustration of Asymmetric Encryption

With asymmetric encryption everybody has two keys that differ from everyone else’s key. One key is public and can be shared freely with anyone you would like to communicate with and the other is private and must never be disclosed.

In the sodium package there is a vignette (vignette("crypto101")) that gives a gentle introduction to how this all works. In practice, you end up creating a pair of keys for yourself. Then to encrypt or decrypt something you encrypt messages with the recipient’s public key and they (and only they) can decrypt it with their private key.

One use for asymmetric encryption is to encrypt a shared secret (such as a symmetric key) - with this you can then safely store or communicate a symmetric key without disclosing it.

openssl

Let’s suppose that we have two parties “Alice” and “Bob” who want to talk with one another. For demonstration purposes we need to generate SSH keys (with no password) in temporary directories (to comply with CRAN policies). In a real situation these would be on different machines (Alice has no access to Bob’s key!) and these keys would be password protected.

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

Note that each directory contains a public key (id_rsa.pub) and a private key (id_rsa).

dir(path_key_alice)
## [1] "id_rsa"     "id_rsa.pub"
dir(path_key_bob)
## [1] "id_rsa"     "id_rsa.pub"

Below, the full path to the key (e.g., .../id_rsa) could be used in place of the directory name if you prefer.

If Alice wants to send a message to Bob she needs to use her private key and his public key

pair_a <- cyphr::keypair_openssl(path_key_bob, path_key_alice)
pair_a
## <cyphr_keypair: openssl>

with this pair she can write a message to “bob”:

secret <- cyphr::encrypt_string("secret message", pair_a)

The secret is now just a big pile of bytes

secret
##   [1] 58 0a 00 00 00 03 00 04 04 02 00 03 05 00 00 00 00 05 55 54 46 2d 38 00 00
##  [26] 02 13 00 00 00 04 00 00 00 18 00 00 00 10 20 c8 45 e5 bc ed a4 ac ed e8 88
##  [51] fd 66 a1 19 85 00 00 00 18 00 00 01 00 ab 90 28 3c 76 58 59 38 12 b0 e5 05
##  [76] 5e fd eb d8 13 ba 80 ad 9b ef 89 f1 34 a2 79 2b 3a ac b8 e0 68 54 db 64 42
## [101] 01 e2 16 6c ae 42 d5 1d 63 54 0c 49 f8 af 81 d6 4a f8 7b 8a 5a a1 7a 4f aa
## [126] 72 2f a7 4c e2 ae 43 25 6d d8 f1 56 5e 4a c4 1f 6d 0b 37 4f 7f 54 66 1d 3e
## [151] e4 ca 64 ed e8 f5 02 76 e3 ed f6 63 65 da a4 82 8e ad b9 55 1e 8f 2e 37 fc
## [176] d9 cb 42 6b eb 11 c2 76 66 f0 88 fc 6f 63 88 2c 25 8c 7c 92 a3 b8 8e 4c cc
## [201] 3c f4 5c e1 e6 cd 99 7b 64 a4 57 b8 21 79 a5 b4 f3 4b 8d bd 60 f2 1c a7 98
## [226] 29 53 3d a9 63 91 fe a8 ff ba 69 13 d6 d4 27 f1 e0 70 d6 5c 39 24 b6 47 f9
## [251] 78 ae e6 8b c6 6a 7a a3 6e cb 82 f6 31 5f 18 1e 09 15 4e 3b 65 ec c0 27 e4
## [276] d3 03 d2 4d 51 8a 2d 15 a0 28 60 28 4d a1 7b 41 ea 6b 62 b6 f2 32 e7 98 ee
## [301] 39 89 98 80 21 6c 06 59 82 3e 31 8c 07 74 08 bb e7 50 95 00 00 00 18 00 00
## [326] 00 10 7d 6b bd a0 b1 23 2c 57 33 cc 57 ce 48 d1 dc ea 00 00 00 18 00 00 01
## [351] 00 9b 3d cf 13 c1 25 95 75 e8 92 c8 3d ad 51 71 67 16 1d 05 30 bb 79 26 af
## [376] 1e b0 e7 59 00 4b 7f 81 5c 59 68 77 d3 83 aa 1b 35 0d 44 c0 64 6d 4d 7a 91
## [401] bf a6 a5 99 1f 5e da 2d 96 5b 31 e2 f6 7d ed c1 a7 c1 82 fd 50 df 1b 3d a5
## [426] 3f ef b2 1b 4f 9b 96 1f 44 83 12 22 e6 65 9e ac db a2 a6 ce 0b 21 5f 1b 90
## [451] f4 50 e1 2e 05 4c cc 8c e5 01 23 0f b5 d0 d9 e0 e6 05 b8 4a 47 41 49 f8 7d
## [476] 9e d5 1f a6 06 bf 02 97 95 61 98 a2 df 59 cc bb a7 81 eb 7f 6c e9 b1 18 ee
## [501] ed 23 c7 ef da c1 9f 71 e5 ac af f5 d1 b8 a2 c5 d4 cc 3d 13 74 ae 08 d0 11
## [526] 2a bb 7d 1b bb 5a 53 5d 9f b6 7d da 4e 08 ee 63 b0 46 45 c3 f2 28 5c 13 f7
## [551] d7 55 c0 d3 6e 75 79 70 57 c1 84 e0 7c 2c 39 0f b7 65 78 7a eb 80 63 6a 7d
## [576] ff e3 d4 f9 03 ea 85 c2 92 7f b2 18 24 1b 34 76 da 2c fc 4f 07 16 99 4c 9c
## [601] f9 b3 6d 4b 88 97 11 00 00 04 02 00 00 00 01 00 04 00 09 00 00 00 05 6e 61
## [626] 6d 65 73 00 00 00 10 00 00 00 04 00 04 00 09 00 00 00 02 69 76 00 04 00 09
## [651] 00 00 00 07 73 65 73 73 69 6f 6e 00 04 00 09 00 00 00 04 64 61 74 61 00 04
## [676] 00 09 00 00 00 09 73 69 67 6e 61 74 75 72 65 00 00 00 fe

Note that unlike symmetric encryption above, Alice cannot decrypt her own message:

cyphr::decrypt_string(secret, pair_a)
## Error in openssl::decrypt_envelope(x$data, x$iv, x$session, key): OpenSSL error: 00A253F5D97F0000:error:03000082:digital envelope routines:EVP_CIPHER_CTX_set_key_length:invalid key length:crypto/evp/evp_enc.c:1055:

For Bob to read the message, he uses his private key and Alice’s public key (which she has transmitted to him previously).

pair_b <- cyphr::keypair_openssl(path_key_alice, path_key_bob)

With this keypair, Bob can decrypt Alice’s message

cyphr::decrypt_string(secret, pair_b)
## [1] "secret message"

And send one back of his own:

secret2 <- cyphr::encrypt_string("another message", pair_b)
secret2
##   [1] 58 0a 00 00 00 03 00 04 04 02 00 03 05 00 00 00 00 05 55 54 46 2d 38 00 00
##  [26] 02 13 00 00 00 04 00 00 00 18 00 00 00 10 b0 c6 c4 46 96 c1 4c 69 ea f7 e5
##  [51] 42 b3 06 85 44 00 00 00 18 00 00 01 00 48 e9 3e 82 9d 62 8e eb e1 0e be eb
##  [76] a1 51 df 6f 39 31 8b 0c f7 05 0f ce e1 40 8a ee b1 bc 39 31 ac 90 b3 26 d2
## [101] 4a 0d 15 cc 83 a2 f3 15 b7 f9 e1 61 c8 20 3d e4 25 4e 0d 91 e4 00 ed eb 0f
## [126] 4f 76 f4 c5 c7 51 44 3f bf b4 19 93 e9 db 6f 24 d1 c7 7b e7 3b 3a 45 a9 bf
## [151] 96 12 08 93 aa 79 6c f7 35 c2 b7 4f 27 db 24 e5 c2 da c1 24 1c b9 88 a7 b5
## [176] e9 bc ac a1 f0 10 0d db cb 67 04 fb 11 6e 70 b4 1d 06 37 47 33 08 c9 57 4e
## [201] 93 ee 5c 9c 85 5f df 25 41 7d a4 18 28 6b c1 f7 63 27 d7 32 d1 76 e2 0d 9a
## [226] 1c 86 c6 5c 1b 37 5f 2b cf 9f fa f0 da 3e 9e 8c 9b fc 9a e6 02 70 a2 18 53
## [251] db ac 92 f9 12 64 a5 8e f2 c5 47 e5 e9 f8 6c 91 74 17 c0 9d ee 67 f4 97 72
## [276] 8e d1 60 d5 aa ae ac c0 0d 2b f5 fd 5a 0f e2 b2 b1 ee f9 43 35 66 28 09 31
## [301] 86 cd 81 32 f5 f3 91 07 76 d5 75 b7 b3 19 2f e4 f8 a4 5d 00 00 00 18 00 00
## [326] 00 10 ed 8b d9 c7 ff 35 e8 0b 9b 3c 8a 1e 81 e5 3f ed 00 00 00 18 00 00 01
## [351] 00 4e a0 06 2c cd a7 e8 e6 48 2e 41 48 ea 4b a3 6e 21 af 5d 2b 6e ea f4 7d
## [376] c8 d5 84 7c 73 66 ea a9 d6 d4 20 ce 98 fe 3a f9 d0 74 e7 79 c3 bb bc 0e 29
## [401] c2 ce 6c fc 79 4e ae c6 6d 82 26 19 97 75 d5 3b 4d f7 e4 58 7a ea 37 c4 a9
## [426] 34 ba 60 4c ed 11 ab 05 98 91 09 8a a3 79 60 66 a3 a6 ab ed fa 86 6a c4 af
## [451] 62 23 5e c7 ab 3d ff fe e3 11 ff fc 15 b9 90 91 26 ed 51 78 38 cb c7 19 9b
## [476] dc 01 9b 04 a2 eb 12 9d 9a aa e5 77 95 1e 68 29 ab a4 ec a1 eb f5 36 96 02
## [501] 1a 97 a4 c2 4c 05 d3 29 7f 85 f4 38 27 69 3a 94 b4 3e c6 14 e9 1c 21 a3 ee
## [526] d5 44 87 02 2f 87 cd eb ab 37 34 df 21 f9 75 66 c5 5a ae 10 b3 c3 ec 99 64
## [551] a5 f2 57 b4 f0 36 3e 07 42 11 61 4b 9b 9f 5f b3 fb 8f 0b e1 45 ff a4 08 b3
## [576] 80 03 5c 22 05 96 71 8d eb 92 3b cb d3 09 13 33 1c 8c 9c 44 ae 90 9f ae 98
## [601] 8b 9c f7 4f 34 96 b7 00 00 04 02 00 00 00 01 00 04 00 09 00 00 00 05 6e 61
## [626] 6d 65 73 00 00 00 10 00 00 00 04 00 04 00 09 00 00 00 02 69 76 00 04 00 09
## [651] 00 00 00 07 73 65 73 73 69 6f 6e 00 04 00 09 00 00 00 04 64 61 74 61 00 04
## [676] 00 09 00 00 00 09 73 69 67 6e 61 74 75 72 65 00 00 00 fe

which she can decrypt

cyphr::decrypt_string(secret2, pair_a)
## [1] "another message"

Chances are, you have an openssl keypair in your .ssh/ directory. If so, you would pass NULL as the path for the private (or less usefully, the public) key pair part. So to send a message to Bob, we’d include the path to Bob’s public key.

pair_us <- cyphr::keypair_openssl(path_key_bob, NULL)

This all skips over how Alice and Bob will exchange this secret information. Because the secret is bytes, it’s a bit odd to work with. Alice could save the secret to disk with

secret <- cyphr::encrypt_string("secret message", pair_a)
path_for_bob <- file.path(tempdir(), "for_bob_only")
writeBin(secret, path_for_bob)

And then send Bob the file for_bob_only (over email or any other insecure medium).

and bob could read the secret in with:

secret <- readBin(path_for_bob, raw(), file.size(path_for_bob))
cyphr::decrypt_string(secret, pair_b)
## [1] "secret message"

As an alternative, you can “base64 encode” the bytes into something that you can just email around:

secret_base64 <- openssl::base64_encode(secret)
secret_base64
## [1] "WAoAAAADAAQEAgADBQAAAAAFVVRGLTgAAAITAAAABAAAABgAAAAQzzJi3vBMT4CqHlIVZqv2fwAAABgAAAEAgnTz1DfbbohSY8upgX3vQeEYJu1N1wgF6+Amktpxf/7fQYk6eElVr4R8BU7MPe8GWvhXUWtSOMTROHGUImsUxQzZUPIyuRbVwU9SJkuY6ORicsoNhjum+hS4mAm+MEAzauhG6ksteyqzdcwajw56+Y0n2AEQy9STW9bEaDLNC1A3er9O0dH//bRoWRaWWfK3Bwo1cFtsj2vq4zZkMv9SAE68l0rKJeHQEQcCsakGO7F8tJwLftcYwauZp6ho2CXyvEjQhztgijSys9gtT/wTvU/B1GuT9//yZOL4FwZi2/8V41bPTkXmzsR0xkJHEpDeYrLipYEzEZtieHSe/RXDXwAAABgAAAAQJN84nguCYtUBapOnGDI1XQAAABgAAAEAmz3PE8EllXXoksg9rVFxZxYdBTC7eSavHrDnWQBLf4FcWWh304OqGzUNRMBkbU16kb+mpZkfXtotllsx4vZ97cGnwYL9UN8bPaU/77IbT5uWH0SDEiLmZZ6s26KmzgshXxuQ9FDhLgVMzIzlASMPtdDZ4OYFuEpHQUn4fZ7VH6YGvwKXlWGYot9ZzLunget/bOmxGO7tI8fv2sGfceWsr/XRuKLF1Mw9E3SuCNARKrt9G7taU12ftn3aTgjuY7BGRcPyKFwT99dVwNNudXlwV8GE4HwsOQ+3ZXh664Bjan3/49T5A+qFwpJ/shgkGzR22iz8TwcWmUyc+bNtS4iXEQAABAIAAAABAAQACQAAAAVuYW1lcwAAABAAAAAEAAQACQAAAAJpdgAEAAkAAAAHc2Vzc2lvbgAEAAkAAAAEZGF0YQAEAAkAAAAJc2lnbmF0dXJlAAAA/g=="

This can be converted back with openssl::base64_decode:

identical(openssl::base64_decode(secret_base64), secret)
## [1] TRUE

Or, less compactly but also suitable for email, you might just convert the bytes into their hex representation:

secret_hex <- sodium::bin2hex(secret)
secret_hex
## [1] "580a000000030004040200030500000000055554462d3800000213000000040000001800000010cf3262def04c4f80aa1e521566abf67f00000018000001008274f3d437db6e885263cba9817def41e11826ed4dd70805ebe02692da717ffedf41893a784955af847c054ecc3def065af857516b5238c4d1387194226b14c50cd950f232b916d5c14f52264b98e8e46272ca0d863ba6fa14b89809be3040336ae846ea4b2d7b2ab375cc1a8f0e7af98d27d80110cbd4935bd6c46832cd0b50377abf4ed1d1fffdb46859169659f2b7070a35705b6c8f6beae3366432ff52004ebc974aca25e1d0110702b1a9063bb17cb49c0b7ed718c1ab99a7a868d825f2bc48d0873b608a34b2b3d82d4ffc13bd4fc1d46b93f7fff264e2f8170662dbff15e356cf4e45e6cec474c642471290de62b2e2a58133119b6278749efd15c35f000000180000001024df389e0b8262d5016a93a71832355d00000018000001009b3dcf13c1259575e892c83dad517167161d0530bb7926af1eb0e759004b7f815c596877d383aa1b350d44c0646d4d7a91bfa6a5991f5eda2d965b31e2f67dedc1a7c182fd50df1b3da53fefb21b4f9b961f44831222e6659eacdba2a6ce0b215f1b90f450e12e054ccc8ce501230fb5d0d9e0e605b84a474149f87d9ed51fa606bf0297956198a2df59ccbba781eb7f6ce9b118eeed23c7efdac19f71e5acaff5d1b8a2c5d4cc3d1374ae08d0112abb7d1bbb5a535d9fb67dda4e08ee63b04645c3f2285c13f7d755c0d36e75797057c184e07c2c390fb765787aeb80636a7dffe3d4f903ea85c2927fb218241b3476da2cfc4f0716994c9cf9b36d4b889711000004020000000100040009000000056e616d6573000000100000000400040009000000026976000400090000000773657373696f6e00040009000000046461746100040009000000097369676e6174757265000000fe"

and the reverse with sodium::hex2bin:

identical(sodium::hex2bin(secret_hex), secret)
## [1] TRUE

(this is somewhat less space efficient than base64 encoding.

As a final option, you can just save the secret with saveRDS and read it in with readRDS like any other option. This will be the best route if the secret is saved into a more complicated R object (e.g., a list or data.frame).

See the other cyphr vignette (vignette("data", package = "cyphr")) for a suggested workflow for exchanging secrets within a team, and the wrapper functions below for more convenient ways of working with encrypted data.

Do you already have an ssh keypair? To find out, run

cyphr::keypair_openssl(NULL, NULL)

One of three things will happen:

  1. you will be prompted for your password to decrypt your private key, and then after entering it an object <cyphr_keypair: openssl> will be returned - you’re good to go!

  2. you were not prompted for your password, but got a <cyphr_keypair: openssl> object. You should consider whether this is appropriate and consider generating a new keypair with the private key encrypted. If you don’t then anyone who can read your private key can decrypt any message intended for you.

  3. you get an error like Did not find default ssh public key at ~/.ssh/id_rsa.pub. You need to create a keypair.

To create a keypair, you can use the cyphr::ssh_keygen() function as

cyphr::ssh_keygen("~/.ssh")

This will create the keypair as ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub, which is where cyphr will look for your keys by default. See ?ssh_keygen for more information. (On Linux and macOS you might use the ssh-keygen command line utility. On windows, PuTTY` has a utility for creating keys.)

sodium

With sodium, things are largely the same with the exception that there is no standard format for saving sodium keys. The bits below use an in-memory key (which is just a collection of bytes) but these can also be filenames, each of which contains the contents of the key written out with writeBin.

First, generate keys for Alice:

key_a <- sodium::keygen()
pub_a <- sodium::pubkey(key_a)

the public key is derived from the private key, and Alice can share that with Bob. We next generate Bob’s keys

key_b <- sodium::keygen()
pub_b <- sodium::pubkey(key_b)

Bob would now share is public key with Alice.

If Alice wants to send a message to Bob she again uses her private key and Bob’s public key:

pair_a <- cyphr::keypair_sodium(pub_b, key_a)

As above, she can now send a message:

secret <- cyphr::encrypt_string("secret message", pair_a)
secret
##  [1] 84 1b 3d e7 b3 cb 45 31 ed cb 60 e1 77 e3 c8 d7 c7 3e 63 7e 11 4e b6 ae 5d
## [26] e5 fd 66 bd ae d8 88 6e e0 9b 92 04 44 1f 52 75 97 86 90 8a ab a5 b0 24 bb
## [51] 7f 0f 54 04

Note how this line is identical to the one in the openssl section.

To decrypt this message, Bob would use Alice’s public key and his private key:

pair_b <- cyphr::keypair_sodium(pub_a, key_b)
cyphr::decrypt_string(secret, pair_b)
## [1] "secret message"

Encrypting things

Above, we used cyphr::encrypt_string and cyphr::decrypt_string to encrypt and decrypt a string. There are several such functions in the package that encrypt and decrypt

For this section we will just use a sodium symmetric encryption key

key <- cyphr::key_sodium(sodium::keygen())

For the examples below, in the case of asymmetric encryption (using either cyphr::keypair_openssl or cyphr::keypair_sodium) the sender would use their private key and the recipient’s public key and the recipient would use the complementary key pair.

Objects

Here’s an object to encrypt:

obj <- list(x = 1:10, y = "secret")

This creates a bunch of raw bytes corresponding to the data (it’s not really possible to print this as anything nicer than bytes).

secret <- cyphr::encrypt_object(obj, key)
secret
##   [1] 8d 81 31 26 4a 1f fd 17 9f b1 06 11 91 fa 1e 75 31 b8 c9 06 92 2c 9d be 92
##  [26] b4 e4 e0 d3 ca f7 a5 30 40 d8 79 94 7c 6b ba bf 97 43 fa 86 ca f6 53 08 2e
##  [51] e7 1a 8d 70 f7 73 2b 37 ce 91 cc ed f7 76 00 5d 1c a9 58 33 53 7b c4 b3 3d
##  [76] 7a 81 b7 2a 2e c5 ca 79 c3 48 38 f6 1a 85 c7 ad 68 0f 0d 06 7a 4c 54 1c a7
## [101] 39 ea 1f f0 61 92 66 4f 0f 18 7d b2 0e 2d 14 fc 4f 6f 79 10 21 bc 62 5a f0
## [126] c6 a8 f0 78 cb a3 1f 5d 3b b7 e8 28 70 e3 fc 54 60 32 a2 8b 2d 91 5c a0 b7
## [151] b9 4b 3c d9 0b b7 37 59 ca ce c3 0a 95 eb 95 f9 b0 c1 65 d5 c3 31 0c e1 ba
## [176] 26 5e 35 25 9a 22 e6 1d 11 db f2 ff 4e 2d 36 93 7a 6d 26 82 0f 75 85 72 6d
## [201] 4d 14 50 e5 3f 1d d3 35 2f 52 63 09 23 3b 63 13 fa 24 ad ca 9e 03 e8 57 70
## [226] 8c b4 97 02 41 03 7a b8 5e ce 1e 9c 07 29 46 c0 9f c0 a0 ac 4a f8 be a6 b1
## [251] 7f 33 59 c9

The data can be decrypted with the decrypt_object function:

cyphr::decrypt_object(secret, key)
## $x
##  [1]  1  2  3  4  5  6  7  8  9 10
## 
## $y
## [1] "secret"

Optionally, this process can go via a file, using a third argument to the functions (note that temporary files are used here for compliance with CRAN policies - any path may be used in practice).

path_secret <- file.path(tempdir(), "secret.rds")
cyphr::encrypt_object(obj, key, path_secret)

There is now a file called secret.rds in the temporary directory:

file.exists(path_secret)
## [1] TRUE

though it is not actually an rds file:

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

When passed a filename (as opposed to a raw vector), cyphr::decrypt_object will read the object in before decrypting it

cyphr::decrypt_object(path_secret, key)
## $x
##  [1]  1  2  3  4  5  6  7  8  9 10
## 
## $y
## [1] "secret"

Strings

For the case of strings we can do this in a slightly more lightweight way (the above function routes through serialize / deserialize which can be slow and will create larger objects than using charToRaw / rawToChar)

secret <- cyphr::encrypt_string("secret", key)
secret
##  [1] b2 c8 9e f1 66 2b d9 5e 8c b9 70 4b 90 e6 b8 e3 d6 d7 82 84 40 bf 45 9a 85
## [26] 4a 8a ae a0 55 c3 9a 79 07 83 b5 f8 1e 41 9d bd 95 bc f9 d8 9f

and decrypt:

cyphr::decrypt_string(secret, key)
## [1] "secret"

Plain raw data

If these are not enough for you, you can work directly with raw objects (bunches of bytes) by using encrypt_data:

dat <- sodium::random(100)
dat # some random bytes
##   [1] 2b c3 9b 6c 9c d5 ff ad c8 64 c5 9d e2 17 6f ca 35 71 2a 86 53 bf 50 41 2e
##  [26] e9 1c c5 a9 30 54 92 2b 67 6c 5c 66 ca cc 2e d4 49 82 7c fb 82 52 70 bd f6
##  [51] 53 02 d8 db 6c a1 f6 17 ec 95 b4 22 34 83 66 bf 88 a5 e3 56 10 b6 01 d4 af
##  [76] ca b4 3a c2 bd c4 19 54 0b 4b d2 c7 e8 4b 1b 9b 2f 2c ee 2a 68 25 1e 75 51
secret <- cyphr::encrypt_data(dat, key)
secret
##   [1] 74 f9 a9 ca a7 b6 63 00 23 d8 5d 88 70 0b 1c e6 35 0b 46 59 2d 4f c5 7a ab
##  [26] f0 18 74 76 cf e3 4a 91 89 eb 60 45 db 2d f6 09 3a 62 6a 5d 70 42 75 ac b3
##  [51] 59 55 d3 77 6b 62 20 e0 65 a1 cd ac 53 83 21 a8 aa 67 a3 bf 85 c1 84 da c1
##  [76] 44 32 98 2b 50 e5 67 ab 37 2a 84 bf ad 51 3e 55 e4 d9 df d9 86 11 af 12 b1
## [101] 0b 76 6f e0 60 7f b7 d6 94 8a dc cb 71 a2 e8 eb d8 3b bb 96 ad 5b 82 3a 8c
## [126] 5b 8a b1 fe a8 c9 73 34 49 ed dc 52 62 f5 11

Decrypted data is the same as a the original data

identical(cyphr::decrypt_data(secret, key), dat)
## [1] TRUE

Files

Suppose we have written a file that we want to encrypt to send to someone (in a temporary directory for compliance with CRAN policies)

path_data_csv <- file.path(tempdir(), "iris.csv")
write.csv(iris, path_data_csv, row.names = FALSE)

You can encrypt that file with

path_data_enc <- file.path(tempdir(), "iris.csv.enc")
cyphr::encrypt_file(path_data_csv, key, path_data_enc)

This encrypted file can then be decrypted with

path_data_decrypted <- file.path(tempdir(), "idis2.csv")
cyphr::decrypt_file(path_data_enc, key, path_data_decrypted)

Which is identical to the original:

tools::md5sum(c(path_data_csv, path_data_decrypted))
##           /tmp/Rtmpj3XoZv/iris.csv          /tmp/Rtmpj3XoZv/idis2.csv 
## "5fe92fe6a2c1928ef5a67b8939fdaf8d" "5fe92fe6a2c1928ef5a67b8939fdaf8d"

An even higher level interface for files

This is the most user-friendly way of using the package when the aim is to encrypt and decrypt files. The package provides a pair of functions cyphr::encrypt and cyphr::decrypt that wrap file writing and file reading functions. In general you would use encrypt when writing a file and decrypt when reading one. They’re designed to be used like so:

Suppose you have a super-secret object that you want to share privately

key <- cyphr::key_sodium(sodium::keygen())
x <- list(a = 1:10, b = "don't tell anyone else")

If you save x to disk with saveRDS it will be readable by everyone until it is deleted. But if you encrypted the file that saveRDS produced it would be protected and only people with the key can read it:

path_object <- file.path(tempdir(), "secret.rds")
cyphr::encrypt(saveRDS(x, path_object), key)

(see below for some more details on how this works).

This file cannot be read with readRDS:

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

but if we wrap the call with decrypt and pass in the config object it can be decrypted and read:

cyphr::decrypt(readRDS(path_object), key)
## $a
##  [1]  1  2  3  4  5  6  7  8  9 10
## 
## $b
## [1] "don't tell anyone else"

What happens in the call above is cyphr uses “non standard evaluation” to rewrite the call above so that it becomes (approximately)

  1. use cyphr::decrypt_file to decrypt “secret.rds” as a temporary file
  2. call readRDS on that temporary file
  3. delete the temporary file (even if there is an error in the above calls)

This non-standard evaluation breaks referential integrity (so may not be suitable for programming). You can always do this manually with encrypt_file / decrypt_file so long as you make sure to clean up after yourself.

The encrypt function inspects the call in the first argument passed to it and works out for the function provided (saveRDS) which argument corresponds to the filename (here "secret.rds"). It then rewrites the call to write out to a temporary file (using tempfile()). Then it calls encrypt_file (see below) on this temporary file to create the file asked for ("secret.rds"). Then it deletes the temporary file, though this will also happen in case of an error in any of the above.

The decrypt function works similarly. It inspects the call and detects that the first argument represents the filename. It decrypts that file to create a temporary file, and then runs readRDS on that file. Again it will delete the temporary file on exit.

The functions supported via this interface are:

But new functions can be added with the rewrite_register function. For example, to support the excellent rio package, whose import and export functions take the filename file you could use:

cyphr::rewrite_register("rio", "import", "file")
cyphr::rewrite_register("rio", "export", "file")

now you can read and write tabular data into and out of a great many different file formats with encryption with calls like

cyphr::encrypt(rio::export(mtcars, "file.json"), key)
cyphr::decrypt(rio::import("file.json"), key)

The functions above use non standard evaluation and so may not be suitable for programming or use in packages. An “escape hatch” is provided via encrypt_ and decrypt_ where the first argument is a quoted expression.

cyphr::encrypt_(quote(saveRDS(x, path_object)), key)
cyphr::decrypt_(quote(readRDS(path_object)), key)
## $a
##  [1]  1  2  3  4  5  6  7  8  9 10
## 
## $b
## [1] "don't tell anyone else"

Session keys

When using key_openssl, keypair_openssl, key_sodium, or keypair_sodium we generate something that can decrypt data. The objects that are returned by these functions can encrypt and decrypt data and so it is reasonable to be concerned that if these objects were themselves saved to disk your data would be compromised.

To avoid this, cyphr does not store private or symmetric keys directly in these objects but instead encrypts the sensitive keys with a cyphr-specific session key that is regenerated each time the package is loaded. This means that the objects are practically only useful within one session, and if saved with save.image (perhaps automatically at the end of a session) the keys cannot be used to decrypt data.

To manually invalidate all keys you can use the cyphr::session_key_refresh function. For example, here is a symmetric key:

key <- cyphr::key_sodium(sodium::keygen())

which we can use to encrypt a secret string

secret <- cyphr::encrypt_string("my secret", key)

and decrypt it:

cyphr::decrypt_string(secret, key)
## [1] "my secret"

If we refresh the session key we invalidate the key object

cyphr::session_key_refresh()

and after this point the key cannot be used any further

cyphr::decrypt_string(secret, key)
## Error: Failed to decrypt key as session key has changed

This approach works because the package holds the session key within its environment (in cyphr:::session$key) which R will not serialize. As noted above - this approach does not prevent an attacker with the ability to snoop on your R session from discovering your private keys or sensitive data but it does prevent accidentally saving keys in a way that would be useful for an attacker to use in a subsequent session.

Further reading

Confused? Need help? Found a bug?