From 61234693e3911a8ebfd25d9991d1e8a73ce85d50 Mon Sep 17 00:00:00 2001 From: brent s Date: Sun, 6 Mar 2022 02:56:45 -0500 Subject: [PATCH] adding better ref structure --- _ref/KEY_GUIDE.adoc | 48 ++++++++++++++++++++++++ _ref/rsa/main.adoc | 8 ++++ _ref/rsa/private/legacy/encrypted.adoc | 2 + _ref/rsa/private/legacy/main.adoc | 2 + _ref/rsa/private/legacy/plain.adoc | 2 + _ref/rsa/private/main.adoc | 5 +++ _ref/rsa/private/v1/encrypted.adoc | 2 + _ref/rsa/private/v1/main.adoc | 2 + _ref/rsa/private/v1/plain.adoc | 2 + _ref/rsa/public.adoc | 51 ++++++++++++++++++++++++++ types/ed25519/consts.go | 1 + types/ed25519/funcs.go | 1 + types/ed25519/types.go | 20 ++++++++++ 13 files changed, 146 insertions(+) create mode 100644 _ref/KEY_GUIDE.adoc create mode 100644 _ref/rsa/main.adoc create mode 100644 _ref/rsa/private/legacy/encrypted.adoc create mode 100644 _ref/rsa/private/legacy/main.adoc create mode 100644 _ref/rsa/private/legacy/plain.adoc create mode 100644 _ref/rsa/private/main.adoc create mode 100644 _ref/rsa/private/v1/encrypted.adoc create mode 100644 _ref/rsa/private/v1/main.adoc create mode 100644 _ref/rsa/private/v1/plain.adoc create mode 100644 _ref/rsa/public.adoc create mode 100644 types/ed25519/consts.go create mode 100644 types/ed25519/funcs.go create mode 100644 types/ed25519/types.go diff --git a/_ref/KEY_GUIDE.adoc b/_ref/KEY_GUIDE.adoc new file mode 100644 index 0000000..045b57a --- /dev/null +++ b/_ref/KEY_GUIDE.adoc @@ -0,0 +1,48 @@ += OpenSSH Key Structure Guide +brent saner , 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 diff --git a/_ref/rsa/main.adoc b/_ref/rsa/main.adoc new file mode 100644 index 0000000..aef0740 --- /dev/null +++ b/_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[] \ No newline at end of file diff --git a/_ref/rsa/private/legacy/encrypted.adoc b/_ref/rsa/private/legacy/encrypted.adoc new file mode 100644 index 0000000..6921cea --- /dev/null +++ b/_ref/rsa/private/legacy/encrypted.adoc @@ -0,0 +1,2 @@ + +TODO diff --git a/_ref/rsa/private/legacy/main.adoc b/_ref/rsa/private/legacy/main.adoc new file mode 100644 index 0000000..36a4887 --- /dev/null +++ b/_ref/rsa/private/legacy/main.adoc @@ -0,0 +1,2 @@ +include::plain.adoc[] +include::encrypted.adoc[] diff --git a/_ref/rsa/private/legacy/plain.adoc b/_ref/rsa/private/legacy/plain.adoc new file mode 100644 index 0000000..6921cea --- /dev/null +++ b/_ref/rsa/private/legacy/plain.adoc @@ -0,0 +1,2 @@ + +TODO diff --git a/_ref/rsa/private/main.adoc b/_ref/rsa/private/main.adoc new file mode 100644 index 0000000..ea6179f --- /dev/null +++ b/_ref/rsa/private/main.adoc @@ -0,0 +1,5 @@ +==== Private +===== Legacy +include::legacy/plain.adoc[] +include::legacy/encrypted.adoc[] +===== v1 diff --git a/_ref/rsa/private/v1/encrypted.adoc b/_ref/rsa/private/v1/encrypted.adoc new file mode 100644 index 0000000..6921cea --- /dev/null +++ b/_ref/rsa/private/v1/encrypted.adoc @@ -0,0 +1,2 @@ + +TODO diff --git a/_ref/rsa/private/v1/main.adoc b/_ref/rsa/private/v1/main.adoc new file mode 100644 index 0000000..36a4887 --- /dev/null +++ b/_ref/rsa/private/v1/main.adoc @@ -0,0 +1,2 @@ +include::plain.adoc[] +include::encrypted.adoc[] diff --git a/_ref/rsa/private/v1/plain.adoc b/_ref/rsa/private/v1/plain.adoc new file mode 100644 index 0000000..6921cea --- /dev/null +++ b/_ref/rsa/private/v1/plain.adoc @@ -0,0 +1,2 @@ + +TODO diff --git a/_ref/rsa/public.adoc b/_ref/rsa/public.adoc new file mode 100644 index 0000000..06a8f4b --- /dev/null +++ b/_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 +---- \ No newline at end of file diff --git a/types/ed25519/consts.go b/types/ed25519/consts.go new file mode 100644 index 0000000..21984ca --- /dev/null +++ b/types/ed25519/consts.go @@ -0,0 +1 @@ +package ed25519 diff --git a/types/ed25519/funcs.go b/types/ed25519/funcs.go new file mode 100644 index 0000000..21984ca --- /dev/null +++ b/types/ed25519/funcs.go @@ -0,0 +1 @@ +package ed25519 diff --git a/types/ed25519/types.go b/types/ed25519/types.go new file mode 100644 index 0000000..4e484df --- /dev/null +++ b/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"` +}