From a0facb2aba1f643e7c2333bbf89e3765ca3f0351 Mon Sep 17 00:00:00 2001 From: Dmitry Bogatov Date: Sat, 8 Mar 2025 19:00:00 -0500 Subject: [PATCH 1/2] Improve the documentation of the store path protocol 1. Fix confusing wording that might imply unnecessary double-hashing. 2. Add references to specifics of base-32 encoding. 3. Fix incorrect description that sha256 hash of `fingerprint` is truncated. "Truncated" is actual wording used in Nix theses, but it has unusual meaning, that is better conveyed by word "compressed", which is used by the reference C++ implementation. 4. Clarify details of base16 encoding. --- doc/manual/source/protocols/store-path.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/manual/source/protocols/store-path.md b/doc/manual/source/protocols/store-path.md index 9abd83f4f..8469195ad 100644 --- a/doc/manual/source/protocols/store-path.md +++ b/doc/manual/source/protocols/store-path.md @@ -20,9 +20,12 @@ where - `store-dir` = the [store directory](@docroot@/store/store-path.md#store-directory) -- `digest` = base-32 representation of the first 160 bits of a [SHA-256] hash of `fingerprint` +- `digest` = base-32 representation of the compressed to 160 bits [SHA-256] hash of `fingerprint` - This the hash part of the store name +For the definition of the hash compression algorithm, please refer to the section 5.1 of +the [Nix thesis](https://edolstra.github.io/pubs/phd-thesis.pdf), which also defines the +specifics of base-32 encoding. Note that base-32 encoding processes the hash bytestring from +the end, while base-16 processes in from the beginning. ## Fingerprint @@ -70,7 +73,8 @@ where `id` is the name of the output (usually, "out"). For content-addressed store objects, `id`, is always "out". -- `inner-digest` = base-16 representation of a SHA-256 hash of `inner-fingerprint` +- `inner-digest` = base-16 representation of a SHA-256 hash of `inner-fingerprint`. The + base-16 encoding uses lower-cased hex digits. ## Inner fingerprint @@ -82,7 +86,7 @@ where - if `type` = `"source:" ...`: - the hash of the [Nix Archive (NAR)] serialization of the [file system object](@docroot@/store/file-system-object.md) of the store object. + the [Nix Archive (NAR)] serialization of the [file system object](@docroot@/store/file-system-object.md) of the store object. - if `type` = `"output:" id`: From affd9bbab7b9da0c60c023209bebe91fdbcdd3d5 Mon Sep 17 00:00:00 2001 From: Dmitry Bogatov Date: Tue, 11 Mar 2025 12:30:21 -0400 Subject: [PATCH 2/2] Update doc/manual/source/protocols/store-path.md Co-authored-by: John Ericson --- doc/manual/source/protocols/store-path.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/manual/source/protocols/store-path.md b/doc/manual/source/protocols/store-path.md index 8469195ad..ee7fb3a12 100644 --- a/doc/manual/source/protocols/store-path.md +++ b/doc/manual/source/protocols/store-path.md @@ -73,8 +73,8 @@ the end, while base-16 processes in from the beginning. `id` is the name of the output (usually, "out"). For content-addressed store objects, `id`, is always "out". -- `inner-digest` = base-16 representation of a SHA-256 hash of `inner-fingerprint`. The - base-16 encoding uses lower-cased hex digits. +- `inner-digest` = base-16 representation of a SHA-256 hash of `inner-fingerprint`. + The base-16 encoding uses lower-cased hex digits. ## Inner fingerprint