View source for Comparison of secret managing schemes

== Introduction ==

Some NixOS modules require the use of secret information to function correctly. This information can include user<ref>The <code>[http://search.nixos.org/options?show=users.users.%253Cname%253E.hashedPasswordFile <nowiki>users.users.<name>.hashedPasswordFile</nowiki>]</code> option.</ref> and Wi-Fi passwords<ref>The {{nixos:option|networking.wireless.secretsFile}} option.</ref>, cryptographic private keys<ref>The {{nixos:option|services.openssh.hostKeys}} option.</ref> and secret API tokens<ref>The {{nixos:option|services.mjolnir.accessTokenFile}} option. (among many others)</ref>, among many other examples of secret information. On a standard Linux system, one would store this kind of information in separate files with restricted access rights (only readable by some Unix user) or encrypt them on-disk. 

While this paradigm is still available to NixOS users, a Nix-managed system is in an unique position to leverage <b>secret managing schemes</b>: special software capable of deploying secret information securely. Instead of writing the secret information unencrypted to a NixOS configuration, the software described below can decrypt the relevant secrets and deploy them at various stages of the NixOS system deployment process. This advanced form of secrets configuration is even more important for NixOS configurations tracked with Git or [[Flakes]], as one will be able to store these encrypted secrets in the Git repository and still be able to upload the repository on the public Internet.

The most popular options for secrets management are [[Agenix]], [https://github.com/Mic92/sops-nix sops-nix] or the secrets management solution native to the deployment tool you chose. Below follows a more in-depth comparison including less well-known solutions.

== Definitions ==

The properties of the different schemes that are listed in the table below are explained in detail here.

; Scheme
: The name of the scheme; if possible also a link to the official website or source.
; Pre-build
: Where does the secret reside before the configuration is built? In a file? In a Nix expression? In an external database? Is it encrypted?
; Build time
: What happens at build time? Is the secret decrypted or encrypted? Which primary passwords, passphrases or helper programs are needed?
; In the store
: Is the data stored in <code>/nix/store</code> after the build? Is it encrypted? This has implications for reproducibility: 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 <code>nixos-rebuild switch</code> or <code>nixos-rebuild switch --rollback</code> 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? Is <code>ssh-agent</code> or <code>gpg-agent</code> supported?
; Usable project
: Whether this is a published software project (maybe even actively developed) or just usage notes in a forum or a blog entry.
; Templating support
: Whether the project supports configuration templates, a way to seamlessly embed secrets in the syntax of a specific configuration file.

== Comparison ==

{| class="wikitable"
|+ Comparison of secret managing schemes<ref>[https://discourse.nixos.org/t/comparison-of-different-key-secret-managing-schemes/12001/1 Comparison of different key/secret managing schemes] on the NixOS Discourse</ref>
! Scheme
! Pre-build
! Build time
! In the store
! System activation
! Runtime
! Encryption technology
! Usable project
! Templating support
! Additional notes
|-
| <code>[https://nixops.readthedocs.io/en/latest/overview.html#managing-keys <nowiki>deployment.keys.<name></nowiki>]</code> option in [[NixOps]]
| Plaintext value in a Nix expression.
| N/A
| Not stored in the Nix Store.
| N/A<ref group="note">The user has to run <code>nixops send-keys</code> to create these files after a (manual) reboot. (not required after every reboot if <code>destDir</code> is in persistent storage)</ref>
| Unencrypted in <code>/run/keys</code> or configured path.
| N/A
| Yes
| No
| Secret management happens outside of <code>nixos-rebuild</code>
|-
| [[Agenix]]
| Encrypted raw files, <code>agenix</code> CLI encrypts with the user and host ssh key
| N/A
| Encrypted
| Decryption with the host SSH key.
| Unencrypted in <code>/run/secrets</code> or configured path.
| Uses <code>[https://github.com/FiloSottile/age age]</code> with SSH user and host keys; does not support <code>ssh-agent</code>.
| Yes
| No
|
|-
| <code>[https://github.com/oddlama/agenix-rekey agenix-rekey]</code>
| Extended <code>agenix</code>.
| N/A
| Encrypted
| Decryption with the host SSH key.
| Unencrypted in <code>/run/secrets</code> or configured path.
| Use with <code>agenix</code>; provides more convenience.
| Yes
| No
|
|-
| [https://github.com/yaxitech/ragenix ragenix]
| Encrypted raw files, <code>ragenix</code> CLI encrypts with the user and host SSH keys.
| N/A
| Encrypted
| Decryption with the host SSH key.
| Unencrypted in <code>/run/secrets</code> or configured path.
| Drop-in replacement of <code>agenix</code>, written in Rust and based on the <code>age</code> crate.
| Yes
| No
|
|-
| [https://github.com/Mic92/sops-nix sops-nix]
| Encrypted file with <code>age</code>, PGP or SSH key, support yubikey when gnupg is used, can be stored in a Git repository.
| N/A
| Encrypted
| Decryption with GPG or <code>age</code> keys.
| Stored in <code>/run/secrets</code> with configurable permissions.
| Uses [https://github.com/getsops/sops SOPS].
| Yes
| Yes
| Can be used with [[NixOps]], <code>nixos-rebuild</code>, [https://github.com/krebs/krops/ krops], [https://github.com/DBCDK/morph morph], [https://github.com/Infinisil/nixus nixus] and possibly other deployment tools.
|-
| [https://github.com/krebs/krops krops]
| Stored in [https://www.passwordstore.org/ the password store].
|
|
|
|
| Uses [https://www.passwordstore.org/ the password store] (aka <code>pass</code>) which uses GPG.
| Yes
| No
|-
| [https://github.com/tweag/terraform-nixos terraform-nixos]
| Plaintext value in a Nix expression.
|
|
|
| Stored in <code>/var/keys</code> owned by the <code>keys</code> Unix group.
|
| Yes
| No
| See the <code>[https://github.com/tweag/terraform-nixos/tree/master/deploy_nixos#inputs terraform-nixos]</code> documentation.
|-
| [https://github.com/platonic-systems/secrix secrix]
| Encrypted raw files, like <code>agenix</code>.
|
| Encrypted
| Decryption with the host SSH key.
| Unencrypted in configured path in <code>/run</code>.
| Uses <code>[https://github.com/FiloSottile/age age]</code> by default with SSH user and host keys; does not support <code>ssh-agent</code>.
| Yes
| No
| Focuses on trying to keep secrets decrypted for a minimal amount of time.
|-
| [https://github.com/milieuim/vaultix vaultix]
| Encrypted raw files like agenix
|
| Encrypted
| Decryption with the host SSH key.
| Unencrypted in specific paths.
| Powered by the <code>[https://docs.rs/age/latest/age/ age]</code> Rust crate.
| Yes
| Yes
|-
| [https://github.com/brizzbuzz/opnix brizzbuzz/opnix]
|
|
|
|
|
| 1password
|
|
|
|-
| [https://elvishjerricco.github.io/2018/06/24/secure-declarative-key-management.html Blog Entry]: wrapper around <code>pass</code> based on <code>[https://github.com/shlevy/nix-plugins nix-plugins]</code>.
| Stored in [https://www.passwordstore.org/ the password store].
| Data is retrieved/decrypted with <code>pass</code> during evaluation time.
| Unencrypted in the store.
|
|
| Uses [https://www.passwordstore.org/ the password store] (aka <code>pass</code>) which uses GPG.
| No
| No
|
|-
| <code>builtins.readfile</code>, <code>builtins.exec</code><ref>[https://discourse.nixos.org/t/using-an-external-secret-file-in-a-nix-sandboxed-build/3274 Using an external secret file in a Nix sandboxed build] on the NixOS Discourse</ref>
| <code>builtins.readfile</code> can read any file, <code>builtins.exec</code> can execute commands and thus query any kind of database or password manager.
| These functions return values in a Nix expression; it is up to the user what happens to these values in the NixOS configuration.
| 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 referenced NixOS Discourse 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
! In the store
! System activation
! Runtime
! Encryption technology
! Usable project
! Templating support
! Additional notes
|}

==Notes==
<references group="note" />

==References==
<references />

[[Category:Guide]]