From 116f72af221d33e65e06d7fccf674f6a10ccac0e Mon Sep 17 00:00:00 2001 From: Dave Date: Wed, 22 Oct 2025 16:54:02 +0200 Subject: [PATCH] Add RFC references to algorithm tables --- README.md | 132 ++++++++++++++++++++++++++---------------------------- 1 file changed, 64 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 61cabe2..c09a1d5 100644 --- a/README.md +++ b/README.md @@ -27,103 +27,99 @@ go get github.com/AeonDave/cryptonite-go ### AEAD -| Algorithm | Constructor(s) | Key | Nonce | Tag | Notes | -|--------------------|------------------------------------------------|-------------|---------------------|------|------------------------------------------------------------------------------------------| -| ASCON-128a | `aead.NewAscon128()` | 16 B | 16 B | 16 B | NIST LwC winner | -| Xoodyak-Encrypt | `aead.NewXoodyak()` | 16 B | 16 B | 16 B | Cyclist mode | -| ChaCha20-Poly1305 | `aead.NewChaCha20Poly1305()` | 32 B | 12 B | 16 B | RFC 8439 layout | -| XChaCha20-Poly1305 | `aead.NewXChaCha20Poly1305()` | 32 B | 24 B | 16 B | Derives nonce via HChaCha20 | -| AES-GCM | `aead.NewAESGCM()` | 16/24/32 B | 12 B | 16 B | AES-NI optional | -| AES-GCM-SIV | `aead.NewAesGcmSiv()` | 16/32 B | 12 B | 16 B | Nonce misuse resistant | -| AES-SIV (128/256) | `aead.NewAES128SIV()`
`aead.NewAES256SIV()` | 32 B / 64 B | Deterministic (AAD) | 16 B | Deterministic SIV construction; optional multi-AD support via `aead.MultiAssociatedData` | -| Deoxys-II-256-128 | `aead.NewDeoxysII128()` | 32 B | 15 B | 16 B | NIST LwC finalist | +| Algorithm | Constructor(s) | Key | Nonce | Tag | Notes | RFC / Spec | +|--------------------|------------------------------------------------|-------------|---------------------|------|----------------------------------------------------------------------------------|------------| +| ASCON-128a | `aead.NewAscon128()` | 16 B | 16 B | 16 B | NIST LwC winner | [FIPS 208](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.208.pdf) | +| Xoodyak-Encrypt | `aead.NewXoodyak()` | 16 B | 16 B | 16 B | Cyclist mode | [Xoodyak specification](https://keccak.team/files/Xoodyak-specification.pdf) | +| ChaCha20-Poly1305 | `aead.NewChaCha20Poly1305()` | 32 B | 12 B | 16 B | RFC 8439 layout | [RFC 8439](https://www.rfc-editor.org/rfc/rfc8439.html) | +| XChaCha20-Poly1305 | `aead.NewXChaCha20Poly1305()` | 32 B | 24 B | 16 B | Derives nonce via HChaCha20 | [draft-irtf-cfrg-xchacha-03](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha-03) | +| AES-GCM | `aead.NewAESGCM()` | 16/24/32 B | 12 B | 16 B | AES-NI optional | [NIST SP 800-38D](https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf) | +| AES-GCM-SIV | `aead.NewAesGcmSiv()` | 16/32 B | 12 B | 16 B | Nonce misuse resistant | [RFC 8452](https://www.rfc-editor.org/rfc/rfc8452.html) | +| AES-SIV (128/256) | `aead.NewAES128SIV()`
`aead.NewAES256SIV()` | 32 B / 64 B | Deterministic (AAD) | 16 B | Deterministic SIV construction; optional multi-AD support via `aead.MultiAssociatedData` | [RFC 5297](https://www.rfc-editor.org/rfc/rfc5297.html) | +| Deoxys-II-256-128 | `aead.NewDeoxysII128()` | 32 B | 15 B | 16 B | NIST LwC finalist | [NIST LWC finalist spec](https://csrc.nist.gov/csrc/media/Projects/lightweight-cryptography/documents/finalists/deoxys-spec-final.pdf) | ### Hashing -Every hashing entry point lives under the `hash` package so callers can rely on the uniform `hash.Hasher` interface or -the Go `hash.Hash` type without importing algorithm-specific subpackages. +Every hashing entry point lives under the `hash` package so callers can rely on the uniform `hash.Hasher` interface or the Go `hash.Hash` type without importing algorithm-specific subpackages. -| Algorithm | Streaming constructor | Single-shot helper(s) | Notes | -|--------------|----------------------------|-------------------------------------------------|-----------------------------------------------------| -| SHA3-224 | `hash.NewSHA3224()` | `hash.NewSHA3224Hasher()` / `hash.Sum224` | 224-bit (28 B) digest | -| SHA3-256 | `hash.NewSHA3256()` | `hash.NewSHA3256Hasher()` / `hash.Sum256` | 256-bit (32 B) digest | -| SHA3-384 | `hash.NewSHA3384()` | `hash.NewSHA3384Hasher()` / `hash.Sum384` | 384-bit (48 B) digest | -| SHA3-512 | `hash.NewSHA3512()` | `hash.NewSHA3512Hasher()` / `hash.Sum512` | 512-bit (64 B) digest | -| BLAKE2b | `hash.NewBlake2b()` / `hash.NewBlake2bBuilder()` | `hash.NewBlake2bHasher()` | Configurable 1–64 B digest, optional keyed MAC mode | -| BLAKE2s | `hash.NewBlake2s()` / `hash.NewBlake2sBuilder()` | `hash.NewBlake2sHasher()` | Configurable 1–32 B digest, optional keyed MAC mode | -| Xoodyak Hash | `hash.NewXoodyak()` | `hash.NewXoodyakHasher()` / `hash.SumXoodyak()` | 32 B Cyclist hash | +| Algorithm | Streaming constructor | Single-shot helper(s) | Notes | RFC / Spec | +|--------------|------------------------------------------------|---------------------------------------------------------|---------------------------|------------| +| SHA3-224 | `hash.NewSHA3224()` | `hash.NewSHA3224Hasher()` / `hash.Sum224` | 224-bit (28 B) digest | [FIPS 202](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | +| SHA3-256 | `hash.NewSHA3256()` | `hash.NewSHA3256Hasher()` / `hash.Sum256` | 256-bit (32 B) digest | [FIPS 202](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | +| SHA3-384 | `hash.NewSHA3384()` | `hash.NewSHA3384Hasher()` / `hash.Sum384` | 384-bit (48 B) digest | [FIPS 202](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | +| SHA3-512 | `hash.NewSHA3512()` | `hash.NewSHA3512Hasher()` / `hash.Sum512` | 512-bit (64 B) digest | [FIPS 202](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | +| BLAKE2b | `hash.NewBlake2b()` / `hash.NewBlake2bBuilder()` | `hash.NewBlake2bHasher()` | Configurable 1–64 B digest, optional keyed MAC mode | [RFC 7693](https://www.rfc-editor.org/rfc/rfc7693.html) | +| BLAKE2s | `hash.NewBlake2s()` / `hash.NewBlake2sBuilder()` | `hash.NewBlake2sHasher()` | Configurable 1–32 B digest, optional keyed MAC mode | [RFC 7693](https://www.rfc-editor.org/rfc/rfc7693.html) | +| Xoodyak Hash | `hash.NewXoodyak()` | `hash.NewXoodyakHasher()` / `hash.SumXoodyak()` | 32 B Cyclist hash | [Xoodyak specification](https://keccak.team/files/Xoodyak-specification.pdf) | #### SP 800-185 constructions -| Algorithm | Helper(s) | Notes | -|-----------------------|----------------------------------------------------------------------------------------|-----------------------------------------------| -| TupleHash128 / 256 | `hash.TupleHash128(tuple, outLen, customization)` / `hash.TupleHash256` | Tuple of byte-strings, optional customization | -| ParallelHash128 / 256 | `hash.ParallelHash128(msg, blockSize, outLen, customization)` / `hash.ParallelHash256` | Parallel-friendly hashing for large messages | +| Algorithm | Helper(s) | Notes | RFC / Spec | +|-----------------------|----------------------------------------------------------------------------------------|----------------------------------------|------------| +| TupleHash128 / 256 | `hash.TupleHash128(tuple, outLen, customization)` / `hash.TupleHash256` | Tuple of byte-strings, optional customization | [NIST SP 800-185](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf) | +| ParallelHash128 / 256 | `hash.ParallelHash128(msg, blockSize, outLen, customization)` / `hash.ParallelHash256` | Parallel-friendly hashing for large messages | [NIST SP 800-185](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf) | ### XOF (Extendable-output function) -Constructors live under the dedicated `xof` package and return the shared `xof.XOF` interface so extendable-output -primitives can be swapped transparently. +Constructors live under the dedicated `xof` package and return the shared `xof.XOF` interface so extendable-output primitives can be swapped transparently. -| Algorithm | Constructor | Notes | -|-------------|------------------|--------------------------------------------| -| SHAKE128 | `xof.SHAKE128()` | Arbitrary-length output (FIPS 202) | -| SHAKE256 | `xof.SHAKE256()` | Wider security margin, arbitrary output | -| BLAKE2b XOF | `xof.Blake2b()` | Supports fixed-length and streaming output | -| BLAKE2s XOF | `xof.Blake2s()` | Lightweight XOF with keyed support | -| Xoodyak XOF | `xof.Xoodyak()` | Cyclist extendable-output mode | +| Algorithm | Constructor | Notes | RFC / Spec | +|-------------|------------------|--------------------------------------------|------------| +| SHAKE128 | `xof.SHAKE128()` | Arbitrary-length output (FIPS 202) | [FIPS 202](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | +| SHAKE256 | `xof.SHAKE256()` | Wider security margin, arbitrary output | [FIPS 202](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf) | +| BLAKE2b XOF | `xof.Blake2b()` | Supports fixed-length and streaming output | [BLAKE2 XOF](https://www.blake2.net/blake2x.pdf) | +| BLAKE2s XOF | `xof.Blake2s()` | Lightweight XOF with keyed support | [BLAKE2 XOF](https://www.blake2.net/blake2x.pdf) | +| Xoodyak XOF | `xof.Xoodyak()` | Cyclist extendable-output mode | [Xoodyak specification](https://keccak.team/files/Xoodyak-specification.pdf) | ### KDF (Key derivation function) -| Algorithm | Deriver constructor | Single-shot helper(s) | Notes | -|---------------------|------------------------------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------| -| HKDF-SHA256 | `kdf.NewHKDFSHA256()` | `kdf.HKDFSHA256()`
`kdf.HKDFSHA256Extract()`
`kdf.HKDFSHA256Expand()` | Max length 255 x 32 B (RFC 5869) | -| HKDF (generic hash) | `kdf.NewHKDF(func() hash.Hash)` | `kdf.HKDF()`
`kdf.HKDFExtractWith()`
`kdf.HKDFExpandWith()` | Length bound = 255 x hash.Size() | -| HKDF-BLAKE2b | `kdf.NewHKDFBlake2b()` | `kdf.HKDFBlake2b()` | 64 B digest variant | -| PBKDF2-SHA1 | `kdf.NewPBKDF2SHA1()` | `kdf.PBKDF2SHA1()`
`kdf.PBKDF2SHA1Into()` | See `kdf.CheckParams` for policy checks | -| PBKDF2-SHA256 | `kdf.NewPBKDF2SHA256()` | `kdf.PBKDF2SHA256()`
`kdf.PBKDF2SHA256Into()` | Iterations > 0; variable output length | -| Argon2id | `kdf.NewArgon2id()`
`kdf.NewArgon2idWithParams()` | `kdf.Argon2id()` | RFC 9106 Argon2id; defaults to time=1, memory=64 MiB, lanes=1 | -| scrypt | `kdf.NewScrypt(n, r, p)` | `kdf.Scrypt()` | RFC 7914 constraints on n,r,p; variable output length | +| Algorithm | Deriver constructor | Single-shot helper(s) | Notes | RFC / Spec | +|---------------------|------------------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------|------------| +| HKDF-SHA256 | `kdf.NewHKDFSHA256()` | `kdf.HKDFSHA256()`
`kdf.HKDFSHA256Extract()`
`kdf.HKDFSHA256Expand()` | Max length 255 × 32 B (RFC 5869) | [RFC 5869](https://www.rfc-editor.org/rfc/rfc5869.html) | +| HKDF (generic hash) | `kdf.NewHKDF(func() hash.Hash)` | `kdf.HKDF()`
`kdf.HKDFExtractWith()`
`kdf.HKDFExpandWith()` | Length bound = 255 × hash.Size() | [RFC 5869](https://www.rfc-editor.org/rfc/rfc5869.html) | +| HKDF-BLAKE2b | `kdf.NewHKDFBlake2b()` | `kdf.HKDFBlake2b()` | 64 B digest variant | [RFC 5869](https://www.rfc-editor.org/rfc/rfc5869.html) | +| PBKDF2-SHA1 | `kdf.NewPBKDF2SHA1()` | `kdf.PBKDF2SHA1()`
`kdf.PBKDF2SHA1Into()` | See `kdf.CheckParams` for policy checks | [RFC 8018](https://www.rfc-editor.org/rfc/rfc8018.html) | +| PBKDF2-SHA256 | `kdf.NewPBKDF2SHA256()` | `kdf.PBKDF2SHA256()`
`kdf.PBKDF2SHA256Into()` | Iterations > 0; variable output length | [RFC 8018](https://www.rfc-editor.org/rfc/rfc8018.html) | +| Argon2id | `kdf.NewArgon2id()`
`kdf.NewArgon2idWithParams()` | `kdf.Argon2id()` | RFC 9106 Argon2id; defaults to time=1, memory=64 MiB, lanes=1 | [RFC 9106](https://www.rfc-editor.org/rfc/rfc9106.html) | +| scrypt | `kdf.NewScrypt(n, r, p)` | `kdf.Scrypt()` | RFC 7914 constraints on n,r,p; variable output length | [RFC 7914](https://www.rfc-editor.org/rfc/rfc7914.html) | ### MAC (Message authentication code) -| Algorithm | Entry points | Key | Tag | Notes | -|-------------|-------------------------------------------------------------------------|-----------------|------|-------------------------------------| -| HMAC-SHA256 | `mac.Sum(key, data)`
`mac.Verify(key, data, tag)` | Any length | 32 B | Single-shot helpers over SHA-256 | -| Poly1305 | `mac.NewPoly1305(key)`
`mac.SumPoly1305()`
`mac.VerifyPoly1305()` | 32 B (one-time) | 16 B | One-time key per message (RFC 7539) | +| Algorithm | Entry points | Key | Tag | Notes | RFC / Spec | +|-------------|-------------------------------------------------------------------------|-----------------|------|-----------------------------|------------| +| HMAC-SHA256 | `mac.Sum(key, data)`
`mac.Verify(key, data, tag)` | Any length | 32 B | Single-shot helpers over SHA-256 | [RFC 2104](https://www.rfc-editor.org/rfc/rfc2104.html) | +| Poly1305 | `mac.NewPoly1305(key)`
`mac.SumPoly1305()`
`mac.VerifyPoly1305()` | 32 B (one-time) | 16 B | One-time key per message (RFC 7539) | [RFC 7539](https://www.rfc-editor.org/rfc/rfc7539.html) | ### Stream ciphers -`stream.NewChaCha20` and `stream.NewXChaCha20` expose the shared `stream.Stream` interface (with `Reset`, `KeyStream`, -and `XORKeyStream`) so applications can swap keystream generators without touching call sites. +`stream.NewChaCha20` and `stream.NewXChaCha20` expose the shared `stream.Stream` interface (with `Reset`, `KeyStream`, and `XORKeyStream`) so applications can swap keystream generators without touching call sites. -| Algorithm | Constructor | Key | Nonce | Notes | -|-----------|-------------------------|------|-------|---------------------------------------------| -| ChaCha20 | `stream.NewChaCha20()` | 32 B | 12 B | IETF variant with configurable counter | -| XChaCha20 | `stream.NewXChaCha20()` | 32 B | 24 B | HChaCha20-derived subkeys and raw keystream | +| Algorithm | Constructor | Key | Nonce | Notes | RFC / Spec | +|-----------|-------------------------|------|-------|---------------------------------------------|------------| +| ChaCha20 | `stream.NewChaCha20()` | 32 B | 12 B | IETF variant with configurable counter | [RFC 8439](https://www.rfc-editor.org/rfc/rfc8439.html) | +| XChaCha20 | `stream.NewXChaCha20()` | 32 B | 24 B | HChaCha20-derived subkeys and raw keystream | [draft-irtf-cfrg-xchacha-03](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha-03) | ### Block ciphers -Block primitives are instantiated through `block.NewAES128` / `block.NewAES256`, both returning the shared -`block.Cipher` interface. +Block primitives are instantiated through `block.NewAES128` / `block.NewAES256`, both returning the shared `block.Cipher` interface. -| Algorithm | Constructor | Key | Block | Notes | -|-----------|---------------------|------|-------|------------------------------| -| AES-128 | `block.NewAES128()` | 16 B | 16 B | Thin wrapper over stdlib AES | -| AES-256 | `block.NewAES256()` | 32 B | 16 B | Thin wrapper over stdlib AES | +| Algorithm | Constructor | Key | Block | Notes | RFC / Spec | +|-----------|---------------------|------|-------|------------------------------|------------| +| AES-128 | `block.NewAES128()` | 16 B | 16 B | Thin wrapper over stdlib AES | [FIPS 197](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197.pdf) | +| AES-256 | `block.NewAES256()` | 32 B | 16 B | Thin wrapper over stdlib AES | [FIPS 197](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.197.pdf) | ### Signatures (ECDSA, EdDSA) -| Algorithm | Constructor(s) | Public | Private | Signature | Notes | -|-------------|----------------------|---------------------|-------------|----------------------|---------------------------------------------------------------------------------| -| Ed25519 | `sig.NewEd25519()` | 32 B | 64 B | 64 B | Deterministic; `sig.FromSeed(32 B)` supported | -| ECDSA P-256 | `sig.NewECDSAP256()` | 65 B (uncompressed) | 32 B scalar | ASN.1 DER (variable) | Helpers: `sig.GenerateKeyECDSAP256`, `sig.SignECDSAP256`, `sig.VerifyECDSAP256` | +| Algorithm | Constructor(s) | Public | Private | Signature | Notes | RFC / Spec | +|-------------|----------------------|---------------------|-------------|----------------------|--------------------------------------------------------|------------| +| Ed25519 | `sig.NewEd25519()` | 32 B | 64 B | 64 B | Deterministic; `sig.FromSeed(32 B)` supported | [RFC 8032](https://www.rfc-editor.org/rfc/rfc8032.html) | +| ECDSA P-256 | `sig.NewECDSAP256()` | 65 B (uncompressed) | 32 B scalar | ASN.1 DER (variable) | Helpers: `sig.GenerateKeyECDSAP256`, `sig.SignECDSAP256`, `sig.VerifyECDSAP256` | [FIPS 186-5](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf) | -| Algorithm | Constructor | Public | Private | Shared | Notes | -|-----------|------------------|---------------------|-------------|--------|---------------------------| -| X25519 | `ecdh.New()` | 32 B | 32 B | 32 B | RFC 7748 (crypto/ecdh) | -| P-256 | `ecdh.NewP256()` | 65 B (uncompressed) | 32 B scalar | 32 B | Uncompressed public: 0x04 || X || Y | -| P-384 | `ecdh.NewP384()` | 97 B (uncompressed) | 48 B scalar | 48 B | Uncompressed public: 0x04 || X || Y | +| Algorithm | Constructor | Public | Private | Shared | Notes | RFC / Spec | +|-----------|------------------|---------------------|-------------|--------|-----------------------------------------|------------| +| X25519 | `ecdh.New()` | 32 B | 32 B | 32 B | RFC 7748 (crypto/ecdh) | [RFC 7748](https://www.rfc-editor.org/rfc/rfc7748.html) | +| P-256 | `ecdh.NewP256()` | 65 B (uncompressed) | 32 B scalar | 32 B | Uncompressed public: 0x04 \|\| X \|\| Y | [FIPS 186-5](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf) | +| P-384 | `ecdh.NewP384()` | 97 B (uncompressed) | 48 B scalar | 48 B | Uncompressed public: 0x04 \|\| X \|\| Y | [FIPS 186-5](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf) | ### Post-quantum key encapsulation