nist-rand 0.1.0

A high-assurance, FIPS 140-3 and NIST SP 800-90A/B/C compliant Cryptographically Secure Pseudorandom Number Generator (CSPRNG) with multi-source entropy blending.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# nist-rand

[![Crates.io](https://img.shields.io/crates/v/nist-rand.svg)](https://crates.io/crates/nist-rand)
[![Documentation](https://docs.rs/nist-rand/badge.svg)](https://docs.rs/nist-rand)
[![License](https://img.shields.io/crates/l/nist-rand.svg)](https://github.com/hacer-bark/nist-rand)

> **⚠️ DISCLAIMER**: This code is **NOT FIPS Verified** and has **NOT** been officially audited by a NIST lab. Furthermore, this code does not receive any formal security audits. It implements the best practices and algorithms described by NIST SP 800-90A/B/C, but does not claim or provide official compliance or certification. Use at your own risk.

A high-assurance, production-ready Cryptographically Secure Pseudorandom Number Generator (CSPRNG) that implements the architectural design and algorithms described in **NIST SP 800-90A/B/C**.

## Features

- **Designed to SP 800-90 Standards:** Implements SP 800-90A (Hash_DRBG) using FIPS 202 approved SHA3-512.
- **Deep Entropy Blending (SP 800-90C):** Blends entropy from up to 7 distinct sources including OS RNG, CPU Jitter, System state, AVX-256 SIMD timing anomalies, Network latency, Hardware instructions (RDSEED/RDRAND), and CPU Performance Counters.
- **Continuous Health Testing:** Strict implementation of SP 800-90B Repetition Count Test (RCT) and Adaptive Proportion Test (APT). Panic-on-fail to ensure FIPS fail-safe requirements.
- **Zeroization:** Optional strict zeroization of sensitive internal states and key material upon drop or panic using the `zeroize` crate.
- **`rand_core` Compatibility:** Seamlessly integrates into the broader Rust ecosystem via the `rand_core` trait.

## Architecture

`nist-rand` implements a highly defensive, multi-layered entropy architecture:

```text
 ┌───────────────────────────────────────────────────────────────┐
 │                    SP 800-90C Blender                         │
 │  ┌──────────────┐  ┌────────────────┐  ┌──────────────────┐   │
 │  │ OS RNG       │  │ CPU Jitter     │  │ Hardware/System  │   │
 │  │ /dev/urandom │  │ (advance feat) │  │ perf_events, TSC │   │
 │  │ + 90B tests  │  │ Von Neumann    │  │ (advance feat)   │   │
 │  └──────┬───────┘  └───────┬────────┘  └────────┬─────────┘   │
 │         └──────────────────┴────────────────────┘             │
 │                            │ SHA3-512                         │
 └────────────────────────────┼──────────────────────────────────┘
                              │ 512-bit conditioned seed
 ┌────────────────────────────▼──────────────────────────────────┐
 │             Hash_DRBG (SP 800-90A § 10.1.1)                   │
 │                    SHA3-512 (FIPS 202)                        │
 │                reseed every 10 000 requests                   │
 └────────────────────────────┬──────────────────────────────────┘
                              │
                        fill() / NistRng
```

## Usage

### Direct Usage

```rust
use nist_rand::fill;

let mut my_key = [0u8; 32];
// Fills the buffer with highly secure pseudorandom bytes.
// Automatically seeds and reseeds securely.
fill(&mut my_key);
```

### With `rand_core`

If you enable the `rand_core` feature (enabled by default), you can use it alongside other `rand` utilities:

```rust
use rand_core::RngCore;
use nist_rand::NistRng;

let mut rng = NistRng;
let random_u32 = rng.next_u32();
```

## Crate Features

| Feature | Default | Description |
|---------|---------|-------------|
| `rand_core` | ✓ | Exposes `NistRng` implementing `rand_core` 0.10 traits. |
| `advance` | ✓ | Adds CPU jitter, System state, and Hardware RNG (RDSEED/RDRAND, perf_events) + extended 90B health tests. |
| `build_separator` | ✓ | Embeds a random build-time salt (via `build.rs`) to ensure different binaries yield different entropy streams. |
| `zeroize` | ✓ | Derives `ZeroizeOnDrop` on internal states; wraps sensitive buffers in `Zeroizing` so key material is erased even on panic. |
| `exp_simd_rng` | ✗ | Experimental: AVX-256 thermal jitter (implies `advance`). |
| `exp_network_rng` | ✗ | Experimental: UDP network-latency jitter (implies `advance`). |

## SP 800-90 Design Principles

*   **Entropy Health:** `rng::HealthTests` runs SP 800-90B RCT + APT tests on raw noise sources.
*   **Blending:** `entropy::get_blended_entropy()` uses SHA3-512 as an approved conditioning function (SP 800-90C § 4.1).
*   **DRBG:** `drbg::HashDrbg` uses SP 800-90A § 10.1.1 with SHA3-512 (FIPS 202).
*   **Reseed Interval:** Enforces a strict 10,000 generate limit between reseeds (Table 2).
*   **Fail-safe:** Implements `panic!` on catastrophic entropy failure to align with FIPS 140-3 § 9.2 fail-safe requirements.

## License

Dual-licensed under either of:
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)