change README from markdown (ew) to AsciiDoctor

This commit is contained in:
brent s. 2023-01-09 06:11:57 -05:00
parent fa5ef9f35e
commit c81edde7db
Signed by: bts
GPG Key ID: 8C004C2F93481F6B

50
README.adoc Normal file
View File

@ -0,0 +1,50 @@
= cc20p1305ssh
Brent Saner <bts@square-r00t.net>
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*