`core.security` — overview

The core.security subtree is Verum's consolidated security layer. Everything every other module touches for authentication, authorisation, confidentiality, integrity, or information-flow control routes through it. There are no parallel crypto stacks, nor shortcut FFI wrappers — the layer below TLS, QUIC, SPIFFE, gRPC tokens, and application-level AEAD tokens is the same code.

Design principles

1. Single horizontal layer, zero duplication

The guiding architectural decision: crypto primitives live once, in core.security, and are consumed by every protocol. When a QUIC packet needs AEAD, it calls the same aead.chacha20_poly1305 that TLS 1.3's record layer uses, and the same that the application itself can use to seal a cookie.

If you find yourself wanting to wrap a different crypto library for "just this one use case", it's a bug. Open an issue.

All key and nonce types are fixed-size byte arrays. AesKey128 is [Byte; 16], AesKey256 is [Byte; 32], ChaChaKey is [Byte; 32], every AEAD nonce is [Byte; 12] (RFC 8446 / RFC 9001 convention). Mis-sized keys or nonces are a type error, not a runtime condition. Nonce-reuse bugs that haunt cipher APIs in other ecosystems are made structurally harder to write.

3. Constant-time by construction — with hardware accel for perf

Every primitive in this layer is constant-time at the algorithm level. Reference implementations use:

no data-dependent branches on secret data;
no memory accesses indexed by secret bytes (with the noted exception of AES, which uses S-box lookups — see cipher);
fixed-count iterations;
constant-time comparisons via util.constant_time_eq.

For production throughput, every hot path has a @cfg(feature = "crypto-accel") substitution point that binds to hardware primitives (AES-NI, VAES-512, SHA-NI, PCLMULQDQ, ARMv8 Crypto Extensions). Reference code remains available and is differentially tested against the accelerated path via property tests in vcs/specs/L1-core/security/.

4. Production-first, standards-aligned

Every primitive cites its authoritative standard in the module header and matches its published test vectors bit-exact:

FIPS 180-4 (SHA-2 family)
FIPS 197 (AES)
NIST SP 800-38D (AES-GCM)
NIST FIPS 203 / 204 / 205 (ML-KEM / ML-DSA / SLH-DSA post-quantum)
RFC 2104 (HMAC), 4231 (HMAC test vectors)
RFC 5869 (HKDF)
RFC 7748 (Curve25519 / X25519)
RFC 8032 (Ed25519)
RFC 8439 (ChaCha20-Poly1305)
RFC 8446 (TLS 1.3), 9001 (QUIC), 9113 (HTTP/2)
RFC 9381 (ECVRF — Verifiable Random Function)
IETF draft-irtf-cfrg-bls-signature (BLS12-381 signatures + threshold aggregation)
IETF draft-irtf-cfrg-pairing-friendly-curves (BLS12-381 parameter pinning)
BLAKE3 specification (O'Connor / Aumasson / Neves / Wilcox-O'Hearn 2020)
Halo2 specification (Zcash Foundation, builds on Bowe / Grigg / Hopwood 2019)
Ben-Sasson et al. STARK + FRI (2018)

Module map

The tree below maps to core/security/ exactly — every filename is linked to a dedicated documentation page.

core/security/
├── hash/
│   ├── sha256.vr       — SHA-256 (FIPS 180-4 §6.2)
│   ├── sha384.vr       — SHA-384 (FIPS 180-4 §6.5)
│   ├── sha512.vr       — SHA-512 (FIPS 180-4 §6.4)
│   └── blake3.vr       — BLAKE3 streaming + XOF + keyed_hash + derive_key
├── mac/
│   ├── hmac.vr         — HMAC-SHA-{256, 384, 512}
│   └── poly1305.vr     — Poly1305 one-time MAC
├── kdf/
│   └── hkdf.vr         — HKDF-{SHA-256, SHA-384, SHA-512}
├── cipher/
│   ├── aes.vr          — AES-128 / AES-256 block cipher
│   └── chacha20.vr     — ChaCha20 stream cipher
├── aead/
│   ├── aes_gcm.vr      — AES-128-GCM / AES-256-GCM AEAD
│   └── chacha20_poly1305.vr — ChaCha20-Poly1305 AEAD
├── ecc/
│   ├── ed25519.vr      — Ed25519 signatures (RFC 8032)
│   ├── p256.vr         — NIST P-256 (FIPS 186-4)
│   ├── x25519.vr       — Curve25519 ECDH (RFC 7748)
│   ├── vrf.vr          — ECVRF-EDWARDS25519-SHA512-TAI (RFC 9381)
│   └── bls12_381.vr    — BLS12-381 pairing curve, threshold + aggregate sigs
├── pq/
│   ├── ml_kem.vr       — ML-KEM-512/768/1024 (FIPS 203)
│   ├── ml_dsa.vr       — ML-DSA (FIPS 204)
│   └── sphincs_plus.vr — SLH-DSA / SPHINCS+ (FIPS 205) — 12 parameter sets
├── zk/
│   ├── halo2/          — Halo2 + KZG10 (Plonk-style over BLS12-381)
│   │   ├── circuit.vr  —   circuit DSL (Column / Selector / Gate / Lookup)
│   │   ├── srs.vr      —   universal SRS + ceremony
│   │   ├── prover.vr   —   precompute + prove + prove_with_aux
│   │   └── verifier.vr —   verify + verify_batch
│   └── stark/          — STARK + FRI (PQ-secure, transparent setup)
│       ├── air.vr      —   AIR DSL (Expr / TransitionConstraint / BoundaryConstraint)
│       ├── prover.vr   —   prove
│       └── verifier.vr —   AirVk + verify + verify_batch
├── util/
│   └── constant_time.vr — constant-time compare, zeroise
├── spiffe/
│   ├── id.vr           — SPIFFE URI parsing
│   ├── svid.vr         — X.509-SVID + JWT-SVID types
│   └── workload_api.vr — SPIRE client
├── secrets/
│   ├── core_protocol.vr — Secrets-backend abstraction
│   ├── aws.vr          — AWS Secrets Manager
│   ├── gcp.vr          — GCP Secret Manager
│   └── vault.vr        — HashiCorp Vault
├── labels.vr           — Information-flow labels (IFC)
└── regions.vr          — Region-based isolation

Documentation map

Cryptographic primitives

hash — SHA-256/384/512 + BLAKE3 (streaming, XOF, keyed, derive_key)
mac — HMAC-SHA-family + Poly1305
kdf — HKDF (Extract/Expand)
cipher — AES, ChaCha20
aead — AES-GCM, ChaCha20-Poly1305
ecc — Ed25519, P-256, X25519, ECVRF (RFC 9381), BLS12-381 (pairing + threshold sigs)
pq — ML-KEM, ML-DSA, SPHINCS+ post-quantum
zk — Halo2 + KZG10 (BLS12-381) and STARK + FRI (PQ-secure)
util — constant-time ops, zeroise, RNG

Identity, secrets, policy

spiffe — workload identity (SPIFFE/SPIRE)
secrets — cloud / Vault secrets backends
labels — information-flow labels + lattice
regions — region-based isolation
capabilities — @cap, declassification

TLS 1.3 / QUIC cipher-suite coverage

This matrix is the concrete justification of the "single horizontal layer" claim. Every TLS 1.3 cipher-suite that QUIC negotiates is implementable with modules from this subtree alone.

Cipher-suite	Hash	KDF	AEAD	KEX
`TLS_AES_128_GCM_SHA256`	`sha256`	`hkdf_sha256`	`aes_gcm-128`	`x25519`
`TLS_AES_256_GCM_SHA384`	`sha384`	`hkdf_sha384`	`aes_gcm-256`	`x25519`
`TLS_CHACHA20_POLY1305_SHA256`	`sha256`	`hkdf_sha256`	`chacha20_poly1305`	`x25519`
`X25519MLKEM768` (PQ hybrid)	—	—	—	`x25519` + `ml_kem-768`

Threat model and what the layer does NOT cover

Endpoint compromise. If the process has been compromised, nothing this library does prevents key theft. Use hardware-backed keystores for high-value keys (platform KMS, HSM via secrets).
Physical side channels. Power analysis, electromagnetic emanations, acoustic attacks are out of scope. If you need resistance against those, run your secrets inside a TEE (Intel SGX / TDX, AMD SEV-SNP, ARM CCA). The library's constant-time discipline protects against timing side channels only.
Cryptanalytic breaks. When a primitive is broken, the library's mitigation is to flag deprecation via a compile-time warning in the next release and to provide a migration path. Downstream protocols with public configs (TLS 1.3 cipher-suite negotiation) remove the broken primitive from their defaults while leaving it available under an explicit opt-in flag.
Misuse of one-time keys. Poly1305's security depends on the MAC key being used exactly once. The aead construction derives a fresh Poly1305 key from ChaCha20 for every message — follow the same pattern if you're building a bespoke scheme.
Weak RNG. All randomness in this library comes from the platform CSPRNG (getrandom(2), arc4random_buf, BCryptGenRandom). Do NOT supply your own "random" bytes unless they originate from an audited CSPRNG.

Relationship to other Verum docs

guides/security — the high-level practitioner's guide: what Verum prevents by construction and what requires programmer discipline.
language/cbgr — memory safety.
verification/contracts — formal contracts on crypto functions (constant-time refinement, nonce-non-reuse invariants in progress).
stdlib/net — TLS 1.3 record layer, QUIC, HTTP/3 all consume the primitives here.

Status and roadmap

Primitive	Status	Notes
SHA-256, SHA-384, SHA-512	✅ Production	Pure Verum reference + `crypto-accel` hook
HMAC-SHA-{256,384,512}	✅ Production	RFC 4231 vectors byte-exact
HKDF-SHA-{256,384,512}	✅ Production	RFC 5869 vectors byte-exact
AES-128, AES-256	✅ Production	Reference + AES-NI / ARMv8 hook
AES-GCM	✅ Production	12-byte IV path (TLS/QUIC)
ChaCha20	✅ Production	RFC 8439
Poly1305	✅ Production	5 × 26-bit limbs
ChaCha20-Poly1305 AEAD	✅ Production	RFC 8439
X25519	✅ Production	Intrinsic-backed scalar-mult
ML-KEM	✅ Production	FIPS 203 via intrinsic
ML-DSA	✅ Production	FIPS 204 via intrinsic
Ed25519	🟡 Planned P1	Modern signatures
P-256 (ECDSA + ECDHE)	🟡 Planned P1	Legacy cert chains
RSA-PSS (verify-only)	🟡 Planned P2	Legacy cert chains
AES-GCM-SIV	🟡 Planned P2	Nonce-misuse-resistant

Citations

When citing this library in a paper or audit report, use:

Verum Security Library, core.security/*.vr,
Verum Language Platform, 2026.

Implementations align with:

NIST FIPS 180-4 (Secure Hash Standard)
NIST FIPS 197 (Advanced Encryption Standard)
NIST FIPS 203 (Module-Lattice-Based Key-Encapsulation)
NIST FIPS 204 (Module-Lattice-Based Digital Signature)
NIST SP 800-38D (Galois/Counter Mode)
IETF RFC 2104, 4231, 5869, 7748, 8439, 8446, 9001

Design principles​

1. Single horizontal layer, zero duplication​

2. Refinement-typed keys and nonces​

3. Constant-time by construction — with hardware accel for perf​

4. Production-first, standards-aligned​

Module map​

Documentation map​

Cryptographic primitives​

Identity, secrets, policy​

TLS 1.3 / QUIC cipher-suite coverage​

Threat model and what the layer does NOT cover​

Relationship to other Verum docs​

Status and roadmap​

Citations​