Improve README and help string

Signed-off-by: Sylvain Rabot <[email protected]>
sylr · Jan 26, 2021 · 1bb6abd · 1bb6abd
1 parent 33d7e32
commit 1bb6abd
Show file tree

Hide file tree

Showing 2 changed files with 98 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -3,9 +3,84 @@ yage
 
 `yage` is a fork of `filippo.io/age/cmd/age` with added YAML support.
 
-This repo contains no cryptographic logic, all of that remains [in the original project](https://github.com/FiloSottile/age).
+This project contains **no cryptographic logic**, all of that remains
+[in the original project](https://github.com/FiloSottile/age).
 
-INSTALL
+`yage` encrypts YAML key values in place using YAML tag `!crypto/age` as marker.
+It only support encoding strings.
+
+```yaml
+---
+simpletag: !crypto/age simple value
+doublequoted: !crypto/age:DoubleQuoted double quoted value
+singlequoted: !crypto/age:SingleQuoted single quoted value
+literal: !crypto/age:Literal literal value
+flowed: !crypto/age:Flow flowed value
+folded: !crypto/age:Folded folded value
+# the NoTag attribute will cause yage to drop the tag when decrypting
+notag: !crypto/age:Literal,NoTag literal untagged value
+```
+
+⚠️ YAML formatting may be modified when encrypting/decrypting in place due to limitations
+of the YAML library used. If you must conserve YAML formatting you'll need to
+encrypt it as a regular file.
+
+Usage
+-----
+
+```
+Usage:
+    yage (-r RECIPIENT | -R PATH)... [--armor] [-o OUTPUT] [INPUT]
+    yage --passphrase [--armor] [-o OUTPUT] [INPUT]
+    yage --decrypt [-i PATH]... [-o OUTPUT] [INPUT]
+
+Options:
+    -o, --output OUTPUT         Write the result to the file at path OUTPUT.
+    -a, --armor                 Encrypt to a PEM encoded format.
+    -p, --passphrase            Encrypt with a passphrase.
+    -r, --recipient RECIPIENT   Encrypt to the specified RECIPIENT. Can be repeated.
+    -R, --recipients-file PATH  Encrypt to recipients listed at PATH. Can be repeated.
+    -d, --decrypt               Decrypt the input to the output.
+    -i, --identity PATH         Use the identity file at PATH. Can be repeated.
+        --version
+    -y, --yaml                  Treat input as YAML and perform in-place encryption / decryption.
+        --yaml-discard-notag    Does not honour NoTag attribute when decrypting (useful for re-keying).
+
+INPUT defaults to standard input, and OUTPUT defaults to standard output.
+
+RECIPIENT can be an age public key generated by age-keygen ("age1...")
+or an SSH public key ("ssh-ed25519 AAAA...", "ssh-rsa AAAA...").
+
+Recipient files contain one or more recipients, one per line. Empty lines
+and lines starting with "#" are ignored as comments. "-" may be used to
+read recipients from standard input.
+
+Identity files contain one or more secret keys ("AGE-SECRET-KEY-1..."),
+one per line, or an SSH key. Empty lines and lines starting with "#" are
+ignored as comments. Multiple key files can be provided, and any unused ones
+will be ignored. "-" may be used to read identities from standard input.
+
+Example:
+    # Generate age key pair
+    $ age-keygen -o key.txt
+    Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+
+    # Tar folder and encrypt it with yage
+    $ tar cvz ~/data | yage -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
+    $ yage --decrypt -i key.txt -o data.tar.gz data.tar.gz.age
+
+    # Encrypt YAML keys in place tagged with !crypto/age
+    $ yage -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p -y config.yaml > config.yaml.age
+
+    # Decrypt YAML file encrypted with yage
+    $ yage --decrypt -i key.txt --yaml config.yaml.age
+
+    # Re-key age encrypted YAML with all tags
+    $ yage --decrypt -i key.txt --yaml --yaml-discard-notag config.yaml.age | \
+        yage -r ... -r ... --yaml
+```
+
+Install
 -------
 
 ### From sources
@@ -21,6 +96,8 @@ You can find pre-built binaries in the [here](https://github.com/sylr/yage/relea
 Upstreams
 ---------
 
-| sylr.dev/yage | [filippo.io/age](https://github.com/FiloSottile/age) | [sylr.dev/yaml/age/v3](https://github.com/sylr/go-yaml-age) | [sylr.dev/yaml/v3](https://github.com/sylr/go-yaml) |
-|:-------------:| ---------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------- |
+| sylr.dev/yage | [filippo.io/age](https://github.com/FiloSottile/age)                 | [sylr.dev/yaml/age/v3](https://github.com/sylr/go-yaml-age)           | [sylr.dev/yaml/v3](https://github.com/sylr/go-yaml)               |
+|:-------------:|:--------------------------------------------------------------------:|:---------------------------------------------------------------------:|:-----------------------------------------------------------------:|
 | v0.0.0        | [31e0d226807f](https://github.com/FiloSottile/age/tree/31e0d226807f) | [a2c1da7b8f3b](https://github.com/sylr/go-yaml-age/tree/a2c1da7b8f3b) | [5fe289210a56](https://github.com/sylr/go-yaml/tree/5fe289210a56) |
+| v0.0.1        | [31e0d226807f](https://github.com/FiloSottile/age/tree/31e0d226807f) | [a2c1da7b8f3b](https://github.com/sylr/go-yaml-age/tree/a2c1da7b8f3b) | [5fe289210a56](https://github.com/sylr/go-yaml/tree/5fe289210a56) |
+| v0.0.2        | [31e0d226807f](https://github.com/FiloSottile/age/tree/31e0d226807f) | [a2c1da7b8f3b](https://github.com/sylr/go-yaml-age/tree/a2c1da7b8f3b) | [5fe289210a56](https://github.com/sylr/go-yaml/tree/5fe289210a56) |
diff --git a/yage.go b/yage.go
@@ -36,9 +36,9 @@ func (f *multiFlag) Set(value string) error {
 }
 
 const usage = `Usage:
-    age (-r RECIPIENT | -R PATH)... [--armor] [-o OUTPUT] [INPUT]
-    age --passphrase [--armor] [-o OUTPUT] [INPUT]
-    age --decrypt [-i PATH]... [-o OUTPUT] [INPUT]
+    yage (-r RECIPIENT | -R PATH)... [--armor] [-o OUTPUT] [INPUT]
+    yage --passphrase [--armor] [-o OUTPUT] [INPUT]
+    yage --decrypt [-i PATH]... [-o OUTPUT] [INPUT]
 
 Options:
     -o, --output OUTPUT         Write the result to the file at path OUTPUT.
@@ -67,14 +67,23 @@ ignored as comments. Multiple key files can be provided, and any unused ones
 will be ignored. "-" may be used to read identities from standard input.
 
 Example:
+    # Generate age key pair
     $ age-keygen -o key.txt
     Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
-    $ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
-    $ age --decrypt -i key.txt -o data.tar.gz data.tar.gz.age
 
-    # only yaml keys tagged with !crypto/age will be encrypted
-    $ age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p -y config.yaml > config.yaml.age
-    $ age --decrypt -i key.txt -y config.yaml.age
+    # Tar folder and encrypt it with yage
+    $ tar cvz ~/data | yage -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
+    $ yage --decrypt -i key.txt -o data.tar.gz data.tar.gz.age
+
+    # Encrypt YAML keys in place tagged with !crypto/age
+    $ yage -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p -y config.yaml > config.yaml.age
+
+    # Decrypt YAML file encrypted with yage
+    $ yage --decrypt -i key.txt --yaml config.yaml.age
+
+    # Re-key age encrypted YAML with all tags
+    $ yage --decrypt -i key.txt --yaml --yaml-discard-notag config.yaml.age | \
+        yage -r ... -r ... --yaml
 `
 
 // Version can be set at link time to override debug.BuildInfo.Main.Version,
@@ -498,6 +507,4 @@ func (l *lazyOpener) Close() error {
 
 func logFatalf(format string, v ...interface{}) {
 	_log.Printf(format, v...)
-	_log.Fatalf("[ Did age not do what you expected? Could an error be more useful?" +
-		" Tell us: https://filippo.io/age/report ]")
 }