From f4329a20f6704c1b645043861ed456f095f13ad0 Mon Sep 17 00:00:00 2001 From: aawsome <37850842+aawsome@users.noreply.github.com> Date: Thu, 16 Feb 2023 22:41:30 +0100 Subject: [PATCH 1/3] docs: Corrections/extra information in design.rst --- doc/design.rst | 37 ++++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/doc/design.rst b/doc/design.rst index 3e25a0852..dde1d2984 100644 --- a/doc/design.rst +++ b/doc/design.rst @@ -45,10 +45,12 @@ comparing its output to the file name. If the prefix of a filename is unique amongst all the other files in the same directory, the prefix may be used instead of the complete filename. -Apart from the files stored within the ``keys`` directory, all files are -encrypted with AES-256 in counter mode (CTR). The integrity of the -encrypted data is secured by a Poly1305-AES message authentication code -(sometimes also referred to as a "signature"). +Apart from the files stored within the ``keys`` and ``data``directories, +all files are encrypted with AES-256 in counter mode (CTR). The integrity +of the encrypted data is secured by a Poly1305-AES message authentication +code (sometimes also referred to as a "signature"). +Files in the ``data`` directory ("pack files") consist of multiple parts +which are all independently enccrypted and authenticated, see below. 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 @@ -298,8 +300,8 @@ example, the Pack ``73d04e61`` contains two data Blobs and one Tree blob, the plaintext hashes are listed afterwards. The ``length`` field corresponds to ``Length(encrypted_blob)`` in the pack file header. Field ``uncompressed_length`` is only present for compressed blobs and -therefore is never present in version 1. It is set to the value of -``Length(blob)``. +therefore is never present in the Repository format version 1. It is set +to the value of ``Length(blob)``. The field ``supersedes`` lists the storage IDs of index files that have been replaced with the current index file. This happens when index files @@ -410,7 +412,9 @@ and pretty-print the contents of a snapshot file: { "time": "2015-01-02T18:10:50.895208559+01:00", "tree": "2da81727b6585232894cfbb8f8bdab8d1eccd3d8f7c92bc934d62e62e618ffdf", - "dir": "/tmp/testdata", + "paths": [ + "/tmp/testdata" + ], "hostname": "kasimir", "username": "fd0", "uid": 1000, @@ -436,7 +440,9 @@ becomes: { "time": "2015-01-02T18:10:50.895208559+01:00", "tree": "2da81727b6585232894cfbb8f8bdab8d1eccd3d8f7c92bc934d62e62e618ffdf", - "dir": "/tmp/testdata", + "paths": [ + "/tmp/testdata" + ], "hostname": "kasimir", "username": "fd0", "uid": 1000, @@ -495,9 +501,18 @@ the JSON is indented): } 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. +meta data like a name and timestamps. Note that there are some specialities of how +this metadata is generated: + +- The name is quoted using before being saved. + This handles non-unicode names, but also changes the representation of names + containing `"` or `\\`. + +- The filemode saved is the mode defined by masked + by ``os.ModePerm | os.ModeType | os.ModeSetuid | os.ModeSetgid | os.ModeSticky`` + +When the entry references a directory, the field ``subtree`` contains the plain text +ID of another tree object. When the command ``restic cat blob`` is used, the plaintext ID is needed to print a tree. The tree referenced above can be dumped as follows: From e2df73b0ac556a41d5d1b930f10e3e0498b82c21 Mon Sep 17 00:00:00 2001 From: aawsome <37850842+aawsome@users.noreply.github.com> Date: Fri, 17 Feb 2023 10:07:53 +0100 Subject: [PATCH 2/3] Update doc/design.rst Co-authored-by: greatroar <61184462+greatroar@users.noreply.github.com> --- doc/design.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/design.rst b/doc/design.rst index dde1d2984..06f0cbf3c 100644 --- a/doc/design.rst +++ b/doc/design.rst @@ -45,12 +45,12 @@ comparing its output to the file name. If the prefix of a filename is unique amongst all the other files in the same directory, the prefix may be used instead of the complete filename. -Apart from the files stored within the ``keys`` and ``data``directories, +Apart from the files stored within the ``keys`` and ``data`` directories, all files are encrypted with AES-256 in counter mode (CTR). The integrity of the encrypted data is secured by a Poly1305-AES message authentication code (sometimes also referred to as a "signature"). Files in the ``data`` directory ("pack files") consist of multiple parts -which are all independently enccrypted and authenticated, see below. +which are all independently encrypted and authenticated, see below. 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 From a67d3781a3d73cc2e5e96975587f2018218b8f47 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Sun, 12 Mar 2023 11:37:37 +0100 Subject: [PATCH 3/3] doc: apply review comments and improve link formatting --- doc/design.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/design.rst b/doc/design.rst index 06f0cbf3c..e3972aeac 100644 --- a/doc/design.rst +++ b/doc/design.rst @@ -300,8 +300,8 @@ example, the Pack ``73d04e61`` contains two data Blobs and one Tree blob, the plaintext hashes are listed afterwards. The ``length`` field corresponds to ``Length(encrypted_blob)`` in the pack file header. Field ``uncompressed_length`` is only present for compressed blobs and -therefore is never present in the Repository format version 1. It is set -to the value of ``Length(blob)``. +therefore is never present in version 1 of the repository format. It is +set to the value of ``Length(blob)``. The field ``supersedes`` lists the storage IDs of index files that have been replaced with the current index file. This happens when index files @@ -504,12 +504,12 @@ A tree contains a list of entries (in the field ``nodes``) which contain meta data like a name and timestamps. Note that there are some specialities of how this metadata is generated: -- The name is quoted using before being saved. - This handles non-unicode names, but also changes the representation of names - containing `"` or `\\`. +- The name is quoted using `strconv.Quote `__ + before being saved. This handles non-unicode names, but also changes the + representation of names containing ``"`` or ``\``. -- The filemode saved is the mode defined by masked - by ``os.ModePerm | os.ModeType | os.ModeSetuid | os.ModeSetgid | os.ModeSticky`` +- The filemode saved is the mode defined by `fs.FileMode `__ + masked by ``os.ModePerm | os.ModeType | os.ModeSetuid | os.ModeSetgid | os.ModeSticky`` When the entry references a directory, the field ``subtree`` contains the plain text ID of another tree object.