diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual/command-ref/conf-file.xml | 20 | ||||
| -rw-r--r-- | doc/manual/command-ref/nix-push.xml | 71 | ||||
| -rw-r--r-- | 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 ec96f750ea8c..c947d19fa0e1 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 a3a3c9623e3c..e9a8c645e8fa 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 a2faeaeba422..e21d53d8b9f0 100644 --- a/doc/manual/command-ref/nix-store.xml +++ b/doc/manual/command-ref/nix-store.xml @@ -1340,6 +1340,56 @@ $ nix-store --clear-failed-paths * <!--######################################################################--> +<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> <variablelist> |