From 1de61a888defa5cda75b00999c2fc0f9da916926 Mon Sep 17 00:00:00 2001 From: brent saner Date: Mon, 1 Sep 2025 13:47:05 -0400 Subject: [PATCH] use named links for each ident --- _ref/KEY_GUIDE.adoc | 24 ++- _ref/KEY_GUIDE.html | 193 +++++++++++++------------ _ref/ed25519/main.adoc | 2 + _ref/ed25519/private/legacy/main.adoc | 1 + _ref/ed25519/private/main.adoc | 1 + _ref/ed25519/private/v1/encrypted.adoc | 11 +- _ref/ed25519/private/v1/plain.adoc | 7 +- _ref/ed25519/public.adoc | 3 + _ref/rsa/main.adoc | 1 + _ref/rsa/private/legacy/encrypted.adoc | 7 +- _ref/rsa/private/legacy/plain.adoc | 5 +- _ref/rsa/private/main.adoc | 1 + _ref/rsa/private/v1/encrypted.adoc | 11 +- _ref/rsa/private/v1/plain.adoc | 7 +- _ref/rsa/public.adoc | 3 + 15 files changed, 154 insertions(+), 123 deletions(-) diff --git a/_ref/KEY_GUIDE.adoc b/_ref/KEY_GUIDE.adoc index ce7ea6a..28dd589 100644 --- a/_ref/KEY_GUIDE.adoc +++ b/_ref/KEY_GUIDE.adoc @@ -21,17 +21,22 @@ To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/. //// +[id="why"] == Purpose This document attempts to present a much more detailed, thorough, and easily-understood form of the key formats used by OpenSSH. The extent of those formats' canonical documentation is https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key[the OpenSSH source tree's `PROTOCOL.key`^], which is a little lacking. +[id="intro"] == Basic Introduction -=== Legacy -==== Private Keys +[id="intro_legc"] +=== Legacy + +[id="intro_legc_priv"] +==== Private Keys In OpenSSH pre-7.8, private keys are stored in their respective PEM encodingfootnote:[https://datatracker.ietf.org/doc/html/rfc7468] with no modification. These legacy private keys should be entirely usable by OpenSSL/LibreSSL/GnuTLS etc. natively with no conversion necessary. +[id="intro_legc_pub"] ==== Public Keys - Each public key *file* (`*.pub`) is written out in the following format: A B C @@ -44,13 +49,14 @@ C:: The key's comment The structures specified in the breakdowns later in this document describe the _decoded_ version of *B* *_only_*. They are specific to each keytype and format version starting with item `2.0`. - +[id="intro_v1"] === New "v1" Format -==== Private Keys +[id="intro_v1_priv"] +==== Private Keys Private key structures have been retooled in the "v1" format. In recent OpenSSH versions, all new keys use the v1 format. They no longer are in straight PEM-compatible format. -Refer to https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key[`PROTOCOL.key`^] for a (very) general description, or each key's specific breakdown for more detailed information. +Refer to https://anongit.mindrot.org/openssh.git/tree/PROTOCOL.key[`PROTOCOL.key`^] (https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.key[GitHub mirror^]) for a (very) general description, or each key type's specific breakdown in this document for more detailed information. The v1 format offers several benefits over the legacy format, including: @@ -59,16 +65,18 @@ The v1 format offers several benefits over the legacy format, including: * embedded public key (no need to derive from the private key) * "checksumming" to confirm proper decryption for encrypted keys +[id="intro_v1_pub"] ==== Public Keys +All public keys in v1 continue to use the same packed binary format as <>. -All public keys in v1 continue to use the same packed binary format as <>. - +[id="bkdn"] == Keytype-Specific Breakdowns include::rsa/main.adoc[] include::ed25519/main.adoc[] +[id="moar"] == Further Information ++++ diff --git a/_ref/KEY_GUIDE.html b/_ref/KEY_GUIDE.html index e0f8311..de7d8a5 100644 --- a/_ref/KEY_GUIDE.html +++ b/_ref/KEY_GUIDE.html @@ -4,7 +4,7 @@ - + OpenSSH Key Structure Guide @@ -141,7 +141,7 @@ p a>code:hover{color:rgba(0,0,0,.9)} #content::before{content:none} #header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0} #header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf} -#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} +#header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px} #header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap} #header .details span:first-child{margin-left:-.125em} #header .details span.email a{color:rgba(0,0,0,.85)} @@ -163,6 +163,7 @@ p a>code:hover{color:rgba(0,0,0,.9)} #toctitle{color:#7a2518;font-size:1.2em} @media screen and (min-width:768px){#toctitle{font-size:1.375em} body.toc2{padding-left:15em;padding-right:0} +body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px} #toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto} #toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em} #toc.toc2>ul{font-size:.9em;margin-bottom:0} @@ -328,7 +329,7 @@ a.image{text-decoration:none;display:inline-block} a.image object{pointer-events:none} sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super} sup.footnote a,sup.footnoteref a{text-decoration:none} -sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline} +sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline} #footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em} #footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0} #footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em} @@ -475,6 +476,10 @@ pre.rouge .gi { color: #116329; background-color: #dafbe1; } +pre.rouge .ges { + font-weight: bold; + font-style: italic; +} pre.rouge .kc { color: #0550ae; } @@ -630,89 +635,89 @@ pre.rouge .gs {

OpenSSH Key Structure Guide

brent saner <bts@square-r00t.net>, https://r00t2.io
-Last updated 2023-09-04 01:40:40 -0400 +Last updated 2025-09-01 13:47:06 -0400
Table of Contents
-

1. Purpose

+

1. Purpose

This document attempts to present a much more detailed, thorough, and easily-understood form of the key formats used by OpenSSH. The extent of those formats' canonical documentation is the OpenSSH source tree’s PROTOCOL.key, which is a little lacking.

@@ -735,18 +740,18 @@ pre.rouge .gs {
-

2. Basic Introduction

+

2. Basic Introduction

-

2.1. Legacy

+

2.1. Legacy

-

2.1.1. Private Keys

+

2.1.1. Private Keys

In OpenSSH pre-7.8, private keys are stored in their respective PEM encoding[1] with no modification. These legacy private keys should be entirely usable by OpenSSL/LibreSSL/GnuTLS etc. natively with no conversion necessary.

-

2.1.2. Public Keys

+

2.1.2. Public Keys

Each public key file (*.pub) is written out in the following format:

@@ -780,14 +785,14 @@ pre.rouge .gs {
-

2.2. New "v1" Format

+

2.2. New "v1" Format

-

2.2.1. Private Keys

+

2.2.1. Private Keys

Private key structures have been retooled in the "v1" format. In recent OpenSSH versions, all new keys use the v1 format. They no longer are in straight PEM-compatible format.

-

Refer to PROTOCOL.key for a (very) general description, or each key’s specific breakdown for more detailed information.

+

Refer to PROTOCOL.key (GitHub mirror) for a (very) general description, or each key type’s specific breakdown in this document for more detailed information.

The v1 format offers several benefits over the legacy format, including:

@@ -810,19 +815,19 @@ pre.rouge .gs {
-

2.2.2. Public Keys

+

2.2.2. Public Keys

-

All public keys in v1 continue to use the same packed binary format as the legacy format.

+

All public keys in v1 continue to use the same packed binary format as the legacy format.

-

3. Keytype-Specific Breakdowns

+

3. Keytype-Specific Breakdowns

-

3.1. RSA

+

3.1. RSA

RSA[3] is a widely-supported PKI system. It is ubiquitous, but it is recommended to use newer systems (e.g. ED25519) for OpenSSH if all clients and destinations support it.

@@ -833,9 +838,9 @@ pre.rouge .gs {

It is highly recommended to use 4096-bit RSA if using RSA keys.

-

3.1.1. Public

+

3.1.1. Public

-
3.1.1.1. Structure
+
3.1.1.1. Structure

Public keys are stored in the following structure:

@@ -859,7 +864,7 @@ pre.rouge .gs {
-
3.1.1.2. Example
+
3.1.1.2. Example
.pub format
@@ -921,17 +926,17 @@ pre.rouge .gs {
-

3.1.2. Private

+

3.1.2. Private

-
3.1.2.1. Legacy (Plain)
+
3.1.2.1. Legacy (Plain)
-
3.1.2.1.1. Structure
+
3.1.2.1.1. Structure

Legacy private keys are encoded in standard RSA PEM format (RFC 7468 § 10, APPENDIX-A).

-
3.1.2.1.2. Example
+
3.1.2.1.2. Example
 1
@@ -1042,9 +1047,9 @@ Zb7jkiz4m88ol7ezdWZyHhVMZqy4bWMCI4moTDcpqJuox6JTQiO2Ajj2pFU=
 
 
 

-
3.1.2.2. Legacy (Encrypted)

+
3.1.2.2. Legacy (Encrypted)

 

-
3.1.2.2.1. Structure

+
3.1.2.2.1. Structure

 

 
Legacy private keys are encoded in standard RSA PEM format (RFC 7468 § 11, APPENDIX-A).

 

@@ -1054,7 +1059,7 @@ The DEK-Info field is defined in 
-
3.1.2.2.2. Example

+
3.1.2.2.2. Example

 

 
The following example, being encrypted, is protected with a passphrase. The passphrase used in this example key is testpassword.

 

@@ -1175,12 +1180,12 @@ ftSfkGNUzTzPFbF5iEukTvKm42a7F/I/ExMVgpN/eQxJ7+m5TOgja0KC1h5fCN4L
 

 

 

-
See the plaintext example for the decrypted (non-password-protected) version of this key.

+
See the plaintext example for the decrypted (non-password-protected) version of this key.

 

 
 
 

-
3.1.2.3. v1 (Plain)

+
3.1.2.3. v1 (Plain)

 

 
@@ -1196,7 +1201,7 @@ ftSfkGNUzTzPFbF5iEukTvKm42a7F/I/ExMVgpN/eQxJ7+m5TOgja0KC1h5fCN4L
 

 

 

 

-
3.1.2.3.1. Structure

+
3.1.2.3.1. Structure

 

 

 
 1
@@ -1278,7 +1283,7 @@ ftSfkGNUzTzPFbF5iEukTvKm42a7F/I/ExMVgpN/eQxJ7+m5TOgja0KC1h5fCN4L
 

 
 

-
Chunk 3.0.0 to 3.0.1: These blocks are not present in unencrypted keys (see the encrypted key structure for what these look like). 3.0 reflects this, as it’s always going to be 00000000 (0).

+
Chunk 3.0.0 to 3.0.1: These blocks are not present in unencrypted keys (see the encrypted key structure for what these look like). 3.0 reflects this, as it’s always going to be 00000000 (0).

 

 

 
Chunk 4.0: This is technically currently unused; upstream hardcodes to 1 (left zero-padded 0x01).

@@ -1295,7 +1300,7 @@ ftSfkGNUzTzPFbF5iEukTvKm42a7F/I/ExMVgpN/eQxJ7+m5TOgja0KC1h5fCN4L
 

 
 

-
3.1.2.3.2. Example

+
3.1.2.3.2. Example

 

 
The following example, being encrypted, is protected with a passphrase. The passphrase used in this example key is test.

 

@@ -1620,7 +1625,7 @@ hau1VzZBnp8AAAAYVGhpcyBpcyBhIGNvbW1lbnQgc3RyaW5nAQID
 

 
 

-
3.1.2.4. v1 (Encrypted)

+
3.1.2.4. v1 (Encrypted)

 

 
@@ -1713,7 +1718,7 @@ Note that 1.0.0 has nothing to do with SSH connections themselv
 

 

 

 

-
3.1.2.4.1. Structure

+
3.1.2.4.1. Structure

 

 

 

@@ -1778,7 +1783,7 @@ Note that 1.0.0 has nothing to do with SSH connections themselv
 

-
3.1.2.4.2. Example

+
3.1.2.4.2. Example

 

 
The following example, being encrypted, is protected with a passphrase. The passphrase used in this example key is test.

 

@@ -2088,7 +2093,7 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 
 

@@ -2250,14 +2255,14 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 

-
See the plaintext structure for details.

+
See the plaintext structure for details.

 

-
3.2. ED25519

+
3.2. ED25519

 

 
ED25519[4] is a relatively somewhat new OpenSSH key algorithm. It has numerous benefits over e.g. RSA, including:

 

@@ -2292,9 +2297,9 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 
I recommend it over all other key types for new SSH keys as long as it’s supported by clients/servers.

 

-
3.2.1. Public

+
3.2.1. Public

 

-
3.2.1.1. Structure

+
3.2.1.1. Structure

 

 
Public keys are stored in the following structure:

 

@@ -2314,7 +2319,7 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 

 

-
3.2.1.2. Example

+
3.2.1.2. Example

 

 
id_ed25519.pub Format

 

@@ -2340,9 +2345,9 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 

 

 

-
3.2.2. Private

+
3.2.2. Private

 

-
3.2.2.1. Legacy

+
3.2.2.1. Legacy

 

 
 1
@@ -1770,7 +1775,7 @@ Note that 1.0.0 has nothing to do with SSH connections themselv
 
Chunk 4.0: This is technically currently unused; upstream hardcodes to 1 (left zero-padded 0x01).

 
 

-
Chunk 4.0.1.0: When decrypted, this is equivalent to the plaintext 4.0.1.0 to 4.0.1.10. It uses a padded size appropriate to the encryption cipher used.

+
Chunk 4.0.1.0: When decrypted, this is equivalent to the plaintext 4.0.1.0 to 4.0.1.10. It uses a padded size appropriate to the encryption cipher used.

 

 

 

 
 

 

-
The decrypted 4.0.1.0 should match the plaintext key’s structure for 4.0.1.0 through 4.0.1.10. The padding length WILL change, however, between the two unless using a cipher with an 8-byte block size.

+
The decrypted 4.0.1.0 should match the plaintext key’s structure for 4.0.1.0 through 4.0.1.10. The padding length WILL change, however, between the two unless using a cipher with an 8-byte block size.

 

 		
 

 
 
 
 
 
 
 
 
 

@@ -2359,7 +2364,7 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 

-
3.2.2.2. v1 (Plain)

+
3.2.2.2. v1 (Plain)

 

 

 

 
 

@@ -2375,7 +2380,7 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 

 

 

 

-
3.2.2.2.1. Structure

+
3.2.2.2.1. Structure

 

 

 
 1
@@ -2437,7 +2442,7 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 

 
 

-
Chunk 3.0.0 to 3.0.1: These blocks are not present in unencrypted keys (see the encrypted key structure for what these look like). 3.0 reflects this, as it’s always going to be 00000000 (0).

+
Chunk 3.0.0 to 3.0.1: These blocks are not present in unencrypted keys (see the encrypted key structure for what these look like). 3.0 reflects this, as it’s always going to be 00000000 (0).

 

 

 
Chunk 4.0: This is technically currently unused; upstream hardcodes to 1 (left zero-padded 0x01).

@@ -2454,7 +2459,7 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 

 
 

-
3.2.2.2.2. Example

+
3.2.2.2.2. Example

 

 
id_ed25519 Format

 

@@ -2542,7 +2547,7 @@ g7umsWLE6XzRH3PDnZewAAAAElRoaXMgaXMgYSB0ZXN0IGtleQECAw==
 

 

 

-
3.2.2.3. v1 (Encrypted)

+
3.2.2.3. v1 (Encrypted)

 

 
@@ -2635,7 +2640,7 @@ Note that 1.0.0 has nothing to do with SSH connections themselv
 

 

 

 

-
3.2.2.3.1. Structure

+
3.2.2.3.1. Structure

 

 

 

@@ -2694,7 +2699,7 @@ Note that 1.0.0 has nothing to do with SSH connections themselv
 

-
3.2.2.3.2. Example

+
3.2.2.3.2. Example

 

 
The following example, being encrypted, is protected with a passphrase. The passphrase used in this example key is test.

 

@@ -2788,7 +2793,7 @@ dCXGDaRlL924VVCYUytRvu7ilZ+dtc9aCQUFJyDF3iXyxN2H68x7teo9e8vqzGtzLkw5KV
 
 

@@ -2834,7 +2839,7 @@ dCXGDaRlL924VVCYUytRvu7ilZ+dtc9aCQUFJyDF3iXyxN2H68x7teo9e8vqzGtzLkw5KV
 

-
See the plaintext structure for details.

+
See the plaintext structure for details.

 

@@ -2843,7 +2848,7 @@ dCXGDaRlL924VVCYUytRvu7ilZ+dtc9aCQUFJyDF3iXyxN2H68x7teo9e8vqzGtzLkw5KV
 

-
4. Further Information

+
4. Further Information

 

 
 	Creative Commons License
@@ -2873,7 +2878,7 @@ dCXGDaRlL924VVCYUytRvu7ilZ+dtc9aCQUFJyDF3iXyxN2H68x7teo9e8vqzGtzLkw5KV
 

 
 
diff --git a/_ref/ed25519/main.adoc b/_ref/ed25519/main.adoc
index 0c47c7d..cfe50fe 100644
--- a/_ref/ed25519/main.adoc
+++ b/_ref/ed25519/main.adoc
@@ -4,6 +4,7 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_ed25519"]
 === ED25519
 
 ED25519footnote:[https://datatracker.ietf.org/doc/html/rfc8709] is a relatively somewhat new OpenSSH key algorithm. It has numerous benefits over e.g. RSA, including:
@@ -17,4 +18,5 @@ ED25519footnote:[https://datatracker.ietf.org/doc/html/rfc8709] is a relatively
 I recommend it over all other key types for new SSH keys as long as it's supported by clients/servers.
 
 include::public.adoc[]
+
 include::private/main.adoc[]
diff --git a/_ref/ed25519/private/legacy/main.adoc b/_ref/ed25519/private/legacy/main.adoc
index 78205d5..ee33a7a 100644
--- a/_ref/ed25519/private/legacy/main.adoc
+++ b/_ref/ed25519/private/legacy/main.adoc
@@ -4,6 +4,7 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_ed25519_priv_legc"]
 ===== Legacy
 
 [NOTE]
diff --git a/_ref/ed25519/private/main.adoc b/_ref/ed25519/private/main.adoc
index 213b218..69277a4 100644
--- a/_ref/ed25519/private/main.adoc
+++ b/_ref/ed25519/private/main.adoc
@@ -4,6 +4,7 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_ed25519_priv"]
 ==== Private
 
 include::legacy/main.adoc[]
diff --git a/_ref/ed25519/private/v1/encrypted.adoc b/_ref/ed25519/private/v1/encrypted.adoc
index 758ed0c..c8cdb46 100644
--- a/_ref/ed25519/private/v1/encrypted.adoc
+++ b/_ref/ed25519/private/v1/encrypted.adoc
@@ -4,6 +4,7 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_ed25519_priv_v1_crypt"]
 ===== v1 (Encrypted)
 
 [TIP]
@@ -40,7 +41,7 @@ This is likely going to be:
 The author recommends using `aes256-ctr`. It is currently the upstream default.
 ====
 
-[id=struct_ed25519_crypt]
+[id="bkdn_ed25519_priv_v1_crypt_struct"]
 ====== Structure
 
 [source,text,linenums]
@@ -68,10 +69,10 @@ The author recommends using `aes256-ctr`. It is currently the upstream default.
 ====
 *Chunk 4.0:* This is technically currently unused; upstream hardcodes to 1 (left zero-padded `0x01`).
 
-*Chunk 4.0.1.0:* When decrypted, this is equivalent to the <> *4.0.1.0* to *4.0.1.6*. It uses a padded size appropriate to the encryption cipher used.
+*Chunk 4.0.1.0:* When decrypted, this is equivalent to the <> *4.0.1.0* to *4.0.1.6*. It uses a padded size appropriate to the encryption cipher used.
 ====
 
-[id=bytes_ed25519_crypt]
+[id="bkdn_ed25519_priv_v1_crypt_ex"]
 ====== Example
 
 The following example, being encrypted, is protected with a passphrase. The passphrase used in this example key is *`test`*.
@@ -123,7 +124,7 @@ dCXGDaRlL924VVCYUytRvu7ilZ+dtc9aCQUFJyDF3iXyxN2H68x7teo9e8vqzGtzLkw5KV
 
 [NOTE]
 ====
-The decrypted *4.0.1.0* should match the <> for *4.0.1* through *4.0.1.6*. The padding length WILL change, however, between the two unless using a cipher with an 8-byte block size.
+The decrypted *4.0.1.0* should match the <> for *4.0.1* through *4.0.1.6*. The padding length WILL change, however, between the two unless using a cipher with an 8-byte block size.
 ====
 
 When *4.0.1.0* is decrypted, it yields:
@@ -148,4 +149,4 @@ When *4.0.1.0* is decrypted, it yields:
 4.0.1.6 0102030405060708090a0b ([1 2 3 4 5 6 7 8 9 10 11], 11 bytes)
 ----
 
-See the <> for details.
+See the <> for details.
diff --git a/_ref/ed25519/private/v1/plain.adoc b/_ref/ed25519/private/v1/plain.adoc
index 5043f15..ae83b96 100644
--- a/_ref/ed25519/private/v1/plain.adoc
+++ b/_ref/ed25519/private/v1/plain.adoc
@@ -4,6 +4,7 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_ed25519_priv_v1_plain"]
 ===== v1 (Plain)
 
 [TIP]
@@ -11,7 +12,7 @@ http://creativecommons.org/licenses/by-sa/4.0/.
 Since plaintext/unencrypted keys do not have a cipher or KDF (as there's no encryption key or algorithm used), they use the string "none" to identify these (and entirely leave out the KDF options).
 ====
 
-[id=struct_ed25519_plain]
+[id="bkdn_ed25519_priv_v1_plain_struct"]
 ====== Structure
 
 [source,text,linenums]
@@ -44,7 +45,7 @@ Since plaintext/unencrypted keys do not have a cipher or KDF (as there's no encr
 
 [NOTE]
 ====
-*Chunk 3.0.0 to 3.0.1:* These blocks are not present in unencrypted keys (see the <> for what these look like). *3.0* reflects this, as it's always going to be `00000000` (0).
+*Chunk 3.0.0 to 3.0.1:* These blocks are not present in unencrypted keys (see the <> for what these look like). *3.0* reflects this, as it's always going to be `00000000` (0).
 
 *Chunk 4.0:* This is technically currently unused; upstream hardcodes to 1 (left zero-padded `0x01`).
 
@@ -53,7 +54,7 @@ Since plaintext/unencrypted keys do not have a cipher or KDF (as there's no encr
 *Chunk 4.0.1.6:* The padding used aligns the private key (*4.0.1.0* to *4.0.1.5.0*) to the cipher blocksize. For plaintext keys, a blocksize of 8 is used.
 ====
 
-[id=bytes_ed25519_plain]
+[id="bkdn_ed25519_priv_v1_plain_ex"]
 ====== Example
 
 .`id_ed25519` Format
diff --git a/_ref/ed25519/public.adoc b/_ref/ed25519/public.adoc
index 8fdfa7d..5713e67 100644
--- a/_ref/ed25519/public.adoc
+++ b/_ref/ed25519/public.adoc
@@ -4,8 +4,10 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_ed25519_pub"]
 ==== Public
 
+[id="bkdn_ed25519_pub_struct"]
 ===== Structure
 
 Public keys are stored in the following structure:
@@ -19,6 +21,7 @@ Public keys are stored in the following structure:
     1.0.0 Public key payload (bytes)
 ----
 
+[id="bkdn_ed25519_pub_ex"]
 ===== Example
 
 .`id_ed25519.pub` Format
diff --git a/_ref/rsa/main.adoc b/_ref/rsa/main.adoc
index ff06469..e2f657d 100644
--- a/_ref/rsa/main.adoc
+++ b/_ref/rsa/main.adoc
@@ -4,6 +4,7 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_rsa"]
 === RSA
 
 RSAfootnote:[https://datatracker.ietf.org/doc/html/rfc8017] is a widely-supported PKI system. It is ubiquitous, but it is recommended to use newer systems (e.g. ED25519) for OpenSSH if all clients and destinations support it.
diff --git a/_ref/rsa/private/legacy/encrypted.adoc b/_ref/rsa/private/legacy/encrypted.adoc
index 0d0228d..ade9585 100644
--- a/_ref/rsa/private/legacy/encrypted.adoc
+++ b/_ref/rsa/private/legacy/encrypted.adoc
@@ -4,9 +4,10 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_rsa_priv_legc_crypt"]
 ===== Legacy (Encrypted)
 
-[id=struct_rsa_crypt_legacy]
+[id="bkdn_rsa_priv_legc_crypt_struct"]
 ====== Structure
 
 Legacy private keys are encoded in standard RSA PEM format (https://datatracker.ietf.org/doc/html/rfc7468[RFC 7468^] § https://datatracker.ietf.org/doc/html/rfc7468#section-11[11^], https://datatracker.ietf.org/doc/html/rfc3447#appendix-A[APPENDIX-A^]).
@@ -14,7 +15,7 @@ Legacy private keys are encoded in standard RSA PEM format (https://datatracker.
 The `Proc-Type` field is defined in https://datatracker.ietf.org/doc/html/rfc1421.html#section-4.6.1.1[RFC 1421 § 4.6.1.1^]. +
 The `DEK-Info` field is defined in https://datatracker.ietf.org/doc/html/rfc1421.html#section-4.6.1.3[RFC 1421 § 4.6.1.3^].
 
-[id=bytes_rsa_crypt_legacy]
+[id="bkdn_rsa_priv_legc_crypt_ex"]
 ====== Example
 
 The following example, being encrypted, is protected with a passphrase. The passphrase used in this example key is *`testpassword`*.
@@ -79,4 +80,4 @@ ftSfkGNUzTzPFbF5iEukTvKm42a7F/I/ExMVgpN/eQxJ7+m5TOgja0KC1h5fCN4L
 -----END RSA PRIVATE KEY-----
 ----
 
-See the <> for the decrypted (non-password-protected) version of this key.
+See the <> for the decrypted (non-password-protected) version of this key.
diff --git a/_ref/rsa/private/legacy/plain.adoc b/_ref/rsa/private/legacy/plain.adoc
index b66e8e3..d512fdb 100644
--- a/_ref/rsa/private/legacy/plain.adoc
+++ b/_ref/rsa/private/legacy/plain.adoc
@@ -4,14 +4,15 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_rsa_priv_legc_plain"]
 ===== Legacy (Plain)
 
-[id=struct_rsa_plain_legacy]
+[id="bkdn_rsa_priv_legc_plain_struct"]
 ====== Structure
 
 Legacy private keys are encoded in standard RSA PEM format (https://datatracker.ietf.org/doc/html/rfc7468[RFC 7468^] § https://datatracker.ietf.org/doc/html/rfc7468#section-10[10^], https://datatracker.ietf.org/doc/html/rfc3447#appendix-A[APPENDIX-A^]).
 
-[id=bytes_rsa_plain_legacy]
+[id="bkdn_rsa_priv_legc_plain_ex"]
 ====== Example
 
 [source,text,linenums]
diff --git a/_ref/rsa/private/main.adoc b/_ref/rsa/private/main.adoc
index 213b218..27fddcd 100644
--- a/_ref/rsa/private/main.adoc
+++ b/_ref/rsa/private/main.adoc
@@ -4,6 +4,7 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_rsa_priv"]
 ==== Private
 
 include::legacy/main.adoc[]
diff --git a/_ref/rsa/private/v1/encrypted.adoc b/_ref/rsa/private/v1/encrypted.adoc
index f13812f..0492a44 100644
--- a/_ref/rsa/private/v1/encrypted.adoc
+++ b/_ref/rsa/private/v1/encrypted.adoc
@@ -4,6 +4,7 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_rsa_priv_v1_crypt"]
 ===== v1 (Encrypted)
 
 [TIP]
@@ -40,7 +41,7 @@ This is likely going to be:
 The author recommends using `aes256-ctr`. It is currently the upstream default.
 ====
 
-[id=struct_rsa_crypt]
+[id="bkdn_rsa_priv_v1_crypt_struct"]
 ====== Structure
 
 [source,text,linenums]
@@ -71,10 +72,10 @@ The author recommends using `aes256-ctr`. It is currently the upstream default.
 ====
 *Chunk 4.0:* This is technically currently unused; upstream hardcodes to 1 (left zero-padded 0x01).
 
-*Chunk 4.0.1.0:* When decrypted, this is equivalent to the <> *4.0.1.0* to *4.0.1.10*. It uses a padded size appropriate to the encryption cipher used.
+*Chunk 4.0.1.0:* When decrypted, this is equivalent to the <> *4.0.1.0* to *4.0.1.10*. It uses a padded size appropriate to the encryption cipher used.
 ====
 
-[id=bytes_rsa_crypt]
+[id="bkdn_rsa_priv_v1_crypt_ex"]
 ====== Example
 
 The following example, being encrypted, is protected with a passphrase. The passphrase used in this example key is *`test`*.
@@ -234,7 +235,7 @@ ZnrXZl+8QIW1MSvaaQFmJFqTs=
 
 [NOTE]
 ====
-The decrypted *4.0.1.0* should match the <> for *4.0.1.0* through *4.0.1.10*. The padding length WILL change, however, between the two unless using a cipher with an 8-byte block size.
+The decrypted *4.0.1.0* should match the <> for *4.0.1.0* through *4.0.1.10*. The padding length WILL change, however, between the two unless using a cipher with an 8-byte block size.
 ====
 
 When *4.0.1.0* is decrypted, it yields:
@@ -317,4 +318,4 @@ When *4.0.1.0* is decrypted, it yields:
 4.0.1.10 010203 ([1 2 3], 3 bytes)
 ----
 
-See the <> for details.
+See the <> for details.
diff --git a/_ref/rsa/private/v1/plain.adoc b/_ref/rsa/private/v1/plain.adoc
index 884d286..a35645c 100644
--- a/_ref/rsa/private/v1/plain.adoc
+++ b/_ref/rsa/private/v1/plain.adoc
@@ -4,6 +4,7 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_rsa_priv_v1_plain"]
 ===== v1 (Plain)
 
 [TIP]
@@ -11,7 +12,7 @@ http://creativecommons.org/licenses/by-sa/4.0/.
 Since plaintext/unencrypted keys do not have a cipher or KDF (as there's no encryption key or algorithm used), they use the string "none" to identify these (and entirely leave out the KDF options).
 ====
 
-[id=struct_rsa_plain]
+[id="bkdn_rsa_priv_v1_plain_struct"]
 ====== Structure
 
 [source,text,linenums]
@@ -54,7 +55,7 @@ Since plaintext/unencrypted keys do not have a cipher or KDF (as there's no encr
 
 [NOTE]
 ====
-*Chunk 3.0.0 to 3.0.1:* These blocks are not present in unencrypted keys (see the <> for what these look like). *3.0* reflects this, as it's always going to be `00000000` (0).
+*Chunk 3.0.0 to 3.0.1:* These blocks are not present in unencrypted keys (see the <> for what these look like). *3.0* reflects this, as it's always going to be `00000000` (0).
 
 *Chunk 4.0:* This is technically currently unused; upstream hardcodes to 1 (left zero-padded 0x01).
 
@@ -63,7 +64,7 @@ Since plaintext/unencrypted keys do not have a cipher or KDF (as there's no encr
 *Chunk 4.0.1.10:* The padding used aligns the private key (*4.0.1.0* to *4.0.1.9.0*) to the cipher blocksize. For plaintext keys, a blocksize of 8 is used.
 ====
 
-[id=bytes_rsa_plain]
+[id="bkdn_rsa_priv_v1_plain_ex"]
 ====== Example
 
 The following example, being encrypted, is protected with a passphrase. The passphrase used in this example key is *`test`*.
diff --git a/_ref/rsa/public.adoc b/_ref/rsa/public.adoc
index 65fc5e9..053e6e1 100644
--- a/_ref/rsa/public.adoc
+++ b/_ref/rsa/public.adoc
@@ -4,8 +4,10 @@ To view a copy of this license, visit
 http://creativecommons.org/licenses/by-sa/4.0/.
 ////
 
+[id="bkdn_rsa_pub"]
 ==== Public
 
+[id="bkdn_rsa_pub_struct"]
 ===== Structure
 
 Public keys are stored in the following structure:
@@ -21,6 +23,7 @@ Public keys are stored in the following structure:
     2.0 modulus ('n') (bytes)
 ----
 
+[id="bkdn_rsa_pub_ex"]
 ===== Example
 
 .`.pub` format

 1
@@ -2686,7 +2691,7 @@ Note that 1.0.0 has nothing to do with SSH connections themselv
 
Chunk 4.0: This is technically currently unused; upstream hardcodes to 1 (left zero-padded 0x01).

 
 

-
Chunk 4.0.1.0: When decrypted, this is equivalent to the plaintext 4.0.1.0 to 4.0.1.6. It uses a padded size appropriate to the encryption cipher used.

+
Chunk 4.0.1.0: When decrypted, this is equivalent to the plaintext 4.0.1.0 to 4.0.1.6. It uses a padded size appropriate to the encryption cipher used.

 

 

 

 
 

 

-
The decrypted 4.0.1.0 should match the plaintext key’s structure for 4.0.1 through 4.0.1.6. The padding length WILL change, however, between the two unless using a cipher with an 8-byte block size.

+
The decrypted 4.0.1.0 should match the plaintext key’s structure for 4.0.1 through 4.0.1.6. The padding length WILL change, however, between the two unless using a cipher with an 8-byte block size.