Nix Hash: Difference between revisions
Artoria2e5 (talk | contribs) →What exactly is hashed: I don't think we should paragraph-break here |
replace link with more permanent version |
||
(3 intermediate revisions by 3 users not shown) | |||
Line 2: | Line 2: | ||
[https://en.wikipedia.org/wiki/Cryptographic_hash_function Cryptographic hashes] play an essential role in a lot of places in the Nix ecosystem. When using a hash somewhere, two criteria are essential to do so properly: the '''algorithm''' used and the '''encoding''' (and, to some extent, ''what'' is hashed). | [https://en.wikipedia.org/wiki/Cryptographic_hash_function Cryptographic hashes] play an essential role in a lot of places in the Nix ecosystem. When using a hash somewhere, two criteria are essential to do so properly: the '''algorithm''' used and the '''encoding''' (and, to some extent, ''what'' is hashed). | ||
Supported algorithms are <code>md5</code>, <code>sha1</code>, <code>sha256</code>, <code>sha512</code>. The first two are deprecated and should not be used anymore, but you may still stumble upon them in existing code. | Supported algorithms are <code>md5</code>, <code>sha1</code>, <code>sha256</code>, <code>sha512</code>, <code>BLAKE3</code>. The first two are deprecated and should not be used anymore, but you may still stumble upon them in existing code. | ||
A hash – which is simply a sequence of bytes – is usually encoded in order to be representable as string. Common encodings are <code>base16</code> (commonly called "hex"), <code>base32</code> and <code>base64</code>. Note that the base32 is a [https://github.com/NixOS/nix/blob/ | A hash – which is simply a sequence of bytes – is usually encoded in order to be representable as string. Common encodings are <code>base16</code> (commonly called "hex"), <code>base32</code> and <code>base64</code>. Note that the base32 is a [https://github.com/NixOS/nix/blob/c70e1433abb61012dffdcd4559ec2aa87672e15c/src/libutil/hash.cc#L91-L112 '''custom one'''] that is not documented nor standardized in any way! If possible, use the provided hashing tools to convert hashes to it (see below). base32 is used by Nix in a lot of places because it is shorter than hex but can still safely be part of a file path (as it contains no slashes). | ||
== Usage == | == Usage == | ||
Line 19: | Line 19: | ||
The format of the hash follows the [https://www.w3.org/TR/SRI/#introduction SRI (Subresource Integrity)] specification. | The format of the hash follows the [https://www.w3.org/TR/SRI/#introduction SRI (Subresource Integrity)] specification. | ||
== Updating | === Updating packages === | ||
[https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers-caveats Using TOFU to get the new hash] | [https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers-caveats Using TOFU to get the new hash] | ||
Line 37: | Line 37: | ||
When dealing with remote files, <code>nix-prefetch-url</code> offers a handy shortcut for downloading the file into the Nix store and printing out its hash. (<code>nix-prefetch-url --unpack</code> is its <code>fetchzip</code> equivalent.) | When dealing with remote files, <code>nix-prefetch-url</code> offers a handy shortcut for downloading the file into the Nix store and printing out its hash. (<code>nix-prefetch-url --unpack</code> is its <code>fetchzip</code> equivalent.) | ||
To get an SRI hash, which isn't supported by <code>nix-prefetch-url</code>, use <code>nix store prefetch-file https://...</code> instead. | |||
== Libraries == | == Libraries == |