diff --git a/doc/manual/source/SUMMARY.md.in b/doc/manual/source/SUMMARY.md.in index 8b6b29f6a7f..7412ca7c52e 100644 --- a/doc/manual/source/SUMMARY.md.in +++ b/doc/manual/source/SUMMARY.md.in @@ -136,6 +136,7 @@ - [Store Path Specification](protocols/store-path.md) - [Nix Archive (NAR) Format](protocols/nix-archive/index.md) - [Derivation "ATerm" file format](protocols/derivation-aterm.md) + - [Nix32 Encoding](protocols/nix32.md) - [C API](c-api.md) - [Glossary](glossary.md) - [Development](development/index.md) diff --git a/doc/manual/source/language/advanced-attributes.md b/doc/manual/source/language/advanced-attributes.md index f0b1a4c730e..67612029c8a 100644 --- a/doc/manual/source/language/advanced-attributes.md +++ b/doc/manual/source/language/advanced-attributes.md @@ -338,7 +338,7 @@ Here is more information on the `output*` attributes, and what values they may b This will specify the output hash of the single output of a [fixed-output derivation]. The `outputHash` attribute must be a string containing the hash in either hexadecimal or "nix32" encoding, or following the format for integrity metadata as defined by [SRI](https://www.w3.org/TR/SRI/). - The "nix32" encoding is an adaptation of base-32 encoding. + The ["nix32" encoding](@docroot@/protocols/nix32.md) is Nix's variant of base-32 encoding. > **Note** > diff --git a/doc/manual/source/protocols/json/schema/store-path-v1.yaml b/doc/manual/source/protocols/json/schema/store-path-v1.yaml index 2012aab9915..f1f58c2bf1a 100644 --- a/doc/manual/source/protocols/json/schema/store-path-v1.yaml +++ b/doc/manual/source/protocols/json/schema/store-path-v1.yaml @@ -24,7 +24,7 @@ description: | The format follows this pattern: `${digest}-${name}` - - **hash**: Digest rendered in a custom variant of [Base32](https://en.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters) + - **hash**: Digest rendered in [Nix32](@docroot@/protocols/nix32.md), a variant of base-32 (20 hash bytes become 32 ASCII characters) - **name**: The package name and optional version/suffix information type: string diff --git a/doc/manual/source/protocols/nix32.md b/doc/manual/source/protocols/nix32.md new file mode 100644 index 00000000000..72afe893ea2 --- /dev/null +++ b/doc/manual/source/protocols/nix32.md @@ -0,0 +1,19 @@ +# Nix32 Encoding + +Nix32 is Nix's variant of base-32 encoding, used for [store path digests](@docroot@/protocols/store-path.md), hash output via [`nix hash`](@docroot@/command-ref/new-cli/nix3-hash.md), and the [`outputHash`](@docroot@/language/advanced-attributes.md#adv-attr-outputHash) derivation attribute. + +## Alphabet + +The Nix32 alphabet consists of these 32 characters: + +``` +0 1 2 3 4 5 6 7 8 9 a b c d f g h i j k l m n p q r s v w x y z +``` + +The letters `e`, `o`, `u`, and `t` are omitted. + +## Byte Order + +Nix32 encoding processes the hash bytes from the end (last byte first), while base-16 encoding processes from the beginning (first byte first). + +Consequently, the string sort order is determined primarily by the first bytes for base-16, and by the last bytes for Nix32. diff --git a/doc/manual/source/protocols/store-path.md b/doc/manual/source/protocols/store-path.md index 5be2355015f..1aa79615d1c 100644 --- a/doc/manual/source/protocols/store-path.md +++ b/doc/manual/source/protocols/store-path.md @@ -20,12 +20,11 @@ where - `store-dir` = the [store directory](@docroot@/store/store-path.md#store-directory) -- `digest` = base-32 representation of the compressed to 160 bits [SHA-256] hash of `fingerprint` +- `digest` = base-32 representation of the compressed to 160 bits [SHA-256] hash of `fingerprint`. -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. + Nix uses a custom base-32 encoding called [Nix32](@docroot@/protocols/nix32.md). + + For the definition of the hash compression algorithm, please refer to section 5.1 of the [Nix thesis](https://edolstra.github.io/pubs/phd-thesis.pdf). ## Fingerprint diff --git a/doc/manual/source/store/store-path.md b/doc/manual/source/store/store-path.md index 08b024e4a84..04bdfec004c 100644 --- a/doc/manual/source/store/store-path.md +++ b/doc/manual/source/store/store-path.md @@ -31,7 +31,7 @@ A store path is rendered to a file system path as the concatenation of - [Store directory](#store-directory) (typically `/nix/store`) - Path separator (`/`) -- Digest rendered in a custom variant of [Base32](https://en.wikipedia.org/wiki/Base32) (20 arbitrary bytes become 32 ASCII characters) +- Digest rendered in [Nix32](@docroot@/protocols/nix32.md), a variant of base-32 (20 hash bytes become 32 ASCII characters) - Hyphen (`-`) - Name