Comparison of secret managing schemes

Warning: You are reading an article on the deprecated unofficial wiki. For the up to date version of this article, see https://wiki.nixos.org/wiki/Comparison_of_secret_managing_schemes.

Introduction

Sometimes you need to use secrets in your system configuration. Those can range from user passwords and Wifi passwords over private keys (ssh, ssl, ...) to API tokens and similar things. Normally one would store this kind of information in files with restricted access rights (only readable by some Unix user) or even encrypt them on disk. Nix and NixOS store a lot of information in the world-readable Nix store where at least the former is not possible. People who track their configuration with Git (or use Flakes) might even want to store these secrets in the Git repository but still upload the repository somewhere.

In these cases it is necessary to think about a suitable scheme to manage the relevant secrets so that they are only readable by the right people or machines. This page tries to give an overview of different schemes that can be used and outlines the aims, requirements and implications of each.

This page was created from a discussion on Discourse and is likely never complete as people will start new projects to handle secrets in Nix(OS).

Definitions

The properties of the different schemes that are listed in the table below are explained in detail here. You are welcome to add more schemes (rows) to the table; please try to fill in as many of the properties as you can. If you add a new column please try to fill it for all existing rows as much as possible.

scheme

the name of the scheme, if possible a link to the official website or source, maybe a short description

pre build

Where does the secret reside before the configuration is build? In a file, in a nix expression, in an external database (password manager)? Is it encrypted?

build time

what happens at build time, is the secret decrypted or encrypted, which master passwords, passphrases or helper programs are needed

in the store (on disk)

Is the data stored in /nix/store after the build? Is it encrypted. This has implications for reproducability. If a secret is not stored in the nix store it might be more difficult to recreate an old system configuration

system activation

what happens to the data at system activation, that is at boot time or when nixos-rebuild switch or --rollback is executed

runtime

where does the secret reside after system activation, is it encrypted, who can read it

encryption technology

which programs or tools are used for encryption or decryption of secrets; whether ssh-agent, gpg-agent or similar are supported

"official" project

whether this is a published software project (maybe even actively developed) or just some notes in a forum or a blog entry

Comparison

In case this table is difficult to read with the default theme, try the vector theme.

Comparison of secret managing schemes

scheme	pre build	build time	/nix/store (or on disk)	system activation	runtime	encryption technology	"official" project	templating support	notes
deployment.keys. options of NixOps	plain value in a nix expression		not stored in the store	N/A the user has to run nixops send-keys to create these files after a (manual) reboot (not required after every reboot if destDir is persistent storage)	unencrypted in /run/keys/... or configured path		yes	no	"out of band", secret management happens outside of nixos-rebuild
agenix	encrypted raw files, agenix CLI encrypts with the user and host ssh key		encrypted	decryption with the host ssh key	unencrypted in /run/secrets/... or configured path	uses age with ssh user and host keys, does not support ssh-agent	yes	no
sops-nix	encrypted with age, pgp or ssh key, support yubikey when gnupg is used, can be stored in git		encrypted	decryption	stored in /run/secrets/ with configurable permissions	uses sops	yes	yes	can be used with NixOps, nixos-rebuild, krops, morph, nixus
krops	stored in the password store					uses the password store (aka pass) which uses gpg	yes	no
terraform-nixos	value of a nix expression		stored in /var/keys/... owned by the keys unix group				yes	no	see [1]
secrix	encrypted raw files, like agenix		encrypted	decryption with the host ssh key	unencrypted in configured path in /run	uses age by default with ssh user and host keys, does not support ssh-agent	yes	no	Focuses on trying to keep secrets decrypted for a minimal amount of time
scheme	pre build	build time	/nix/store (or on disk)	system activation	runtime	encryption technology	"official" project	templates	notes
Blog entry 1	plain text file (unencrypted), can be stored in git	encryption	encrypted in the store	decrypted by a systemd unit		uses age and the ssh host key of the target machine	no, blog, and config repository	no	Warning: plaintext is unencrypted in the nix store of the deployment machine
Blog entry 2 wrapper around pass based on nix-plugins	stored in the password store	data is retrieved/decrypted with pass during evaluation time	unencrypted in the store			uses the password store (aka pass) which uses gpg	no	no
builtins.readfile builtins.exec discussion on discourse about build time secrets	builtins.readfile can read any file, builtins.exec can execute commands and thus query any kind of database or password manager etc.	these functions return values in a nix expression, it is up to the user what happens to these values in configuration.nix	see "build time"	see "build time"	see "build time"	these functions just read files or execute commands, they do not provide anything inherently "secure" or "cryptographic"	no	no	the linked discussion is about a signing key that is only needed during build time and should not be stored in the nix store at all
scheme	pre build	build time	/nix/store (or on disk)	system activation	runtime	encryption technology	"official" project	notes