From b6872fb454191b29b685502444a0b5fa1e8697ac Mon Sep 17 00:00:00 2001 From: Alexander Neumann Date: Sat, 22 Aug 2015 13:28:28 +0200 Subject: [PATCH 1/3] Clarify documentation about MAC key --- doc/Design.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/Design.md b/doc/Design.md index 5a3d0e2e9..ac5ec7dc8 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -249,13 +249,13 @@ 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 (see the paper for details). -This message authentication 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 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 encryption and message authentication keys for this +This message authentication key (`k` and `r`) 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 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 encryption and message authentication keys for this repository (encoded in Base64). The command `restic cat masterkey` can be used as follows to decrypt and pretty-print the master key: From e0e9cd86809a044c2f05f7d9f55007c34b8ae007 Mon Sep 17 00:00:00 2001 From: Alexander Neumann Date: Sat, 22 Aug 2015 15:08:35 +0200 Subject: [PATCH 2/3] More documentation fixes --- doc/Design.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/Design.md b/doc/Design.md index ac5ec7dc8..3c73d75c1 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -12,7 +12,7 @@ several subdirectories. A repository implementation must be able to fulfill a number of operations, e.g. list the contents. *Blob*: A Blob combines a number of data bytes with identifying information -like the SHA256 hash of the data and its length. +like the SHA-256 hash of the data and its length. *Pack*: A Pack combines one or more Blobs, e.g. in a single file. @@ -315,9 +315,8 @@ Trees and Data -------------- A snapshot references a tree by the SHA-256 hash of the JSON string -representation of its contents. Trees are saved in a subdirectory of the -directory `trees`. The sub directory's name is the first two characters of the -filename the tree object is stored in. +representation of its contents. Trees and data are saved in pack files in a +subdirectory of the directory `data`. The command `restic cat tree` can be used to inspect the tree referenced above: @@ -464,8 +463,8 @@ The restic backup program guarantees the following: * Accessing the unencrypted content of stored files and meta data should not be possible without a password for the repository. Everything except the - `version` and `id` files and the meta data included for informational - purposes in the key files is encrypted and authenticated. + meta data included for informational purposes in the key files is encrypted and + authenticated. * Modifications (intentional or unintentional) can be detected automatically on several layers: From 3a50c2bbfbe6379e9683b0de6138a49acb95d514 Mon Sep 17 00:00:00 2001 From: Alexander Neumann Date: Sat, 22 Aug 2015 23:03:25 +0200 Subject: [PATCH 3/3] Fix docs --- doc/Design.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/Design.md b/doc/Design.md index 3c73d75c1..0a925202f 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -246,18 +246,18 @@ repository password. This is then used with `scrypt`, a key derivation function bytes. The first 32 bytes are used as the encryption key (for AES-256) and the last 32 bytes are used as the message authentication 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 (see the +of secret key `r`. The key `r` is then masked for use with Poly1305 (see the paper for details). -This message authentication key (`k` and `r`) 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 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 encryption and message authentication keys for this -repository (encoded in Base64). The command `restic cat masterkey` can be used -as follows to decrypt and pretty-print the master key: +Those message authentication keys (`k` and `r`) are 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 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 encryption and message authentication keys +for this repository (encoded in Base64). The command `restic cat masterkey` can +be used as follows to decrypt and pretty-print the master key: $ restic -r /tmp/restic-repo cat masterkey { @@ -461,9 +461,9 @@ General assumptions: The restic backup program guarantees the following: - * Accessing the unencrypted content of stored files and meta data should not + * Accessing the unencrypted content of stored files and metadata should not be possible without a password for the repository. Everything except the - meta data included for informational purposes in the key files is encrypted and + metadata included for informational purposes in the key files is encrypted and authenticated. * Modifications (intentional or unintentional) can be detected automatically