diff --git a/.githooks/pre-commit/01-keymanual b/.githooks/pre-commit/01-keymanual index 900119d..15269dd 100755 --- a/.githooks/pre-commit/01-keymanual +++ b/.githooks/pre-commit/01-keymanual @@ -5,3 +5,4 @@ set -e # cd "${GIT_WORK_TREE}/_ref" cd "${PWD}/_ref" asciidoctor -o ./KEY_GUIDE.html ./KEY_GUIDE.adoc +git add KEY_GUIDE.html diff --git a/_ref/KEY_GUIDE.html b/_ref/KEY_GUIDE.html new file mode 100644 index 0000000..b427d5e --- /dev/null +++ b/_ref/KEY_GUIDE.html @@ -0,0 +1,910 @@ + + + + + + + + +OpenSSH Key Structure Guide + + + + + + +
+
+

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.

+
+
+
+
+

2. Basic Introduction

+
+
+

2.1. Legacy

+
+

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

+
+

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

+
+
+
+
A B C
+
+
+
+

Where:

+
+
+
+
A
+
+

The key type (e.g. ssh-rsa, ssh-ed25519, etc.)

+
+
B
+
+

The public key itself, Base64[2]-encoded

+
+
C
+
+

The key’s comment

+
+
+
+
+

The structures specified in the breakdowns later in this document describe the decoded version of B only.

+
+
+
+
+

2.2. New "v1" Format

+
+

2.2.1. Private Keys

+ +
+
+

2.2.2. Public Keys

+ +
+
+
+
+
+

3. Keytype-Specific Breakdowns

+
+
+

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.

+
+
+

The key structures have references to the RSA notations in single quotes. You can find these enumerated in RFC 8017 ยง 2. See also the Wikipedia article.

+
+
+

3.1.1. Public

+
+
3.1.1.1. Structure
+
+

Public keys are stored in the following structure:

+
+
+
Key Structure
+
+
1
+2
+3
+4
+5
+6
+
0 uint32 allocator for 0.0 (4 bytes)
+    0.0 Public key type string (ASCII bytes; length defined above)
+1 uint32 allocator for 1.0 (4 bytes)
+    1.0 Public exponent ('e')
+2 uint32 allocator for 2.0 (4 bytes)
+    2.0 modulus ('n')
+
+
+
+
+
+
3.1.1.2. Example
+
+
.pub format
+
+
1
+
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC3zsBGAc4qEvDJJMuaMOuZAGaBLLFDaRk/MLK5/dSvyzAMkY8qd9ZEEPNheufIyjGMJX08TfTixBCLu+k6holLoUs1dfL3IVC8OB3L+3QsehloZv0xhKzpZ2Gt2g/CmS9shm11aZGfwi2cS/DeQFqMdtUZqipTKdxoJXdyKaXQt1OnglqJuVJ1+cAl4hU0PGyIzWaQoiH4rp72de5GTcfRGNpBBQfqXWtkid1gr9imZGSS2z4nnxp4JA24q72mxQcUyWNmUKcggef6XUcsFCiwfq5dFbZOoeKnUIUS/pq2VfhqMTSG08yh3Y6QrMXJ+6TW52dQf7q586f2jHSBQq8qNwHTGoqbdRGViqdxh7pwLtk004WvzuQjgOleDn6bwPTSM2f8dwN0Fnt/CSb7b9ttBarRz9GRgkhFsBThgVO/DR08Ox+tuyWj8dFR+baEYz2MFpD82MrQWqwq6yPb8Zo35ICgCJEDGcEW1HvZJLOZQlQ7iKD2EnlSstjhKQ8wKfVCrr6cDI42zzKWhlzWZDyJJNVm6/SXGAk5mhrAlv4e3Dtfhxv17wtNRODqJ2INIFFC4L/PZ3tNsCVTISGj8HRapNBYYzFzMleFWlzsvjrEQD0E/wzAxYt8BJBLQCElwrwqY6IOuzCcxvPmXbMBoFi42s4H5xs48/NZVDP2mxmPBw== This is a comment string
+
+
+
+
+
Structure Reference (Hex) (Decoded Base64 component only; AAA…​PBw==)
+
+
 1
+ 2
+ 3
+ 4
+ 5
+ 6
+ 7
+ 8
+ 9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+
0 00000007 (7)
+    0.0 7373682d727361 ("ssh-rsa")
+1 00000003 (3)
+    1.0 010001 (65537)
+2 00000201 (513)
+    2.0 00b7cec04601ce2a12f0c924cb9a30eb990066812cb14369193f30b2b9fdd4af
+        cb300c918f2a77d64410f3617ae7c8ca318c257d3c4df4e2c4108bbbe93a8689
+        4ba14b3575f2f72150bc381dcbfb742c7a196866fd3184ace96761adda0fc299
+        2f6c866d7569919fc22d9c4bf0de405a8c76d519aa2a5329dc6825777229a5d0
+        b753a7825a89b95275f9c025e215343c6c88cd6690a221f8ae9ef675ee464dc7
+        d118da410507ea5d6b6489dd60afd8a6646492db3e279f1a78240db8abbda6c5
+        0714c9636650a72081e7fa5d472c1428b07eae5d15b64ea1e2a7508512fe9ab6
+        55f86a313486d3cca1dd8e90acc5c9fba4d6e767507fbab9f3a7f68c748142af
+        2a3701d31a8a9b7511958aa77187ba702ed934d385afcee42380e95e0e7e9bc0
+        f4d23367fc770374167b7f0926fb6fdb6d05aad1cfd191824845b014e18153bf
+        0d1d3c3b1fadbb25a3f1d151f9b684633d8c1690fcd8cad05aac2aeb23dbf19a
+        37e480a008910319c116d47bd924b39942543b88a0f6127952b2d8e1290f3029
+        f542aebe9c0c8e36cf3296865cd6643c8924d566ebf4971809399a1ac096fe1e
+        dc3b5f871bf5ef0b4d44e0ea27620d205142e0bfcf677b4db025532121a3f074
+        5aa4d0586331733257855a5cecbe3ac4403d04ff0cc0c58b7c04904b402125c2
+        bc2a63a20ebb309cc6f3e65db301a058b8dace07e71b38f3f3595433f69b198f
+        07
+
+
+
+
+
+
+

3.1.2. Private

+
+
3.1.2.1. Legacy
+
+

TODO

+
+
+

TODO +===== v1

+
+
+
+
+
+

3.2. ED25519

+ +
+
+
+
+
+
+
+1. https://datatracker.ietf.org/doc/html/rfc7468 +
+
+2. https://datatracker.ietf.org/doc/html/rfc4648 +
+
+3. https://datatracker.ietf.org/doc/html/rfc8017 +
+
+ + + \ No newline at end of file