From 663b8cc9298c87940dde596e292006fad02393c1 Mon Sep 17 00:00:00 2001 From: danbst Date: Thu, 10 Jan 2019 23:15:23 +0200 Subject: manual: document ways of obtaining source hashes ... and security nuances --- doc/Makefile | 6 ++- doc/coding-conventions.xml | 101 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 2 deletions(-) (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile index c6aed62a939..91b62fe138b 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -9,8 +9,10 @@ debug: .PHONY: format format: - find . -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \ - xmlformat --config-file "$$XMLFORMAT_CONFIG" -i {} + find . -iname '*.xml' -type f | while read f; do \ + echo $$f ;\ + xmlformat --config-file "$$XMLFORMAT_CONFIG" -i $$f ;\ + done .PHONY: fix-misc-xml fix-misc-xml: diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index a8a4557b461..88ce6281a25 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -876,6 +876,107 @@ src = fetchFromGitHub { +
+ Obtaining source hash + + + Preferred source hash type is sha256. There are several ways to get it. + + + + + + Prefetch URL (with nix-prefetch-XXX + URL, where + XXX is one of url, + git, hg, cvs, + bzr, svn). Hash is printed to + stdout. + + + + + Prefetch by package source (with nix-prefetch-url + '<nixpkgs>' -A PACKAGE.src, + where PACKAGE is package attribute name). Hash + is printed to stdout. + + + This works well when you've upgraded existing package version and want to + find out new hash, but is useless if package doesn't have top-level + attribute or package has multiple sources (.srcs, + architecture-dependent sources, etc). + + + + + Upstream provided hash: use it when upstream provides + sha256 or sha512 (when upstream + provides md5, don't use it, compute + sha256 instead). + + + A little nuance is that nix-prefetch-* tools produce + hash encoded with base32, but upstream usually provides + hexadecimal (base16) encoding. Fetchers understand both + formats. Nixpkgs doesn't stadartize on any one format. + + + You can convert between formats with nix-hash, for example: + +$ nix-hash --type sha256 --to-base32 HASH + + + + + + Extracting hash from local source tarball can be done with + sha256sum. Use nix-prefetch-url + file:///path/to/tarball if you want base32 hash. + + + + + Fake hash: set fake hash in package expression, perform build and extract + correct hash from error Nix prints. + + + You can use lib.fakeSha256, + lib.fakeSha512 or any other fake hash for this purpose. + 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). The easiest way then + would be replace hash with a fake one and rebuild. Nix build will fail and + error message will contain wanted hash. + + + + +
+ Obtaining hashes securely + + + From security point of view first four methods are most secure. + nix-prefetch-url does verify TLS certificates for + https:// URLs. TLS certificates aren't + verified in fake hash method even when there is https:// + URL. Obviously, getting hashes for http:// + URLs isn't secure, so recheck using some other network that hash is same. + + + + Upstream provided hashes are not secure if obtained over + http://. + + + + Nixpkgs build farm can act as an additional verification step. When + compromised hash was obtained, package may be rejected on Hydra due to hash + mismatch. + +
+
Patches -- cgit 1.4.1 From 2898377cd9f83405d8b87fbc0f96627a4324ca5c Mon Sep 17 00:00:00 2001 From: danbst Date: Thu, 17 Jan 2019 12:32:08 +0200 Subject: rephrase and apply suggestions --- doc/coding-conventions.xml | 68 ++++++++++++++++++++++++++++------------------ 1 file changed, 42 insertions(+), 26 deletions(-) (limited to 'doc') diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index 88ce6281a25..d2c7a1baae9 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -814,7 +814,7 @@ args.stdenv.mkDerivation (args // { There are multiple ways to fetch a package source in nixpkgs. The general - guideline is that you should package sources with a high degree of + guideline is that you should package reproducible sources with a high degree of availability. Right now there is only one fetcher which has mirroring support and that is fetchurl. Note that you should also prefer protocols which have a corresponding proxy environment variable. @@ -883,7 +883,7 @@ src = fetchFromGitHub { Preferred source hash type is sha256. There are several ways to get it. - + Prefetch URL (with nix-prefetch-XXX @@ -903,7 +903,7 @@ src = fetchFromGitHub { This works well when you've upgraded existing package version and want to - find out new hash, but is useless if package doesn't have top-level + find out new hash, but is useless if package can't be accessed by attribute or package has multiple sources (.srcs, architecture-dependent sources, etc). @@ -919,7 +919,7 @@ src = fetchFromGitHub { A little nuance is that nix-prefetch-* tools produce hash encoded with base32, but upstream usually provides hexadecimal (base16) encoding. Fetchers understand both - formats. Nixpkgs doesn't stadartize on any one format. + formats. Nixpkgs does not standardize on any one format. You can convert between formats with nix-hash, for example: @@ -941,40 +941,56 @@ $ nix-hash --type sha256 --to-base32 HASH correct hash from error Nix prints. - You can use lib.fakeSha256, - lib.fakeSha512 or any other fake hash for this purpose. + 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. + + 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). The easiest way then would be replace hash with a fake one and rebuild. Nix build will fail and - error message will contain wanted hash. + error message will contain desired hash. + This method has security problems. Check below for details. - +
Obtaining hashes securely - - - From security point of view first four methods are most secure. - nix-prefetch-url does verify TLS certificates for - https:// URLs. TLS certificates aren't - verified in fake hash method even when there is https:// - URL. Obviously, getting hashes for http:// - URLs isn't secure, so recheck using some other network that hash is same. - - - Upstream provided hashes are not secure if obtained over - http://. - - - - Nixpkgs build farm can act as an additional verification step. When - compromised hash was obtained, package may be rejected on Hydra due to hash - mismatch. + Let's say Man-in-the-Middle (MITM) sits close to your network. Then instead of fetching + source you can fetch malware, and instead of source hash you get hash of malware. Here are + security considerations for this scenario: + + + + http:// URLs are not secure to prefetch hash from; + + + + + hashes from upstream (in method 3) should be obtained via secure protocol; + + + + + 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. + + +
-- cgit 1.4.1