From 351eb06c9e48c668fc3d3ba2d3706f18f8447746 Mon Sep 17 00:00:00 2001 From: Sander Date: Thu, 4 Apr 2024 07:31:54 +0000 Subject: [PATCH] Update docs regarding signing keys --- source/getting-started.rst | 22 ++++++++++++++-------- source/security.rst | 16 +++++++++------- 2 files changed, 23 insertions(+), 15 deletions(-) diff --git a/source/getting-started.rst b/source/getting-started.rst index 42a1944..c1fe475 100644 --- a/source/getting-started.rst +++ b/source/getting-started.rst @@ -38,29 +38,35 @@ b) Per-cache These allow write and/or read access to only a specific binary cache. On `dashboard `_ you can click on your newly generated binary cache `Settings` and - generate new term:`access token`. + generate a new :term:`access token`. - You can set auth token either with: + You can set the auth token with either: a) ``$ cachix authtoken XXX`` b) ``$ export CACHIX_AUTH_TOKEN=XXX`` -Signing key (advanced mode) +Signing key (advanced) --------------------------- -.. note:: In case you didn't opt-in to self-generated signing key, you can skip this step. +.. note:: If you didn't opt in to using a self-generated signing key when creating the cache, you can skip this step. -`Read a blog post on upsides and downsides of self-generated signing key. `_ +Store paths in Nix are signed with public-key encryption to prevent tampering. +By default, Cachix will manage the entire signing process for you and it's what we recommend for most users. -To generate a :term:`signing key`:: +Advanced users can opt in to use their own signing key when creating a new cache. The signing key can be securely generated and stored on your machine. +The Cachix CLI will then sign the store paths locally, adding a extra layer of protection against Man-In-The-Middle and cache poisoning attacks. + +`Read our blog post on the pros and cons of using a self-generated signing key. `_ + +To generate a new :term:`signing key`:: $ cachix authtoken $ cachix generate-keypair -:term:`Signing key ` is saved locally on your computer (the only copy!) and printed -to stdout, make sure to make a backup. +The :term:`Signing key ` is saved locally on your computer and is printed +to stdout. This is the only copy. Make sure to create a backup. Cachix will automatically pick up the recently written signing key (or if you export it via environment variable ``$CACHIX_SIGNING_KEY``). diff --git a/source/security.rst b/source/security.rst index 99113fa..c77b479 100644 --- a/source/security.rst +++ b/source/security.rst @@ -17,20 +17,22 @@ If you'd like to deny access to specific organizations, follow Secrets ------- -:term:`signing key` is used to verify the pusher (write access) of the entries to the binary cache. +An :term:`access token` is used to authenticate the user with the Cachix HTTP API. -:term:`access token` is used to authenticate the user to the Cachix HTTP API. +Public caches can be read by anyone on the internet. An :term:`access token` is required to push to the cache. -For public caches, :term:`signing key` is needed when pushing to Cachix. Otherwise all read access is public to everyone. +For private caches, both read or write access requires an :term:`access token`. -For private caches, on top of the :term:`signing key`, all requests also need :term:`access token` configured. +A :term:`signing key` is used to verify the pusher of the entries to the binary cache. +For managed caches (the default), the :term:`signing key` is created and managed by Cachix. Cachix will sign the store paths with this key once they're pushed to the cache. +For self-signed caches, you create and manage your own :term:`signing key` locally. Signing happens on the machine pushing the store paths. Binary Caches ------------- By using a binary cache, you are trusting that the binaries within were built by the user -with write access. +with write access. -For that reason the github username of the owner of the binary cache is listed on the public page -so that you can verify their social trust. \ No newline at end of file +For that reason, the GitHub username of the owner of the binary cache is listed on the public page +so that you can verify their social trust.