How smuellerdd/jitterentropy-library works
1. This repository is a standalone C library implementing the Jitter RNG: a CPU timing-jitter entropy source. The core architectural boundary is a small public API in jitterentropy.h backed by a platform-neutral engine that can run on Linux, Android, Windows, or even bare metal.
2. The main runtime object is struct rand_data, which represents one RNG instance. The README’s operational guidance makes the instance boundary important: one instance is not meant to be shared across threads, and callers should allocate one collector per thread if needed.
3. The entropy collection pipeline lives in src/ and is split into layers:
- jitterentropy-base.c / -base.h: base collection and common helpers
- jitterentropy-noise.c / -noise.h: extracts timing jitter/noise
- jitterentropy-timer.c / -timer.h: high-resolution time source abstraction
- jitterentropy-health.c / -health.h: startup/runtime health tests
- jitterentropy-sha3.c / -sha3.h: conditioner/whitening
- jitterentropy-status.c: status reporting
- jitterentropy-gcd.c / -gcd.h: helper logic used by the entropy analysis machinery
4. Data flow is: caller initializes an RNG instance, the engine repeatedly measures execution-time jitter via the timer layer, converts those measurements into raw noise, runs health checks, and then conditions the noise through SHA3 before returning output bytes. The design intentionally separates raw noise acquisition from output conditioning.
5. The timer layer is the key platform boundary. The repo includes architecture-specific headers under arch/ for x86, s390, power, Windows, and Android, plus a generic user header. This is where the library adapts to the local timestamp mechanism without changing the higher-level entropy logic.
6. Health testing is a first-class subsystem, not an add-on. The README’s compliance sections show that failing health tests can permanently block output, and the status API must expose whether health tests are failing, whether FIPS mode is enabled, and whether the internal timer is disabled. That makes health state part of the observable architecture.
7. Compliance/configuration is handled by runtime flags rather than separate binaries. Important modes include JENT_FORCE_FIPS, JENT_NTG1, JENT_FORCE_INTERNAL_TIMER, and memory-access related options. These flags affect which subsystems are active and whether the library is suitable for SP800-90B or AIS 20/31 NTG.1 use.
8. The library is intentionally OS-independent, but it can integrate with external crypto or platform build environments. The root contains both Makefile and CMakeLists.txt, plus CMake packaging templates under cmake/, and an Android NDK makefile under arch/android/. This suggests the same core engine is compiled into different target environments rather than deployed as a service.
9. Packaging and documentation are part of the repo but not part of runtime execution. doc/jitterentropy.3 documents the API, while the root README.md and CHANGES.md define usage, compatibility, and versioning. The shared library is the primary deliverable.
10. Testing is a separate subsystem with two distinct purposes:
- functional/unit-style checks such as tests/gcd
- entropy-rate measurement and compliance validation under tests/raw-entropy/
The raw-entropy area is further split into userspace, runtime-kernelspace, restart-kernelspace, and validation pipelines, showing that entropy quality is evaluated across execution environments and test modes.
11. The raw entropy tests form a tooling pipeline rather than a simple test case. They include data capture programs, scripts to record or restart tests, LSB extraction helpers, and analysis scripts/R code to compute entropy rates and validate whether the chosen operating mode meets the required thresholds.
12. Overall architecture: a small public library API at the top; a portable entropy engine in the middle; platform-specific timer/arch hooks at the edge; and a substantial compliance/test harness surrounding it. The library is designed to be embedded as an entropy source, often feeding a larger deterministic RNG rather than serving as a high-throughput random byte generator itself.
Main entry points: jitterentropy-base.c Base engine · jitterentropy-timer.c Timer layer · README.md Entropy harness · jitterentropy-noise.c Noise layer
Components 19
Public API
External entry points and usage contract
- API header · Main external API and instance boundary
jitterentropy.h - RNG state · Per-instance collector state; not intended for sharing across threads
jitterentropy.h - Status API · Reports health, FIPS mode, and timer-disable state
src/jitterentropy-status.c
Entropy Engine
Portable runtime that collects, analyzes, and conditions jitter
- Base engine · Top-level entropy collection orchestration
src/jitterentropy-base.c - Noise layer · Converts timing variation into raw noise samples
src/jitterentropy-noise.c - Timer layer · High-resolution timestamp abstraction and platform boundary
src/jitterentropy-timer.c - Health tests · Startup and ongoing health validation that can block output
src/jitterentropy-health.c - SHA3 conditioner · Conditions and whitens raw noise before output
src/jitterentropy-sha3.c - GCD helper · Supporting logic used by entropy analysis machinery
src/jitterentropy-gcd.c - Internal defs · Shared internal declarations and configuration wiring
src/jitterentropy-internal.h
Platform Hooks
Architecture- and OS-specific timing integration points
- x86 hooks · x86-specific timing and assembly-facing support
arch/jitterentropy-base-x86.h - s390 hooks · s390-specific timing support
arch/jitterentropy-base-s390.h - Power hooks · Power architecture timing support
arch/jitterentropy-base-power.h - Windows hooks · Windows platform support for the timer boundary
arch/jitterentropy-base-windows.h - User hooks · Generic user-space platform integration header
jitterentropy-base-user.h
Build & Docs
Build scripts, packaging metadata, and documentation
- Build docs · Top-level build, packaging, and API documentation
README.md - CMake pkg · CMake package and pkg-config templates
cmake/jitterentropyConfig.cmake.in
Tests & Validation
Functional checks and entropy-rate measurement tooling
- GCD test · Targeted check for helper logic
tests/gcd/gcd.c - Entropy harness · Capture and analysis framework for raw entropy modes
tests/raw-entropy/README.md
Connections 21
- API header → RNG state: defines · Public API exposes the per-instance RNG state
- API header → Base engine: calls · External callers drive the core collector through the API
- Base engine → Timer layer: measures · Collection begins with timestamp acquisition
- Base engine → Noise layer: collects · Engine transforms timing differences into raw noise
- Noise layer → Health tests: checks · Raw samples are screened by startup/runtime health logic
- Noise layer → SHA3 conditioner: feeds · Noise is passed into the conditioner for output whitening
- Health tests → Status API: reports · Health state is reflected through observable status
- Base engine → Status API: updates · Runtime mode and timer state surface through status reporting
- Base engine → GCD helper: uses · Entropy analysis helpers support the core pipeline
- Base engine → Internal defs: depends on · Shared internal definitions connect the core layers
- Timer layer → x86 hooks: adapts to · Architecture-specific timer support on x86
- Timer layer → s390 hooks: adapts to · Architecture-specific timer support on s390
- Timer layer → Power hooks: adapts to · Architecture-specific timer support on Power
- Timer layer → Windows hooks: adapts to · Windows timer integration
- Timer layer → User hooks: adapts to · Generic user-space platform boundary
- Build docs → API header: documents · README and manual describe API and operational constraints
- Build docs → CMake pkg: packages · Root build and packaging metadata support multiple environments
- GCD test → GCD helper: validates · Focused test coverage for the GCD helper
- Entropy harness → Base engine: benchmarks · Validation pipeline exercises the runtime engine under different modes
- Entropy harness → Health tests: evaluates · Compliance runs observe health-test behavior and blocking conditions
- Entropy harness → Status API: observes · Validation tooling checks reported mode and health state