Skip to content

paths.md

Latest commit

 

History

History
133 lines (104 loc) · 5.11 KB

paths.md

File metadata and controls

133 lines (104 loc) · 5.11 KB
Raw

Store Paths

A store path is the absolute filesystem path of a {term}store object. Store paths are based on the store object's contents. This document specifies the restrictions on store object names the restrictions on {term}store directories <store directory>, and the algorithm for computing store paths.

.. index:: store path; syntax

(store-path-syntax)=

Syntax

The syntax of a store path in Augmented Backus-Naur Form (as described in {rfc}5234) is as follows:

path = unix-path / windows-path

unix-path           =  *("/" unix-directory-part) "/" store-object-name
unix-directory-part =  ["."] (path-char / "\") *(path-char / "." / "\")
unix-directory-part =/ ".." 1*(path-char / "." / "\")

windows-path           =  windows-volume *("\" windows-directory-part) "\" store-object-name
windows-directory-part =  ["."] path-char *(path-char / ".")
windows-directory-part =/ ".." 1*(path-char / ".")
windows-volume         =  windows-drive-letter ":"
windows-volume         =/ "\" ["\."]                ; UNC
windows-volume         =/ "\??"                     ; Root Local Device path
windows-drive-letter   = %x01-2E / %30-5B / %5D-7F
                         ; CHAR except "/" or "\"

store-object-name      = 32(base32-digit) "-" 1*211(store-object-name-char)
store-object-name-char = ALPHA / DIGIT / "+" / "-" / "." / "_" / "="

path-char = ALPHA / DIGIT / "+" / "-" / "_" / "=" / "@" / %x80-FF
            ; characters that are always safe to use in file names

base32-digit = DIGIT / %x61-64 / %x66-6E / %x70-73 / %x76-7A
               ; lowercase alphanumeric except "e", "o", "t", or "u".

The 32 Base-32 digits at the beginning of a store-object-name are referred to the {index}store path's digest <store path; digest>. The characters after the first hyphen in a store-object-name are referred to the {index}store object's name <store object; name, store path; name>.

(path-algorithm)=

Computing the Digest

Store paths are computed based on the contents of the store object. There are three types of store objects for the purpose of computing a path:

  • Source store objects are the most common: non-fixed derivation outputs and files imported into the store are source store objects. They can reference other store objects and themselves.
  • Text store objects are used for .drv files. They can reference other store objects, but not themselves. Text store objects MUST be a non-executable regular file.
  • Fixed-output store objects are outputs of fixed-output derivations. They cannot contain references.

Once you know the type of store object, the {term}store directory, the store object's name, and the store object's contents, you can compute the store object's digest. The process for computing the path is as follows:

  1. Calculate the hash digest for the store object.

    • For a source store object, the hash digest MUST be the SHA-256 hash of the {term}NAR serialization of the store object.

    • For a text store object, the hash digest MUST be a hash of the store object file's contents. One of the supported hash algorithms MUST be used, and SHOULD be SHA-256.

    • The hash digest for a fixed-output store object is a bit more involved. Given the output hash, the hash digest MUST be the SHA-256 hash of a string with the following syntax:

      fixed-output-fingerprint = %s"fixed:out:" [%s"r:"] hash-algo ":" 1*(2lower-hexdig)

hash-algo    = %s"md5" / %s"sha1" / %s"sha256" / %s"sha512"
lower-hexdig = DIGIT / %s"a" / %s"b" / %s"c" / %s"d" / %s"e" / %s"f"

      r: is added if the fixed-output hash is computed from the {term}NAR serialization of the store object.

  2. Use the hash digest of the store object to produce a string with the following syntax:

    fingerprint = store-path-type ":"
              hash-algo ":"
              1*(2lower-hexdig) ":"
              store-directory ":"
              1*211(store-object-name-char)
store-path-type =  "source" *(":" path) [%s":self"]
                   ; Source store object
store-path-type =/ "text" *(":" path)
                   ; Text store object
store-path-type =/ "output:out"
                   ; Fixed-output store object

store-directory   = unix-directory / windows-directory
unix-directory    = "/" / 1*("/" unix-directory-part)
windows-directory = windows-volume ("\" / 1*("\" windows-directory-part))

hash-algo    = %s"md5" / %s"sha1" / %s"sha256" / %s"sha512"
lower-hexdig = DIGIT / %s"a" / %s"b" / %s"c" / %s"d" / %s"e" / %s"f"

  3. Compute the SHA-256 digest of the string from the previous step.

  4. Build a 20-byte string based on the SHA-256 digest from the previous step. The first 12 bytes of the SHA-256 digest are XOR-ed with the last 12 bytes of the SHA-256 digest and then used as the first 12 bytes of the string. The last 8 bytes of the string are the 13th through 20th bytes of the SHA-256 digest.

  5. The 20-byte string from the previous step is {term}Nix-Base-32-encoded <Nix Base-32> to produce the store path digest.