adding better ref structure

_ref/KEY_GUIDE.adoc

@@ -0,0 +1,48 @@
+= OpenSSH Key Structure Guide
+brent saner <bts@square-r00t.net>, https://r00t2.io
+Last updated {localdatetime}
+:doctype: book
+:docinfo: shared
+:data-uri:
+:imagesdir: images
+:sectlinks:
+:sectnums:
+:sectnumlevels: 7
+:toc: preamble
+:toc2: left
+:idprefix:
+:toclevels: 7
+:source-highlighter: rouge
+
+== 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.
+
+== Basic Introduction
+=== Legacy
+==== 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.
+
+==== 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, Base64footnote:[https://datatracker.ietf.org/doc/html/rfc4648]-encoded
+C:: The key's comment
+
+The structures specified in the breakdowns later in this document describe the _decoded_ version of *B* *_only_*.
+
+
+=== New "v1" Format
+==== Private Keys
+==== Public Keys
+
+== Keytype-Specific Breakdowns
+include::rsa/main.adoc[]
+
+=== ED25519

_ref/rsa/main.adoc

@@ -0,0 +1,8 @@
+=== 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.
+
+The key structures have references to the RSA notations in single quotes. You can find these enumerated in https://datatracker.ietf.org/doc/html/rfc8017#section-2[RFC 8017 § 2]. See also the https://en.wikipedia.org/wiki/RSA_(cryptosystem)#Key_generation[Wikipedia article^].
+
+include::public.adoc[]
+include::private/main.adoc[]

_ref/rsa/private/legacy/encrypted.adoc

@@ -0,0 +1,2 @@
+
+TODO

_ref/rsa/private/legacy/main.adoc

@@ -0,0 +1,2 @@
+include::plain.adoc[]
+include::encrypted.adoc[]

_ref/rsa/private/legacy/plain.adoc

@@ -0,0 +1,2 @@
+
+TODO

_ref/rsa/private/main.adoc

@@ -0,0 +1,5 @@
+==== Private
+===== Legacy
+include::legacy/plain.adoc[]
+include::legacy/encrypted.adoc[]
+===== v1

_ref/rsa/private/v1/encrypted.adoc

@@ -0,0 +1,2 @@
+
+TODO

_ref/rsa/private/v1/main.adoc

@@ -0,0 +1,2 @@
+include::plain.adoc[]
+include::encrypted.adoc[]

_ref/rsa/private/v1/plain.adoc

@@ -0,0 +1,2 @@
+
+TODO

_ref/rsa/public.adoc

@@ -0,0 +1,51 @@
+
+==== Public
+
+===== Structure
+Public keys are stored in the following structure:
+
+.Key Structure
+[source,text,linenums]
+----
+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')
+----
+
+===== Example
+
+.`.pub` format
+[source,text,linenums]
+----
+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==`)
+[source,text,linenums]
+----
+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
+----

types/ed25519/consts.go

@@ -0,0 +1 @@
+package ed25519

types/ed25519/funcs.go

@@ -0,0 +1 @@
+package ed25519

types/ed25519/types.go

@@ -0,0 +1,20 @@
+package ed25519
+
+import (
+	`crypto/ed25519`
+
+	`r00t2.io/sshkeys/kdf`
+)
+
+// KeyEd25519 is an ed25519 OpenSSH key.
+type KeyEd25519 struct {
+	KeyPairs []*KeypairEd25519 `xml:"keypairs" json:"keypairs" yaml:"Keypairs"`
+	Cipher   string            // TODO: (sshkeys/cipher).Cipher
+	KDF      kdf.KDF
+}
+
+type KeypairEd25519 struct {
+	Private ed25519.PrivateKey `xml:"private" json:"private_key" yaml:"Private Key"`
+	Public  ed25519.PublicKey  `xml:"public" json:"public_key" yaml:"Public Key"`
+	Comment string             `xml:"comment,attr" json:"comment" yaml:"comment"`
+}