this folder primarily deals with secrets within our nixos system. to do so we make use of the [agenix module](https://github.com/ryantm/agenix), which will be described below.
## enabling agenix within your system
the agenix flake provides a module, and a command line tool, we will need both for this.
in our `nixosSystem` definition (currently in [flake.nix](../flake.nix)), we add the module `agenix.nixosModules.age` to the `modules` list, as well as import the `secrets` directory, which contains information about how to decrypt our files, and the encrypted files themselves.
[default.nix](./default.nix) in our secrets directory also adds the `agenix` overlay to nixpkgs, allowing access to the `agenix` cli tool (TODO: thread `pkgs` into this file so we can add it here instead of the user profile).
## encrypting a file
[secrets.nix](./secrets.nix) contains an attribute set of each file that is encrypted, and the public keys of the keys that can decrypt them.
in addition to `publicKeys`, it is also possible to set the `mode`, `owner`, `group` - relating to permissions, as well as the `path`, which controls where the decrypted secret is placed on the filesystem (if none is specified, it defaults to /run/secrets, however keep in mind on a lot of systems this directory wont persist through reboots).
the `agenix` cli tool requires this file to be in the working directory, so once we have it we can run:
```
EDITOR=vim agenix -e secrets1.age
```
where `secrets1.age` is the name of a file defined in `secrets.nix`.
once these have been commited to the repo, nix will be able to decrypt them at build time.
## decrypting a file
in [default.nix](./default.nix) we define the `age` module settings. the important bits here are to give the location of each secrets file (we must have one for each line in `secrets.nix`, as well as the path (or paths) to the private keys we can use to decrypt them. These keys will have to be present in the system in order for a rebuild to succeed, so i have added a folder `keys` to the gitignore so we have a place to put keys needed to rebuild, without uploading them to the repo.
on rebuild, agenix will decrypt each secret, and place its contents at either the specified path, or in /run/secrets. meanwhile in the git repo, we only store the encrypted `.age` file, and in the nix store (which is globally readable by any user on the system) we store the encrypted `.age` file, whereas (unless otherwise specified) the decrypted files are readable by `root` only.
please note, also, that if using a password protected private key, you will need to type in the password for each file encrypted using it, at every rebuild, so it can be useful to generate a passwordless key for use with `agenix`
