From 0d0c03fb0bb3b7407243bde95c482831ed9bfa9c Mon Sep 17 00:00:00 2001 From: Adam Joseph <54836058+amjoseph-nixpkgs@users.noreply.github.com> Date: Wed, 12 Oct 2022 09:08:50 +0000 Subject: [PATCH] coding-conventions.chapter.md: update to account for #89885 (#191378) https://github.com/NixOS/nixpkgs/pull/89885 ensures that fetches are done securely (i.e. without `--insecure`) when the `hash` parameter is one of the four special "fake" hashes. However the manual was not updated in that PR. This commit updates the manual to account for the already-merged changes from that PR. Co-authored-by: Valentin Gagarin --- .../coding-conventions.chapter.md | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md index 585b8d3679c9..e4e7b5bd3a86 100644 --- a/doc/contributing/coding-conventions.chapter.md +++ b/doc/contributing/coding-conventions.chapter.md @@ -480,15 +480,23 @@ Preferred source hash type is sha256. There are several ways to get it. 4. Extracting hash from local source tarball can be done with `sha256sum`. Use `nix-prefetch-url file:///path/to/tarball` if you want base32 hash. -5. Fake hash: set fake hash in package expression, perform build and extract correct hash from error Nix prints. +5. Fake hash: set the hash to one of - For package updates it is enough to change one symbol to make hash fake. For new packages, you can use `lib.fakeSha256`, `lib.fakeSha512` or any other fake hash. + - `""` + - `lib.fakeHash` + - `lib.fakeSha256` + - `lib.fakeSha512` + + in the package expression, attempt build and extract correct hash from error messages. + + :::{.warning} + You must use one of these four fake hashes and not some arbitrarily-chosen hash. + + See [](#sec-source-hashes-security). + ::: This is last resort method when reconstructing source URL is non-trivial and `nix-prefetch-url -A` isn’t applicable (for example, [one of `kodi` dependencies](https://github.com/NixOS/nixpkgs/blob/d2ab091dd308b99e4912b805a5eb088dd536adb9/pkgs/applications/video/kodi/default.nix#L73)). The easiest way then would be replace hash with a fake one and rebuild. Nix build will fail and error message will contain desired hash. -::: {.warning} -This method has security problems. Check below for details. -::: ### Obtaining hashes securely {#sec-source-hashes-security} @@ -500,7 +508,7 @@ Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of f - `https://` URLs are secure in methods 1, 2, 3; -- `https://` URLs are not secure in method 5. When obtaining hashes with fake hash method, TLS checks are disabled. So refetch source hash from several different networks to exclude MITM scenario. Alternatively, use fake hash method to make Nix error, but instead of extracting hash from error, extract `https://` URL and prefetch it with method 1. +- `https://` URLs are secure in method 5 *only if* you use one of the listed fake hashes. If you use any other hash, `fetchurl` will pass `--insecure` to `curl` and may then degrade to HTTP in case of TLS certificate expiration. ## Patches {#sec-patches}