From 53dd97bb9d70d98f648d3888b806b4044ea45f4c Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Mon, 1 Jun 2015 17:14:16 +0200
Subject: [PATCH] Document setting up signed binary caches

---
 doc/manual/command-ref/conf-file.xml | 20 ++++++++
 doc/manual/command-ref/nix-push.xml  | 71 ++++++++++++++++++++++++++--
 doc/manual/command-ref/nix-store.xml | 50 ++++++++++++++++++++
 3 files changed, 138 insertions(+), 3 deletions(-)

diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml
index ec96f750e..c947d19fa 100644
--- a/doc/manual/command-ref/conf-file.xml
+++ b/doc/manual/command-ref/conf-file.xml
@@ -401,6 +401,26 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
   </varlistentry>
 
 
+  <varlistentry><term><literal>signed-binary-caches</literal></term>
+
+    <listitem><para>If set to <literal>*</literal>, Nix will only
+    download binaries if they are signed using one of the keys listed
+    in <option>binary-cache-public-keys</option>.</para></listitem>
+
+  </varlistentry>
+
+
+  <varlistentry><term><literal>binary-cache-public-keys</literal></term>
+
+    <listitem><para>A whitespace-separated list of public keys
+    corresponding to the secret keys trusted to sign binary
+    caches. For example:
+    <literal>cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
+    hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=</literal>.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry><term><literal>binary-caches-parallel-connections</literal></term>
 
     <listitem><para>The maximum number of parallel HTTP connections
diff --git a/doc/manual/command-ref/nix-push.xml b/doc/manual/command-ref/nix-push.xml
index a3a3c9623..e9a8c645e 100644
--- a/doc/manual/command-ref/nix-push.xml
+++ b/doc/manual/command-ref/nix-push.xml
@@ -27,6 +27,7 @@
     <arg><option>--manifest</option></arg>
     <arg><option>--manifest-path</option> <replaceable>filename</replaceable></arg>
     <arg><option>--url-prefix</option> <replaceable>url</replaceable></arg>
+    <arg><option>--key-file</option> <replaceable>path</replaceable></arg>
     <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
@@ -43,7 +44,7 @@ source and instead download binaries from the cache
 automatically.</para>
 
 <para><command>nix-push</command> performs the following actions.
-      
+
 <orderedlist>
 
   <listitem><para>Each path in <replaceable>paths</replaceable> is
@@ -155,6 +156,19 @@ automatically.</para>
 
   </varlistentry>
 
+  <varlistentry><term><option>--key-file</option> <replaceable>path</replaceable></term>
+
+    <listitem><para>Sign the binary cache using the secret key stored
+    in <replaceable>path</replaceable>. This secret key must have been
+    created using <command
+    linkend="rsec-nix-store-generate-binary-cache-key">nix-store
+    --generate-binary-cache-key</command>. Users of this binary cache
+    should add the corresponding public key to the option
+    <option>binary-cache-public-keys</option> in
+    <filename>nix.conf</filename>.</para></listitem>
+
+  </varlistentry>
+
 </variablelist>
 
 </refsection>
@@ -203,6 +217,40 @@ $ nix-pull http://example.org/cache
 
 to cause the binaries to be used by subsequent Nix operations.</para>
 
+<para>To generate a signed binary cache, you must first generate a key
+pair, in this example called <literal>cache.example.org-1</literal>,
+storing the secret key in <filename>./sk</filename> and the public key
+in <filename>./pk</filename>:
+
+<screen>
+$ nix-store --generate-binary-cache-key cache.example.org-1 sk pk
+
+$ cat sk
+cache.example.org-1:jcMRQYFo8pQKzTtimpQLIPeHkMYZjfhB24hGfwF+u9PuX8H8FO7q564+X3G/JDlqqIqGar3OXRRwS9N3Wh3vbw==
+
+$ cat pk
+cache.example.org-1:7l/B/BTu6ueuPl9xvyQ5aqiKhmq9zl0UcEvTd1od728=
+</screen>
+
+You can then generate a binary cache signed with the secret key:
+
+<screen>
+$ nix-push --dest /tmp/cache --key-file ./sk $(type -p firefox)
+</screen>
+
+Users who wish to verify the integrity of binaries downloaded from
+your cache would add the following to their
+<filename>nix.conf</filename>:
+
+<programlisting>
+binary-caches = http://cache.example.org
+signed-binary-caches = *
+binary-cache-public-keys = cache.example.org-1:7l/B/BTu6ueuPl9xvyQ5aqiKhmq9zl0UcEvTd1od728=
+</programlisting>
+
+Nix will then ignore any binary that has a missing, incorrect or
+unrecognised signature.</para>
+
 </refsection>
 
 
@@ -224,7 +272,7 @@ Priority: 10
 The properties that are currently supported are:
 
 <variablelist>
-  
+
   <varlistentry><term><literal>StoreDir</literal></term>
 
     <listitem><para>The path of the Nix store to which this binary
@@ -303,12 +351,13 @@ NarHash: sha256:0s491y1h9hxj5ghiizlxk7ax6jwbha00zwn7lpyd5xg5bhf60vzg
 NarSize: 109521136
 References: 2ma2k0ys8knh4an48n28vigcmc2z8773-linux-headers-2.6.23.16 ...
 Deriver: 7akyyc87ka32xwmqza9dvyg5pwx3j212-glibc-2.7.drv
+Sig: cache.example.org-1:WepnSp2UT0odDpR3NRjPVhJBHmdBgSBSTbHpdh4SCz92nGXwFY82bkPEmISoC0hGqBXDXEmB6y3Ohgna3mMgDg==
 </screen>
 
 The fields are as follows:
 
 <variablelist>
-  
+
   <varlistentry><term><literal>StorePath</literal></term>
 
     <listitem><para>The full store path, including the name part
@@ -381,6 +430,22 @@ The fields are as follows:
 
   </varlistentry>
 
+  <varlistentry><term><literal>Sig</literal></term>
+
+    <listitem><para>A signature of the the form
+    <literal><replaceable>key-name</replaceable>:<replaceable>sig</replaceable></literal>,
+    where <replaceable>key-name</replaceable> is the symbolic name of
+    the key pair used to sign and verify the cache
+    (e.g. <literal>cache.example.org-1</literal>), and
+    <replaceable>sig</replaceable> is the actual signature, computed
+    over the <varname>StorePath</varname>, <varname>NarHash</varname>,
+    <varname>NarSize</varname> and <varname>References</varname>
+    fields using the <link
+    xlink:href="http://ed25519.cr.yp.to/">Ed25519 public-key signature
+    system</link>.</para></listitem>
+
+  </varlistentry>
+
 </variablelist>
 
 </para>
diff --git a/doc/manual/command-ref/nix-store.xml b/doc/manual/command-ref/nix-store.xml
index a2faeaeba..e21d53d8b 100644
--- a/doc/manual/command-ref/nix-store.xml
+++ b/doc/manual/command-ref/nix-store.xml
@@ -1338,6 +1338,56 @@ $ nix-store --clear-failed-paths *
 </refsection>
 
 
+<!--######################################################################-->
+
+<refsection xml:id='rsec-nix-store-generate-binary-cache-key'><title>Operation <option>--generate-binary-cache-key</option></title>
+
+<refsection>
+  <title>Synopsis</title>
+  <cmdsynopsis>
+    <command>nix-store</command>
+    <arg choice='plain'>
+      <option>--generate-binary-cache-key</option>
+      <option>key-name</option>
+      <option>secret-key-file</option>
+      <option>public-key-file</option>
+    </arg>
+  </cmdsynopsis>
+</refsection>
+
+<refsection><title>Description</title>
+
+<para>This command generates an <link
+xlink:href="http://ed25519.cr.yp.to/">Ed25519 key pair</link> that can
+be used to create a signed binary cache. It takes three mandatory
+parameters:
+
+<orderedlist>
+
+  <listitem><para>A key name, such as
+  <literal>cache.example.org-1</literal>, that is used to look up keys
+  on the client when it verifies signatures. It can be anything, but
+  it’s suggested to use the host name of your cache
+  (e.g. <literal>cache.example.org</literal>) with a suffix denoting
+  the number of the key (to be incremented every time you need to
+  revoke a key).</para></listitem>
+
+  <listitem><para>The file name where the secret key is to be
+  stored.</para></listitem>
+
+  <listitem><para>The file name where the public key is to be
+  stored.</para></listitem>
+
+</orderedlist>
+
+For an example, see the manual page for <command
+linkend="sec-nix-push">nix-push</command>.</para>
+
+</refsection>
+
+</refsection>
+
+
 <!--######################################################################-->
 
 <refsection condition="manpage"><title>Environment variables</title>