203 lines
6.4 KiB
Markdown
203 lines
6.4 KiB
Markdown
# agenix - [age](https://github.com/FiloSottile/age)-encrypted secrets for NixOS
|
|
|
|
`agenix` is a commandline tool for managing secrets encrypted with your existing SSH keys. This project also includes the NixOS module `age` for adding encrypted secrets into the Nix store and decrypting them.
|
|
|
|
## Problem and solution
|
|
|
|
All files in the Nix store are readable by any system user, so it is not a suitable place for including cleartext secrets. Many existing tools (like NixOps deployment.keys) deploy secrets separately from `nixos-rebuild`, making deployment, caching, and auditing more difficult. Out-of-band secret management is also less reproducible.
|
|
|
|
`agenix` solves these issues by using your pre-existing SSH key infrastructure and `age` to encrypt secrets into the Nix store. Secrets are decrypted using an SSH host private key during NixOS system activation.
|
|
|
|
## Features
|
|
|
|
* Secrets are encrypted with SSH keys
|
|
* system public keys via `ssh-keyscan`
|
|
* can use public keys available on GitHub for users (for example, https://github.com/ryantm.keys)
|
|
* No GPG
|
|
* Very little code, so it should be easy for you to audit
|
|
* Encrypted secrets are stored in the Nix store, so a separate distribution mechanism is not necessary
|
|
|
|
## Notices
|
|
|
|
* The `age` module will only work if you use NixOS with [commit e6b8587](https://github.com/NixOS/nixpkgs/commit/e6b8587b25a19528695c5c270e6ff1c209705c31) which is included in the latest `nixos-20.09` or `nixos-unstable` releases.
|
|
* Password-protected ssh keys: since the underlying tool age/rage do not support ssh-agent, password-protected ssh keys do not work well. For example, if you need to rekey 20 secrets you will have to enter your password 20 times.
|
|
|
|
## Installation
|
|
|
|
Choose one of the following methods:
|
|
|
|
### [niv](https://github.com/nmattia/niv) (Current recommendation)
|
|
|
|
First add it to niv:
|
|
|
|
```ShellSession
|
|
$ niv add ryantm/agenix
|
|
```
|
|
|
|
#### Module
|
|
|
|
Then add the following to your configuration.nix in the `imports` list:
|
|
|
|
```nix
|
|
{
|
|
imports = [ "${(import ./nix/sources.nix).agenix}/modules/age" ];
|
|
}
|
|
```
|
|
|
|
### nix-channel
|
|
|
|
As root run:
|
|
|
|
```ShellSession
|
|
$ nix-channel --add https://github.com/ryantm/agenix/archive/master.tar.gz agenix
|
|
$ nix-channel --update
|
|
```
|
|
|
|
Than add the following to your configuration.nix in the `imports` list:
|
|
|
|
```nix
|
|
{
|
|
imports = [ <agenix/modules/age> ];
|
|
}
|
|
```
|
|
|
|
### fetchTarball
|
|
|
|
Add the following to your configuration.nix:
|
|
|
|
```nix
|
|
{
|
|
imports = [ "${builtins.fetchTarball "https://github.com/ryantm/agenix/archive/master.tar.gz"}/modules/age" ];
|
|
}
|
|
```
|
|
|
|
or with pinning:
|
|
|
|
```nix
|
|
{
|
|
imports = let
|
|
# replace this with an actual commit id or tag
|
|
commit = "298b235f664f925b433614dc33380f0662adfc3f";
|
|
in [
|
|
"${builtins.fetchTarball {
|
|
url = "https://github.com/ryantm/agenix/archive/${commit}.tar.gz";
|
|
# replace this with an actual hash
|
|
sha256 = "0000000000000000000000000000000000000000000000000000";
|
|
}}/modules/age"
|
|
];
|
|
}
|
|
```
|
|
|
|
### Flakes
|
|
|
|
#### Module
|
|
|
|
```nix
|
|
{
|
|
inputs.agenix.url = "github:ryantm/agenix";
|
|
# optional, not necessary for the module
|
|
#inputs.agenix.inputs.nixpkgs.follows = "nixpkgs";
|
|
|
|
outputs = { self, nixpkgs, agenix }: {
|
|
# change `yourhostname` to your actual hostname
|
|
nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
|
|
# change to your system:
|
|
system = "x86_64-linux";
|
|
modules = [
|
|
./configuration.nix
|
|
agenix.nixosModules.age
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
#### CLI
|
|
|
|
You don't need to install it,
|
|
|
|
```ShellSession
|
|
nix run github:ryantm/agenix -- --help
|
|
```
|
|
|
|
but, if you want to (change the system based on your system):
|
|
|
|
```nix
|
|
{
|
|
environment.systemPackages = [ agenix.defaultPackage.x86_64-linux ];
|
|
}
|
|
```
|
|
|
|
## Tutorial
|
|
|
|
1. The system you want to deploy secrets to should already exist and
|
|
have `sshd` running on it so that it has generated SSH host keys in
|
|
`/etc/ssh/`.
|
|
|
|
2. Make a directory to store secrets and `secrets.nix` file for listing secrets and their public keys:
|
|
|
|
```ShellSession
|
|
$ mkdir secrets
|
|
$ cd secrets
|
|
$ touch secrets.nix
|
|
```
|
|
3. Add public keys to `secrets.nix` file (hint: use `ssh-keyscan` or GitHub (for example, https://github.com/ryantm.keys)):
|
|
```nix
|
|
let
|
|
user1 = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0idNvgGiucWgup/mP78zyC23uFjYq0evcWdjGQUaBH";
|
|
user2 = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILI6jSq53F/3hEmSs+oq9L4TwOo1PrDMAgcA1uo1CCV/";
|
|
users = [ user1 user2 ];
|
|
|
|
system1 = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPJDyIr/FSz1cJdcoW69R+NrWzwGK/+3gJpqD1t8L2zE";
|
|
system2 = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKzxQgondgEYcLpcPdJLrTdNgZ2gznOHCAxMdaceTUT1";
|
|
systems = [ system1 system2 ];
|
|
in
|
|
{
|
|
"secret1.age".publicKeys = [ user1 system1 ];
|
|
"secret2.age".publicKeys = users ++ systems;
|
|
}
|
|
```
|
|
4. Edit secret files (these instructions assume your SSH private key is in ~/.ssh/):
|
|
```ShellSession
|
|
$ agenix -e secret1.age
|
|
```
|
|
5. Add secret to a NixOS module config:
|
|
```nix
|
|
age.secrets.secret1.file = ../secrets/secret1.age;
|
|
```
|
|
6. NixOS rebuild or use your deployment tool like usual.
|
|
|
|
The secret will be decrypted to the value of `age.secrets.secret1.path` (`/run/secrets/secret1` by default). For per-secret options controlling ownership etc, see [modules/age.nix](modules/age.nix).
|
|
|
|
## Rekeying
|
|
|
|
If you change the public keys in `secrets.nix`, you should rekey your
|
|
secrets:
|
|
|
|
```ShellSession
|
|
$ agenix --rekey
|
|
```
|
|
|
|
To rekey a secret, you have to be able to decrypt it. Because of
|
|
randomness in `age`'s encryption algorithms, the files always change
|
|
when rekeyed, even if the identities do not. (This eventually could be
|
|
improved upon by reading the identities from the age file.)
|
|
|
|
## Threat model/Warnings
|
|
|
|
This project has not be audited by a security professional.
|
|
|
|
People unfamiliar with `age` might be surprised that secrets are not
|
|
authenticated. This means that every attacker that has write access to
|
|
the secret files can modify secrets because public keys are exposed.
|
|
This seems like not a problem on the first glance because changing the
|
|
configuration itself could expose secrets easily. However, reviewing
|
|
configuration changes is easier than reviewing random secrets (for
|
|
example, 4096-bit rsa keys). This would be solved by having a message
|
|
authentication code (MAC) like other implementations like GPG or
|
|
[sops](https://github.com/Mic92/sops-nix) have, however this was left
|
|
out for simplicity in `age`.
|
|
|
|
## Acknowledgements
|
|
|
|
This project is based off of [sops-nix](https://github.com/Mic92/sops-nix) created Mic92. Thank you to Mic92 for inspiration and advice.
|