All notable changes are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
- Ed25519 signatures:
GenerateEd25519,SignEd25519,VerifyEd25519for asymmetric (public-key) signing. - Asymmetric encryption (sealed-box style):
GenerateKeyPair,SealAsymmetric,OpenAsymmetricusing X25519 ECDH + ChaCha20-Poly1305. Anonymous-sender semantics; sign with Ed25519 first if you need sender authentication. Wire format version 0x05. - KMS adapter interface:
KMSinterface (GenerateDataKey,Decrypt,Encrypt) andEnvelopeSealerfor envelope encryption (per-row DEK wrapped under a KMS-managed KEK). Wire format version 0x06. - In-memory
StaticKMSadapter for dev and tests.
- Streaming AEAD:
SealStream/OpenStreamfor chunked file encryption with truncation detection. Each chunk binds its position and final-flag into AAD. - Time-locked tokens:
IssueToken/VerifyTokenwith embedded expiry. Stateless one-time tokens for password reset, email verify, magic login. ReturnsErrExpiredon expiry.
- HKDF key derivation:
DeriveKey(SHA-256) for per-tenant or per-purpose sub-keys from a master key. - KeyRing for rotation:
NewKeyRing,Add,Remove,SetActive,ActiveKid. Wire format version 0x03 with embedded kid; old v1 ciphertexts still readable via try-each fallback. - ChaCha20-Poly1305 AEAD:
SealChaCha20/OpenChaCha20for non-AES-NI hardware. Wire format version 0x02. - Bcrypt password hashing:
HashPasswordBcrypt/VerifyPasswordBcryptfor compatibility with systems migrating from bcrypt. MarkedDeprecated; new code should use argon2idHashPassword.
- AEAD authenticated encryption with AES-256-GCM:
Seal,Open,Sealer,NewSealer. AAD support for context binding. Wire format version 0x01. - Argon2id password hashing:
HashPassword,VerifyPasswordwith PHC-format output. - HMAC signing:
Sign(HMAC-SHA256),Verify(constant-time),ConstantTimeEqualwrapper. - Random helpers:
RandomBytes,RandomToken(URL-safe base64 no-pad),RandomHex. - AES-CBC as a first-class peer of AES-GCM —
EncryptCBC/DecryptCBCfor interop with existing CBC systems (PHP/Java/Python) or reading ciphertext your application already wrote in this format. No built-in authentication; pair with HMAC if needed. - Migration helper at
crypt.OpenAutofor transitional reads across formats. - Cross-language test vectors at
testdata/vectors.jsonshared with the TypeScript counterpart crypt-ts. - Sentinel errors:
ErrInvalidKey,ErrTampered,ErrUnsupportedVersion,ErrInvalidCiphertext,ErrInvalidPasswordHash,ErrTruncated,ErrExpired, etc. - Documentation:
USAGE.md,SECURITY.md,WIRE_FORMAT.md,MIGRATION.md,RECIPES.md,FAQ.md,BENCHMARKS.md. - Runnable examples in
examples/covering encryption-at-rest, magic links, session tokens, webhook signing, encrypted cookies, CSRF tokens, key rotation, audit log integrity, file encryption, API key checks, per-tenant HKDF, cross-language interop.
Cipher,New,Cipher.Encrypt,Cipher.Decrypt— v0.x type-based string-input wrappers. Use the byte-typedEncryptCBC/DecryptCBCdirectly.EncryptWithKey/DecryptWithKey— same v0.x string-typed wrappers. Use byte-typed forms.
(Note: EncryptCBC and DecryptCBC themselves are NOT deprecated — they are first-class peers of Seal / Open. Only the older string-typed wrappers are.)