From c81edde7db25d70bbb99ed2b3bccb22a50acf545 Mon Sep 17 00:00:00 2001 From: brent s Date: Mon, 9 Jan 2023 06:11:57 -0500 Subject: [PATCH] change README from markdown (ew) to AsciiDoctor --- README.adoc | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 README.adoc diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..fb12180 --- /dev/null +++ b/README.adoc @@ -0,0 +1,50 @@ += cc20p1305ssh +Brent Saner +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 + +== What is it? + +A Golang library variant of ChaCha20-Poly1305 that OpenSSH uses (`chacha20-poly1305@openssh.com`). + +Note that this module *only* supports the OpenSSH variant, and should only be used for key generation/parsing/modification/manipulation, not actual connection/stream encryption. + +== Why is this necessary? + +Because Golang.org/x/crypto https://github.com/golang/go/issues/36646[removes functionality^] (even for https://github.com/golang/go/issues/44226[very common tech^]) and thinks OpenSSH is a "weird" use case. That's a direct reference; they called it "weird". + +I *really, really* hope this library is https://github.com/golang/go/issues/57699[no longer necessary^] by the time I'm done writing it but based on my past experiences with core Golang devs, my expectations are extremely low. + +They have no decent support for OpenSSH keys or lower-level operations. And guess what -- sometimes you *need* lower-level functionality. Who knew? + +So now because I'm just a single individual, bug fixes will probably lag behind upstream. All because Golang devs decided the OpenSSH variant was "too weird". + +But, of course, not "weird" enough to https://github.com/golang/crypto/blob/3d872d042823aed41f28af3b13beb27c0c9b1e35/ssh/cipher.go#L652[not support the *wire* protocol^] for SSH. Just the key encryption. Because of course. And not publicly exposed either. Because *of course*. + +Assholes. + +== Why is the name so ugly? + +I couldn't think of a better one and I wanted something notably distinct from the stdlib-x naming. + +And module names can't include the `@` symbol. + +== Why don't you expose the rest of ChaCha20/Poly1305/ChaCha20-Poly1305? + +* To keep code changes from upstream light (and thus easier to debug, audit, etc.) +* Because otherwise the module name is inaccurate +** Because OpenSSH has their own specific variant +** Which means we can handle SSH-specific functionality if needed +* Because golang/x/crypto has made it painfully clear that if you want something that deviates from what they *think* is "best practice", you need to do it yourself +** Which ironically is something they also brand an "anti-pattern" which is just \*chef's kiss*