feature: Added WithSelfTests and WithZeroization

Author: mprimeaux

CHANGELOG/CHANGELOG-1.x.md

@@ -12,8 +12,24 @@ Date format: `YYYY-MM-DD`
 
 ### Added
 ### Changed
-- **debt:** Upgraded all dependencies to their latest stable versions.
-- **risk:** Add retry logic to signature verification make target to handle transient network errors.
+### Deprecated
+### Removed
+### Fixed
+### Security
+
+---
+
+## [1.15.0] - 2025-12-29
+
+
+### Added
+- **feature:** Added `WithSelfTests` option to enable FIPS 140-2 Known Answer Test (KAT) self-tests at DRBG initialization using NIST CAVP vectors.
+- **feature:** Added `WithZeroization` option to enable secure erasure of old key material during key rotation for forward secrecy (FIPS 140-2 §4.7.6 compliance).
+
+### Changed
+- **risk:** Added 64 KB maximum request size limit per DRBG call to comply with NIST SP 800-90A §10.2.1.
+- **risk:** Clamped user-configured reseed interval to a maximum of 2^48 requests per NIST SP 800-90A §10.2.1.1.
+- **debt:** Updated NIST SP 800-90A specification mapping table in documentation to reflect new FIPS compliance features (max request size, reseed interval cap, KATs, and key zeroization).
 
 ### Deprecated
 ### Removed
@@ -193,7 +209,7 @@ Date format: `YYYY-MM-DD`
 
 ### Added
 ### Changed
-- **feature:** Prediction resistance mode (`WithPredictionResistance`), enabling NIST SP 800-90A Section 9.3 compliance by reseeding before every output.
+- **feature:** Prediction resistance mode (`WithPredictionResistance`), enabling NIST SP 800-90A §9.3 compliance by reseeding before every output.
 - **feature:** Automatic interval-based reseeding (`WithReseedInterval`) and reseed-on-request-count (`WithReseedRequests`) options.
 - **feature:** Added `ReadWithAdditionalInput([]byte)` method for supplying per-call additional input as permitted by the NIST SP 800-90A standard.
 - **feature:** Added `Reseed([]byte)` method to manually reseed a DRBG instance with new entropy.
@@ -264,7 +280,8 @@ Date format: `YYYY-MM-DD`
 ### Fixed
 ### Security
 
-[Unreleased]: https://github.com/sixafter/aes-ctr-drbg/compare/v1.14.5...HEAD
+[Unreleased]: https://github.com/sixafter/aes-ctr-drbg/compare/v1.15.0...HEAD
+[1.15.0]: https://github.com/sixafter/aes-ctr-drbg/compare/v1.14.5...v1.15.0
 [1.14.5]: https://github.com/sixafter/aes-ctr-drbg/compare/v1.14.1...v1.14.5
 [1.14.1]: https://github.com/sixafter/aes-ctr-drbg/compare/v1.14.0...v1.14.1
 [1.14.0]: https://github.com/sixafter/aes-ctr-drbg/compare/v1.13.0...v1.14.0

Makefile

@@ -20,7 +20,7 @@ GO_WORK_FILE := ./go.work
 FUZZTIME ?= 25s
 
 .PHONY: all
-all: deps vendor update vendor tidy clean test
+all: deps update tidy vendor clean test
 
 .PHONY: deps
 deps: ## Get the dependencies and vendor

README.md

@@ -117,10 +117,10 @@ For a detailed mapping between the implementation and NIST SP 800-90A requiremen
 To verify the integrity of the release tarball, you can use Cosign to check the signature and checksums. Follow these steps:
 
 ```sh
-# Fetch the latest release tag from GitHub API (e.g., "v1.14.0")
+# Fetch the latest release tag from GitHub API (e.g., "v1.15.0")
 TAG=$(curl -s https://api.github.com/repos/sixafter/aes-ctr-drbg/releases/latest | jq -r .tag_name)
 
-# Remove leading "v" for filenames (e.g., "v1.14.0" -> "1.14.0")
+# Remove leading "v" for filenames (e.g., "v1.15.0" -> "1.15.0")
 VERSION=${TAG#v}
 
 # ---------------------------------------------------------------------

aes_ctr_drbg.go

@@ -7,7 +7,7 @@
 //
 // This package implements a cryptographically secure, pool-backed Deterministic Random Bit Generator
 // (DRBG) following the NIST SP 800-90A AES-CTR-DRBG construction, specifically as defined in
-// Section 10.2.1 of NIST SP 800-90A Rev. 1 ("Recommendation for Random Number Generation Using
+// §10.2.1 of NIST SP 800-90A Rev. 1 ("Recommendation for Random Number Generation Using
 // Deterministic Random Bit Generators").
 //
 // Each generator instance uses an AES block cipher in counter (CTR) mode to produce cryptographically
@@ -18,14 +18,16 @@
 //
 // Reference:
 //
-//	NIST Special Publication 800-90A Rev. 1, Section 10.2.1 (CTR_DRBG Construction)
+//	NIST Special Publication 800-90A Rev. 1, §10.2.1 (CTR_DRBG Construction)
 //	https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-90Ar1.pdf
 package ctrdrbg
 
 import (
 	"crypto/aes"
 	"crypto/cipher"
 	"crypto/rand"
+	"crypto/subtle"
+	"errors"
 	"fmt"
 	"io"
 	mrand "math/rand/v2"
@@ -35,6 +37,14 @@ import (
 	"time"
 )
 
+const (
+	// MaxBytesPerRequest is the NIST SP 800-90A maximum bytes per request for CTR_DRBG (2^19 bits = 64 KB).
+	MaxBytesPerRequest = 1 << 16
+)
+
+// ErrRequestTooLarge is returned when a Read request exceeds the NIST SP 800-90A maximum (64 KB).
+var ErrRequestTooLarge = errors.New("ctrdrbg: request exceeds NIST SP 800-90A max_number_of_bits_per_request (64 KB)")
+
 // Reader is a package-level, cryptographically secure random source suitable for high-concurrency applications.
 //
 // Reader is initialized at package load time via NewReader and is safe for concurrent use. If initialization fails
@@ -193,6 +203,13 @@ func NewReader(opts ...Option) (Interface, error) {
 		opt(&cfg)
 	}
 
+	// FIPS 140-2 §4.9.1: Run Known Answer Tests if enabled.
+	if cfg.EnableSelfTests {
+		if err := RunSelfTests(); err != nil {
+			return nil, err
+		}
+	}
+
 	// Validate the configured key size is appropriate for AES.
 	// Only 16, 24, or 32 bytes (AES-128, AES-192, AES-256) are supported.
 	switch cfg.KeySize {
@@ -541,6 +558,11 @@ func (d *drbg) Read(b []byte) (int, error) {
 		return 0, nil
 	}
 
+	// NIST SP 800-90A §10.2.1: Validate max_number_of_bits_per_request (64 KB).
+	if n > MaxBytesPerRequest {
+		return 0, ErrRequestTooLarge
+	}
+
 	d.reseedIfForked()
 
 	// Prediction Resistance
@@ -650,6 +672,11 @@ func (d *drbg) ReadWithAdditionalInput(b []byte, additionalInput []byte) (int, e
 		return 0, nil
 	}
 
+	// NIST SP 800-90A §10.2.1: Validate max_number_of_bits_per_request (64 KB).
+	if n > MaxBytesPerRequest {
+		return 0, ErrRequestTooLarge
+	}
+
 	d.reseedIfForked()
 
 	// If PredictionResistance is enabled, always reseed from fresh entropy before output,
@@ -1074,8 +1101,18 @@ func (d *drbg) asyncRekey() {
 			copy(key[:], seed[:d.config.KeySize])
 			var v [16]byte
 			copy(v[:], seed[d.config.KeySize:])
-			block, err := aes.NewCipher(key[:d.config.KeySize])
+			var block cipher.Block
+			block, err = aes.NewCipher(key[:d.config.KeySize])
 			if err == nil {
+				// FIPS 140-2 §4.7.6: Zeroize old key material before replacement.
+				if d.config.EnableZeroization {
+					if oldState := d.state.Load(); oldState != nil {
+						// Use subtle.XORBytes to prevent compiler optimization.
+						subtle.XORBytes(oldState.key[:], oldState.key[:], oldState.key[:])
+						subtle.XORBytes(oldState.v[:], oldState.v[:], oldState.v[:])
+					}
+				}
+
 				// Store new cryptographic state atomically.
 				newState := &state{
 					block: block,
@@ -1087,6 +1124,10 @@ func (d *drbg) asyncRekey() {
 
 				// Reset the working counter (v) under mutex lock to ensure no overlap.
 				d.vMu.Lock()
+				// Zeroize old working counter before overwriting.
+				if d.config.EnableZeroization {
+					subtle.XORBytes(d.v[:], d.v[:], d.v[:])
+				}
 				copy(d.v[:], v[:])
 				d.vMu.Unlock()
 				return // Rekey complete.

aes_ctr_drbg_bench_test.go

@@ -83,8 +83,9 @@ func BenchmarkDRBG_Read_Concurrent(b *testing.B) {
 }
 
 // BenchmarkDRBG_Read_LargeSizes_Sequential benchmarks sequential Read performance for large buffer sizes.
+// Buffer sizes are capped at 64 KB per NIST SP 800-90A max_number_of_bits_per_request.
 func BenchmarkDRBG_Read_LargeSizes_Sequential(b *testing.B) {
-	largeBufferSizes := []int{4096, 16384, 65536, 1048576}
+	largeBufferSizes := []int{4096, 16384, 65536}
 	for _, size := range largeBufferSizes {
 		b.Run(fmt.Sprintf("Serial_Read_Large_%dBytes", size), func(b *testing.B) {
 			buffer := make([]byte, size)
@@ -102,8 +103,9 @@ func BenchmarkDRBG_Read_LargeSizes_Sequential(b *testing.B) {
 
 // BenchmarkDRBG_Read_LargeSizes_Concurrent benchmarks concurrent Read performance
 // for large buffer sizes and multiple goroutines.
+// Buffer sizes are capped at 64 KB per NIST SP 800-90A max_number_of_bits_per_request.
 func BenchmarkDRBG_Read_LargeSizes_Concurrent(b *testing.B) {
-	largeBufferSizes := []int{4096, 16384, 65536, 1048576}
+	largeBufferSizes := []int{4096, 16384, 65536}
 	goroutineCounts := []int{2, 4, 8, 16, 32, 64, 128}
 	for _, size := range largeBufferSizes {
 		for _, gc := range goroutineCounts {
@@ -170,7 +172,9 @@ func BenchmarkDRBG_Read_VariableSizes_Concurrent(b *testing.B) {
 
 // BenchmarkDRBG_Read_ExtremeSizes benchmarks Read performance for very large buffer sizes
 // (10MB, 50MB, 100MB) both serially and concurrently.
+// Reads are performed in 64 KB chunks per NIST SP 800-90A max_number_of_bits_per_request.
 func BenchmarkDRBG_Read_ExtremeSizes(b *testing.B) {
+	const chunkSize = 65536                                    // 64 KB (NIST max)
 	extremeBufferSizes := []int{10485760, 52428800, 104857600} // 10MB, 50MB, 100MB
 	for _, size := range extremeBufferSizes {
 		// Serial
@@ -179,9 +183,16 @@ func BenchmarkDRBG_Read_ExtremeSizes(b *testing.B) {
 			b.ReportAllocs()
 			b.ResetTimer()
 			for i := 0; i < b.N; i++ {
-				_, err := Reader.Read(buffer)
-				if err != nil {
-					b.Fatalf("Read failed: %v", err)
+				// Read in 64 KB chunks
+				for offset := 0; offset < size; offset += chunkSize {
+					end := offset + chunkSize
+					if end > size {
+						end = size
+					}
+					_, err := Reader.Read(buffer[offset:end])
+					if err != nil {
+						b.Fatalf("Read failed: %v", err)
+					}
 				}
 			}
 		})
@@ -195,9 +206,16 @@ func BenchmarkDRBG_Read_ExtremeSizes(b *testing.B) {
 				b.ResetTimer()
 				b.RunParallel(func(pb *testing.PB) {
 					for pb.Next() {
-						_, err := Reader.Read(buffer)
-						if err != nil {
-							b.Fatalf("Read failed: %v", err)
+						// Read in 64 KB chunks
+						for offset := 0; offset < size; offset += chunkSize {
+							end := offset + chunkSize
+							if end > size {
+								end = size
+							}
+							_, err := Reader.Read(buffer[offset:end])
+							if err != nil {
+								b.Fatalf("Read failed: %v", err)
+							}
 						}
 					}
 				})

aes_ctr_drbg_fuzz_test.go

@@ -15,7 +15,8 @@ import (
 
 // Fuzz_Reader_Read exercises the Reader.Read method using a variety of buffer sizes.
 // It ensures that Read does not return an error and produces the requested number of bytes
-// for all valid sizes in the range [0, 65536]. Invalid sizes outside this range are skipped.
+// for all valid sizes in the range [0, 65536]. Sizes exceeding 65536 (64 KB) are skipped
+// as they exceed the NIST SP 800-90A max_number_of_bits_per_request limit.
 func Fuzz_Reader_Read(f *testing.F) {
 	for _, sz := range []int{0, 1, 15, 16, 17, 32, 64, 1024, 4096} {
 		f.Add(sz)