From 7133e545ffdbaec51bd0db1791042bb71edd5594 Mon Sep 17 00:00:00 2001
From: Andrew Lubawy <andrew@andrewlubawy.com>
Date: Mon, 29 Jul 2024 10:50:01 -0700
Subject: [PATCH] Update docs to include example of armored output

---
 README.md       | 20 ++++++++++++--------
 doc/tutorial.md |  4 ++++
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 67718f60..58aaab73 100644
--- a/README.md
+++ b/README.md
@@ -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:
 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.  
-This project contains two parts: 
+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:
 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
     * 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
    $ 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.
 3. Add public keys to your `secrets.nix` file:
    ```nix
@@ -266,10 +266,14 @@ e.g. inside your `flake.nix` file:
    {
      "secret1.age".publicKeys = [ user1 system1 ];
      "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.
-   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`.
    * from a running target machine with `ssh-keyscan`:
      ```ShellSession
@@ -290,7 +294,7 @@ e.g. inside your `flake.nix` file:
      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.
 
 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.
 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.
 8. Edit secret files:
    ```ShellSession
    $ agenix -e secret1.age
    ```
-   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 
+   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
    it was encrypted with. You can pass the private key you want to use explicitly with `-i`, e.g.
    ```ShellSession
    $ agenix -e secret1.age -i ~/.ssh/id_ed25519
diff --git a/doc/tutorial.md b/doc/tutorial.md
index 83441214..751afa9c 100644
--- a/doc/tutorial.md
+++ b/doc/tutorial.md
@@ -25,6 +25,10 @@
    {
      "secret1.age".publicKeys = [ user1 system1 ];
      "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/):