# smuellerdd/jitterentropy-library architecture

> Architecture diagram of the GitHub repository smuellerdd/jitterentropy-library, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smuellerdd/jitterentropy-library
- Repository: https://github.com/smuellerdd/jitterentropy-library

## Overview

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: [`src/jitterentropy-base.c`](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-base.c) (Base engine), [`src/jitterentropy-timer.c`](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-timer.c) (Timer layer), [`tests/raw-entropy/README.md`](https://github.com/smuellerdd/jitterentropy-library/blob/master/tests/raw-entropy/README.md) (Entropy harness), [`src/jitterentropy-noise.c`](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-noise.c) (Noise layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_jitterentropy_h["API header<br/>public header<br/>[jitterentropy.h]"]
  node_rand_data(("RNG state<br/>runtime object<br/>[jitterentropy.h]"))
  node_status_api["Status API<br/>observable state"]
end

subgraph group_core["Entropy Engine"]
  node_base_engine["Base engine<br/>collection core"]
  node_noise_layer["Noise layer<br/>jitter extraction"]
  node_timer_layer["Timer layer<br/>time source"]
  node_health_tests["Health tests<br/>runtime checks"]
  node_sha3_cond["SHA3 conditioner<br/>whitening"]
  node_gcd_utils["GCD helper<br/>analysis helper"]
  node_internal_hdr["Internal defs<br/>private header"]
end

subgraph group_platform["Platform Hooks"]
  node_arch_x86["x86 hooks<br/>arch header"]
  node_arch_s390["s390 hooks<br/>arch header"]
  node_arch_power["Power hooks<br/>arch header"]
  node_arch_windows["Windows hooks<br/>arch header"]
  node_arch_user["User hooks<br/>platform header"]
end

subgraph group_packaging["Build & Docs"]
  node_build_docs["Build docs<br/>build and manuals<br/>[README.md]"]
  node_cmake_pkg["CMake pkg<br/>packaging metadata"]
end

subgraph group_tests["Tests & Validation"]
  node_tests_gcd["GCD test<br/>functional test<br/>[gcd.c]"]
  node_raw_entropy_harness["Entropy harness<br/>validation pipeline<br/>[README.md]"]
end

node_jitterentropy_h -->|"defines"| node_rand_data
node_jitterentropy_h -->|"calls"| node_base_engine
node_base_engine -->|"measures"| node_timer_layer
node_base_engine -->|"collects"| node_noise_layer
node_noise_layer -->|"checks"| node_health_tests
node_noise_layer -->|"feeds"| node_sha3_cond
node_health_tests -->|"reports"| node_status_api
node_base_engine -->|"updates"| node_status_api
node_base_engine -->|"uses"| node_gcd_utils
node_base_engine -->|"depends on"| node_internal_hdr
node_timer_layer -->|"adapts to"| node_arch_x86
node_timer_layer -->|"adapts to"| node_arch_s390
node_timer_layer -->|"adapts to"| node_arch_power
node_timer_layer -->|"adapts to"| node_arch_windows
node_timer_layer -->|"adapts to"| node_arch_user
node_build_docs -->|"documents"| node_jitterentropy_h
node_build_docs -->|"packages"| node_cmake_pkg
node_tests_gcd -->|"validates"| node_gcd_utils
node_raw_entropy_harness -->|"benchmarks"| node_base_engine
node_raw_entropy_harness -->|"evaluates"| node_health_tests
node_raw_entropy_harness -->|"observes"| node_status_api

click node_jitterentropy_h "https://github.com/smuellerdd/jitterentropy-library/blob/master/jitterentropy.h"
click node_rand_data "https://github.com/smuellerdd/jitterentropy-library/blob/master/jitterentropy.h"
click node_status_api "https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-status.c"
click node_base_engine "https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-base.c"
click node_noise_layer "https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-noise.c"
click node_timer_layer "https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-timer.c"
click node_health_tests "https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-health.c"
click node_sha3_cond "https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-sha3.c"
click node_gcd_utils "https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-gcd.c"
click node_internal_hdr "https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-internal.h"
click node_arch_x86 "https://github.com/smuellerdd/jitterentropy-library/blob/master/arch/jitterentropy-base-x86.h"
click node_arch_s390 "https://github.com/smuellerdd/jitterentropy-library/blob/master/arch/jitterentropy-base-s390.h"
click node_arch_power "https://github.com/smuellerdd/jitterentropy-library/blob/master/arch/jitterentropy-base-power.h"
click node_arch_windows "https://github.com/smuellerdd/jitterentropy-library/blob/master/arch/jitterentropy-base-windows.h"
click node_arch_user "https://github.com/smuellerdd/jitterentropy-library/blob/master/jitterentropy-base-user.h"
click node_build_docs "https://github.com/smuellerdd/jitterentropy-library/blob/master/README.md"
click node_cmake_pkg "https://github.com/smuellerdd/jitterentropy-library/blob/master/cmake/jitterentropyConfig.cmake.in"
click node_tests_gcd "https://github.com/smuellerdd/jitterentropy-library/blob/master/tests/gcd/gcd.c"
click node_raw_entropy_harness "https://github.com/smuellerdd/jitterentropy-library/blob/master/tests/raw-entropy/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_jitterentropy_h,node_rand_data,node_status_api toneBlue
class node_base_engine,node_noise_layer,node_timer_layer,node_health_tests,node_sha3_cond,node_gcd_utils,node_internal_hdr toneAmber
class node_arch_x86,node_arch_s390,node_arch_power,node_arch_windows,node_arch_user toneMint
class node_build_docs,node_cmake_pkg toneRose
class node_tests_gcd,node_raw_entropy_harness toneIndigo
```

## Components

### Public API

External entry points and usage contract

- [API header](https://github.com/smuellerdd/jitterentropy-library/blob/master/jitterentropy.h): public header · Main external API and instance boundary · `jitterentropy.h`
- [RNG state](https://github.com/smuellerdd/jitterentropy-library/blob/master/jitterentropy.h): runtime object · Per-instance collector state; not intended for sharing across threads · `jitterentropy.h`
- [Status API](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-status.c): observable state · Reports health, FIPS mode, and timer-disable state · `src/jitterentropy-status.c`

### Entropy Engine

Portable runtime that collects, analyzes, and conditions jitter

- [Base engine](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-base.c): collection core · Top-level entropy collection orchestration · `src/jitterentropy-base.c`
- [Noise layer](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-noise.c): jitter extraction · Converts timing variation into raw noise samples · `src/jitterentropy-noise.c`
- [Timer layer](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-timer.c): time source · High-resolution timestamp abstraction and platform boundary · `src/jitterentropy-timer.c`
- [Health tests](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-health.c): runtime checks · Startup and ongoing health validation that can block output · `src/jitterentropy-health.c`
- [SHA3 conditioner](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-sha3.c): whitening · Conditions and whitens raw noise before output · `src/jitterentropy-sha3.c`
- [GCD helper](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-gcd.c): analysis helper · Supporting logic used by entropy analysis machinery · `src/jitterentropy-gcd.c`
- [Internal defs](https://github.com/smuellerdd/jitterentropy-library/blob/master/src/jitterentropy-internal.h): private header · Shared internal declarations and configuration wiring · `src/jitterentropy-internal.h`

### Platform Hooks

Architecture- and OS-specific timing integration points

- [x86 hooks](https://github.com/smuellerdd/jitterentropy-library/blob/master/arch/jitterentropy-base-x86.h): arch header · x86-specific timing and assembly-facing support · `arch/jitterentropy-base-x86.h`
- [s390 hooks](https://github.com/smuellerdd/jitterentropy-library/blob/master/arch/jitterentropy-base-s390.h): arch header · s390-specific timing support · `arch/jitterentropy-base-s390.h`
- [Power hooks](https://github.com/smuellerdd/jitterentropy-library/blob/master/arch/jitterentropy-base-power.h): arch header · Power architecture timing support · `arch/jitterentropy-base-power.h`
- [Windows hooks](https://github.com/smuellerdd/jitterentropy-library/blob/master/arch/jitterentropy-base-windows.h): arch header · Windows platform support for the timer boundary · `arch/jitterentropy-base-windows.h`
- [User hooks](https://github.com/smuellerdd/jitterentropy-library/blob/master/jitterentropy-base-user.h): platform header · Generic user-space platform integration header · `jitterentropy-base-user.h`

### Build & Docs

Build scripts, packaging metadata, and documentation

- [Build docs](https://github.com/smuellerdd/jitterentropy-library/blob/master/README.md): build and manuals · Top-level build, packaging, and API documentation · `README.md`
- [CMake pkg](https://github.com/smuellerdd/jitterentropy-library/blob/master/cmake/jitterentropyConfig.cmake.in): packaging metadata · CMake package and pkg-config templates · `cmake/jitterentropyConfig.cmake.in`

### Tests & Validation

Functional checks and entropy-rate measurement tooling

- [GCD test](https://github.com/smuellerdd/jitterentropy-library/blob/master/tests/gcd/gcd.c): functional test · Targeted check for helper logic · `tests/gcd/gcd.c`
- [Entropy harness](https://github.com/smuellerdd/jitterentropy-library/blob/master/tests/raw-entropy/README.md): validation pipeline · Capture and analysis framework for raw entropy modes · `tests/raw-entropy/README.md`

## Connections

- 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
