SaneCppLibraries release/2026/08

Platform Abstraction C++ Libraries

Release notes

[August 2026 Update Blog Post](https://pagghiu.github.io/site/blog/2026-08-31-SaneCppLibrariesUpdate.html)

# Cryptography

The biggest addition this month is the new
<a href="https://pagghiu.github.io/SaneCppLibraries/libraries/cryptography/">`Cryptography`</a> library.

It provides a small synchronous interface for secure random bytes, AES-GCM, HMAC, HKDF, and legacy AES-CBC with
PKCS#7 padding. Inputs and outputs are caller-owned spans, public objects keep provider state in fixed inline storage,
and the native implementation delegates primitive operations to the operating system instead of bundling a portable
cryptographic implementation.

The scope is intentionally narrow. This is a low-level primitive adapter, not a protocol library. It does not provide
password hashing, signatures, public-key cryptography, certificate validation, key storage, nonce allocation, or
protocol framing. AES-GCM is the preferred authenticated-encryption API; CBC remains available only for compatibility
with protocols that already specify the required authentication, IV, framing, and failure rules.

`Cryptography` is still Draft and has not received a formal cryptographic or side-channel audit. The implementation has
NIST known-answer vectors, mutation tests, deterministic stress coverage, and cross-platform CI, but those are not a
replacement for a security review. I want that boundary to stay visible while the API and backend coverage are still
evolving.

The AES-GCM coverage now also compares the native and OpenSSL backends directly. It exercises message and associated-data
boundary sizes, in-place operation, cross-backend decryption, and corrupted ciphertext, tags, and AAD. This catches
provider differences that known-answer vectors alone may not expose.

The API also makes provider capability discovery explicit. Applications query the active backend before selecting a
primitive instead of assuming that every algorithm is available just because the code compiled. This matters most on
Linux, where the native `AF_ALG` algorithms are runtime kernel capabilities rather than build-time guarantees.

**Detailed list of commits:**

- 30c307c2 Cryptography: Add native symmetric cryptography library
- 4aa30751 Cryptography: Add deterministic CBC streaming stress coverage
- 4c7ae30f Cryptography: Harden Draft contracts and test coverage
- 5e345569 Cryptography: Expose maximum AEAD associated data size in Features
- bc25f954 Cryptography: Distinguish Windows authentication failures from parameter errors
- 90e6bf5d Cryptography: Widen NIST GCM corpus and pin HMAC long-key behavior
- dfc0508f Cryptography: Add AES-GCM backend differential testing
- 33142803 Cryptography: Fix Windows build broken by ntstatus.h include
- 07b205d9 Cryptography: Complete Draft capability coverage
- 0bb57bb9 Cryptography: Add public umbrella header

# Native and OpenSSL Backends

The native backend uses the platform facilities already present on each operating system: CommonCrypto on Apple, CNG
on Windows, and `getrandom()` plus `AF_ALG` on Linux. The public API stays the same, while `queryFeatures()` reports
what the selected backend can actually provide in the running process.

AES-GCM took the most platform-specific work. Linux uses the kernel AEAD interface with a bounded associated-data
contract. Apple now has a narrowly scoped GCM composition over CommonCrypto AES because CommonCrypto does not expose a
public GCM interface. The implementation keeps that construction private and exercises both key sizes with shared NIST
vectors and corruption tests. Windows uses the native CNG authenticated-cipher path.

An optional OpenSSL 3 backend is also available on macOS, Windows, and Linux. It is selected explicitly and loaded at
runtime, so Sane C++ still has no OpenSSL header or link-time dependency. A missing or policy-restricted OpenSSL library
simply reports its features as unavailable and does not change the native backe…

Share this resource