mynix/agenix
1
0
Fork 0
mirror of https://github.com/ryantm/agenix.git synced 2024-11-22 17:50:48 +03:00
Code Issues Projects Releases Packages Wiki Activity

Update docs to include example of armored output

Browse source
This commit is contained in:
Andrew Lubawy 2024-07-29 10:50:01 -07:00
parent af954310f1
commit 7133e545ff
No known key found for this signature in database
GPG key ID: 8E98BAE1F49C2709
2 changed files with 16 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
README.md
View file

@ -2,8 +2,8 @@
`agenix` is a small and convenient Nix library for securely managing and deploying secrets using common public-private SSH key pairs: `agenix` is a small and convenient Nix library for securely managing and deploying secrets using common public-private SSH key pairs:
You can encrypt a secret (password, access-token, etc.) on a source machine using a number of public SSH keys, You can encrypt a secret (password, access-token, etc.) on a source machine using a number of public SSH keys,
and deploy that encrypted secret to any another target machine that has the corresponding private SSH key of one of those public keys. and deploy that encrypted secret to any another target machine that has the corresponding private SSH key of one of those public keys.
This project contains two parts: This project contains two parts:
1. An `agenix` commandline app (CLI) to encrypt secrets into secured `.age` files that can be copied into the Nix store. 1. An `agenix` commandline app (CLI) to encrypt secrets into secured `.age` files that can be copied into the Nix store.
2. An `agenix` NixOS module to conveniently 2. An `agenix` NixOS module to conveniently
* add those encrypted secrets (`.age` files) into the Nix store so that they can be deployed like any other Nix package using `nixos-rebuild` or similar tools. * add those encrypted secrets (`.age` files) into the Nix store so that they can be deployed like any other Nix package using `nixos-rebuild` or similar tools.
@ -250,7 +250,7 @@ e.g. inside your `flake.nix` file:
$ cd secrets $ cd secrets
$ touch secrets.nix $ touch secrets.nix
``` ```
This `secrets.nix` file is **not** imported into your NixOS configuration. This `secrets.nix` file is **not** imported into your NixOS configuration.
It's only used for the `agenix` CLI tool (example below) to know which public keys to use for encryption. It's only used for the `agenix` CLI tool (example below) to know which public keys to use for encryption.
3. Add public keys to your `secrets.nix` file: 3. Add public keys to your `secrets.nix` file:
```nix ```nix
@ -266,10 +266,14 @@ e.g. inside your `flake.nix` file:
{ {
"secret1.age".publicKeys = [ user1 system1 ]; "secret1.age".publicKeys = [ user1 system1 ];
"secret2.age".publicKeys = users ++ systems; "secret2.age".publicKeys = users ++ systems;
"armored-secret.age" = {
publicKeys = [ user1 ];
armor = true;
};
} }
``` ```
These are the users and systems that will be able to decrypt the `.age` files later with their corresponding private keys. These are the users and systems that will be able to decrypt the `.age` files later with their corresponding private keys.
You can obtain the public keys from You can obtain the public keys from
* your local computer usually in `~/.ssh`, e.g. `~/.ssh/id_ed25519.pub`. * your local computer usually in `~/.ssh`, e.g. `~/.ssh/id_ed25519.pub`.
* from a running target machine with `ssh-keyscan`: * from a running target machine with `ssh-keyscan`:
```ShellSession ```ShellSession
@ -290,7 +294,7 @@ e.g. inside your `flake.nix` file:
age.secrets.secret1.file = ../secrets/secret1.age; age.secrets.secret1.file = ../secrets/secret1.age;
} }
``` ```
When the `age.secrets` attribute set contains a secret, the `agenix` NixOS module will later automatically decrypt and mount that secret under the default path `/run/agenix/secret1`. When the `age.secrets` attribute set contains a secret, the `agenix` NixOS module will later automatically decrypt and mount that secret under the default path `/run/agenix/secret1`.
Here the `secret1.age` file becomes part of your NixOS deployment, i.e. moves into the Nix store. Here the `secret1.age` file becomes part of your NixOS deployment, i.e. moves into the Nix store.
6. Reference the secrets' mount path in your config: 6. Reference the secrets' mount path in your config:
@ -306,14 +310,14 @@ e.g. inside your `flake.nix` file:
So `config.age.secrets.secret1.path` will contain the path `/run/agenix/secret1` by default. So `config.age.secrets.secret1.path` will contain the path `/run/agenix/secret1` by default.
7. Use `nixos-rebuild` or [another deployment tool](https://nixos.wiki/wiki/Applications#Deployment") of choice as usual. 7. Use `nixos-rebuild` or [another deployment tool](https://nixos.wiki/wiki/Applications#Deployment") of choice as usual.
The `secret1.age` file will be copied over to the target machine like any other Nix package. The `secret1.age` file will be copied over to the target machine like any other Nix package.
Then it will be decrypted and mounted as described before. Then it will be decrypted and mounted as described before.
8. Edit secret files: 8. Edit secret files:
```ShellSession ```ShellSession
$ agenix -e secret1.age $ agenix -e secret1.age
``` ```
It assumes your SSH private key is in `~/.ssh/`. It assumes your SSH private key is in `~/.ssh/`.
In order to decrypt and open a `.age` file for editing you need the private key of one of the public keys In order to decrypt and open a `.age` file for editing you need the private key of one of the public keys
it was encrypted with. You can pass the private key you want to use explicitly with `-i`, e.g. it was encrypted with. You can pass the private key you want to use explicitly with `-i`, e.g.
```ShellSession ```ShellSession
$ agenix -e secret1.age -i ~/.ssh/id_ed25519 $ agenix -e secret1.age -i ~/.ssh/id_ed25519

4
doc/tutorial.md
View file

@ -25,6 +25,10 @@
{ {
"secret1.age".publicKeys = [ user1 system1 ]; "secret1.age".publicKeys = [ user1 system1 ];
"secret2.age".publicKeys = users ++ systems; "secret2.age".publicKeys = users ++ systems;
"armored-secret.age" = {
publicKeys = [ user1 ];
armor = true;
};
} }
``` ```
4. Edit secret files (these instructions assume your SSH private key is in ~/.ssh/): 4. Edit secret files (these instructions assume your SSH private key is in ~/.ssh/):