Comparison of secret managing schemes: Difference between revisions

From NixOS Wiki
← Older edit
VisualWikitext
imported>Lucc
Rewrite to follow the Manual of Style and a general cleanup of outdated information. TODO: the rest of the table needs a cleanup.
 
(20 intermediate revisions by 13 users not shown)
Line 1: Line 1:
== Introduction ==
== Introduction ==


Sometimes you need to use secrets in your system configuration. Those can
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.  
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
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.
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.


== Definitions ==
== Definitions ==


The properties of the different schemes that are listed in the table below are
The properties of the different schemes that are listed in the table below are explained in detail here.
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
; Scheme
: the name of the scheme, if possible a link to the official website or source, maybe a short description
: The name of the scheme; if possible also a link to the official website or source.
; pre build
; 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?
: 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
; Build time
: what happens at build time, is the secret decrypted or encrypted, which master passwords, passphrases or helper programs are needed
: What happens at build time? Is the secret decrypted or encrypted? Which primary passwords, passphrases or helper programs are needed?
; in the store (on disk)
; In the store
: Is the data stored in {{ic|/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
: 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
; System activation
: what happens to the data at system activation, that is at boot time or when {{ic|nixos-rebuild switch}} or {{ic|--rollback}} is executed
: 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
; Runtime
: where does the secret reside after system activation, is it encrypted, who can read it
: Where does the secret reside after system activation? Is it encrypted? Who can read it?
; encryption technology
; Encryption technology
: which programs or tools are used for encryption or decryption of secrets; whether {{ic|ssh-agent}}, {{ic|gpg-agent}} or similar are supported
: Which programs or tools are used for encryption or decryption of secrets? Is <code>ssh-agent</code> or <code>gpg-agent</code> supported?
; "official" project
; Usable project
: whether this is a published software project (maybe even actively developed) or just some notes in a forum or a blog entry
: 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 ==
== Comparison ==
In case this table is difficult to read with the default theme, try [https://nixos.wiki/index.php?title=Comparison_of_secret_managing_schemes&useskin=vector#Comparison the vector theme].


{| class="wikitable"
{| class="wikitable"
|+ Comparison of secret managing schemes
|+ 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
! Scheme
! pre build
! Pre-build
! build time
! Build time
! {{ic|/nix/store}} (or on disk)
! In the store
! system activation
! System activation
! runtime
! Runtime
! encryption technology
! Encryption technology
! "official" project
! Usable project
! notes
! 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
|-
|-
| [https://hydra.nixos.org/build/115931128/download/1/manual/manual.html#idm140737322649152 NixOps keys]
| <code>[https://github.com/oddlama/agenix-rekey agenix-rekey]</code>
(is there a better link to the docs that does not depend on a hydra build id?)
| Extended <code>agenix</code>.
| plain value in a nix expression
| N/A
|
| Encrypted
| not stored in the store
| Decryption with the host SSH key.
| ''N/A'' the user has to run {{ic|nixops send-keys}} to create these files after a (manual) reboot (not required after every reboot if destDir is persistent storage)
| Unencrypted in <code>/run/secrets</code> or configured path.
| unencrypted in {{ic|/run/keys/...}} or configured path
| Use with <code>agenix</code>; provides more convenience.
|
| Yes
| yes
| No
| "out of band", secret management happens outside of {{ic|nixos-rebuild}}
|-
|-
| [https://github.com/ryantm/agenix agenix]
| [https://github.com/yaxitech/ragenix ragenix]
| encrypted raw files, {{ic|agenix}} CLI encrypts with the user and host ssh key
| Encrypted raw files, <code>ragenix</code> CLI encrypts with the user and host SSH keys.
|
| N/A
| encrypted
| Encrypted
| decryption with the host ssh key
| Decryption with the host SSH key.
| unencrypted in {{ic|/run/secrets/...}} or configured path
| Unencrypted in <code>/run/secrets</code> or configured path.
| uses [https://github.com/FiloSottile/age {{ic|age}}] with ssh user and host keys, does not support {{ic|ssh-agent}}
| Drop-in replacement of <code>agenix</code>, written in Rust and based on the <code>age</code> crate.
| yes
| Yes
|
| No
|-
|-
| [https://github.com/Mic92/sops-nix sops-nix]
| [https://github.com/Mic92/sops-nix sops-nix]
| encrypted with gpg or ssh key
| 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
| Encrypted
| decryption
| Decryption with GPG or <code>age</code> keys.
| stored in {{ic|/run/secrests/}} with configurable permissions
| Stored in <code>/run/secrets</code> with configurable permissions.
| uses [https://github.com/mozilla/sops sops]
| Uses [https://github.com/getsops/sops SOPS].
| yes
| Yes
| can be used with [[NixOps]], {{ic|nixos-rebuild}}, [https://github.com/krebs/krops/ krops], [https://github.com/DBCDK/morph morph], [https://github.com/Infinisil/nixus nixus]
| 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]
| [https://github.com/krebs/krops krops]
| stored in [https://www.passwordstore.org/ the password store]
| Stored in [https://www.passwordstore.org/ the password store].
|
|
|
|
|
|
|
|
| uses [https://www.passwordstore.org/ the password store] (aka {{ic|pass}}) which uses gpg
| Uses [https://www.passwordstore.org/ the password store] (aka <code>pass</code>) which uses GPG.
| yes
| Yes
|
| No
|-
|-
| [https://github.com/tweag/terraform-nixos terraform-nixos]
| [https://github.com/tweag/terraform-nixos terraform-nixos]
| value of a nix expression
| Plaintext value in a Nix expression.
|
|
| stored in {{ic|/var/keys/...}} owned by the {{ic|keys}} unix group
|
|
|
|
| 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>.
|
|
| yes
| Encrypted
| see [https://github.com/tweag/terraform-nixos/tree/master/deploy_nixos#inputs]
| 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.
|-
|-
! scheme
| [https://github.com/milieuim/vaultix vaultix]
! pre build
| Encrypted raw files like agenix
! build time
|
! {{ic|/nix/store}} (or on disk)
| Encrypted
! system activation
| Decryption with the host SSH key.
! runtime
| Unencrypted in specific paths.
! encryption technology
| Powered by the <code>[https://docs.rs/age/latest/age/ age]</code> Rust crate.
! "official" project
| Yes
! notes
| Yes
|-
|-
| [https://christine.website/blog/nixos-encrypted-secrets-2021-01-20 Blog entry 1]
| [https://github.com/brizzbuzz/opnix brizzbuzz/opnix]
| plain text file (unencrypted), can be stored in git
|
| encryption
|
| encrypted in the store
|
| decrypted by a systemd unit
|
|
| 1password
|
|
|
|
| uses [https://github.com/FiloSottile/age age] and the ssh host key of the target machine
| no, [https://christine.website/blog/nixos-encrypted-secrets-2021-01-20 blog], and [https://github.com/Xe/nixos-configs/blob/master/common/crypto/default.nix config repository]
| Warning: plaintext is unencrypted in the nix store of the deployment machine
|-
|-
| [https://elvishjerricco.github.io/2018/06/24/secure-declarative-key-management.html Blog entry 2]
| [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>.
wrapper around {{ic|pass}} based on [https://github.com/shlevy/nix-plugins nix-plugins]
| Stored in [https://www.passwordstore.org/ the password store].
| stored in [https://www.passwordstore.org/ the password store]
| Data is retrieved/decrypted with <code>pass</code> during evaluation time.
| data is retrieved/decrypted with {{ic|pass}} during evaluation time
| Unencrypted in the store.
| unencrypted in the store
|
|
|
|
| uses [https://www.passwordstore.org/ the password store] (aka {{ic|pass}}) which uses gpg
| Uses [https://www.passwordstore.org/ the password store] (aka <code>pass</code>) which uses GPG.
| no
| No
| No
|
|
|-
|-
| {{ic|builtins.readfile}}
| <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>
{{ic|builtins.exec}}
| <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.
discussion [https://discourse.nixos.org/t/using-an-external-secret-file-in-a-nix-sandboxed-build/3274 on discourse] about build time secrets
| These functions return values in a Nix expression; it is up to the user what happens to these values in the NixOS configuration.
| {{ic|builtins.readfile}} can read any file, {{ic|builtins.exec}} can execute commands and thus query any kind of database or password manager etc.
| See "build time"
| these functions return values in a nix expression, it is up to the user what happens to these values in {{ic|configuration.nix}}
| See "build time"
| 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".
| see "build time"
| No
| 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.
| 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
! Scheme
! pre build
! Pre-build
! build time
! Build time
! {{ic|/nix/store}} (or on disk)
! In the store
! system activation
! System activation
! runtime
! Runtime
! encryption technology
! Encryption technology
! "official" project
! Usable project
! notes
! Templating support
! Additional notes
|}
|}
==Notes==
<references group="note" />
==References==
<references />
[[Category:Guide]]

Latest revision as of 17:46, 23 February 2025

Introduction

Some NixOS modules require the use of secret information to function correctly. This information can include user[1] and Wi-Fi passwords[2], cryptographic private keys[3] and secret API tokens[4], 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 secret managing schemes: 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.

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 /nix/store 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 nixos-rebuild switch or nixos-rebuild switch --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? Is ssh-agent or gpg-agent 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

Comparison of secret managing schemes[5]
Scheme Pre-build Build time In the store System activation Runtime Encryption technology Usable project Templating support Additional notes
deployment.keys.<name> option in NixOps Plaintext value in a Nix expression. N/A Not stored in the Nix Store. N/A[note 1] Unencrypted in /run/keys or configured path. N/A Yes No Secret management happens outside of nixos-rebuild
Agenix Encrypted raw files, agenix CLI encrypts with the user and host ssh key N/A 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
agenix-rekey Extended agenix. N/A Encrypted Decryption with the host SSH key. Unencrypted in /run/secrets or configured path. Use with agenix; provides more convenience. Yes No
ragenix Encrypted raw files, ragenix CLI encrypts with the user and host SSH keys. N/A Encrypted Decryption with the host SSH key. Unencrypted in /run/secrets or configured path. Drop-in replacement of agenix, written in Rust and based on the age crate. Yes No
sops-nix Encrypted file with age, PGP or SSH key, support yubikey when gnupg is used, can be stored in a Git repository. N/A Encrypted Decryption with GPG or age keys. Stored in /run/secrets with configurable permissions. Uses SOPS. Yes Yes Can be used with NixOps, nixos-rebuild, krops, morph, nixus and possibly other deployment tools.
krops Stored in the password store. Uses the password store (aka pass) which uses GPG. Yes No
terraform-nixos Plaintext value in a Nix expression. Stored in /var/keys owned by the keys Unix group. Yes No See the terraform-nixos documentation.
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.
vaultix Encrypted raw files like agenix Encrypted Decryption with the host SSH key. Unencrypted in specific paths. Powered by the age Rust crate. Yes Yes
brizzbuzz/opnix 1password
Blog Entry: 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[6] builtins.readfile can read any file, builtins.exec 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

  1. ↑ The user has to run nixops send-keys to create these files after a (manual) reboot. (not required after every reboot if destDir is in persistent storage)

References

  1. ↑ The users.users.<name>.hashedPasswordFile option.
  2. ↑ The networking.wireless.secretsFile option.
  3. ↑ The services.openssh.hostKeys option.
  4. ↑ The services.mjolnir.accessTokenFile option. (among many others)
  5. ↑ Comparison of different key/secret managing schemes on the NixOS Discourse
  6. ↑ Using an external secret file in a Nix sandboxed build on the NixOS Discourse
Retrieved from "https://wiki.nixos.org/w/index.php?title=Comparison_of_secret_managing_schemes&oldid=20226"