mirrors/age
1
0
Fork 0
mirror of https://github.com/FiloSottile/age.git synced 2026-01-04 11:23:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: add age(1) and age-keygen(1) man pages

Browse Source 
doc: SEC 1 encoding is for ECDSA, which we don't support
doc: fix typo in age-keygen(1) (#273) <Andreas Wachowski>
doc: document backwards compatibility policy
doc: clarify backwards compatibility section
doc: fix typo in age(1) (#333) <y-yagi>
doc: fix typo in age(1) (#336) <puenka>
This commit is contained in:
Filippo Valsorda
2021-05-25 13:20:50 +02:00
parent 11659e8c97
commit 40ef1b6a62
10 changed files with 379 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
.github/workflows/ronn.yml vendored Normal file
View File

@@ -0,0 +1,33 @@
on:
push:
branches:
- '**'
paths:
- '**.ronn'
name: Generate man pages
jobs:
ronn:
runs-on: ubuntu-latest
name: Ronn
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Run ronn
uses: ./.github/workflows/ronn
id: ronn
- name: Undo email mangling
# rdiscount randomizes the output for no good reason, which causes
# changes to always get committed. Sigh.
# https://github.com/davidfstr/rdiscount/blob/6b1471ec3/ext/generate.c#L781-L795
run: |-
for f in doc/*.html; do
awk '/Filippo Valsorda/ { $0 = "<p>Filippo Valsorda <a href=\"mailto:age@filippo.io\" data-bare-link=\"true\">age@filippo.io</a></p>" } { print }' "$f" > "$f.tmp"
mv "$f.tmp" "$f"
done
- name: Commit and push if changed
run: |-
git config user.name "GitHub Actions"
git config user.email "actions@users.noreply.github.com"
git add -A
git commit -m "doc: regenerate groff and html man pages" || exit 0
git push

8
.github/workflows/ronn/Dockerfile vendored Normal file
View File

@@ -0,0 +1,8 @@
FROM ruby:3.0.1-buster
RUN apt-get update && apt-get install -y groff
RUN bundle config --global frozen 1
COPY Gemfile Gemfile.lock ./
RUN bundle install
ENTRYPOINT ["bash", "-O", "globstar", "-c", \
"/usr/local/bundle/bin/ronn **/*.ronn"]

5
.github/workflows/ronn/Gemfile vendored Normal file
View File

@@ -0,0 +1,5 @@
# frozen_string_literal: true
source "https://rubygems.org"
gem "ronn", "~> 0.7.3"

20
.github/workflows/ronn/Gemfile.lock vendored Normal file
View File

@@ -0,0 +1,20 @@
GEM
remote: https://rubygems.org/
specs:
hpricot (0.8.6)
mustache (1.1.1)
rdiscount (2.2.0.2)
ronn (0.7.3)
hpricot (>= 0.8.2)
mustache (>= 0.7.0)
rdiscount (>= 1.5.8)
PLATFORMS
aarch64-linux
x86_64-linux
DEPENDENCIES
ronn (~> 0.7.3)
BUNDLED WITH
2.2.15

4
.github/workflows/ronn/action.yml vendored Normal file
View File

@@ -0,0 +1,4 @@
name: Ronn
runs:
using: docker
image: Dockerfile

2
HomebrewFormula/age.rb
View File

@@ -16,5 +16,7 @@ class Age < Formula
mkdir bin
system "go", "build", "-trimpath", "-o", bin, "-ldflags", "-X main.Version=v#{version}", "filippo.io/age/cmd/..."
prefix.install_metafiles
man1.install "doc/age.1"
man1.install "doc/age-keygen.1"
end
end

10
age.go
View File

@@ -35,6 +35,16 @@
// encryption operations. If you need to tie into existing key management
// infrastructure, you might want to consider implementing your own Recipient
// and Identity.
//
// Backwards compatibility
//
// Files encrypted with a stable version (not alpha, beta, or release candidate)
// of age, or with any v1.0.0 beta or release candidate, will decrypt with any
// later versions of the v1 API. This might change in v2, in which case v1 will
// be maintained with security fixes for compatibility with older files.
//
// If decrypting an older file poses a security risk, doing so might require an
// explicit opt-in in the API.
package age
import (

2
cmd/age-keygen/keygen.go
View File

@@ -27,7 +27,7 @@ Options:
-o, --output OUTPUT Write the result to the file at path OUTPUT.
-y Convert an identity file to a recipients file.
age-keygen generates a new standard X25519 key pair, and outputs it to
age-keygen generates a new native X25519 key pair, and outputs it to
standard output or to the OUTPUT file.
If an OUTPUT file is specified, the public key is printed to standard error.

57
doc/age-keygen.1.ronn Normal file
View File

@@ -0,0 +1,57 @@
age-keygen(1) -- generate age(1) key pairs
====================================================
## SYNOPSIS
`age-keygen` [`-o` <OUTPUT>]<br>
`age-keygen` `-y` [`-o` <OUTPUT>] [<INPUT>]<br>
## DESCRIPTION
`age-keygen` generates a new native age(1) key pair, and outputs the identity to
standard output or to the <OUTPUT> file. The output includes the public key and
the current time as comments.
If the output is not going to a terminal, `age-keygen` prints the public key to
standard error.
## OPTIONS
* `-o`, `--output`=<OUTPUT>:
Write the identity to <OUTPUT> instead of standard output.
If <OUTPUT> already exists, it is not overwritten.
* `-y`:
Read an identity file from <INPUT> or from standard input and output the
corresponding recipient(s), one per line, with no comments.
* `--version`:
Print the version and exit.
## EXAMPLES
Generate a new identity:
$ age-keygen
# created: 2021-01-02T15:30:45+01:00
# public key: age1lvyvwawkr0mcnnnncaghunadrqkmuf9e6507x9y920xxpp866cnql7dp2z
AGE-SECRET-KEY-1N9JEPW6DWJ0ZQUDX63F5A03GX8QUW7PXDE39N8UYF82VZ9PC8UFS3M7XA9
Write a new identity to `key.txt`:
$ age-keygen -o key.txt
Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
Convert an identity to a recipient:
$ age-keygen -y key.txt
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
## SEE ALSO
age(1)
## AUTHORS
Filippo Valsorda <age@filippo.io>

239
doc/age.1.ronn Normal file
View File

@@ -0,0 +1,239 @@
age(1) -- simple, modern, and secure file encryption
====================================================
## SYNOPSIS
`age` [`--encrypt`] (`-r` <RECIPIENT> | `-R` <PATH>)... [`--armor`] [`-o` <OUTPUT>] [<INPUT>]<br>
`age` [`--encrypt`] `--passphrase` [`--armor`] [`-o` <OUTPUT>] [<INPUT>]<br>
`age` `--decrypt` [`-i` <PATH>]... [`-o` <OUTPUT>] [<INPUT>]<br>
## DESCRIPTION
`age` encrypts or decrypts <INPUT> to <OUTPUT>. The <INPUT> argument is
optional and defaults to standard input. Only a single <INPUT> file may be
specified. If `-o` is not specified, <OUTPUT> defaults to standard output.
If `--passphrase` is specified, the file is encrypted with a passphrase
requested interactively. Otherwise, it's encrypted to one or more
[RECIPIENTS][RECIPIENTS AND IDENTITIES] specified with `-r`/`--recipient` or
`-R`/`--recipients-file`. Every recipient can decrypt the file.
In `--decrypt` mode, passphrase-encrypted files are detected automatically and
the passphrase is requested interactively. Otherwise, one or more
[IDENTITIES][RECIPIENTS AND IDENTITIES] specified with `-i`/`--identity` are
used to decrypt the file.
`age` encrypted files are binary and not malleable, with around 200 bytes of
overhead per recipient, plus 16 bytes every 64KiB of plaintext.
## OPTIONS
* `-o`, `--output`=<OUTPUT>:
Write encrypted or decrypted file to <OUTPUT> instead of standard output.
If <OUTPUT> already exists it will be overwritten.
If encrypting without `--armor`, `age` will refuse to output binary to a
TTY. This can be forced by specifying `-` as <OUTPUT>.
* `--version`:
Print the version and exit.
### Encryption options
* `-e`, `--encrypt`:
Encrypt <INPUT> to <OUTPUT>. This is the default.
* `-r`, `--recipient`=<RECIPIENT>:
Encrypt to the explicitly specified <RECIPIENT>. See the
[RECIPIENTS AND IDENTITIES][] section for possible recipient formats.
This option can be repeated and combined with `-R`/`--recipients-file`,
and the file can be decrypted by all provided recipients independently.
* `-R`, `--recipients-file`=<PATH>:
Encrypt to the [RECIPIENTS][RECIPIENTS AND IDENTITIES] listed in the
file at <PATH>, one per line. Empty lines and lines starting with `#`
are ignored as comments.
If <PATH> is `-`, the recipients are read from standard input. In
this case, the <INPUT> argument must be specified.
This option can be repeated and combined with `-r`/`--recipient`,
and the file can be decrypted by all provided recipients independently.
* `-p`, `--passphrase`:
Encrypt with a passphrase, requested interactively from the terminal.
`age` will offer to auto-generate a secure passphrase.
This option can't be used with `-r`/`--recipient` or
`-R`/`--recipients-file`.
* `-a`, `--armor`:
Encrypt to an ASCII-only "armored" encoding.
`age` armor is a strict version of PEM with type `AGE ENCRYPTED FILE`,
canonical "strict" Base64, no headers, and no support for leading and
trailing extra data.
Decryption transparently detects and decodes ASCII armoring.
### Decryption options
* `-d`, `--decrypt`:
Decrypt <INPUT> to <OUTPUT>.
If <INPUT> is passphrase encrypted, it will be automatically detected
and the passphrase will be requested interactively. Otherwise, the
[IDENTITIES][RECIPIENTS AND IDENTITIES] specified with `-i`/`--identity`
are used.
ASCII armoring is transparently detected and decoded.
* `-i`, `--identity`=<PATH>:
Decrypt using the [IDENTITIES][RECIPIENTS AND IDENTITIES] at <PATH>.
<PATH> may be one of the following:
a\. A file listing [IDENTITIES][RECIPIENTS AND IDENTITIES] one per line.
Empty lines and lines starting with "`#`" are ignored as comments.
b\. An SSH private key file, in PKCS#1, PKCS#8, or OpenSSH format.
If the private key is password-protected, the password is requested
interactively only if the SSH identity matches the file. See the
[SSH keys][] section for more information, including supported key types.
c\. "`-`", causing one of the options above to be read from standard input.
In this case, the <INPUT> argument must be specified.
This option can be repeated. Identities are tried in the order in which
are provided, and the first one matching one of the file's recipients is
used. Unused identities are ignored.
If `-e`/`--encrypt` is explicitly specified (to avoid confusion),
`-i`/`--identity` may also be used to encrypt to the `RECIPIENTS`
corresponding to the `IDENTITIES` listed at <PATH>. This allows using an
identity file as a symmetric key, if desired.
## RECIPIENTS AND IDENTITIES
`RECIPIENTS` are public values, like a public key, that a file can be encrypted
to. `IDENTITIES` are private values, like a private key, that allow decrypting
a file encrypted to the corresponding `RECIPIENT`.
### Native X25519 keys
Native `age` key pairs are generated with age-keygen(1), and provide small
encodings and strong encryption based on X25519. They are the recommended
recipient type for most applications.
A `RECIPIENT` encoding begins with `age1` and looks like the following:
age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh
An `IDENTITY` encoding begins with `AGE-SECRET-KEY-1` and looks like the
following:
AGE-SECRET-KEY-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ
An encrypted file can't be linked to the native recipient it's encrypted to
without access to the corresponding identity.
### SSH keys
As a convenience feature, `age` also supports encrypting to RSA or Ed25519
ssh(1) keys. RSA keys must be at least 2048 bits. This feature employs more
complex cryptography, and should only be used when a native key is not available
for the recipient. Note that SSH keys might not be protected long-term by the
recipient, since they are revokable when used only for authentication.
A `RECIPIENT` encoding is an SSH public key in `authorized_keys` format
(see the `AUTHORIZED_KEYS FILE FORMAT` section of sshd(8)), starting with
`ssh-rsa` or `ssh-ed25519`, like the following:
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDULTit0KUehbi[...]GU4BtElAbzh8=
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH9pO5pz22JZEas[...]l1uZc31FGYMXa
The comment at the end of the line, if present, is ignored.
In recipient files passed to `-R`/`--recipients-file`, unsupported but valid
SSH public keys are ignored with a warning, to facilitate using
`authorized_keys` or GitHub `.keys` files. (See [EXAMPLES][].)
An `IDENTITY` is an SSH private key _file_ passed individually to
`-i`/`--identity`. Note that keys held on hardware tokens such as YubiKeys
or accessed via ssh-agent(1) are not supported.
An encrypted file _can_ be linked to the SSH public key it was encrypted to.
This is so that `age` can identify the correct SSH private key before
requesting its password, if any.
## EXIT STATUS
`age` will exit 0 if and only if encryption or decryption are successful for the
full length of the input.
If an error occurs during decryption, partial output might still be generated,
but only if it was possible to securely authenticate it. No unauthenticathed
output is ever released.
## BACKWARDS COMPATIBILITY
Files encrypted with a stable version (not alpha, beta, or release candidate) of
`age`, or with any v1.0.0 beta or release candidate, will decrypt with any later
version of the tool.
If decrypting older files poses a security risk, doing so might cause an error
by default. In this case, a flag will be provided to force the operation.
## EXAMPLES
Generate a new identity, encrypt data, and decrypt:
$ age-keygen -o key.txt
Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
$ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data.tar.gz.age
$ age -d -o data.tar.gz -i key.txt data.tar.gz.age
Encrypt `example.jpg` to multiple recipients and output to `example.jpg.age`:
$ age -o example.jpg.age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \
-r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example.jpg
Encrypt to a list of recipients:
$ cat > recipients.txt
# Alice
age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
# Bob
age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg
$ age -R recipients.txt example.jpg > example.jpg.age
Encrypt and decrypt a file using a passphrase:
$ age -p secrets.txt > secrets.txt.age
Enter passphrase (leave empty to autogenerate a secure one):
Using the autogenerated passphrase "release-response-step-brand-wrap-ankle-pair-unusual-sword-train".
$ age -d secrets.txt.age > secrets.txt
Enter passphrase:
Encrypt and decrypt with an SSH public key:
$ age -R ~/.ssh/id_ed25519.pub example.jpg > example.jpg.age
$ age -d -i ~/.ssh/id_ed25519 example.jpg.age > example.jpg
Encrypt to the SSH keys of a GitHub user:
$ curl https://github.com/benjojo.keys | age -R - example.jpg > example.jpg.age
## SEE ALSO
age-keygen(1)
## AUTHORS
Filippo Valsorda <age@filippo.io>