fantuz/entropy-service

Randomness, on your terms. A self-hosted Go toolkit to generate, stream and inspect random data from hardware or software RNGs, through HTTP and WebSocket APIs

Summary

Entropy Service is a self-hosted Go server and command-line client for generating, streaming, and inspecting pseudorandom data. It seeds a deterministic random bit generator from a hardware device or the operating system CSPRNG, then exposes bounded binary data through HTTP and WebSocket APIs alongside browser diagnostics and Prometheus metrics.

What it is useful for

Engineers can use the service to develop and test applications that consume random bytes. A client can request a bounded sample such as 4 KiB from /v1/data/random, or maintain a WebSocket connection that continuously delivers configurable binary frames.

It is also useful for laboratory and integration work involving hardware entropy sources. The server can seed from a device such as /dev/qrandom0, while /dev/urandom provides a convenient software-based starting point. AES-256-CTR and ChaCha20 are available as DRBG backends.

The embedded browser interface supports byte previews, histograms, bit-balance and entropy estimates, FFT previews, words, colors, QR codes, sounds, and file analysis. For service integration, /ready reports readiness, while /metrics-2 exposes Prometheus metrics covering traffic, reseeding, and resource admission.

The boundaries matter: DRBG output is expanded from seed material rather than consisting of fresh physical entropy measurements. Statistical diagnostics and rngtest results do not prove unpredictability or certify a cryptographic implementation. The project is not an HSM, key-management system, or certified entropy source.

How engineers can use it

The documented local setup requires Go 1.24.4 or newer, Git, and Make. Linux is the primary deployment target:

git clone https://github.com/fantuz/entropy-service.git
cd entropy-service
make build
./bin/entropy-server -device=/dev/urandom -enable-https=false -http=127.0.0.1:8080

Fetch a binary sample and check its size:

curl --fail 'http://127.0.0.1:8080/v1/data/random?bytes=4096' -o sample.bin
wc -c sample.bin

For repeated delivery, the documented client can pull 64 KiB responses or receive the same-sized WebSocket messages:

./bin/entropy-client -mode=pull -url=http://127.0.0.1:8080/v1/data/random -slice=65536 -refresh=100ms
./bin/entropy-client -mode=stream -wsurl=ws://127.0.0.1:8080/stream -slice=65536 -refresh=100ms

When hardware availability is mandatory, use -require-device=true; otherwise the server may fall back to the OS CSPRNG. Remote deployments should use https:// or wss:// with their own certificates, because the service has no built-in client authentication and access controls belong at the deployment boundary. Binary requests are capped at 32 MiB by default, and a failed reseed does not automatically stop existing DRBG output, so readiness should be included in operational checks.