mirrors/age
1
0
Fork 0
mirror of https://github.com/FiloSottile/age.git synced 2025-12-23 05:25:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: regenerate groff and html man pages

Browse Source
This commit is contained in:
GitHub Actions
2022-05-24 13:59:08 +00:00
parent acb1170bbc
commit f4112110f1
2 changed files with 135 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
doc/age.1
View File

@@ -13,7 +13,7 @@
\fBage\fR [\fB\-\-encrypt\fR] \fB\-\-passphrase\fR [\fB\-\-armor\fR] [\fB\-o\fR \fIOUTPUT\fR] [\fIINPUT\fR]
.
.br
\fBage\fR \fB\-\-decrypt\fR [\fB\-i\fR \fIPATH\fR]\.\.\. [\fB\-o\fR \fIOUTPUT\fR] [\fIINPUT\fR]
\fBage\fR \fB\-\-decrypt\fR [\fB\-i\fR \fIPATH\fR | \fB\-j\fR \fIPLUGIN\fR]\.\.\. [\fB\-o\fR \fIOUTPUT\fR] [\fIINPUT\fR]
.
.br
.
@@ -21,10 +21,10 @@
\fBage\fR encrypts or decrypts \fIINPUT\fR to \fIOUTPUT\fR\. The \fIINPUT\fR argument is optional and defaults to standard input\. Only a single \fIINPUT\fR file may be specified\. If \fB\-o\fR is not specified, \fIOUTPUT\fR defaults to standard output\.
.
.P
If \fB\-\-passphrase\fR is specified, the file is encrypted with a passphrase requested interactively\. Otherwise, it\'s encrypted to one or more \fIRECIPIENTS\fR specified with \fB\-r\fR/\fB\-\-recipient\fR or \fB\-R\fR/\fB\-\-recipients\-file\fR\. Every recipient can decrypt the file\.
If \fB\-p\fR/\fB\-\-passphrase\fR is specified, the file is encrypted with a passphrase requested interactively\. Otherwise, it\'s encrypted to one or more \fIRECIPIENTS\fR specified with \fB\-r\fR/\fB\-\-recipient\fR or \fB\-R\fR/\fB\-\-recipients\-file\fR\. Every recipient can decrypt the file\.
.
.P
In \fB\-\-decrypt\fR mode, passphrase\-encrypted files are detected automatically and the passphrase is requested interactively\. Otherwise, one or more \fIIDENTITIES\fR specified with \fB\-i\fR/\fB\-\-identity\fR are used to decrypt the file\.
In \fB\-d\fR/\fB\-\-decrypt\fR mode, passphrase\-encrypted files are detected automatically and the passphrase is requested interactively\. Otherwise, one or more \fIIDENTITIES\fR specified with \fB\-i\fR/\fB\-\-identity\fR are used to decrypt the file\.
.
.P
\fBage\fR encrypted files are binary and not malleable, with around 200 bytes of overhead per recipient, plus 16 bytes every 64KiB of plaintext\.
@@ -53,7 +53,7 @@ Encrypt \fIINPUT\fR to \fIOUTPUT\fR\. This is the default\.
Encrypt to the explicitly specified \fIRECIPIENT\fR\. See the \fIRECIPIENTS AND IDENTITIES\fR section for possible recipient formats\.
.
.IP
This option can be repeated and combined with \fB\-R\fR/\fB\-\-recipients\-file\fR, and the file can be decrypted by all provided recipients independently\.
This option can be repeated and combined with other recipient flags, and the file can be decrypted by all provided recipients independently\.
.
.TP
\fB\-R\fR, \fB\-\-recipients\-file\fR=\fIPATH\fR
@@ -63,14 +63,14 @@ Encrypt to the \fIRECIPIENTS\fR listed in the file at \fIPATH\fR, one per line\.
If \fIPATH\fR is \fB\-\fR, the recipients are read from standard input\. In this case, the \fIINPUT\fR argument must be specified\.
.
.IP
This option can be repeated and combined with \fB\-r\fR/\fB\-\-recipient\fR, and the file can be decrypted by all provided recipients independently\.
This option can be repeated and combined with other recipient flags, and the file can be decrypted by all provided recipients independently\.
.
.TP
\fB\-p\fR, \fB\-\-passphrase\fR
Encrypt with a passphrase, requested interactively from the terminal\. \fBage\fR will offer to auto\-generate a secure passphrase\.
.
.IP
This option can\'t be used with \fB\-r\fR/\fB\-\-recipient\fR or \fB\-R\fR/\fB\-\-recipients\-file\fR\.
This option can\'t be used with other recipient flags\.
.
.TP
\fB\-a\fR, \fB\-\-armor\fR
@@ -82,6 +82,26 @@ Encrypt to an ASCII\-only "armored" encoding\.
.IP
Decryption transparently detects and decodes ASCII armoring\.
.
.TP
\fB\-i\fR, \fB\-\-identity\fR=\fIPATH\fR
Encrypt to the \fIRECIPIENTS\fR corresponding to the \fIIDENTITIES\fR listed in the file at \fIPATH\fR\. This is equivalent to converting the file at \fIPATH\fR to a recipients file with \fBage\-keygen \-y\fR and then passing that to \fB\-R\fR/\fB\-\-recipients\-file\fR\.
.
.IP
For the format of \fIPATH\fR, see the definition of \fB\-i\fR/\fB\-\-identity\fR in the \fIDecryption options\fR section\.
.
.IP
\fB\-e\fR/\fB\-\-encrypt\fR must be explicitly specified when using \fB\-i\fR/\fB\-\-identity\fR in encryption mode to avoid confusion\.
.
.TP
\fB\-j\fR \fIPLUGIN\fR
Encrypt using the data\-less \fIplugin\fR \fIPLUGIN\fR\.
.
.IP
This is equivalent to using \fB\-i\fR/\fB\-\-identity\fR with a file that contains a single plugin \fBIDENTITY\fR that encodes no plugin\-specific data\.
.
.IP
\fB\-e\fR/\fB\-\-encrypt\fR must be explicitly specified when using \fB\-j\fR in encryption mode to avoid confusion\.
.
.SS "Decryption options"
.
.TP
@@ -114,10 +134,14 @@ c\. An SSH private key file, in PKCS#1, PKCS#8, or OpenSSH format\. If the priva
d\. "\fB\-\fR", causing one of the options above to be read from standard input\. In this case, the \fIINPUT\fR argument must be specified\.
.
.IP
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\.
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, but it is an error if the \fIINPUT\fR file is passphrase\-encrypted and \fB\-i\fR/\fB\-\-identity\fR is specified\.
.
.TP
\fB\-j\fR \fIPLUGIN\fR
Decrypt using the data\-less \fIplugin\fR \fIPLUGIN\fR\.
.
.IP
If \fB\-e\fR/\fB\-\-encrypt\fR is explicitly specified (to avoid confusion), \fB\-i\fR/\fB\-\-identity\fR may also be used to encrypt to the \fBRECIPIENTS\fR corresponding to the \fBIDENTITIES\fR listed at \fIPATH\fR\. This allows using an identity file as a symmetric key, if desired\.
This is equivalent to using \fB\-i\fR/\fB\-\-identity\fR with a file that contains a single plugin \fBIDENTITY\fR that encodes no plugin\-specific data\.
.
.SH "RECIPIENTS AND IDENTITIES"
\fBRECIPIENTS\fR are public values, like a public key, that a file can be encrypted to\. \fBIDENTITIES\fR are private values, like a private key, that allow decrypting a file encrypted to the corresponding \fBRECIPIENT\fR\.
@@ -183,6 +207,24 @@ An \fBIDENTITY\fR is an SSH private key \fIfile\fR passed individually to \fB\-i
.P
An encrypted file \fIcan\fR be linked to the SSH public key it was encrypted to\. This is so that \fBage\fR can identify the correct SSH private key before requesting its password, if any\.
.
.SS "Plugins"
\fBage\fR can be extended through plugins\. A plugin is only loaded if a corresponding \fBRECIPIENT\fR or \fBIDENTITY\fR is specified\. (Simply decrypting a file encrypted with a plugin will not cause it to load, for security reasons among others\.)
.
.P
A \fBRECIPIENT\fR for a plugin named \fBexample\fR starts with \fBage1example1\fR, while an \fBIDENTITY\fR starts with \fBAGE\-PLUGIN\-EXAMPLE\-1\fR\. They both encode arbitrary plugin\-specific data, and are generated by the plugin\.
.
.P
When either is specified, \fBage\fR searches for \fBage\-plugin\-example\fR in the PATH and executes it to perform the file header encryption or decryption\. The plugin may request input from the user through \fBage\fR to complete the operation\.
.
.P
Plugins can be freely mixed with other plugins or natively supported keys\.
.
.P
A plugin is not bound to only encrypt or decrypt files meant for or generated by the plugin\. For example, a plugin can be used to decrypt files encrypted to a native X25519 \fBRECIPIENT\fR or even with a passphrase\. Similarly, a plugin can encrypt a file such that it can be decrypted without the use of any plugin\.
.
.P
Plugins for which the \fBIDENTITY\fR/\fBRECIPIENT\fR distinction doesn\'t make sense (such as a symmetric encryption plugin) may generate only an \fBIDENTITY\fR and instruct the user to perform encryption with the \fB\-e\fR/\fB\-\-encrypt\fR and \fB\-i\fR/\fB\-\-identity\fR flags\. Plugins for which the concept of separate identities doesn\'t make sense (such as a password\-encryption plugin) may instruct the user to use the \fB\-j\fR flag\.
.
.SH "EXIT STATUS"
\fBage\fR will exit 0 if and only if encryption or decryption are successful for the full length of the input\.
.
@@ -301,6 +343,23 @@ $ age \-d \-i ~/\.ssh/id_ed25519 example\.jpg\.age > example\.jpg
.IP "" 0
.
.P
Encrypt and decrypt with age\-plugin\-yubikey:
.
.IP "" 4
.
.nf
$ age\-plugin\-yubikey # run interactive setup, generate identity file and obtain recipient
$ age \-r age1yubikey1qwt50d05nh5vutpdzmlg5wn80xq5negm4uj9ghv0snvdd3yysf5yw3rhl3t secrets\.txt > secrets\.txt\.age
$ age \-d \-i age\-yubikey\-identity\-388178f3\.txt secrets\.txt\.age
.
.fi
.
.IP "" 0
.
.P
Encrypt to the SSH keys of a GitHub user:
.
.IP "" 4

83
doc/age.1.html
View File

@@ -80,7 +80,7 @@
<p><code>age</code> [<code>--encrypt</code>] (<code>-r</code> <var>RECIPIENT</var> | <code>-R</code> <var>PATH</var>)... [<code>--armor</code>] [<code>-o</code> <var>OUTPUT</var>] [<var>INPUT</var>]<br />
<code>age</code> [<code>--encrypt</code>] <code>--passphrase</code> [<code>--armor</code>] [<code>-o</code> <var>OUTPUT</var>] [<var>INPUT</var>]<br />
<code>age</code> <code>--decrypt</code> [<code>-i</code> <var>PATH</var>]... [<code>-o</code> <var>OUTPUT</var>] [<var>INPUT</var>]<br /></p>
<code>age</code> <code>--decrypt</code> [<code>-i</code> <var>PATH</var> | <code>-j</code> <var>PLUGIN</var>]... [<code>-o</code> <var>OUTPUT</var>] [<var>INPUT</var>]<br /></p>
<h2 id="DESCRIPTION">DESCRIPTION</h2>
@@ -88,13 +88,13 @@
optional and defaults to standard input. Only a single <var>INPUT</var> file may be
specified. If <code>-o</code> is not specified, <var>OUTPUT</var> defaults to standard output.</p>
<p>If <code>--passphrase</code> is specified, the file is encrypted with a passphrase
<p>If <code>-p</code>/<code>--passphrase</code> is specified, the file is encrypted with a passphrase
requested interactively. Otherwise, it's encrypted to one or more
<a href="#RECIPIENTS-AND-IDENTITIES" title="RECIPIENTS AND IDENTITIES" data-bare-link="true">RECIPIENTS</a> specified with <code>-r</code>/<code>--recipient</code> or
<code>-R</code>/<code>--recipients-file</code>. Every recipient can decrypt the file.</p>
<p>In <code>--decrypt</code> mode, passphrase-encrypted files are detected automatically and
the passphrase is requested interactively. Otherwise, one or more
<p>In <code>-d</code>/<code>--decrypt</code> mode, passphrase-encrypted files are detected automatically
and the passphrase is requested interactively. Otherwise, one or more
<a href="#RECIPIENTS-AND-IDENTITIES" title="RECIPIENTS AND IDENTITIES" data-bare-link="true">IDENTITIES</a> specified with <code>-i</code>/<code>--identity</code> are
used to decrypt the file.</p>
@@ -120,7 +120,7 @@ overhead per recipient, plus 16 bytes every 64KiB of plaintext.</p>
<dt><code>-r</code>, <code>--recipient</code>=<var>RECIPIENT</var></dt><dd><p> Encrypt to the explicitly specified <var>RECIPIENT</var>. See the
<a href="#RECIPIENTS-AND-IDENTITIES" title="RECIPIENTS AND IDENTITIES" data-bare-link="true">RECIPIENTS AND IDENTITIES</a> section for possible recipient formats.</p>
<p> This option can be repeated and combined with <code>-R</code>/<code>--recipients-file</code>,
<p> This option can be repeated and combined with other recipient flags,
and the file can be decrypted by all provided recipients independently.</p></dd>
<dt><code>-R</code>, <code>--recipients-file</code>=<var>PATH</var></dt><dd><p> Encrypt to the <a href="#RECIPIENTS-AND-IDENTITIES" title="RECIPIENTS AND IDENTITIES" data-bare-link="true">RECIPIENTS</a> listed in the
file at <var>PATH</var>, one per line. Empty lines and lines starting with <code>#</code>
@@ -129,13 +129,12 @@ overhead per recipient, plus 16 bytes every 64KiB of plaintext.</p>
<p> If <var>PATH</var> is <code>-</code>, the recipients are read from standard input. In
this case, the <var>INPUT</var> argument must be specified.</p>
<p> This option can be repeated and combined with <code>-r</code>/<code>--recipient</code>,
<p> This option can be repeated and combined with other recipient flags,
and the file can be decrypted by all provided recipients independently.</p></dd>
<dt><code>-p</code>, <code>--passphrase</code></dt><dd><p> Encrypt with a passphrase, requested interactively from the terminal.
<code>age</code> will offer to auto-generate a secure passphrase.</p>
<p> This option can't be used with <code>-r</code>/<code>--recipient</code> or
<code>-R</code>/<code>--recipients-file</code>.</p></dd>
<p> This option can't be used with other recipient flags.</p></dd>
<dt><code>-a</code>, <code>--armor</code></dt><dd><p> Encrypt to an ASCII-only "armored" encoding.</p>
<p> <code>age</code> armor is a strict version of PEM with type <code>AGE ENCRYPTED FILE</code>,
@@ -143,6 +142,23 @@ overhead per recipient, plus 16 bytes every 64KiB of plaintext.</p>
trailing extra data.</p>
<p> Decryption transparently detects and decodes ASCII armoring.</p></dd>
<dt><code>-i</code>, <code>--identity</code>=<var>PATH</var></dt><dd><p> Encrypt to the <a href="#RECIPIENTS-AND-IDENTITIES" title="RECIPIENTS AND IDENTITIES" data-bare-link="true">RECIPIENTS</a> corresponding to the
<a href="#RECIPIENTS-AND-IDENTITIES" title="RECIPIENTS AND IDENTITIES" data-bare-link="true">IDENTITIES</a> listed in the file at <var>PATH</var>. This
is equivalent to converting the file at <var>PATH</var> to a recipients file with
<code>age-keygen -y</code> and then passing that to <code>-R</code>/<code>--recipients-file</code>.</p>
<p> For the format of <var>PATH</var>, see the definition of <code>-i</code>/<code>--identity</code> in the
<a href="#Decryption-options" title="Decryption options" data-bare-link="true">Decryption options</a> section.</p>
<p> <code>-e</code>/<code>--encrypt</code> must be explicitly specified when using <code>-i</code>/<code>--identity</code>
in encryption mode to avoid confusion.</p></dd>
<dt><code>-j</code> <var>PLUGIN</var></dt><dd><p> Encrypt using the data-less <a href="#Plugins" title="Plugins" data-bare-link="true">plugin</a> <var>PLUGIN</var>.</p>
<p> This is equivalent to using <code>-i</code>/<code>--identity</code> with a file that contains a
single plugin <code>IDENTITY</code> that encodes no plugin-specific data.</p>
<p> <code>-e</code>/<code>--encrypt</code> must be explicitly specified when using <code>-j</code> in encryption
mode to avoid confusion.</p></dd>
</dl>
@@ -178,14 +194,14 @@ overhead per recipient, plus 16 bytes every 64KiB of plaintext.</p>
<p> d. "<code>-</code>", causing one of the options above to be read from standard input.
In this case, the <var>INPUT</var> argument must be specified.</p>
<p> 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.</p>
<p> 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, but it is an error if the <var>INPUT</var> file is
passphrase-encrypted and <code>-i</code>/<code>--identity</code> is specified.</p></dd>
<dt><code>-j</code> <var>PLUGIN</var></dt><dd><p> Decrypt using the data-less <a href="#Plugins" title="Plugins" data-bare-link="true">plugin</a> <var>PLUGIN</var>.</p>
<p> If <code>-e</code>/<code>--encrypt</code> is explicitly specified (to avoid confusion),
<code>-i</code>/<code>--identity</code> may also be used to encrypt to the <code>RECIPIENTS</code>
corresponding to the <code>IDENTITIES</code> listed at <var>PATH</var>. This allows using an
identity file as a symmetric key, if desired.</p></dd>
<p> This is equivalent to using <code>-i</code>/<code>--identity</code> with a file that contains a
single plugin <code>IDENTITY</code> that encodes no plugin-specific data.</p></dd>
</dl>
@@ -245,6 +261,34 @@ or accessed via <span class="man-ref">ssh-agent<span class="s">(1)</span></span>
This is so that <code>age</code> can identify the correct SSH private key before
requesting its password, if any.</p>
<h3 id="Plugins">Plugins</h3>
<p><code>age</code> can be extended through plugins. A plugin is only loaded if a corresponding
<code>RECIPIENT</code> or <code>IDENTITY</code> is specified. (Simply decrypting a file encrypted with
a plugin will not cause it to load, for security reasons among others.)</p>
<p>A <code>RECIPIENT</code> for a plugin named <code>example</code> starts with <code>age1example1</code>, while an
<code>IDENTITY</code> starts with <code>AGE-PLUGIN-EXAMPLE-1</code>. They both encode arbitrary
plugin-specific data, and are generated by the plugin.</p>
<p>When either is specified, <code>age</code> searches for <code>age-plugin-example</code> in the PATH
and executes it to perform the file header encryption or decryption. The plugin
may request input from the user through <code>age</code> to complete the operation.</p>
<p>Plugins can be freely mixed with other plugins or natively supported keys.</p>
<p>A plugin is not bound to only encrypt or decrypt files meant for or generated by
the plugin. For example, a plugin can be used to decrypt files encrypted to a
native X25519 <code>RECIPIENT</code> or even with a passphrase. Similarly, a plugin can
encrypt a file such that it can be decrypted without the use of any plugin.</p>
<p>Plugins for which the <code>IDENTITY</code>/<code>RECIPIENT</code> distinction doesn't make sense
(such as a symmetric encryption plugin) may generate only an <code>IDENTITY</code> and
instruct the user to perform encryption with the <code>-e</code>/<code>--encrypt</code> and
<code>-i</code>/<code>--identity</code> flags. Plugins for which the concept of separate identities
doesn't make sense (such as a password-encryption plugin) may instruct the user
to use the <code>-j</code> flag.</p>
<h2 id="EXIT-STATUS">EXIT STATUS</h2>
<p><code>age</code> will exit 0 if and only if encryption or decryption are successful for the
@@ -322,6 +366,15 @@ Enter passphrase for identity file "key.age":
$ age -d -i ~/.ssh/id_ed25519 example.jpg.age &gt; example.jpg
</code></pre>
<p>Encrypt and decrypt with age-plugin-yubikey:</p>
<pre><code>$ age-plugin-yubikey # run interactive setup, generate identity file and obtain recipient
$ age -r age1yubikey1qwt50d05nh5vutpdzmlg5wn80xq5negm4uj9ghv0snvdd3yysf5yw3rhl3t secrets.txt &gt; secrets.txt.age
$ age -d -i age-yubikey-identity-388178f3.txt secrets.txt.age
</code></pre>
<p>Encrypt to the SSH keys of a GitHub user:</p>
<pre><code>$ curl https://github.com/benjojo.keys | age -R - example.jpg &gt; example.jpg.age