From 2898377cd9f83405d8b87fbc0f96627a4324ca5c Mon Sep 17 00:00:00 2001 From: danbst <abcz2.uprola@gmail.com> Date: Thu, 17 Jan 2019 12:32:08 +0200 Subject: [PATCH] rephrase and apply suggestions --- doc/coding-conventions.xml | 68 +++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 26 deletions(-) diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index 88ce6281a253..d2c7a1baae9c 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -814,7 +814,7 @@ args.stdenv.mkDerivation (args // { <para> 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 <literal>fetchurl</literal>. 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. </para> - <itemizedlist> + <orderedlist> <listitem> <para> Prefetch URL (with <literal>nix-prefetch-<replaceable>XXX</replaceable> @@ -903,7 +903,7 @@ src = fetchFromGitHub { </para> <para> 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 (<literal>.srcs</literal>, architecture-dependent sources, etc). </para> @@ -919,7 +919,7 @@ src = fetchFromGitHub { A little nuance is that <literal>nix-prefetch-*</literal> tools produce hash encoded with <literal>base32</literal>, but upstream usually provides hexadecimal (<literal>base16</literal>) encoding. Fetchers understand both - formats. Nixpkgs doesn't stadartize on any one format. + formats. Nixpkgs does not standardize on any one format. </para> <para> You can convert between formats with nix-hash, for example: @@ -941,40 +941,56 @@ $ nix-hash --type sha256 --to-base32 <replaceable>HASH</replaceable> correct hash from error Nix prints. </para> <para> - You can use <literal>lib.fakeSha256</literal>, - <literal>lib.fakeSha512</literal> 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 <literal>lib.fakeSha256</literal>, + <literal>lib.fakeSha512</literal> or any other fake hash. + </para> + <para> This is last resort method when reconstructing source URL is non-trivial and <literal>nix-prefetch-url -A</literal> isn't applicable (for example, <link xlink:href="https://github.com/NixOS/nixpkgs/blob/d2ab091dd308b99e4912b805a5eb088dd536adb9/pkgs/applications/video/kodi/default.nix#L73"> one of <literal>kodi</literal> dependencies</link>). 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. </para> + <warning><para>This method has security problems. Check below for details.</para></warning> </listitem> - </itemizedlist> + </orderedlist> <section xml:id="sec-source-hashes-security"> <title>Obtaining hashes securely</title> - <para> - From security point of view first four methods are most secure. - nix-prefetch-url does verify TLS certificates for - <literal>https://</literal> URLs. <emphasis>TLS certificates aren't - verified in fake hash method even when there is <literal>https://</literal> - URL</emphasis>. Obviously, getting hashes for <literal>http://</literal> - URLs isn't secure, so recheck using some other network that hash is same. - </para> - - <para> - Upstream provided hashes are not secure if obtained over - <literal>http://</literal>. - </para> - - <para> - 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: </para> + <itemizedlist> + <listitem> + <para> + <literal>http://</literal> URLs are not secure to prefetch hash from; + </para> + </listitem> + <listitem> + <para> + hashes from upstream (in method 3) should be obtained via secure protocol; + </para> + </listitem> + <listitem> + <para> + <literal>https://</literal> URLs are secure in methods 1, 2, 3; + </para> + </listitem> + <listitem> + <para> + <literal>https://</literal> 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 <literal>https://</literal> URL and prefetch it + with method 1. + </para> + </listitem> + </itemizedlist> </section> </section> <section xml:id="sec-patches">