Documentation updates

README.md

@@ -13,13 +13,21 @@ age was designed by [@Benjojo12](https://twitter.com/Benjojo12) and
 The reference interoperable Go implementation is available at
 [filippo.io/age](https://filippo.io/age).
 
+Hardware PIV tokens such as YubiKeys are supported through the
+[age-plugin-yubikey](https://github.com/str4d/age-plugin-yubikey) plugin.
+
+For more plugins, implementations, tools, and integrations, check out the
+[awesome age](https://github.com/FiloSottile/awesome-age) list.
+
 ## Installation
 
 | Environment | CLI command |
 |-------------|-------------|
-| Cargo (Rust 1.59+) | `cargo install rage` |
+| Cargo (Rust 1.65+) | `cargo install rage` |
 | Homebrew (macOS or Linux) | `brew tap str4d.xyz/rage https://str4d.xyz/rage`<br>`brew install rage` |
+| Debian | [Debian packages](https://github.com/str4d/rage/releases) |
 | openSUSE Tumbleweed | `zypper install rage-encryption` |
+| Ubuntu 20.04+ | [Debian packages](https://github.com/str4d/rage/releases) |
 
 On Windows, Linux, and macOS, you can use the
 [pre-built binaries](https://github.com/str4d/rage/releases).
@@ -33,40 +41,43 @@ On Windows, Linux, and macOS, you can use the
 ## Usage
 
 ```
-Usage:
-  rage [--encrypt] -r RECIPIENT [-i IDENTITY] [-a] [-o OUTPUT] [INPUT]
-  rage --decrypt [-i IDENTITY] [-o OUTPUT] [INPUT]
-
-Positional arguments:
-  INPUT                       Path to a file to read from.
-
-Optional arguments:
-  -h, --help                  Print this help message and exit.
-  -V, --version               Print version info and exit.
-  -e, --encrypt               Encrypt the input (the default).
-  -d, --decrypt               Decrypt the input.
-  -p, --passphrase            Encrypt with a passphrase instead of recipients.
-  --max-work-factor WF        Maximum work factor to allow for passphrase decryption.
-  -a, --armor                 Encrypt to a PEM encoded format.
-  -r, --recipient RECIPIENT   Encrypt to the specified RECIPIENT. May be repeated.
-  -R, --recipients-file PATH  Encrypt to the recipients listed at PATH. May be repeated.
-  -i, --identity IDENTITY     Use the identity file at IDENTITY. May be repeated.
-  -j PLUGIN-NAME              Use age-plugin-PLUGIN-NAME in its default mode as an identity.
-  -o, --output OUTPUT         Write the result to the file at path OUTPUT.
+Usage: rage [--encrypt] (-r RECIPIENT | -R PATH)... [-i IDENTITY] [-a] [-o OUTPUT] [INPUT]
+       rage [--encrypt] --passphrase [-a] [-o OUTPUT] [INPUT]
+       rage --decrypt [-i IDENTITY] [-o OUTPUT] [INPUT]
+
+Arguments:
+  [INPUT]  Path to a file to read from.
+
+Options:
+  -h, --help                    Print this help message and exit.
+  -V, --version                 Print version info and exit.
+  -e, --encrypt                 Encrypt the input (the default).
+  -d, --decrypt                 Decrypt the input.
+  -p, --passphrase              Encrypt with a passphrase instead of recipients.
+      --max-work-factor <WF>    Maximum work factor to allow for passphrase decryption.
+  -a, --armor                   Encrypt to a PEM encoded format.
+  -r, --recipient <RECIPIENT>   Encrypt to the specified RECIPIENT. May be repeated.
+  -R, --recipients-file <PATH>  Encrypt to the recipients listed at PATH. May be repeated.
+  -i, --identity <IDENTITY>     Use the identity file at IDENTITY. May be repeated.
+  -j <PLUGIN-NAME>              Use age-plugin-PLUGIN-NAME in its default mode as an identity.
+  -o, --output <OUTPUT>         Write the result to the file at path OUTPUT.
 
 INPUT defaults to standard input, and OUTPUT defaults to standard output.
+If OUTPUT exists, it will be overwritten.
 
 RECIPIENT can be:
 - An age public key, as generated by rage-keygen ("age1...").
 - An SSH public key ("ssh-ed25519 AAAA...", "ssh-rsa AAAA...").
 
 PATH is a path to a file containing age recipients, one per line
-(ignoring "#" prefixed comments and empty lines).
+(ignoring "#" prefixed comments and empty lines). "-" may be used to
+read recipients from standard input.
 
 IDENTITY is a path to a file with age identities, one per line
 (ignoring "#" prefixed comments and empty lines), or to an SSH key file.
 Passphrase-encrypted age identity files can be used as identity files.
 Multiple identities may be provided, and any unused ones will be ignored.
+"-" may be used to read identities from standard input.
 ```
 
 ### Multiple recipients
@@ -93,6 +104,8 @@ age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg
 $ rage -R recipients.txt example.jpg > example.jpg.age
 ```
 
+If the argument to `-R` (or `-i`) is `-`, the file is read from standard input.
+
 ### Passphrases
 
 Files can be encrypted with a passphrase by using `-p/--passphrase`. By default
@@ -185,4 +198,3 @@ Unless you explicitly state otherwise, any contribution intentionally
 submitted for inclusion in the work by you, as defined in the Apache-2.0
 license, shall be dual licensed as above, without any additional terms or
 conditions.
-

age/i18n/en-US/age.ftl

@@ -8,10 +8,18 @@
 
 ### Localization for strings in the age library crate
 
+## Terms (not to be localized)
+
 -age = age
 -rage = rage
+
+-openssh = OpenSSH
+-ssh-keygen = ssh-keygen
 -ssh-rsa = ssh-rsa
 -ssh-ed25519 = ssh-ed25519
+-fido-u2f = FIDO/U2F
+-yubikeys = YubiKeys
+-piv = PIV
 
 ## CLI helpers
 
@@ -82,7 +90,7 @@ err-read-multiple-stdin = Standard input can't be used for multiple purposes.
 err-read-rsa-modulus-too-large =
     RSA Modulus Too Large
     ---------------------
-    OpenSSH supports various RSA modulus sizes, but {-rage} only supports public
+    {-openssh} supports various RSA modulus sizes, but {-rage} only supports public
     keys of at most {$max_size} bits, to prevent a Denial of Service (DoS) condition
     when encrypting to untrusted public keys.
 
@@ -100,35 +108,35 @@ plugin-waiting-on-binary = Waiting for {$binary_name}...
 
 ## SSH identities
 
-ssh-passphrase-prompt = Type passphrase for OpenSSH key '{$filename}'
+ssh-passphrase-prompt = Type passphrase for {-openssh} key '{$filename}'
 
 ssh-unsupported-key = Unsupported SSH key: {$name}
 
 ssh-insecure-key-format =
     Insecure Encrypted Key Format
     -----------------------------
-    Prior to OpenSSH version 7.8, if a password was set when generating a new
-    DSA, ECDSA, or RSA key, ssh-keygen would encrypt the key using the encrypted
+    Prior to {-openssh} version 7.8, if a password was set when generating a new
+    DSA, ECDSA, or RSA key, {-ssh-keygen} would encrypt the key using the encrypted
     PEM format. This encryption format is insecure and should no longer be used.
 
     You can migrate your key to the encrypted SSH private key format (which has
-    been supported by OpenSSH since version 6.5, released in January 2014) by
+    been supported by {-openssh} since version 6.5, released in January 2014) by
     changing its passphrase with the following command:
 
     {"    "}{$change_passphrase}
 
-    If you are using an OpenSSH version between 6.5 and 7.7 (such as the default
-    OpenSSH provided on Ubuntu 18.04 LTS), you can use the following command to
+    If you are using an {-openssh} version between 6.5 and 7.7 (such as the default
+    {-openssh} provided on Ubuntu 18.04 LTS), you can use the following command to
     force keys to be generated using the new format:
 
     {"    "}{$gen_new}
 
 ssh-unsupported-cipher =
     Unsupported Cipher for Encrypted SSH Key
     ----------------------------------------
-    OpenSSH internally supports several different ciphers for encrypted keys,
+    {-openssh} internally supports several different ciphers for encrypted keys,
     but it has only ever directly generated a few of them. {-rage} supports all
-    ciphers that ssh-keygen might generate, and is being updated on a
+    ciphers that {-ssh-keygen} might generate, and is being updated on a
     case-by-case basis with support for non-standard ciphers. Your key uses a
     currently-unsupported cipher ({$cipher}).
 
@@ -139,7 +147,23 @@ ssh-unsupported-cipher =
 ssh-unsupported-key-type =
     Unsupported SSH Key Type
     ------------------------
-    OpenSSH supports various different key types, but {-rage} only supports a
+    {-openssh} supports various different key types, but {-rage} only supports a
     subset of these for backwards compatibility, specifically the '{-ssh-rsa}'
     and '{-ssh-ed25519}' key types. This SSH key uses the unsupported key type
     '{$key_type}'.
+
+ssh-unsupported-security-key =
+    Unsupported SSH Hardware Authenticator
+    --------------------------------------
+    {-openssh} version 8.2p1 added support for {-fido-u2f} hardware authenticators,
+    including hardware security keys such as {-yubikeys}. {-rage} does not work with
+    these SSH key types, because their protocol does not support encryption.
+    This SSH key uses the incompatible type '{$key_type}'.
+
+    If you have a compatible hardware security key, you should use this plugin:
+
+    {$age_plugin_yubikey_url}
+
+    A hardware security key used with both {-openssh} and this plugin will have a
+    separate SSH public key and {-age} encryption recipient, because the plugin
+    implements the {-piv} protocol.

age/i18n/es-AR/age.ftl

@@ -8,10 +8,18 @@
 
 ### Localization for strings in the age library crate
 
+## Terms (not to be localized)
+
 -age = age
 -rage = rage
+
+-openssh = OpenSSH
+-ssh-keygen = ssh-keygen
 -ssh-rsa = ssh-rsa
 -ssh-ed25519 = ssh-ed25519
+-fido-u2f = FIDO/U2F
+-yubikeys = YubiKeys
+-piv = PIV
 
 ## CLI helpers
 
@@ -58,25 +66,25 @@ err-read-invalid-recipient = Destinatario inválido '{$recipient}'.
 
 ## SSH identities
 
-ssh-passphrase-prompt = Escribe frase contraseña para clave OpenSSH '{$filename}'
+ssh-passphrase-prompt = Escribe frase contraseña para clave {-openssh} '{$filename}'
 
 ssh-unsupported-key = Clave SSH no soportada: {$name}
 
 ssh-insecure-key-format =
     Formato de Clave Encriptada inseguro
     ------------------------------------
-    Antes de OpenSSH version 7.8, su una contraseña era establecida al generar
-    una nueva clave DS, ECDSA o RSA, ssh-keygen encriptaría dicha clave utilizando
+    Antes de {-openssh} version 7.8, su una contraseña era establecida al generar
+    una nueva clave DS, ECDSA o RSA, {-ssh-keygen} encriptaría dicha clave utilizando
     el formato PEM. Este formato de encripción es inseguro y no debería utilizarse
     más.
 
     Puedes migrar tu clave al formato de Clave Privada SSH (que has sido soportado
-    por OpenSSH desde la versión 6.5, lanzada en enero de 2014) cambiado su frase
+    por {-openssh} desde la versión 6.5, lanzada en enero de 2014) cambiado su frase
     contraseña (passphrase) con el siguiente comando:
 
     {"    "}{$change_passphrase}
 
-    Si estas utilizando OpenSSH entre las versiones 6.5 y 7.7 (tal como el OpenSSH
+    Si estas utilizando {-openssh} entre las versiones 6.5 y 7.7 (tal como el {-openssh}
     provisto por defecto en Ubuntu 18.04 LTS), puedes usar el siguiente comando para
     forzar la generación de claves utilizando el nuevo formato:
 
@@ -85,9 +93,9 @@ ssh-insecure-key-format =
 ssh-unsupported-cipher =
     Cifrado no soportado para Clave Encriptada SHH
     ----------------------------------------------
-    OpenSSH soporta internamente varios cifrados diferentes para claves encriptadas,
+    {-openssh} soporta internamente varios cifrados diferentes para claves encriptadas,
     pero solo ha soportado solo algunos de pocos de ellos. {-rage} soporta todos
-    los cifrados que ssh-keygen pudiera generar, y esta siendo actualizado
+    los cifrados que {-ssh-keygen} pudiera generar, y esta siendo actualizado
     caso a caso para soportar aquellos cifrados no-estándar. Tu clave utiliza
     un cifrado no soportado actualmente: ({$cipher}).
 

age/i18n/it/age.ftl

@@ -8,10 +8,18 @@
 
 ### Localization for strings in the age library crate
 
+## Terms (not to be localized)
+
 -age = age
 -rage = rage
+
+-openssh = OpenSSH
+-ssh-keygen = ssh-keygen
 -ssh-rsa = ssh-rsa
 -ssh-ed25519 = ssh-ed25519
+-fido-u2f = FIDO/U2F
+-yubikeys = YubiKeys
+-piv = PIV
 
 ## CLI helpers
 
@@ -77,24 +85,24 @@ plugin-waiting-on-binary = In attesa di {$binary_name}...
 
 ## SSH identities
 
-ssh-passphrase-prompt = Inserisci la passphrase per la chiave OpenSSH '{$filename}'
+ssh-passphrase-prompt = Inserisci la passphrase per la chiave {-openssh} '{$filename}'
 
 ssh-unsupported-key = Chiave SSH non supportata: {$name}
 
 ssh-insecure-key-format =
     Formato della Chiave Crittografica Non Sicuro
     ---------------------------------------------
-    Precedentemente alla versione 7.8 di OpenSSH, se una password veniva
-    impostata quando si generava una nuova chiave DSA, ECDSA, o RSA, ssh-keygen
+    Precedentemente alla versione 7.8 di {-openssh}, se una password veniva
+    impostata quando si generava una nuova chiave DSA, ECDSA, o RSA, {-ssh-keygen}
     avrebbe crittografato la chiave usando un formato PEM cifrato.
 
     Puoi migrare la tua chiave nel formato della chiave privata SSH
-    crittografata (supportato dalla versione 6.5 di OpenSSH in poi, rilasciata
+    crittografata (supportato dalla versione 6.5 di {-openssh} in poi, rilasciata
     nel gennaio 2014) cambiando la passphrase associata con il seguente comando:
 
     {"    "}{$change_passphrase}
 
-    Se stai usando una versione di OpenSSH tra 6.5 e 7.7 (come quella
+    Se stai usando una versione di {-openssh} tra 6.5 e 7.7 (come quella
     predefinita di Ubuntu 18.04 LTS), puoi usare il comando seguente per forzare
     la generazione delle chiavi nel nuovo formato:
 
@@ -103,9 +111,9 @@ ssh-insecure-key-format =
 ssh-unsupported-cipher =
     Cifrario Non Supportato per la Chiave SSH Crittografata
     -------------------------------------------------------
-    OpenSSH supporta internamente diversi cifrari per chiavi crittografate, ma
+    {-openssh} supporta internamente diversi cifrari per chiavi crittografate, ma
     ne ha generate direttamente solo alcune di queste. {-rage} supporta tutti i
-    cifrari che ssh-keygen potrebbe generare, e viene aggiornato caso per caso
+    cifrari che {-ssh-keygen} potrebbe generare, e viene aggiornato caso per caso
     con il supporto a cifrari non standard. La tua chiave usa un cifrario
     attualmente non supportato ({$cipher}).
 
@@ -117,6 +125,6 @@ ssh-unsupported-cipher =
 ssh-unsupported-key-type =
     Tipo di Chiave SSH Non Supportato
     ---------------------------------
-    OpenSSH supporta diversi tipi di chiavi, ma {-rage} ne supporta solo alcuni;
+    {-openssh} supporta diversi tipi di chiavi, ma {-rage} ne supporta solo alcuni;
     specificatamente, i tipi '{-ssh-rsa}' e '{-ssh-ed25519}'. Questa chiave SSH
     è del tipo '{$key_type}', che non è supportato.

age/i18n/zh-CN/age.ftl

@@ -8,10 +8,18 @@
 
 ### Localization for strings in the age library crate
 
+## Terms (not to be localized)
+
 -age = age
 -rage = rage
+
+-openssh = OpenSSH
+-ssh-keygen = ssh-keygen
 -ssh-rsa = ssh-rsa
 -ssh-ed25519 = ssh-ed25519
+-fido-u2f = FIDO/U2F
+-yubikeys = YubiKeys
+-piv = PIV
 
 ## CLI helpers
 
@@ -58,31 +66,31 @@ err-read-invalid-recipient = 无效接收方 '{$recipient}'。
 
 ## SSH identities
 
-ssh-passphrase-prompt = 输入 OpenSSH 密钥 '{$filename}' 的密码短语
+ssh-passphrase-prompt = 输入 {-openssh} 密钥 '{$filename}' 的密码短语
 
 ssh-unsupported-key = 该 SSH 身份不受支持： {$name}
 
 ssh-insecure-key-format =
     不安全的私钥格式
     --------------
-    在 OpenSSH 7.8 版本之前，若在生成新 DSA、ECDSA、或 RSA 密钥时设定口令, ssh-keygen 会使用 PEM 加密格式
+    在 {-openssh} 7.8 版本之前，若在生成新 DSA、ECDSA、或 RSA 密钥时设定口令, {-ssh-keygen} 会使用 PEM 加密格式
     来加密密钥。 该加密格式是不安全的，且不应继续使用。
 
-    若您想将密钥迁移至加密 SSH 私钥格式 (该格式从 2014 一月份的 OpenSSH 6.5 版本已受支持)， 可采用此命令以更换
+    若您想将密钥迁移至加密 SSH 私钥格式 (该格式从 2014 一月份的 {-openssh} 6.5 版本已受支持)， 可采用此命令以更换
     它的密码短语:
 
     {"    "}{$change_passphrase}
 
-    若您目前使用的是 OpenSSH 6.5 —— 7.7 版本 (例如 Ubuntu 18.04 LTS 默认提供的 OpenSSH）, 可采用此命令以
+    若您目前使用的是 {-openssh} 6.5 —— 7.7 版本 (例如 Ubuntu 18.04 LTS 默认提供的 {-openssh}）, 可采用此命令以
     强制使用新格式生成密钥：
 
     {"    "}{$gen_new}
 
 ssh-unsupported-cipher =
     未受支持的 SSH 加密密钥密码
     ------------------------
-    OpenSSH 内部支持几种不同的加密钥密码 （ciphers）,但其中只有少数是直接生成的。{-rage} 支持所有
-    ssh-keygen 可生成的密码， 并且正在进行更新，以在个案基础上扩展非标准密码支持。您的密钥使用的密码 ({$cipher})
+    {-openssh} 内部支持几种不同的加密钥密码 （ciphers）,但其中只有少数是直接生成的。{-rage} 支持所有
+    {-ssh-keygen} 可生成的密码， 并且正在进行更新，以在个案基础上扩展非标准密码支持。您的密钥使用的密码 ({$cipher})
     当前不受支持。
 
     若您希望该密钥类型可受支持, 请在此创建新议题 （issue）：