From 78727c17a3db64af7c180d35f09d34d66300b3ad Mon Sep 17 00:00:00 2001 From: Alexander Neumann Date: Sun, 22 Mar 2015 19:18:09 +0100 Subject: [PATCH] Update documentation to reflect changed crypto --- doc/Design.md | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/doc/Design.md b/doc/Design.md index 33180f190..6e837bb5c 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -29,11 +29,11 @@ complete filename. Apart from the `version` file and the files stored below the `keys` directory, all files are encrypted with AES-256 in counter mode (CTR). The integrity of -the encrypted data is secured by an HMAC-SHA-256 signature. +the encrypted data is secured by an Poly1305-AES signature. In the first 16 bytes of each encrypted file the initialisation vector (IV) is -stored. It is followed by the encrypted data and completed by the 32 byte HMAC -signature. The format is: `IV || CIPHERTEXT || HMAC`. The complete encryption +stored. It is followed by the encrypted data and completed by the 16 byte MAC +signature. The format is: `IV || CIPHERTEXT || MAC`. The complete encryption overhead is 48 byte. For each file, a new random IV is selected. The basic layout of a sample restic repository is shown below: @@ -69,8 +69,8 @@ A repository can be initialized with the `restic init` command, e.g.: $ restic -r /tmp/restic-repo init -Keys and Encryption -------------------- +Keys, Encryption and MAC +------------------------ The directory `keys` contains key files. These are simple JSON documents which contain all data that is needed to derive the repository's master signing and @@ -95,15 +95,21 @@ When the repository is opened by restic, the user is prompted for the repository password. This is then used with `scrypt`, a key derivation function (KDF), and the supplied parameters (`N`, `r`, `p` and `salt`) to derive 64 key bytes. The first 32 bytes are used as the encryption key (for AES-256) and the -last 32 bytes are used as the signing key (for HMAC-SHA-256). +last 32 bytes are used as the signing key (for Poly1305-AES). These last 32 +bytes are divided into a 16 byte AES key `k` followed by 16 bytes of secret key +`r`. They key `r` is then masked for use with Poly1305. For details see the +original paper [The Poly1305-AES message-authentication +code](http://cr.yp.to/mac/poly1305-20050329.pdf) by Dan Bernstein. -This signing key is used to compute an HMAC over the bytes contained in the +This signing key is used to compute a MAC over the bytes contained in the JSON field `data` (after removing the Base64 encoding and not including the last 32 byte). If the password is incorrect or the key file has been tampered -with, the computed HMAC will not match the last 32 bytes of the data, and +with, the computed MAC will not match the last 16 bytes of the data, and restic exits with an error. Otherwise, the data is decrypted with the encryption key derived from `scrypt`. This yields a JSON document which -contains the master signing and encryption keys for this repository. +contains the master signing and encryption keys for this repository. All data +in the repository is encrypted and signed with these master keys with AES-256 +in Counter mode and signed with Poly1305-AES as described above. A repository can have several different passwords, with a key file for each. This way, the password can be changed without having to re-encrypt all data. @@ -196,7 +202,7 @@ A tree contains a list of entries (in the field `nodes`) which contain meta data like a name and timestamps. When the entry references a directory, the field `subtree` contains the plain text ID of another tree object. The associated storage ID can be found in the map object. All referenced plaintext -hashes are mapped to their corresponding storage hashes in the list containid +hashes are mapped to their corresponding storage hashes in the list contained in the field `map`. When the command `restic cat tree` is used, the storage hash is needed to print @@ -239,8 +245,8 @@ a tree. The tree referenced above can be dumped as follows: This tree contains a file entry. This time, the `subtree` field is not present and the `content` field contains a list with one plain text SHA-256 hash. The storage ID for this ID can in turn be looked up in the map. Data chunks stored -as encrypted files in a sub directory of the directory `data`, similar to tree -objects. +as encrypted and signed files in a sub directory of the directory `data`, +similar to tree objects. The command `restic cat data` can be used to extract and decrypt data given a storage hash, e.g. for the data mentioned above: @@ -297,7 +303,7 @@ The restic backup program guarantees the following: file's name). This way, modifications (bad RAM, broken harddisk) can be detected easily. - 2. Before decrypting any data, the HMAC signature on the encrypted data is + 2. Before decrypting any data, the MAC signature on the encrypted data is checked. If there has been a modification, the signature check will fail. This step happens even before the data is decrypted, so data that has been tampered with is not decrypted at all.