# Changelog

## 2026-03-17

---

### Added

- Added AES-XTS and SM4-XTS APIs in `symm` and root wrappers:
  - bytes APIs: `Encrypt*/Decrypt*XTS`
  - data-unit indexed APIs: `Encrypt*/Decrypt*XTSAt`
  - stream APIs: `Encrypt*/Decrypt*XTSStream`
  - stream + data-unit indexed APIs: `Encrypt*/Decrypt*XTSStreamAt`
- Added XTS master-key split helpers:
  - `SplitXTSMasterKey`
  - `SplitAesXTSMasterKey`
  - `SplitSM4XTSMasterKey`
- Added XTS parameter validation and explicit no-CTS behavior:
  - dual keys must be non-empty and equal length
  - `dataUnitSize` must be a positive multiple of 16
  - non-stream input must be 16-byte aligned
  - stream tail must be 16-byte aligned
- Added key-derivation APIs in `hashx` and root wrappers:
  - `DerivePBKDF2SHA256Key` (`crypto/pbkdf2`, stdlib)
  - `DerivePBKDF2SHA512Key` (`crypto/pbkdf2`, stdlib)
  - `DeriveArgon2idKey` / `DeriveArgon2iKey` (`golang.org/x/crypto/argon2`)
  - `Argon2Params` + `DefaultArgon2idParams`
- Added benchmark coverage for symmetric hot paths:
  - AES/SM4 `GCM`, `CCM`, `XTS`
  - AES/SM4 `XTS` stream path
- Added file random fill APIs:
  - `FillWithRandom` (math/rand pseudo-random)
  - `FillWithCryptoRandom` (crypto/rand secure random, may be slower)
- Added HMAC verify APIs (bytes + hex wrappers) in `macx` and root package.
- Added XTS standard-vector tests (IEEE P1619 subset) and XTS fuzz tests.
- Added CCM/XTS related test coverage for root wrappers and `symm`.

### Changed

- Refactored XTS internals to reduce duplication via shared factory/path.
- Switched AEAD options behavior to require explicit `Nonce` (no `IV` fallback in GCM/CCM paths).
- Reworked CFB-8 register update to ring-buffer state handling.
- Refined `README.md` structure and added:
  - XTS usage/constraints documentation
  - AEAD nonce non-reuse requirement
  - AEAD `CipherOptions` nonce-only behavior note
  - legacy GCM/CCM stream decryption memory warning
  - `FillWithRandom` vs `FillWithCryptoRandom` guidance
  - XTS `dataUnitIndex` mapping consistency note

## Unreleased

### Added
- Introduced subpackages and root wrappers:
  - `asymm`, `symm`, `hashx`, `encodingx`, `paddingx`, `filex`, `legacy`, `macx`.
- Added Chinese `README.md` and Apache-2.0 `LICENSE`.
- Added `SM9` support in asymmetric APIs.
- Added `ChaCha20` and `ChaCha20-Poly1305` APIs (memory + stream wrappers where applicable).
- Added unified symmetric cipher options API:
  - `CipherOptions{Mode, Padding, IV, Nonce, AAD}`.
- Added AEAD APIs and wrappers:
  - `AES-GCM`, `SM4-GCM`, `AES-CCM`, `SM4-CCM` (bytes + chunk + stream helper APIs).
- Added more symmetric mode coverage for SM4:
  - `ECB/CBC/CFB/OFB/CTR` (bytes + stream derived APIs).
- Added comprehensive tests across packages and root wrappers.
- Added fuzz tests for `paddingx`, `encodingx`, and `symm` round-trip invariants.

### Changed
- Refactored monolithic implementation to subpackage architecture while preserving root-package convenience APIs.
- AES mode APIs now support generic mode selection and derived mode helpers.
- Stream APIs expanded across AES/SM4/DES/3DES and ChaCha20.
- Updated docs to include a security-first recommendation and algorithm capability matrix.
- Updated dependencies and modules for current code paths (`gmsm`, `x/crypto`).
- Refactored duplicated AES/SM4 symmetric code paths by extracting shared dispatch/helpers in `symm`.
- Unified hash method validation semantics: `hashx.SumAll` and `hashx.FileSumAll` now return errors for unknown methods (aligned with `FileSum`).
- Updated `hashx` tests for unsupported-method behavior.

### Fixed
- Fixed Base128 encode/decode round-trip bug in `encodingx`.
- Corrected CRC32A test expectations and clarified CRC32A variant comments.
- Corrected default padding behavior for AES-CBC to PKCS7.

### Notes
- Legacy/insecure algorithms and modes remain available for compatibility.
- Production recommendations now explicitly prefer AEAD schemes.