Document setting up signed binary caches

This commit is contained in:
Eelco Dolstra 2015-06-01 17:14:16 +02:00
parent b8b571cfc1
commit 53dd97bb9d
3 changed files with 138 additions and 3 deletions

View file

@ -401,6 +401,26 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
</varlistentry> </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> <varlistentry><term><literal>binary-caches-parallel-connections</literal></term>
<listitem><para>The maximum number of parallel HTTP connections <listitem><para>The maximum number of parallel HTTP connections

View file

@ -27,6 +27,7 @@
<arg><option>--manifest</option></arg> <arg><option>--manifest</option></arg>
<arg><option>--manifest-path</option> <replaceable>filename</replaceable></arg> <arg><option>--manifest-path</option> <replaceable>filename</replaceable></arg>
<arg><option>--url-prefix</option> <replaceable>url</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> <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
</refsynopsisdiv> </refsynopsisdiv>
@ -155,6 +156,19 @@ automatically.</para>
</varlistentry> </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> </variablelist>
</refsection> </refsection>
@ -203,6 +217,40 @@ $ nix-pull http://example.org/cache
to cause the binaries to be used by subsequent Nix operations.</para> 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> </refsection>
@ -303,6 +351,7 @@ NarHash: sha256:0s491y1h9hxj5ghiizlxk7ax6jwbha00zwn7lpyd5xg5bhf60vzg
NarSize: 109521136 NarSize: 109521136
References: 2ma2k0ys8knh4an48n28vigcmc2z8773-linux-headers-2.6.23.16 ... References: 2ma2k0ys8knh4an48n28vigcmc2z8773-linux-headers-2.6.23.16 ...
Deriver: 7akyyc87ka32xwmqza9dvyg5pwx3j212-glibc-2.7.drv Deriver: 7akyyc87ka32xwmqza9dvyg5pwx3j212-glibc-2.7.drv
Sig: cache.example.org-1:WepnSp2UT0odDpR3NRjPVhJBHmdBgSBSTbHpdh4SCz92nGXwFY82bkPEmISoC0hGqBXDXEmB6y3Ohgna3mMgDg==
</screen> </screen>
The fields are as follows: The fields are as follows:
@ -381,6 +430,22 @@ The fields are as follows:
</varlistentry> </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> </variablelist>
</para> </para>

View file

@ -1338,6 +1338,56 @@ $ nix-store --clear-failed-paths *
</refsection> </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
its 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> <refsection condition="manpage"><title>Environment variables</title>