Secrets (sops-nix)

All network secrets (passwords, keys, tokens) live encrypted in a single file managed by sops-nix 🡕. It is committed to git in encrypted form; only key holders can decrypt it.

# usr/secrets/secrets.yaml (chiffré au repos)
default-password-hash: ...
user:
  alice:
    password-hash: ...

The two keys

Decryption relies on two age 🡕 keys:

Key	Where	Role
Admin key	~/.config/sops/age/keys.txt	Edit secrets from the admin workstation
Infra key	/etc/sops/age/infra.key	Decrypt on each host at deploy time

• The admin key derives from your SSH key (~/.ssh/id_ed25519, via ssh-to-age).
• The infra key is generated once, then pushed to each host.
• Recipients are listed in usr/secrets/.sops.yaml (admin + infra).

Never commit a private key

The infra key lives outside the repo (/etc/sops/age/). The usr/secrets/ .gitignore already excludes *.key. Never copy it into the repo.

Initialize (admin host)

A single command prepares all the secrets machinery:

just configure-admin-host

It is idempotent and creates, as needed:

• the deployer’s SSH key (nix);
• a random password, known to no one, for the nix account: it is only accessed via its key;
• the admin key (from the SSH key) and the infra key (age-keygen);
• the .sops.yaml file (recipients);
• the fingerprint of the default password (just passwd-default);
• the Harmonia binary cache signing key;
• all internal secrets of the declared services (see below).

Re-run after enabling a service

The command reads the secrets required by each host in the fleet and creates any that are missing. Enabling a new service, adding a host or a zone: run just configure-admin-host again, it will only fill in what is missing.

Path detail

This step is part of the initial installation.

Internal secrets and external secrets

The framework sorts each secret into one of two families. The reference list lives in dnf/lib/secrets.nix ; each host of the farm is the authority on what is claimed.

Internal — the value only makes sense to machines, no one remembers it. just configure-admin-host draws them at random, once and for all :

Family	Examples
Kanidm OAuth2 clients	oidc-secret-<client>, oauth2-proxy cookie
Backup	restic-password-<zone>, restic/<host>/rest-password
Matrix	MAS secrets, livekit-secret, bridge tokens, turn-secret
Identities	Kanidm fallback passwords, internal TLS pair
Services	AdGuard Home, Nextcloud, Grafana, SearXNG, Vaultwarden, Garage, MinIO…

External — the value comes from elsewhere, DNF cannot invent it :

Family	Origin
Account passwords	chosen by a human (just passwd)
smtp/password (with network.smtp), wifi-password-<zone>	provider, box, operator
mautrix-telegram-api-*	my.telegram.org
luks-passphrase, yubikey/...	typed at boot, or derived from the physical key
alertmanager-matrix-*	account created on the server (just configure-alert-bot)

An internal secret can still be useful to a human

AdGuard Home admin password (adguardhome-admin-password, whose hash only partially lands on the gateways), Kanidm fallback accounts, Vaultwarden token: re-read them with just sops.

Nothing is ever overwritten

Generation only creates what is missing. Rotating a secret remains a deliberate act : delete it with just sops, then rerun just configure-admin-host.

What DNF does not know about

A missing secret that the registry cannot classify is reported on every pass. Fill it in with just sops — or, if it belongs to a framework module, add its rule in dnf/lib/secrets.nix.

Manage passwords

Command	Effect
just passwd-default	Records the fleet default password (hash only)
just passwd <user>	Sets a user’s password
just configure-admin-host	Generates missing internal secrets (OIDC, backup, service tokens…)
just yubikey <user>	Enrolls a YubiKey (derived LUKS secret + luks-passphrase)
just luks <host>	Provisions disk encryption (shared + per-host passphrases)
just sops	Edits the secrets file by hand ($EDITOR)

After a change, deploy to propagate it:

just passwd alice
just apply @user-alice     # deploys the new hash

Hashes, never plaintext

Account passwords are stored hashed (password-hash). The plaintext is never deployed to the hosts.

The default password configures no account

just passwd-default only records the hash of the fleet reference password, and bootstraps the sops file. An account only opens a session after just passwd <login>. Rotating it therefore means touching every affected account again.

Disabling sops disables passwords

darkone.system.core.enableSops = false removes the user/<login>/password-hash secrets, the framework’s only password source: the declared accounts would be created with no authentication at all. Evaluation thus stops with a message naming the option to restore. For a host deliberately without DNF accounts, also set darkone.user.build.enable = false.

YubiKey: public registry + secrets

YubiKey enrollment stores its public credentials in usr/secrets/yubikeys.json (committed in clear, unusable without the physical key) and its secrets (yubikey/<user>/<key>/luks-secret, luks-passphrase) in the sops file. See Strong authentication.

Push the key to a host

A host can only decrypt secrets with the infra key. It is placed automatically by just configure <host>, or manually:

just push-key <host>      # copies /etc/sops/age/infra.key to the host

Rarely needed

push-key is already built into just install (and just configure): in practice, you should not need to call it yourself.

Rotating the infra key

Rotation replaces the infra key across the entire fleet, in three verified steps:

Finalize only when the entire fleet is updated

finalize removes the old key. If a host hasn’t yet received the new one (rotate push-keys + just apply), it becomes impossible to decrypt, and thus inaccessible to deployment. Only run finalize after confirming that all hosts are using the new key.

1. Introduce the new key

   just rotate init        # new key + re-encryption (old + new)

2. Distribute to all hosts

   just rotate push-keys   # each host receives both keys
   just apply '*'

3. Finalize

   just rotate finalize    # discards the old key (after verification)
   just apply '*'

Mandatory order

The presence of /etc/sops/age/infra.key.old indicates a rotation in progress. Always finish with finalize: until then, hosts carry both keys.

FAQ

Hashed Vaultwarden token (Argon2)?

just invite connects on its own to the /admin panel with the plaintext vaultwarden-admin-token value. A manually set Argon2 hash forces it to ask for the token; just configure-admin-host reports it.

To migrate delete the entry with just sops, run just configure-admin-host again, then just apply hcs. Vaultwarden restarts with the new token. The panel remains protected by the network : it only responds from the LAN and the tailnet.

New admin machine, existing project?

The project’s secrets are encrypted for the old admin machine’s keys. just configure-admin-host therefore refuses to create new ones: first restore /home/nix/.ssh/id_ed25519 and /etc/sops/age/infra.key (owned by nix, mode 600).

Prepare a machine without a nix account?

just bootstrap-keys creates the keys and the sops skeleton under a given root, for example /mnt from the installer, with the credentials NixOS will give the nix account. See the Justfile.