doc: regenerate groff and html man pages

2025-12-23 05:25:14 +00:00 · 2025-12-22 18:42:32 +00:00
parent ba67de8a4e
commit 50acf91174
4 changed files with 117 additions and 39 deletions
--- a/doc/age-keygen.1
+++ b/doc/age-keygen.1
@@ -1,10 +1,10 @@
 .\" generated with Ronn-NG/v0.9.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.9.1
-.TH "AGE\-KEYGEN" "1" "June 2024" ""
+.TH "AGE\-KEYGEN" "1" "December 2025" ""
 .SH "NAME"
 \fBage\-keygen\fR \- generate age(1) key pairs
 .SH "SYNOPSIS"
-\fBage\-keygen\fR [\fB\-o\fR \fIOUTPUT\fR]
+\fBage\-keygen\fR [\fB\-pq\fR] [\fB\-o\fR \fIOUTPUT\fR]
 .br
 \fBage\-keygen\fR \fB\-y\fR [\fB\-o\fR \fIOUTPUT\fR] [\fIINPUT\fR]
 .br
@@ -14,6 +14,11 @@
 If the output is not going to a terminal, \fBage\-keygen\fR prints the public key to standard error\.
 .SH "OPTIONS"
 .TP
+\fB\-pq\fR
+Generate a post\-quantum hybrid ML\-KEM\-768 + X25519 key pair\.
+.IP
+In the future, this might become the default\.
+.TP
 \fB\-o\fR, \fB\-\-output\fR=\fIOUTPUT\fR
 Write the identity to \fIOUTPUT\fR instead of standard output\.
 .IP
@@ -25,7 +30,17 @@ Read an identity file from \fIINPUT\fR or from standard input and output the cor
 \fB\-\-version\fR
 Print the version and exit\.
 .SH "EXAMPLES"
-Generate a new identity:
+Generate a new post\-quantum identity:
+.IP "" 4
+.nf
+$ age\-keygen \-pq
+# created: 2025\-11\-17T13:39:06+01:00
+# public key: age1pq167[\|\.\|\.\|\. 1950 more characters \|\.\|\.\|\.]
+AGE\-SECRET\-KEY\-PQ\-1K30MYPZAHAXHR22YHH27EGDVLU0QNSUH3DSV7J7NR3X6D9LHXNWSDLTV4T
+.fi
+.IP "" 0
+.P
+Generate a new traditional identity:
 .IP "" 4
 .nf
 $ age\-keygen
@@ -35,11 +50,11 @@ AGE\-SECRET\-KEY\-1N9JEPW6DWJ0ZQUDX63F5A03GX8QUW7PXDE39N8UYF82VZ9PC8UFS3M7XA9
 .fi
 .IP "" 0
 .P
-Write a new identity to \fBkey\.txt\fR:
+Write a new post\-quantum identity to \fBkey\.txt\fR:
 .IP "" 4
 .nf
 $ age\-keygen \-o key\.txt
-Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+Public key: age1pq1cd[\|\.\|\.\|\. 1950 more characters \|\.\|\.\|\.]
 .fi
 .IP "" 0
 .P
@@ -47,7 +62,7 @@ Convert an identity to a recipient:
 .IP "" 4
 .nf
 $ age\-keygen \-y key\.txt
-age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+age1pq1cd[\|\.\|\.\|\. 1950 more characters \|\.\|\.\|\.]
 .fi
 .IP "" 0
 .SH "SEE ALSO"
--- a/doc/age-keygen.1.html
+++ b/doc/age-keygen.1.html
@@ -76,7 +76,7 @@
 </p>
 <h2 id="SYNOPSIS">SYNOPSIS</h2>

-<p><code>age-keygen</code> [<code>-o</code> <var>OUTPUT</var>]<br>
+<p><code>age-keygen</code> [<code>-pq</code>] [<code>-o</code> <var>OUTPUT</var>]<br>
 <code>age-keygen</code> <code>-y</code> [<code>-o</code> <var>OUTPUT</var>] [<var>INPUT</var>]<br></p>

 <h2 id="DESCRIPTION">DESCRIPTION</h2>
@@ -91,6 +91,11 @@ standard error.</p>
 <h2 id="OPTIONS">OPTIONS</h2>

 <dl>
+<dt><code>-pq</code></dt>
+<dd>  Generate a post-quantum hybrid ML-KEM-768 + X25519 key pair.
+
+    <p>In the future, this might become the default.</p>
+</dd>
 <dt>
 <code>-o</code>, <code>--output</code>=<var>OUTPUT</var>
 </dt>
@@ -107,7 +112,15 @@ standard error.</p>

 <h2 id="EXAMPLES">EXAMPLES</h2>

-<p>Generate a new identity:</p>
+<p>Generate a new post-quantum identity:</p>
+
+<pre><code>$ age-keygen -pq
+# created: 2025-11-17T13:39:06+01:00
+# public key: age1pq167[... 1950 more characters ...]
+AGE-SECRET-KEY-PQ-1K30MYPZAHAXHR22YHH27EGDVLU0QNSUH3DSV7J7NR3X6D9LHXNWSDLTV4T
+</code></pre>
+
+<p>Generate a new traditional identity:</p>

 <pre><code>$ age-keygen
 # created: 2021-01-02T15:30:45+01:00
@@ -115,16 +128,16 @@ standard error.</p>
 AGE-SECRET-KEY-1N9JEPW6DWJ0ZQUDX63F5A03GX8QUW7PXDE39N8UYF82VZ9PC8UFS3M7XA9
 </code></pre>

-<p>Write a new identity to <code>key.txt</code>:</p>
+<p>Write a new post-quantum identity to <code>key.txt</code>:</p>

 <pre><code>$ age-keygen -o key.txt
-Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+Public key: age1pq1cd[... 1950 more characters ...]
 </code></pre>

 <p>Convert an identity to a recipient:</p>

 <pre><code>$ age-keygen -y key.txt
-age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+age1pq1cd[... 1950 more characters ...]
 </code></pre>

 <h2 id="SEE-ALSO">SEE ALSO</h2>
@@ -137,7 +150,7 @@ age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

  <ol class='man-decor man-foot man foot'>
    <li class='tl'></li>
-    <li class='tc'>June 2024</li>
+    <li class='tc'>December 2025</li>
    <li class='tr'>age-keygen(1)</li>
  </ol>

--- a/doc/age.1
+++ b/doc/age.1
@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.9.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.9.1
-.TH "AGE" "1" "June 2024" ""
+.TH "AGE" "1" "December 2025" ""
 .SH "NAME"
 \fBage\fR \- simple, modern, and secure file encryption
 .SH "SYNOPSIS"
@@ -99,23 +99,39 @@ Decrypt using the data\-less \fIplugin\fR \fIPLUGIN\fR\.
 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\.
-.SS "Native X25519 keys"
-Native \fBage\fR 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\.
+.SS "Native keys"
+Native \fBage\fR key pairs are generated with age\-keygen(1), and provide small encodings and strong encryption based on X25519 for classic keys, and X25519 + ML\-KEM\-768 for post\-quantum hybrid keys\. The post\-quantum hybrid keys are secure against future quantum computers and are the recommended recipient type for most applications\.
 .P
-A \fBRECIPIENT\fR encoding begins with \fBage1\fR and looks like the following:
+A hybrid \fBRECIPIENT\fR encoding begins with \fBage1pq1\fR and looks like the following:
+.IP "" 4
+.nf
+age1pq167[\|\.\|\.\|\. 1950 more characters \|\.\|\.\|\.]
+.fi
+.IP "" 0
+.P
+A hybrid \fBIDENTITY\fR encoding begins with \fBAGE\-SECRET\-KEY\-PQ\-1\fR and looks like the following:
+.IP "" 4
+.nf
+AGE\-SECRET\-KEY\-PQ\-1K30MYPZAHAXHR22YHH27EGDVLU0QNSUH3DSV7J7NR3X6D9LHXNWSDLTV4T
+.fi
+.IP "" 0
+.P
+A classic \fBRECIPIENT\fR encoding begins with \fBage1\fR and looks like the following:
 .IP "" 4
 .nf
 age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh
 .fi
 .IP "" 0
 .P
-An \fBIDENTITY\fR encoding begins with \fBAGE\-SECRET\-KEY\-1\fR and looks like the following:
+A classic \fBIDENTITY\fR encoding begins with \fBAGE\-SECRET\-KEY\-1\fR and looks like the following:
 .IP "" 4
 .nf
 AGE\-SECRET\-KEY\-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ
 .fi
 .IP "" 0
 .P
+A file can't be encrypted to both post\-quantum and classic keys, as that would defeat the post\-quantum security of the encryption\.
+.P
 An encrypted file can't be linked to the native recipient it's encrypted to without access to the corresponding identity\.
 .SS "SSH keys"
 As a convenience feature, \fBage\fR 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\.
@@ -147,6 +163,12 @@ Plugins can be freely mixed with other plugins or natively supported keys\.
 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\.
+.P
+\fBage\fR can natively encrypt to recipients starting with \fBage1tag1\fR (using P\-256 ECDH) or \fBage1tagpq1\fR (using the ML\-KEM\-768 + P\-256 post\-quantum hybrid)\. These are intended to be the public side of private keys held in hardware\.
+.P
+They are directly supported to avoid the need to install the plugin, which may be platform\-specific, on the encrypting side\.
+.P
+The tag reduces privacy, by allowing an observer to correlate files with a recipient (but not files amongst them without knowledge of the recipient), but this is also a desirable property for hardware keys that require user interaction for each decryption operation\.
 .SH "EXIT STATUS"
 \fBage\fR will exit 0 if and only if encryption or decryption are successful for the full length of the input\.
 .P
@@ -156,13 +178,13 @@ Files encrypted with a stable version (not alpha, beta, or release candidate) of
 .P
 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\.
 .SH "EXAMPLES"
-Generate a new identity, encrypt data, and decrypt:
+Generate a new post\-quantum identity, encrypt data, and decrypt:
 .IP "" 4
 .nf
-$ age\-keygen \-o key\.txt
-Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+$ age\-keygen \-pq \-o key\.txt
+Public key: age1pq167[\|\.\|\.\|\. 1950 more characters \|\.\|\.\|\.]

-$ tar cvz ~/data | age \-r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p > data\.tar\.gz\.age
+$ tar cvz ~/data | age \-r age1pq167[\|\.\|\.\|\.] > data\.tar\.gz\.age

 $ age \-d \-o data\.tar\.gz \-i key\.txt data\.tar\.gz\.age
 .fi
@@ -171,8 +193,7 @@ $ age \-d \-o data\.tar\.gz \-i key\.txt data\.tar\.gz\.age
 Encrypt \fBexample\.jpg\fR to multiple recipients and output to \fBexample\.jpg\.age\fR:
 .IP "" 4
 .nf
-$ age \-o example\.jpg\.age \-r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \e
-    \-r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example\.jpg
+$ age \-o example\.jpg\.age \-r age1pq167[\|\.\|\.\|\.] \-r age1pq1e3[\|\.\|\.\|\.] example\.jpg
 .fi
 .IP "" 0
 .P
@@ -181,9 +202,9 @@ Encrypt to a list of recipients:
 .nf
 $ cat > recipients\.txt
 # Alice
-age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+age1pq167[\|\.\|\.\|\. 1950 more characters \|\.\|\.\|\.]
 # Bob
-age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg
+age1pq1e3[\|\.\|\.\|\. 1950 more characters \|\.\|\.\|\.]

 $ age \-R recipients\.txt example\.jpg > example\.jpg\.age
 .fi
--- a/doc/age.1.html
+++ b/doc/age.1.html
@@ -253,23 +253,39 @@ overhead per recipient, plus 16 bytes every 64KiB of plaintext.</p>
 to. <code>IDENTITIES</code> are private values, like a private key, that allow decrypting
 a file encrypted to the corresponding <code>RECIPIENT</code>.</p>

-<h3 id="Native-X25519-keys">Native X25519 keys</h3>
+<h3 id="Native-keys">Native keys</h3>

 <p>Native <code>age</code> key pairs are generated with <a class="man-ref" href="age-keygen.1.html">age-keygen<span class="s">(1)</span></a>, and provide small
-encodings and strong encryption based on X25519. They are the recommended
-recipient type for most applications.</p>
+encodings and strong encryption based on X25519 for classic keys, and X25519 +
+ML-KEM-768 for post-quantum hybrid keys. The post-quantum hybrid keys are secure
+against future quantum computers and are the recommended recipient type for most
+applications.</p>

-<p>A <code>RECIPIENT</code> encoding begins with <code>age1</code> and looks like the following:</p>
+<p>A hybrid <code>RECIPIENT</code> encoding begins with <code>age1pq1</code> and looks like the following:</p>
+
+<pre><code>age1pq167[... 1950 more characters ...]
+</code></pre>
+
+<p>A hybrid <code>IDENTITY</code> encoding begins with <code>AGE-SECRET-KEY-PQ-1</code> and looks like
+the following:</p>
+
+<pre><code>AGE-SECRET-KEY-PQ-1K30MYPZAHAXHR22YHH27EGDVLU0QNSUH3DSV7J7NR3X6D9LHXNWSDLTV4T
+</code></pre>
+
+<p>A classic <code>RECIPIENT</code> encoding begins with <code>age1</code> and looks like the following:</p>

 <pre><code>age1gde3ncmahlqd9gg50tanl99r960llztrhfapnmx853s4tjum03uqfssgdh
 </code></pre>

-<p>An <code>IDENTITY</code> encoding begins with <code>AGE-SECRET-KEY-1</code> and looks like the
+<p>A classic <code>IDENTITY</code> encoding begins with <code>AGE-SECRET-KEY-1</code> and looks like the
 following:</p>

 <pre><code>AGE-SECRET-KEY-1KTYK6RVLN5TAPE7VF6FQQSKZ9HWWCDSKUGXXNUQDWZ7XXT5YK5LSF3UTKQ
 </code></pre>

+<p>A file can't be encrypted to both post-quantum and classic keys, as that would
+defeat the post-quantum security of the encryption.</p>
+
 <p>An encrypted file can't be linked to the native recipient it's encrypted to
 without access to the corresponding identity.</p>

@@ -331,6 +347,20 @@ instruct the user to perform encryption with the <code>-e</code>/<code>--encrypt
 doesn't make sense (such as a password-encryption plugin) may instruct the user
 to use the <code>-j</code> flag.</p>

+<h4 id="Tagged-recipients">Tagged recipients</h4>
+
+<p><code>age</code> can natively encrypt to recipients starting with <code>age1tag1</code> (using P-256
+ECDH) or <code>age1tagpq1</code> (using the ML-KEM-768 + P-256 post-quantum hybrid). These
+are intended to be the public side of private keys held in hardware.</p>
+
+<p>They are directly supported to avoid the need to install the plugin, which may
+be platform-specific, on the encrypting side.</p>
+
+<p>The tag reduces privacy, by allowing an observer to correlate files with a
+recipient (but not files amongst them without knowledge of the recipient),
+but this is also a desirable property for hardware keys that require user
+interaction for each decryption operation.</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
@@ -351,29 +381,28 @@ by default. In this case, a flag will be provided to force the operation.</p>

 <h2 id="EXAMPLES">EXAMPLES</h2>

-<p>Generate a new identity, encrypt data, and decrypt:</p>
+<p>Generate a new post-quantum identity, encrypt data, and decrypt:</p>

-<pre><code>$ age-keygen -o key.txt
-Public key: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+<pre><code>$ age-keygen -pq -o key.txt
+Public key: age1pq167[... 1950 more characters ...]

-$ tar cvz ~/data | age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p &gt; data.tar.gz.age
+$ tar cvz ~/data | age -r age1pq167[...] &gt; data.tar.gz.age

 $ age -d -o data.tar.gz -i key.txt data.tar.gz.age
 </code></pre>

 <p>Encrypt <code>example.jpg</code> to multiple recipients and output to <code>example.jpg.age</code>:</p>

-<pre><code>$ age -o example.jpg.age -r age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p \
-    -r age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg example.jpg
+<pre><code>$ age -o example.jpg.age -r age1pq167[...] -r age1pq1e3[...] example.jpg
 </code></pre>

 <p>Encrypt to a list of recipients:</p>

 <pre><code>$ cat &gt; recipients.txt
 # Alice
-age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p
+age1pq167[... 1950 more characters ...]
 # Bob
-age1lggyhqrw2nlhcxprm67z43rta597azn8gknawjehu9d9dl0jq3yqqvfafg
+age1pq1e3[... 1950 more characters ...]

 $ age -R recipients.txt example.jpg &gt; example.jpg.age
 </code></pre>
@@ -432,7 +461,7 @@ $ age -d -i age-yubikey-identity-388178f3.txt secrets.txt.age

  <ol class='man-decor man-foot man foot'>
    <li class='tl'></li>
-    <li class='tc'>June 2024</li>
+    <li class='tc'>December 2025</li>
    <li class='tr'>age(1)</li>
  </ol>