add README and examples

README.md

@@ -2,35 +2,40 @@
 
 [age](https://github.com/FiloSottile/age)-encrypted secrets for NixOS.
 
-# Features
+It consists of a NixOS module `age`, and a CLI tool called `agenix`
+used for editing and rekeying the secret files.
+
+## 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
 
-# Installation
+## Installation
 
 Choose one of the following methods:
 
-#### [niv](https://github.com/nmattia/niv) (Current recommendation)
+### [niv](https://github.com/nmattia/niv) (Current recommendation)
 
 First add it to niv:
 
 ```console
 $ niv add ryantm/agenix
 ```
 
-  Than add the following to your configuration.nix in the `imports` list:
+#### Module
+
+Then add the following to your configuration.nix in the `imports` list:
 
 ```nix
 {
   imports = [ "${(import ./nix/sources.nix).agenix}/modules/age" ];
 }
 ```
 
-#### nix-channel
+### nix-channel
 
   As root run:
 
@@ -47,11 +52,11 @@ $ nix-channel --update
 }
 ```
 
-#### fetchTarball
+### fetchTarball
 
   Add the following to your configuration.nix:
 
-``` nix
+```nix
 {
   imports = [ "${builtins.fetchTarball "https://github.com/ryantm/agenix/archive/master.tar.gz"}/modules/age" ];
 }
@@ -74,9 +79,11 @@ $ nix-channel --update
 }
 ```
 
-#### Flakes
+### Flakes
+
+#### Module
 
-``` nix
+```nix
 {
   inputs.agenix.url = "github:ryantm/agenix";
   # optional, not necessary for the module
@@ -96,6 +103,82 @@ $ nix-channel --update
 }
 ```
 
-# Tutorial
+#### CLI
+
+You don't need to install it:
+
+```console
+nix run github:ryantm/agenix -- --help
+```
+
+
+## Tutorial
+
+1. Make a directory to store secrets and a YAML file for configuring encryption.
+
+   ```console
+   $ mkdir secrets
+   $ cd secerts
+   $ touch secrets.yaml
+   ```
+2. Add public keys to `secrets.yaml` file (hint use `ssh-keyscan` or GitHub (for example, https://github.com/ryantm.keys):
+   ```yaml
+   public_keys:
+     # users
+     - &user1 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0idNvgGiucWgup/mP78zyC23uFjYq0evcWdjGQUaBH
+     # systems
+     - &system1 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPJDyIr/FSz1cJdcoW69R+NrWzwGK/+3gJpqD1t8L2zE
+
+   secrets:
+     - name: secret1.age
+       public_keys:
+         - *user1
+         - *system1
+     - name: secret2.age
+       public_keys:
+         - *user1
+   ```
+3. Edit secret files (assuming your SSH private key is in ~/.ssh/):
+   ```console
+   $ agenix -e secret1.age
+   ```
+4. Add secret to NixOS module config:
+   ```nix
+   age.secrets.secret1 = ../secrets/secret1.age;
+   ```
+5. NixOS rebuild or use your deployment too like usual.
+
+## Rekeying
+
+If you change the public keys in `secrets.yaml`, you should rekey your
+secrets:
+
+```console
+$ 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 library 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 repository 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 it is easier
+to review configuration changes rather than 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
 
-# Threat model
+This project is based off of
+[sops-nix](https://github.com/Mic92/sops-nix) created Mic92. Thank you
+to Mic92 for inspiration and help with making this.

example/secret2.age

@@ -0,0 +1,5 @@
+age-encryption.org/v1
+-> ssh-ed25519 V3XmEA OB4+1FbPhQ3r6iGksM7peWX5it8NClpXIq/o5nnP7GA
+FmHVUj+A5i5+bDFgySQskmlvynnosJiWUTJmBRiNA9I
+--- tP+3mFVtd7ogVu1Lkboh55zoi5a77Ht08Uc/QuIviv4
+��X�{��O����tMXx�vӪ(�I�myP���+3�S3i

example/secrets.yaml

@@ -0,0 +1,14 @@
+public_keys:
+  # users
+  - &user1 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0idNvgGiucWgup/mP78zyC23uFjYq0evcWdjGQUaBH
+  # systems
+  - &system1 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPJDyIr/FSz1cJdcoW69R+NrWzwGK/+3gJpqD1t8L2zE
+
+secrets:
+  - name: secret1.age
+    public_keys:
+      - *user1
+      - *system1
+  - name: secret2.age
+    public_keys:
+      - *user1

example_keys/system1

@@ -0,0 +1,7 @@
+-----BEGIN OPENSSH PRIVATE KEY-----
+b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
+QyNTUxOQAAACDyQ8iK/xUs9XCXXKFuvUfja1s8Biv/t4Caag9bfC9sxAAAAJA3yvCWN8rw
+lgAAAAtzc2gtZWQyNTUxOQAAACDyQ8iK/xUs9XCXXKFuvUfja1s8Biv/t4Caag9bfC9sxA
+AAAEA+J2V6AG1NriAIvnNKRauIEh1JE9HSdhvKJ68a5Fm0w/JDyIr/FSz1cJdcoW69R+Nr
+WzwGK/+3gJpqD1t8L2zEAAAADHJ5YW50bUBob21lMQE=
+-----END OPENSSH PRIVATE KEY-----

example_keys/system1.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPJDyIr/FSz1cJdcoW69R+NrWzwGK/+3gJpqD1t8L2zE

example_keys/user1

@@ -0,0 +1,7 @@
+-----BEGIN OPENSSH PRIVATE KEY-----
+b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
+QyNTUxOQAAACC9InTb4BornFoLqf5j+/M8gtt7hY2KtHr3FnYxkFGgRwAAAJC2JJ8htiSf
+IQAAAAtzc2gtZWQyNTUxOQAAACC9InTb4BornFoLqf5j+/M8gtt7hY2KtHr3FnYxkFGgRw
+AAAEDxt5gC/s53IxiKAjfZJVCCcFIsdeERdIgbYhLO719+Kb0idNvgGiucWgup/mP78zyC
+23uFjYq0evcWdjGQUaBHAAAADHJ5YW50bUBob21lMQE=
+-----END OPENSSH PRIVATE KEY-----

example_keys/user1.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL0idNvgGiucWgup/mP78zyC23uFjYq0evcWdjGQUaBH

pkgs/agenix.nix

@@ -6,16 +6,19 @@ PACKAGE="agenix"
 function show_help () {
   echo "$PACKAGE - edit and rekey age secret files"
   echo " "
-  echo "$PACKAGE -e FILE"
-  echo "$PACKAGE -r"
+  echo "$PACKAGE -e FILE [-i PRIVATE_KEY]"
+  echo "$PACKAGE -r [-i PRIVATE_KEY]"
   echo ' '
   echo 'options:'
   echo '-h, --help                show help'
   echo '-e, --edit FILE           edits FILE using $EDITOR'
   echo '-r, --rekey               re-encrypts all secrets with specified recipients'
+  echo '-i, --identity            identity to use when decrypting'
   echo ' '
   echo 'FILE an age-encrypted file'
   echo ' '
+  echo 'PRIVATE_KEY a path to a private SSH key used to decrypt file'
+  echo ' '
   echo 'EDITOR environment variable of editor to use when editing FILE'
   echo ' '
   echo 'RULES environment variable with path to YAML file specifying recipient public keys.'
@@ -25,6 +28,7 @@ function show_help () {
 test $# -eq 0 && (show_help && exit 1)
 
 REKEY=0
+DECRYPT=(--decrypt)
 
 while test $# -gt 0; do
   case "$1" in
@@ -37,7 +41,17 @@ while test $# -gt 0; do
       if test $# -gt 0; then
         export FILE=$1
       else
-        echo "no file specified"
+        echo "no FILE specified"
+        exit 1
+      fi
+      shift
+      ;;
+    -i|--identity)
+      shift
+      if test $# -gt 0; then
+        DECRYPT+=(--identity "$1")
+      else
+        echo "no PRIVATE_KEY specified"
         exit 1
       fi
       shift
@@ -81,7 +95,6 @@ function edit {
 
     if [ -f "$FILE" ]
     then
-        DECRYPT=(--decrypt)
         while IFS= read -r key
         do
             DECRYPT+=(--identity "$key")