[RFC 0005] Nix encryption

rfcs/0005-nix-encryption.md

@@ -0,0 +1,273 @@
+---
+feature: nix-encryption
+start-date: 2016-03-28
+author: Eelco Dolstra
+co-authors:
+related-issues: https://github.com/NixOS/nix/issues/8, https://github.com/NixOS/nix/pull/329
+---
+
+# Summary
+[summary]: #summary
+
+We currently lack a way to store secret information in the Nix
+store. The proposal is to add a builtin function to Nix to allow
+secrets to be encrypted at evaluation time with a key. At runtime,
+files containing encrypted data can be decrypted using the same key.
+
+# Motivation
+[motivation]: #motivation
+
+It is often necessary to store secrets such as passwords or SSL
+certificates in NixOS system closures. Unfortunately, the Nix store is
+world-readable, so this is currently not possible in a secure way;
+anybody who gains access to the filesystem of a NixOS machine can read
+any file in its Nix store. Nevertheless, lots of NixOS modules *do*
+store secrets in the Nix store (see
+https://github.com/NixOS/nixpkgs/issues/24288), many of them lacking
+warnings about the danger of doing so.
+
+# Detailed design
+[design]: #detailed-design
+
+The proposal consists of the following components:
+
+* A builtin function `encryptString :: Path -> String -> String` that
+  encrypts a string using a symmetric key stored in the specified
+  path. The encryption is done using libsodium's authenticated
+  encryption function `crypto_secretbox_easy()`. The resulting string
+  has the format `<{|nixcrypt:base64-encoded-data|}>`, where
+  `base64-encoded-data` is the base-64-encoded output of
+  `crypto_secretbox_easy()`, along with the nonce used.
+
+* A command `nix decrypt` to decrypt files containing encrypted
+  strings produced by `encryptString`. This command searches for
+  `<{|nixcrypt:...|}>` fragments and decrypts them using a decryption
+  key specified on the command line. Any other data is copied
+  verbatim.
+
+* A command `nix generate-key` to generate a key in the format
+  expected by `encryptString` and `nix decrypt`.
+
+A typical usage in a module NixOS would look like this:
+
+```
+let
+  configFile = pkgs.writeText "foo.conf"
+    ''
+      # Store the password of the foo service in encrypted form.
+      password=${builtins.encryptString <nixos-store-key> cfg.password}
+    '';
+in {
+
+  systemd.services.foo = {
+    preStart =
+      ''
+        # Decrypt the configuration file.
+        ${config.nix.package}/bin/nix-store \
+          --decrypt ${toString <nixos-store-key>} \
+          ${configFile} > /run/secret/foo.conf
+      '';
+    # Run the service using the decrypted configuration file/
+    serviceConfig.Exec =
+      "${pkgs.foo}/bin/foo -c /run/secret/foo.conf";
+  };
+};
+```
+(See below for a discussion of simplifications to this example.)
+
+At evaluation time, this causes the following string to be emitted by
+the Nix evaluator:
+```
+password=<{|nixcrypt:base64-encoded-data|}>
+```
+
+Note that we don't necessarily encrypt entire files (though that's
+possible); generally, we'll encrypt only the sensitive parts of
+files. This allows users to read non-sensitive parts of configuration
+files. It *may* also enable graceful degradation if secrets cannot be
+decrypted, but this is risky (see below under "Decryption failure").
+
+The assumption is that `<nixos-store-key>` resolves to something like
+`/var/lib/nixos/store-key`, which should contain a key generated by
+`nix generate-key` and should obviously be readable by root only.
+
+# Prototype
+
+* Nix implementation: https://github.com/edolstra/nix/commit/6b70036
+* Nixpkgs example: https://github.com/edolstra/nixpkgs/commit/4c8212069429bf9fb959e00ce8d9345ac7cb7ff0
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+* The main downside of this approach is that encrypted files need to
+  be decrypted before they can be used. Thus, for example, a daemon
+  configuration file cannot be used directly from the Nix store by
+  passing something like `--config /nix/store/.../foo.conf` to the
+  daemon. Instead, we have to decrypt the configuration file to some
+  suitably secure temporary location in a pre-start script, and then
+  pass that location (e.g. `--config /tmp/.../foo.conf`).
+
+  In NixOS, we can provide some helper functions to reduce boilerplate
+  code dealing with encrypted files in systemd services. For example,
+  we can add an option to allow modules to declare files that need
+  decryption:
+
+    ```
+    security.encryptedFiles = [ wpaSupplicantConf ];
+    ```
+
+  which would be decrypted by the activation script to a well-known
+  location such as `/var/secrets/<storepath>`. This way, services can
+  refer to the decrypted path easily:
+
+    ```
+    systemd.services.wpa_supplicant.serviceConfig.Exec =
+      "wpa_supplicant -c /var/secrets/${wpaSupplicantConf}";
+      # i.e. ... -c /var/secrets/nix/store/.../wpa_supplicant.conf
+    ```
+
+  The above can also be extended to support access by non-root users,
+  e.g.
+
+    ```
+    security.encryptedFiles = [
+      { file = httpdConf;
+        owner = "httpd";
+      }
+    ];
+    ```
+
+  An alternative is to write a little FUSE filesystem that
+  transparently decrypts files on the underlying filesystem. For
+  example, the filesystem mounted on /var/secrets (accessible only to
+  root) would automatically decrypt files from /nix/store. But that's
+  probably over-engineering it.
+
+* This approach only allows secrets to be stored at evaluation time
+  and used at runtime. Secrets cannot be created or used at build time
+  (except by copying encrypted secrets verbatim), since no keys are
+  available at build time.
+
+* The fact that encrypted secrets are world-readable allows attackers
+  to mount (offline) brute-force attacks. Depending of how we handle
+  nonces (see below), it may also be possible for attackers to observe
+  that secret values have changed, that identical secrets are used in
+  multiple places, or that secrets have changed back to a previous
+  value.
+
+# Alternatives
+[alternatives]: #alternatives
+
+## Access control
+
+The main alternative is to add some notion of access control
+(i.e. ownership and permissions) to Nix store paths. (See
+e.g. https://github.com/NixOS/nix/pull/329.) This has the advantage
+that secret files can be used "directly" by a sufficiently privileged
+user. However, adding access control raises many issues:
+
+* Nix has always assumed a world-readable store, so we'd have to
+  carefully audit that nothing in the daemon can leak the contents of
+  store paths.
+
+* Users should be allowed to export closures that they built, even
+  when those closures include paths not readable by them. This is
+  essential for tools such as NixOps, which perform a `nix-build`
+  followed by `nix-copy-closure`, generally running under a
+  unprivileged user account. However, this requires Nix to keep track
+  of which users instantiated or built which paths, which is an
+  unfortunate amount of statefulness. It also prevents an evaluation
+  optimization: currently, if we're adding a derivation X that depends
+  on derivation Y to the store, we don't have to check Y if we see
+  that X is already valid.
+
+* If we want to allow the creation of files with arbitrary uids/gids,
+  how does a builder create them? The builder runs as a non-privileged
+  `nixbld` user, so it does not have the ability to chown files.
+
+  Also, the desired users and groups may not exist at build time. (On
+  NixOS, they are created at activation time, so *after* the system
+  has been built.)
+
+  Finally, allowing builders to create files with arbitrary ownership
+  (in particular when combined with permissions) creates obvious
+  security issues.
+
+* The NAR format needs to be extended to store ownership and
+  permission data. A NAR can no longer necessarily be unpacked in a
+  lossless way if the required uids/gids don't exist.
+
+* How should binary caches deal with ownership and permissions?
+
+Encryption support, on the other hand, is a very localised change,
+requiring only the addition of an encryptString primop and a
+decryption tool.
+
+## NixOps keys mechanism
+
+NixOps has a somewhat ad hoc mechanism for dealing with
+secrets. Secrets can be defined in the NixOps machine specification
+via the option `deployment.keys`:
+
+```
+deployment.keys.my-password.text = "fnord";
+```
+
+These secrets do not end up in the system closure; rather, they are
+copied by the command `nixops send-keys` to `/run/keys/<key-id>`.
+
+This mechanism could be generalised beyond NixOps into a Nix feature.
+
+# Unresolved questions
+[unresolved]: #unresolved-questions
+
+## Reproducibility and nonces
+
+An important goal of NixOS is reproducibility. Nowadays this goal also
+includes bitwise-identical reproducibility (see
+https://reproducible-builds.org/); that is, building a NixOS system
+twice from the same Nix expressions should yield an identical result.
+
+However, libsodium's authenticated encryption requires supplying a
+nonce which (by definition) should be used only once. From
+https://download.libsodium.org/doc/secret-key_cryptography/authenticated_encryption.html:
+"The nonce doesn't have to be confidential, but it should never ever
+be reused with the same key."
+
+Unfortunately, the uniqueness of nonces is at odds with the
+requirement of bitwise reproducibility: if multiple calls to
+`encryptString` with the same inputs return different results, then
+logically identical NixOS system closures will not be bitwise
+identical.
+
+We could replace the nonce with a deterministic value, but it's not
+entirely clear what the cryptographic implications are. At the very
+least, it allows attackers to obverse that a secret has changed, or
+that it has changed back to a previously observed value.
+
+## Decryption failure
+
+What should `nix decrypt` do if it cannot decrypt an encrypted string?
+Keeping the encrypted string or replacing it by an empty string is
+dangerous because it can cause e.g. a predictable password to be
+emitted. Probably the best solution is to fail by default (i.e. not
+emit a file at all), or optionally replace the encrypted string by a
+cryptographically secure random string.
+
+## Public-key cryptography
+
+We could have `encryptString` use a public key, and `nix decrypt` use
+the corresponding private key. This is kind of nice because Nix
+already has a command to generate public/private key pairs using
+libsodium for binary cache signing.
+
+However, I couldn't think of a plausible use case for this. It would
+allow the user who generates/builds the configuration not to have the
+decryption key, but that doesn't seem very useful.
+
+## Key generation
+
+Currently, we assume that `<nixos-store-key>` exists beforehand. It
+might be nice if Nix can generate keys on the fly. For example,
+`<nixos-store-key>` could resolve to `$HOME/.config/nix/key` and be
+generated on first use.