From 91a2b66134eaef710f138c3572c80a38e58ec925 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Benjamin=20Yule=20B=C3=A4dorf?= <git@benjaminbaedorf.eu>
Date: Fri, 5 Apr 2024 14:45:59 +0200
Subject: [PATCH] docs: explain admin access and secrets

---
 docs/administrative-access.md | 37 +++++++++++++++++++++++++++++++++++
 docs/secrets.md               |  4 ++++
 docs/ssh.md                   |  3 ---
 3 files changed, 41 insertions(+), 3 deletions(-)
 create mode 100644 docs/administrative-access.md
 delete mode 100644 docs/ssh.md

diff --git a/docs/administrative-access.md b/docs/administrative-access.md
new file mode 100644
index 0000000..6b7faa4
--- /dev/null
+++ b/docs/administrative-access.md
@@ -0,0 +1,37 @@
+# Adminstrative access
+
+People with admin access to the infrastructure are added to [`logins/admins.nix`](../logins/admins.nix). This is a attrset with the following structure:
+
+```
+{
+    <username> = {
+        sshPubKeys = {
+            <name> = <pubkey-string>;
+        };
+
+        wireguardDevices = [
+            {
+                publicKey = <pubkey-string>;
+                allowedIPs = [ "10.7.6.<ip-address>/32" "fd00:fae:fae:fae:fae:<ip-address>::/96" ];
+            }
+        }];
+
+        secretEncryptionKeys = {
+            <name> = <encryption-key-string>;
+        };
+    };
+}
+```
+
+# SSH Access
+
+SSH is not reachable from the open internet. Instead, SSH Port 22 is protected by a wireguard VPN network. Thus, to get root access on the servers, at least two pieces of information have to be added to the admins config:
+
+1. **SSH Public key**: self-explanatory. Add your public key to your user attrset under `sshPubKeys`.
+2. **Wireguard device**: each wireguard device has two parts: the public key and the IP addresses it should have in the wireguard network. The pub.solar wireguard network is spaced under `10.7.6.0/24` and `fd00:fae:fae:fae:fae::/80`. To add your device, it's best to choose a free number between 200 and 255 and use that in both the ipv4 and ipv6 ranges: `10.7.6.<ip-address>/32` `fd00:fae:fae:fae:fae:<ip-address>::/96`. For more information on how to generate keypairs, see [the NixOS Wireguard docs](https://nixos.wiki/wiki/WireGuard#Generate_keypair).
+
+# Secret encryption
+
+Deployment secrets are added to the repository in encrypted files. To be able to work with these encrypted files, your public key(s) will have to be added to your user attrset under `secretEncryptionKeys`.
+
+See also the docs on [working with secrets](./secrets.md).
diff --git a/docs/secrets.md b/docs/secrets.md
index de9b536..585cdb0 100644
--- a/docs/secrets.md
+++ b/docs/secrets.md
@@ -1 +1,5 @@
 # Working with secrets
+
+Secrets are handled with [agenix](https://github.com/ryantm/agenix). To be able to view secrets, your public key will have to be added to the admins config. See [Administrative Access](./administrative-access.md) on how to do this.
+
+For a comprehensive tutorial, see [the agenix repository](https://github.com/ryantm/agenix?tab=readme-ov-file#tutorial).
diff --git a/docs/ssh.md b/docs/ssh.md
deleted file mode 100644
index 3ab2011..0000000
--- a/docs/ssh.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# SSH Access
-
-SSH Access is granted by adding a public key to [`public-keys/admins.nix`](../public-keys/admins.nix). This change will then have to be deployed to all hosts by an existing key. The keys will also grant access to the initrd SSH Server to enable remote unlock.