releasing key guide under CC 4.0 BY-SA

cipher/chacha20/poly1305/TODO

@@ -1 +1,14 @@
 TODO
+
+I need to fork out the chacha20-poly1305 pkg from golang x-stdlib
+(
+	https://pkg.go.dev/golang.org/x/crypto/chacha20poly1305
+	https://cs.opensource.google/go/x/crypto/+/master:chacha20poly1305/
+	https://github.com/golang/go/issues/36646
+)
+because they explicitly do NOT support the chacha20-poly1305 OpenSSH variant (chacha20-poly1305@openssh.com)
+(https://github.com/golang/go/issues/36646#issue-552055939
+"and there is exactly one widely used (or otherwise) composition:
+ ChaCha20Poly1305 as implemented by x/crypto/chacha20poly1305 (or by SSH in their weird variant)"
+
+sidenote, this is the same guy that decided it would be a good idea to deprecate golang x-stdlib gpg).

cipher/chacha20/poly1305/consts.go

@@ -1,5 +1,6 @@
 package poly1305
 
 const (
-	Name string = "chacha20-poly1305@openssh.com"
+	Name      string = "chacha20-poly1305@openssh.com"
+	BlockSize int    = 8
 )

cipher/chacha20/poly1305/funcs.go

@@ -4,8 +4,7 @@ import (
 	`bytes`
 	`io`
 
-	`r00t2.io/sshkeys/cipher/aes`
-	`r00t2.io/sshkeys/cipher/aes/aes128`
+	`r00t2.io/cc20p1305ssh`
 	`r00t2.io/sshkeys/internal`
 )
 
@@ -39,7 +38,7 @@ func (c *Cipher) NameBytes() (name []byte) {
 // BlockSize returns the blocksize of this Cipher.
 func (c *Cipher) BlockSize() (size int) {
 
-	size = aes.BlockSize
+	size = BlockSize
 
 	return
 }
@@ -47,7 +46,7 @@ func (c *Cipher) BlockSize() (size int) {
 // KdfKeySize returns the target key length from KDF to use with this Cipher.
 func (c *Cipher) KdfKeySize() (size int) {
 
-	size = aes128.KeySize
+	size = cc20p1305ssh.KeySize
 
 	return
 }

cipher/chacha20/poly1305/types.go

@@ -1,5 +1,22 @@
 package poly1305
 
+/*
+	Cipher is a ChaCha20-Poly1305 (OpenSSH variant) cipher.Cipher.
+
+	In the OpenSSH variant (for *key* encryption), only the first
+	32 bytes is used from the 64-byte key as generated from ChaCha20.
+
+	It then proceeds per https://datatracker.ietf.org/doc/html/rfc8439#section-2.8
+	except:
+
+		* The nonce used is a constant of 16 zero bytes
+		* There is no additional authenticated data
+		* The Poly1305 authentication tag is generated via a message
+		  that consists *only* of the ciphertext.
+		  In other words, OpenSSH does *not* add padding or
+		  encode message lengths to generate the Poly1305
+		  authentication tag.
+*/
 type Cipher struct {
 	Key []byte
 }