cryptonite-go

Cryptonite-go

Modern, ultra-fast, zero-dependency cryptography library for Go 1.22+ Implemented using only the standard library. Battle-tested primitives, minimal attack surface, ergonomic APIs.

Overview

• Small and auditable: pure Go, no third-party dependencies.
• Reduced attack surface: shared, tested internal primitives and minimal cross-package APIs.
• Consistent, ergonomic interfaces: uniform AEAD, hashing, KDF, signature, and ECDH APIs for easy composition.
• Practical security defaults: spec-aligned choices, selective zeroisation of sensitive buffers, constant-time behavior where required.
• Robust test coverage and regression protection: known-answer tests, Wycheproof-inspired suites, and fuzzing harnesses.
• Interoperability for real-world use: implements widely used constructions without exposing low-level implementation details.

Requirements

• Go 1.22+

Installation

go get github.com/AeonDave/cryptonite-go

Supported Algorithms

AEAD (Authenticated Encryption)

• Mainstream: AES-GCM, ChaCha20-Poly1305, XChaCha20-Poly1305, AES-GCM-SIV
• Lightweight: ASCON-128a/80pq (NIST winner), Xoodyak, GIFT-COFB, SKINNY, Deoxys-II
• Nonce-misuse resistant: AES-SIV, AES-GCM-SIV

Hashing & XOF

• Fast: BLAKE2b/s (742 MB/s), SHA-3 family
• Streaming: SHAKE128/256, BLAKE2 XOF, Xoodyak
• Specialized: TupleHash, ParallelHash (SP 800-185)

Key Derivation (KDF)

• Modern: HKDF-SHA256/BLAKE2b, Argon2id, scrypt
• Password: PBKDF2-SHA1/SHA256

MAC & Stream Ciphers

• MAC: HMAC-SHA256, Poly1305 (3+ GB/s)
• Stream: ChaCha20, XChaCha20, AES-CTR

Public Key Crypto

• Signatures: Ed25519, ML-DSA-44/65/87 (Dilithium), ECDSA P-256
• Key Exchange: X25519, X448, ECDH P-256/P-384
• KEM: ML-KEM-512/768/1024 (Kyber) via pq.NewMLKEM*
• Hybrid: X25519 + ML-KEM builders (pq.NewHybridX25519MLKEM*)

Full algorithm matrix with specs: See docs/ALGORITHMS.md

API Quick Start

Authenticated Encryption (ASCON-128a)

package main

import (
    "fmt"
    "github.com/AeonDave/cryptonite-go/aead"
)

func main() {
    cipher := aead.NewAscon128()
    key := make([]byte, 16)
    nonce := make([]byte, 16)
    
    ciphertext, _ := cipher.Encrypt(key, nonce, []byte("header"), []byte("secret data"))
    plaintext, _ := cipher.Decrypt(key, nonce, []byte("header"), ciphertext)
    
    fmt.Println(string(plaintext)) // "secret data"
}

Hashing (BLAKE2b)

import "github.com/AeonDave/cryptonite-go/hash"

hasher := hash.NewBlake2bHasher()
digest := hasher.Hash([]byte("hello world"))
fmt.Printf("%x\n", digest)

Key Exchange (X25519 / X448)

import "github.com/AeonDave/cryptonite-go/ecdh"

x25519 := ecdh.NewX25519()
x448 := ecdh.NewX448()
alicePriv, _ := x25519.GenerateKey()
bobPriv, _ := x25519.GenerateKey()

aliceShared, _ := x25519.SharedSecret(alicePriv, bobPriv.PublicKey())
bobShared, _ := x25519.SharedSecret(bobPriv, alicePriv.PublicKey())
// aliceShared == bobShared

// X448 exposes the same API for higher security deployments.
alice448, _ := x448.GenerateKey()
bob448, _ := x448.GenerateKey()
shared448, _ := x448.SharedSecret(alice448, bob448.PublicKey())

Digital Signatures (Ed25519)

import "github.com/AeonDave/cryptonite-go/sig"

pub, priv, _ := sig.GenerateKey()
signature := sig.Sign(priv, []byte("message"))
valid := sig.Verify(pub, []byte("message"), signature)

Post-Quantum Signatures (ML-DSA-44 / Dilithium-2)

import "github.com/AeonDave/cryptonite-go/sig"

scheme := sig.NewMLDSA44()
pub, priv, _ := scheme.GenerateKey()
signature, _ := scheme.Sign(priv, []byte("message"))
valid := scheme.Verify(pub, []byte("message"), signature)

For deterministic signing (useful for KAT/interop), replace sig.NewMLDSA44() with sig.NewDeterministicMLDSA44() or derive keys from a fixed 32-byte seed via sig.GenerateDeterministicKeyMLDSA44(seed).

Post-Quantum KEM (ML-KEM-768 / Kyber-768)

import "github.com/AeonDave/cryptonite-go/pq"

kem := pq.NewMLKEM768()
pk, sk, _ := kem.GenerateKey()
ciphertext, shared1, _ := kem.Encapsulate(pk)
shared2, _ := kem.Decapsulate(sk, ciphertext)
// shared1 == shared2

hybrid := pq.NewHybridX25519MLKEM768()
hybridPK, hybridSK, _ := hybrid.GenerateKey()
ct, combined, _ := hybrid.Encapsulate(hybridPK)
recovered, _ := hybrid.Decapsulate(hybridSK, ct)
// combined == recovered

Running tests

• All tests: go test ./...
• With race detector: go test -race ./...
• ML-KEM / ML-DSA KATs: go test ./test/pq -run TestMLKEMKAT and go test ./test/sig -run TestMLDSAKAT

Tests include KAT suites for ASCON, Xoodyak, ChaCha20‑Poly1305, AES-GCM-SIV, and AES-SIV (RFC 5297), plus tamper checks on tags and ciphertext.

Benchmarks

Benchmark environment: AMD Ryzen 7, Go 1.22+, -benchmem

Highlights:

• Zero allocations on hot paths (AES, ChaCha20, signature verify)
• Hardware acceleration (AES-NI) when available
• Competitive with specialized C libraries

These commands exercise the encryption/decryption, hashing, KDF, MAC, stream, block, signature, ECDH, HPKE, post-quantum, and secret-management benchmarks added alongside the existing test vectors.

Symmetric protection remains classical (AEAD); only the key agreement layer is made hybrid/PQ-ready following the recommendations from draft-ietf-tls-hybrid-design.

Full benchmarks: benchmark.md Run locally:

go test ./test/... -bench=. -benchmem

# Focused ML-KEM profiling
go test ./test/pq -bench=BenchmarkMLKEM -benchmem

On Windows PowerShell, quote the empty test pattern with double quotes:

go test ./test/... -run="^$" -bench . -benchmem -count=1

Security

Guarantees

• Constant-time operations where required (Poly1305, X25519, Ed25519)
• Automatic key/nonce zeroization via secret package helpers
• Wycheproof test vectors + fuzzing harnesses
• No CGO → reduced supply chain risk

Limitations

• This library has NOT been independently audited. Even though it is deployed in production, perform thorough internal review and threat modeling before upgrading or integrating it into new systems.
• Nonce management: Caller responsible for uniqueness (use secret.NewNonce() or counters)
• Side channels: Best-effort mitigation; validate in your threat model
• Algorithm selection: Some primitives are experimental (e.g., GIFT-COFB) – prefer mainstream options (AES-GCM, ChaCha20) unless you need specific properties

Reporting Issues

Security vulnerabilities: open a private advisory via GitHub.
See SECURITY.md for full policy.

Documentation

• API Docs: pkg.go.dev/github.com/AeonDave/cryptonite-go
• Guides:
  • Algorithm Matrix – full specs & references
  • Nonce Management – avoid reuse, counters, random generation
  • HPKE Usage – hybrid public key encryption
  • Post-Quantum – hybrid X25519+ML-KEM guide
  • Interoperability – wire formats, encodings, gotchas
• Testing: docs/TESTING.md – KAT, fuzzing, adding test vectors

Contributing

Contributions welcome! Please:

1. Run tests: go test -race ./...
2. Check formatting: go fmt ./... + golangci-lint run
3. Add vectors: Include KAT for new algorithms (see CONTRIBUTING.md)
4. Benchmark: go test ./test/... -bench=YourFunc -benchmem

See CONTRIBUTING.md for full guidelines.

License

MIT – see LICENSE

If you find this useful, star the repo! | Questions? Open an issue.