diff options
author | Lars Wirzenius <liw@liw.fi> | 2021-03-11 08:56:33 +0000 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2021-03-11 08:56:33 +0000 |
commit | 2a46a1122938e0ffcf28ded131997a405ad67055 (patch) | |
tree | 84075d456edb83d26f9b270776fed11501df7f76 | |
parent | 2658849a1fc6bfc88dfb9b45fcb49d26fa1d4331 (diff) | |
parent | 498bb29dbcfc913b876e2cf5a3389134dcf1f9b4 (diff) | |
download | obnam2-2a46a1122938e0ffcf28ded131997a405ad67055.tar.gz |
Merge branch 'enc-plan' into 'main'
doc: add plan for using encryption
Closes #83
See merge request larswirzenius/obnam!104
-rw-r--r-- | obnam.md | 82 |
1 files changed, 82 insertions, 0 deletions
@@ -876,6 +876,88 @@ restores all the files in the SQLite database. +## Encryption and authenticity of chunks + +*This is a plan that will be implemented soon. When it has been, this +section needs to be updated to to use present tense.* + +Obnam encrypts data it stores on the server, and checks that the data +it retrieves from the server is what it stored. This is all done in +the client: the server should never see any data isn't encrypted, and +the client can't trust the server to validate anything. + +Obnam will be using _Authenticated Encryption with Associated Data_ or +[AEAD][]. AEAD both encrypts data, and validates it before decrypting. +AEAD uses two encryption keys, one algorithm for symmetric encryption, +and one algorithm for a message authentication codes or [MAC][]. AEAD +encrypts the plaintext with a symmetric encryption algorithm using the +first key, giving a ciphertext. It then computes a MAC of the +ciphertext using the second key. Both the ciphertext and MAC are +stored on the server. + +For decryption, a MAC is computed against the retrieved +ciphertext, and compared to the retrieved MAC. If the MACs differ, +that's an error and no decryption is done. If they do match, the +ciphertext is decrypted. + +Obnam will require the user to provide a passphrase, and will derive +the two keys from the single passphrase, using [PBKDF2][], rather than +having the user provide two passphrases. The derived keys will be +stored in a file that only the owner can read. (This is simple, and good +enough for now, but needs to improved later.) + +When this is all implemented, there will be a setup step before the +first backup: + +~~~sh +$ obnam init +Passphrase for encryption: +Re-enter to make sure: +$ obnam backup +~~~ + +The `init` step asks for a passphrase, uses PBKDF2 (with the [pbkdf2 +crate][]) to derive the two keys, and writes a JSON file with the keys +into `~/.config/obnam/keys.json`, making that file be readable only by +the user running Obnam. Other operations get the keys from that file. +For now, we will use the default parameters of the pbkdf2 crate, to +keep things simple. (This will need to be made more flexible later: if +nothing else, Obnam should not be vulnerable to the defaults +changing.) + +The `init` step will not be optional. There will only be encrypted +backups. + +Obnam will use the [aes-gcm crate][] for AEAD, since it has been +audited. If that choice turns out to be less than optimal, it can be +reconsidered later. The `encrypt` function doesn't return the MAC and +ciphertext separately, so we don't store them separately. However, +each chunk needs its own [nonce][], which we will generate. We'll use +a 96-bit (or 12-byte) nonce. We'll use the [rand crate][] to generate +random bytes. + +The chunk sent to the server will be encoded as follows: + +* chunk format: a 32-bit unsigned integer, 0x0001, store in + little-endian form. +* a 12-byte nonce unique to the chunk +* the ciphertext + +The format version prefix dictates the content and structure of the +chunk. This document defines version 1 of the format. The Obnam client +will refuse to operate on backup generations which use chunk formats +it cannot understand. + + +[AEAD]: https://en.wikipedia.org/wiki/Authenticated_encryption#Authenticated_encryption_with_associated_data_(AEAD) +[MAC]: https://en.wikipedia.org/wiki/Message_authentication_code +[aes-gcm crate]: https://crates.io/crates/aes-gcm +[PBKDF2]: https://en.wikipedia.org/wiki/PBKDF2 +[pbkdf2 crate]: https://crates.io/crates/pbkdf2 +[nonce]: https://en.wikipedia.org/wiki/Cryptographic_nonce +[rand crate]: https://crates.io/crates/rand + + # Acceptance criteria for the chunk server These scenarios verify that the chunk server works on its own. The |