added agenix article

README.md

@@ -17,3 +17,4 @@ i would like to create a module producing function that means i dont have to man
 ## rest of the wiki
 
 * [programs](./wiki/programs/index.md)
+* [agenix](./secrets/index.md)

flake.nix

@@ -24,7 +24,7 @@
 
         # enable secrets in the store
         agenix.nixosModules.age
-        (import ./secrets)
+        (import ./secrets { inherit agenix; })
 	
         # enable flakes or we'll be sad
         (import ./modules/flakes)
@@ -65,7 +65,6 @@
           nixpkgs.overlays = [
             swatch.overlay
             vim.overlay
-            agenix.overlay
             (import ./overlays/picom.nix)
           ];
           nix.registry.nixpkgs.flake = nixpkgs;

secrets/default.nix

@@ -1,9 +1,12 @@
-{
+{ agenix, ... }: {
+  nixpkgs = {
+    overlays = [ agenix.overlay ];
+  };
   age = {
     secrets = {
       secret1.file = ./secret1.age;
     };
-    # sshKeyPaths = [ ../keys ];
+    # sshKeyPaths = [ "../keys/id_ed25519" ];
     sshKeyPaths = [ "/home/thorn/.ssh/id_ed25519" ];
   };
 }

secrets/index.md

@@ -0,0 +1,41 @@
+# Agenix Secrets
+
+[return to index](../index.md)
+
+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`
+
+## further TODO
+
+* add example of using the deccrypted secret in a safe way.