octoleo/restic
2
2
Fork 0
mirror of https://github.com/octoleo/restic.git synced 2024-11-29 08:14:03 +00:00
Code Issues Releases Wiki Activity

Update documentation to reflect changed crypto

Browse Source
This commit is contained in:
Alexander Neumann 2015-03-22 19:18:09 +01:00
parent 47d71d23d2
commit 78727c17a3
1 changed files with 19 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
doc/Design.md
View File

@ -29,11 +29,11 @@ complete filename.
Apart from the `version` file and the files stored below the `keys` directory, 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 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 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 stored. It is followed by the encrypted data and completed by the 16 byte MAC
signature. The format is: `IV || CIPHERTEXT || HMAC`. The complete encryption signature. The format is: `IV || CIPHERTEXT || MAC`. The complete encryption
overhead is 48 byte. For each file, a new random IV is selected. overhead is 48 byte. For each file, a new random IV is selected.
The basic layout of a sample restic repository is shown below: 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 $ 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 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 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 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 (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 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 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 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 restic exits with an error. Otherwise, the data is decrypted with the
encryption key derived from `scrypt`. This yields a JSON document which 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. 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. 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 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 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 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`. in the field `map`.
When the command `restic cat tree` is used, the storage hash is needed to print 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 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 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 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 as encrypted and signed files in a sub directory of the directory `data`,
objects. similar to tree objects.
The command `restic cat data` can be used to extract and decrypt data given a The command `restic cat data` can be used to extract and decrypt data given a
storage hash, e.g. for the data mentioned above: 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 file's name). This way, modifications (bad RAM, broken harddisk) can be
detected easily. 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 checked. If there has been a modification, the signature check will
fail. This step happens even before the data is decrypted, so data that fail. This step happens even before the data is decrypted, so data that
has been tampered with is not decrypted at all. has been tampered with is not decrypted at all.