multirandom 0.0.7__tar.gz → 0.1.5__tar.gz

{multirandom-0.0.7 → multirandom-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multirandom
-Version: 0.0.7
+Version: 0.1.5
 Summary: 🎲 The truth external PyPI random package, have trng (true randomness), prng_unsecure, csprng, ...
 Author-email: BlackCatOfficialytb <quanvm0501@gmail.com>
 License: Apache-2.0
@@ -13,6 +13,7 @@ License-File: LICENSE
 Requires-Dist: aiohttp
 Requires-Dist: pyautogui
 Requires-Dist: geopy
+Requires-Dist: pycryptodome>=3.0
 Provides-Extra: microphone
 Requires-Dist: real-random>=0.1.1; extra == "microphone"
 Dynamic: license-file
@@ -30,6 +31,20 @@ A comprehensive library for exploring and generating randomness across the spect
 
 ---
 
+## 📚 Full Documentation
+
+Deep-dive docs live in [`docs/`](docs/):
+
+| Page | Contents |
+|---|---|
+| [Getting started](docs/getting-started.md) | installation, quickstart, which generator to pick |
+| [True randomness (`trng`)](docs/trng.md) | mouse clicks, quantum APIs, microphone, weather |
+| [Cryptographic randomness (`csprng`)](docs/csprng.md) | OS CSPRNGs, NIST DRBGs, the Dual_EC backdoor demo, Keccak sponge, Blum Blum Shub, RDRAND |
+| [Unsecure PRNGs (`prng_unsecure`)](docs/prng_unsecure.md) | XorShift/Xoshiro, LCGs, Doom, PCG32, V8's Math.random, and their reversal attacks |
+| [Self-checks](docs/self-checks.md) | the assert batteries verifying every generator |
+
+---
+
 ## 🏗 Project Structure
 
 ```text
@@ -40,15 +55,32 @@ multirandom/
         │   ├── rand_via_clicks.py        # Human-in-the-loop entropy
         │   ├── rand_using_online_api.py  # Quantum & Hardware APIs (ANU QRNG, Roll-API)
         │   ├── rand_using_real_random.py # Microphone entropy (real-random)
-        │   └── weather_rand.py           # [Coming Soon] Weather-based entropy
+        │   └── weather_rand.py           # Open-Meteo weather entropy (large unhashed seeds)
         ├── csprng/             # Cryptographically Strong Randomness
-        │   ├── secure_rand.py            # OS CSPRNGs, NIST DRBGs, Fortuna/Yarrow, ISAAC
+        │   ├── os_random.py              # OS CSPRNGs (secrets, urandom, getrandom, BCrypt, SecRandom)
+        │   ├── ctr_drbg.py / hmac_drbg.py / hash_drbg.py   # NIST SP 800-90A DRBGs
+        │   ├── dual_ec_drbg.py           # the backdoored DRBG, live
+        │   ├── chacha20_drbg.py / salsa20_drbg.py          # stream-cipher DRBGs
+        │   ├── fortuna.py / yarrow.py / isaac.py           # pools and the classics
+        │   ├── sponge_drbg.py            # Keccak-f[1600] sponge DRBG (from scratch)
+        │   ├── ansi_x931.py              # ANS X9.17/X9.31, the banking generator
+        │   ├── blum_blum_shub.py         # factoring-hard, one bit per squaring
+        │   ├── rdrand_hardware.py        # RDRAND / RDSEED CPU instructions
+        │   ├── _aes.py                   # the library AES (FIPS-197 KATs)
         │   ├── sha_rand.py               # MD5, SHA-1/2/3, BLAKE2, SHAKE PRNGs
         │   └── original_random.py        # Wrapper for Python's built-in random
         └── prng_unsecure/      # Mathematical Randomness (UNSECURE PRNGs)
             ├── xor_shift.py              # XorShift & Xoshiro Family
-            ├── rand_using_virt_lcg.py    # Linear Congruential Generators (LCGs)
-            └── flash_rand_and_reverse.py # [Coming Soon] Specialized PRNGs
+            ├── mersenne_twister.py       # MT19937 + the 624-output clone attack
+            ├── lcg.py                    # Linear Congruential Generators (LCGs)
+            ├── flash_player_prng.py      # Flash Player Math.random() + its reversal attacks
+            ├── randu.py                  # IBM's RANDU, the 15-planes generator
+            ├── middle_square.py          # von Neumann's middle square + MSWS
+            ├── doom_prng.py              # Doom's 256-entry lookup table
+            ├── splitmix64.py             # SplitMix64, inverted exactly
+            ├── lagged_fibonacci.py       # BSD-style LF(31, 3); last j outputs = state
+            ├── pcg.py                    # O'Neill's PCG32, closed-form jump
+            └── v8_xorshift128plus.py     # Math.random()'s engine + the GF(2) seed solve
 ```
 
 ---
@@ -95,7 +127,31 @@ Run `python -m multirandom.prng_unsecure.xor_shift` to check every generator aga
 ### 4. Mathematical LCGs (`prng_unsecure`)
 Classic Linear Congruential Generators with customizable shift parameters. Includes `reverse_roll()` methods to demonstrate the insecurity of simple modular arithmetic.
 
-### 5. Hash-based Generators (`csprng`)
+### 5. Iconic & historic PRNGs (`prng_unsecure`)
+The famous, the infamous, and the ones running inside your favourite games —
+each module ships its reference vectors and its own reversal.
+
+- **IBM's RANDU** (`randu`): the 15-planes generator; one output recovers the seed via the modular inverse of 65539.
+- **Middle Square** (`middle_square`): von Neumann's 1949 idea, plus the MSWS variant.
+- **Doom's RNG** (`doom_prng`): the 256-entry lookup table behind every shotgun spread, increment-then-index; one draw pins the index.
+- **SplitMix64** (`splitmix64`): the seeding engine behind xoshiro; the mixer is inverted exactly from one output.
+- **Lagged Fibonacci** (`lagged_fibonacci`): the BSD `random()`-style LF(31, 3); the last j outputs ARE the state.
+- **PCG32** (`pcg`): O'Neill's permutation-on-an-LCG — the "good" end, with a closed-form `jump()` for a billion outputs in one call.
+- **V8's XorShift128+** (`v8_xorshift128plus`): JavaScript's `Math.random()` engine; five consecutive doubles recover the exact 128-bit seed by GF(2) elimination.
+
+```python
+from multirandom.prng_unsecure.doom_prng import DoomRandom
+from multirandom.prng_unsecure.v8_xorshift128plus import V8XorShift128Plus
+
+doom = DoomRandom()
+doom.P_Random()                     # the same table the game rolls
+
+v8 = V8XorShift128Plus(seed="demo")
+clone = V8XorShift128Plus.from_outputs([v8.random() for _ in range(5)])
+clone.getstate() == v8.getstate()   # True: Math.random, predicted exactly
+```
+
+### 6. Hash-based Generators (`csprng`)
 Counter-mode hash DRBGs: `H(seed || counter)` drives the full `random.Random` API.
 
 - **SHA-2**: SHA-224, SHA-256, SHA-384, SHA-512
@@ -111,7 +167,7 @@ gen = BLAKE2bRandom("my seed")
 print(gen.randbytes(16).hex(), gen.random(), gen.choice(["a", "b"]))
 ```
 
-### 6. Cryptographically Strong Generators (`csprng/secure_rand`)
+### 7. Cryptographically Strong Generators (`csprng`)
 The ones to actually guard things with, plus deliberately broken ones that teach.
 
 **OS-level CSPRNGs** (live entropy, behave like `random.SystemRandom` — seeding
@@ -136,14 +192,23 @@ the native API is not reachable on the running platform.
 - `Hash_DRBG` – SHA-256 with Hash_df (440-bit state)
 - `Dual_EC_DRBG` — *deliberately backdoored*, kept as a teaching exhibit
 
-**Stream / accumulator designs**: `ChaCha20DRBG`, `Salsa20DRBG` (counter-mode
-DRBGs on the two classic stream ciphers), `FortunaRandom` (32 seed pools +
-AES-256-CTR, rekey every 65536 blocks, `add_entropy(data, pool)`) and its
-legacy predecessor `YarrowRandom` (fast/slow pools, AES-192-CTR), plus
-`ISAACRandom` (Bob Jenkins' ISAAC, validated against his reference vectors).
+**Stream / accumulator / sponge designs**: `ChaCha20DRBG`, `Salsa20DRBG`
+(counter-mode DRBGs on the two classic stream ciphers), `FortunaRandom`
+(32 seed pools + AES-256-CTR, rekey every 65536 blocks,
+`add_entropy(data, pool)`) and its legacy predecessor `YarrowRandom`
+(fast/slow pools, AES-192-CTR), `ISAACRandom` (Bob Jenkins' ISAAC, validated
+against his reference vectors), `SpongeDRBG` (a sponge-mode DRBG on a
+hand-transcribed Keccak-f[1600], pinned against `hashlib`), and
+`AnsiX931DRBG` (the banking world's ANS X9.17/X9.31 generator).
+
+**Factoring-hard and hardware**: `BlumBlumShub`
+(x' = x² mod n — one provably factoring-hard bit per squaring, genuine Blum
+primes enforced by a self-contained Miller-Rabin) and the CPU's own entropy
+instructions `RDRANDRandom` / `RDSEEDRandom` (x86-64 shellcode through
+ctypes, probed availability).
 
 ```python
-from multirandom.csprng.secure_rand import SecretsRandom, CTR_DRBG, Dual_EC_DRBG
+from multirandom.csprng import SecretsRandom, CTR_DRBG, Dual_EC_DRBG
 
 gen = SecretsRandom()
 print(gen.token_hex(32))            # live kernel entropy
@@ -178,7 +243,7 @@ module ships with this demo running in its own self-checks at
 `truncate_bits=8`. It warns on first use. Never use it for real randomness.
 
 ```python
-# Run its assert battery: python -m multirandom.csprng.secure_rand
+# Run the DRBG sweep: python -m multirandom.csprng._drbg_base
 ```
 
 ### The global unsecure-prng warning switch
@@ -200,7 +265,7 @@ multirandom.ignore_unsecure_prng_warning_do_not_set_to_true_unless_you_know_how_
 
 ### Requirements
 - Python 3.9+
-- Dependencies listed in `requirements.txt` (e.g., `pyautogui`, `aiohttp`)
+- Dependencies listed in `requirements.txt` (e.g., `pyautogui`, `aiohttp`, `pycryptodome`)
 
 ### Installation
 ```bash

{multirandom-0.0.7 → multirandom-0.1.5}/README.md

@@ -11,6 +11,20 @@ A comprehensive library for exploring and generating randomness across the spect
 
 ---
 
+## 📚 Full Documentation
+
+Deep-dive docs live in [`docs/`](docs/):
+
+| Page | Contents |
+|---|---|
+| [Getting started](docs/getting-started.md) | installation, quickstart, which generator to pick |
+| [True randomness (`trng`)](docs/trng.md) | mouse clicks, quantum APIs, microphone, weather |
+| [Cryptographic randomness (`csprng`)](docs/csprng.md) | OS CSPRNGs, NIST DRBGs, the Dual_EC backdoor demo, Keccak sponge, Blum Blum Shub, RDRAND |
+| [Unsecure PRNGs (`prng_unsecure`)](docs/prng_unsecure.md) | XorShift/Xoshiro, LCGs, Doom, PCG32, V8's Math.random, and their reversal attacks |
+| [Self-checks](docs/self-checks.md) | the assert batteries verifying every generator |
+
+---
+
 ## 🏗 Project Structure
 
 ```text
@@ -21,15 +35,32 @@ multirandom/
         │   ├── rand_via_clicks.py        # Human-in-the-loop entropy
         │   ├── rand_using_online_api.py  # Quantum & Hardware APIs (ANU QRNG, Roll-API)
         │   ├── rand_using_real_random.py # Microphone entropy (real-random)
-        │   └── weather_rand.py           # [Coming Soon] Weather-based entropy
+        │   └── weather_rand.py           # Open-Meteo weather entropy (large unhashed seeds)
         ├── csprng/             # Cryptographically Strong Randomness
-        │   ├── secure_rand.py            # OS CSPRNGs, NIST DRBGs, Fortuna/Yarrow, ISAAC
+        │   ├── os_random.py              # OS CSPRNGs (secrets, urandom, getrandom, BCrypt, SecRandom)
+        │   ├── ctr_drbg.py / hmac_drbg.py / hash_drbg.py   # NIST SP 800-90A DRBGs
+        │   ├── dual_ec_drbg.py           # the backdoored DRBG, live
+        │   ├── chacha20_drbg.py / salsa20_drbg.py          # stream-cipher DRBGs
+        │   ├── fortuna.py / yarrow.py / isaac.py           # pools and the classics
+        │   ├── sponge_drbg.py            # Keccak-f[1600] sponge DRBG (from scratch)
+        │   ├── ansi_x931.py              # ANS X9.17/X9.31, the banking generator
+        │   ├── blum_blum_shub.py         # factoring-hard, one bit per squaring
+        │   ├── rdrand_hardware.py        # RDRAND / RDSEED CPU instructions
+        │   ├── _aes.py                   # the library AES (FIPS-197 KATs)
         │   ├── sha_rand.py               # MD5, SHA-1/2/3, BLAKE2, SHAKE PRNGs
         │   └── original_random.py        # Wrapper for Python's built-in random
         └── prng_unsecure/      # Mathematical Randomness (UNSECURE PRNGs)
             ├── xor_shift.py              # XorShift & Xoshiro Family
-            ├── rand_using_virt_lcg.py    # Linear Congruential Generators (LCGs)
-            └── flash_rand_and_reverse.py # [Coming Soon] Specialized PRNGs
+            ├── mersenne_twister.py       # MT19937 + the 624-output clone attack
+            ├── lcg.py                    # Linear Congruential Generators (LCGs)
+            ├── flash_player_prng.py      # Flash Player Math.random() + its reversal attacks
+            ├── randu.py                  # IBM's RANDU, the 15-planes generator
+            ├── middle_square.py          # von Neumann's middle square + MSWS
+            ├── doom_prng.py              # Doom's 256-entry lookup table
+            ├── splitmix64.py             # SplitMix64, inverted exactly
+            ├── lagged_fibonacci.py       # BSD-style LF(31, 3); last j outputs = state
+            ├── pcg.py                    # O'Neill's PCG32, closed-form jump
+            └── v8_xorshift128plus.py     # Math.random()'s engine + the GF(2) seed solve
 ```
 
 ---
@@ -76,7 +107,31 @@ Run `python -m multirandom.prng_unsecure.xor_shift` to check every generator aga
 ### 4. Mathematical LCGs (`prng_unsecure`)
 Classic Linear Congruential Generators with customizable shift parameters. Includes `reverse_roll()` methods to demonstrate the insecurity of simple modular arithmetic.
 
-### 5. Hash-based Generators (`csprng`)
+### 5. Iconic & historic PRNGs (`prng_unsecure`)
+The famous, the infamous, and the ones running inside your favourite games —
+each module ships its reference vectors and its own reversal.
+
+- **IBM's RANDU** (`randu`): the 15-planes generator; one output recovers the seed via the modular inverse of 65539.
+- **Middle Square** (`middle_square`): von Neumann's 1949 idea, plus the MSWS variant.
+- **Doom's RNG** (`doom_prng`): the 256-entry lookup table behind every shotgun spread, increment-then-index; one draw pins the index.
+- **SplitMix64** (`splitmix64`): the seeding engine behind xoshiro; the mixer is inverted exactly from one output.
+- **Lagged Fibonacci** (`lagged_fibonacci`): the BSD `random()`-style LF(31, 3); the last j outputs ARE the state.
+- **PCG32** (`pcg`): O'Neill's permutation-on-an-LCG — the "good" end, with a closed-form `jump()` for a billion outputs in one call.
+- **V8's XorShift128+** (`v8_xorshift128plus`): JavaScript's `Math.random()` engine; five consecutive doubles recover the exact 128-bit seed by GF(2) elimination.
+
+```python
+from multirandom.prng_unsecure.doom_prng import DoomRandom
+from multirandom.prng_unsecure.v8_xorshift128plus import V8XorShift128Plus
+
+doom = DoomRandom()
+doom.P_Random()                     # the same table the game rolls
+
+v8 = V8XorShift128Plus(seed="demo")
+clone = V8XorShift128Plus.from_outputs([v8.random() for _ in range(5)])
+clone.getstate() == v8.getstate()   # True: Math.random, predicted exactly
+```
+
+### 6. Hash-based Generators (`csprng`)
 Counter-mode hash DRBGs: `H(seed || counter)` drives the full `random.Random` API.
 
 - **SHA-2**: SHA-224, SHA-256, SHA-384, SHA-512
@@ -92,7 +147,7 @@ gen = BLAKE2bRandom("my seed")
 print(gen.randbytes(16).hex(), gen.random(), gen.choice(["a", "b"]))
 ```
 
-### 6. Cryptographically Strong Generators (`csprng/secure_rand`)
+### 7. Cryptographically Strong Generators (`csprng`)
 The ones to actually guard things with, plus deliberately broken ones that teach.
 
 **OS-level CSPRNGs** (live entropy, behave like `random.SystemRandom` — seeding
@@ -117,14 +172,23 @@ the native API is not reachable on the running platform.
 - `Hash_DRBG` – SHA-256 with Hash_df (440-bit state)
 - `Dual_EC_DRBG` — *deliberately backdoored*, kept as a teaching exhibit
 
-**Stream / accumulator designs**: `ChaCha20DRBG`, `Salsa20DRBG` (counter-mode
-DRBGs on the two classic stream ciphers), `FortunaRandom` (32 seed pools +
-AES-256-CTR, rekey every 65536 blocks, `add_entropy(data, pool)`) and its
-legacy predecessor `YarrowRandom` (fast/slow pools, AES-192-CTR), plus
-`ISAACRandom` (Bob Jenkins' ISAAC, validated against his reference vectors).
+**Stream / accumulator / sponge designs**: `ChaCha20DRBG`, `Salsa20DRBG`
+(counter-mode DRBGs on the two classic stream ciphers), `FortunaRandom`
+(32 seed pools + AES-256-CTR, rekey every 65536 blocks,
+`add_entropy(data, pool)`) and its legacy predecessor `YarrowRandom`
+(fast/slow pools, AES-192-CTR), `ISAACRandom` (Bob Jenkins' ISAAC, validated
+against his reference vectors), `SpongeDRBG` (a sponge-mode DRBG on a
+hand-transcribed Keccak-f[1600], pinned against `hashlib`), and
+`AnsiX931DRBG` (the banking world's ANS X9.17/X9.31 generator).
+
+**Factoring-hard and hardware**: `BlumBlumShub`
+(x' = x² mod n — one provably factoring-hard bit per squaring, genuine Blum
+primes enforced by a self-contained Miller-Rabin) and the CPU's own entropy
+instructions `RDRANDRandom` / `RDSEEDRandom` (x86-64 shellcode through
+ctypes, probed availability).
 
 ```python
-from multirandom.csprng.secure_rand import SecretsRandom, CTR_DRBG, Dual_EC_DRBG
+from multirandom.csprng import SecretsRandom, CTR_DRBG, Dual_EC_DRBG
 
 gen = SecretsRandom()
 print(gen.token_hex(32))            # live kernel entropy
@@ -159,7 +223,7 @@ module ships with this demo running in its own self-checks at
 `truncate_bits=8`. It warns on first use. Never use it for real randomness.
 
 ```python
-# Run its assert battery: python -m multirandom.csprng.secure_rand
+# Run the DRBG sweep: python -m multirandom.csprng._drbg_base
 ```
 
 ### The global unsecure-prng warning switch
@@ -181,7 +245,7 @@ multirandom.ignore_unsecure_prng_warning_do_not_set_to_true_unless_you_know_how_
 
 ### Requirements
 - Python 3.9+
-- Dependencies listed in `requirements.txt` (e.g., `pyautogui`, `aiohttp`)
+- Dependencies listed in `requirements.txt` (e.g., `pyautogui`, `aiohttp`, `pycryptodome`)
 
 ### Installation
 ```bash

{multirandom-0.0.7 → multirandom-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "multirandom"
-version = "0.0.7"
+version = "0.1.5"
 authors = [
   { name="BlackCatOfficialytb", email="quanvm0501@gmail.com" },
 ]
@@ -18,8 +18,9 @@ classifiers = [
 ]
 dependencies = [
     "aiohttp",
-	  "pyautogui",
-    "geopy"
+    "pyautogui",
+    "geopy",
+    "pycryptodome>=3.0"
 ]
 
 [project.optional-dependencies]

{multirandom-0.0.7 → multirandom-0.1.5}/src/multirandom/__init__.py

@@ -1,8 +1,14 @@
-"""multirandom - one random-number package, several philosophies of chance.
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom
+Description:
+One random-number package, several philosophies of chance:
 
-* ``prng_unsecure/`` - educational PRNGs that must never guard anything (LCGs, xorshift).
-* ``csprng/``       - cryptographically strong generators (OS entropy, NIST DRBGs, stream ciphers).
 * ``trng/``         - true/hardware entropy sources (microphones, weather, clicks, online APIs).
+* ``csprng/``       - cryptographically strong generators (OS entropy, NIST DRBGs, stream ciphers).
+* ``prng_unsecure/`` - educational PRNGs that must never guard anything (LCGs, xorshift).
 
 Everything in ``prng_unsecure/`` and the deliberately broken ``Dual_EC_DRBG`` warns the
 first time it is used. Those warnings are controlled by ONE global variable::

multirandom-0.1.5/src/multirandom/csprng/__init__.py

@@ -0,0 +1,104 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.csprng
+Description:
+Cryptographically strong randomness ("csprng") -- one module per method:
+
+1. OS-level CSPRNGs - the sources you should actually use
+   (:mod:`multirandom.csprng.os_random`): :class:`SecretsRandom` (the
+   ``secrets`` module), :class:`OSURandom` (``os.urandom``),
+   :class:`GetRandomRandom` (Linux ``getrandom(2)``),
+   :class:`BCryptGenRandomRandom` (Windows ``BCryptGenRandom``) and
+   :class:`SecRandomCopyBytesRandom` (Apple ``SecRandomCopyBytes``).  The
+   ctypes ones fall back gracefully to ``os.urandom`` (the very same kernel
+   entropy pool) when the native API is not reachable on the running
+   platform.
+
+2. NIST SP 800-90A DRBGs: :class:`CTR_DRBG` (AES-128, via the crypto
+   library), :class:`HMAC_DRBG` and :class:`Hash_DRBG` (SHA-256) - plus the
+   infamous *backdoored* :class:`Dual_EC_DRBG`, kept deliberately: it warns
+   loudly and shows how its backdoor is exploited with
+   ``Dual_EC_DRBG.reveal`` (its own module: ``dual_ec_drbg``).
+
+3. Stream/accumulator designs: :class:`ChaCha20DRBG`
+   (``chacha20_drbg``), :class:`Salsa20DRBG` (``salsa20_drbg``),
+   :class:`FortunaRandom` (``fortuna``) and its legacy predecessor
+   :class:`YarrowRandom` (``yarrow``), plus :class:`ISAACRandom`
+   (``isaac`` - Bob Jenkins' ISAAC, transcribed from the author's
+   ``readable.c``) and :class:`SpongeDRBG` (``sponge_drbg`` - a sponge-mode
+   DRBG on a from-scratch Keccak-f[1600], KAT-pinned against ``hashlib``).
+
+4. The classics: :class:`AnsiX931DRBG` (``ansi_x931`` - ANS X9.17/X9.31,
+   the banking-world generator) and :class:`BlumBlumShub`
+   (``blum_blum_shub`` - one provably factoring-hard bit per squaring).
+
+5. The CPU's own entropy instructions (``rdrand_hardware``): the
+   :class:`RDRANDRandom` and :class:`RDSEEDRandom` hardware TRNGs, run
+   through x64 shellcode stubs - probed, never assumed.
+
+Every DRBG class is a ``random.Random`` subclass, so ``.random()``,
+``.randint()``, ``.choice()``, ``.shuffle()`` ... all work on top of the
+cryptographic core.  Everything without a restorable state (the OS-level
+sources) behaves like ``random.SystemRandom``: seeding is a no-op and
+``getstate()``/``setstate()`` raise ``NotImplementedError``.
+
+The raw AES used by CTR_DRBG / Fortuna / Yarrow comes from an installed
+crypto library (pycryptodome / pycryptodomex, with ``cryptography`` as a
+fallback) - see :mod:`multirandom.csprng._aes`; the shared ``random.Random``
+plumbing of the seedable DRBGs lives in
+:mod:`multirandom.csprng._drbg_base`.
+
+Unsecure- or backdoor-related warnings here are governed by one global
+switch in the package root::
+
+    import multirandom
+    multirandom.ignore_unsecure_prng_warning_do_not_set_to_true_unless_you_know_how_risky_it_is
+
+``False`` (the default) sends those warnings to the console; ``True``
+silences them.
+"""
+from .os_random import (
+    SecretsRandom, OSURandom, GetRandomRandom,
+    BCryptGenRandomRandom, SecRandomCopyBytesRandom,
+)
+from .ctr_drbg import CTR_DRBG
+from .hmac_drbg import HMAC_DRBG
+from .hash_drbg import Hash_DRBG
+from .dual_ec_drbg import Dual_EC_DRBG
+from .chacha20_drbg import ChaCha20DRBG
+from .salsa20_drbg import Salsa20DRBG
+from .fortuna import FortunaRandom
+from .yarrow import YarrowRandom
+from .isaac import ISAACRandom
+from .sponge_drbg import SpongeDRBG
+from .ansi_x931 import AnsiX931DRBG
+from .blum_blum_shub import BlumBlumShub
+from .rdrand_hardware import RDRANDRandom, RDSEEDRandom
+
+DRBG_GENERATORS = [
+    CTR_DRBG, HMAC_DRBG, Hash_DRBG, Dual_EC_DRBG,
+    ChaCha20DRBG, Salsa20DRBG, FortunaRandom, YarrowRandom, ISAACRandom,
+    SpongeDRBG, AnsiX931DRBG,
+]
+# BlumBlumShub is deliberately absent: its constructor demands the Blum
+# prime pair (it is not a seed-only DRBG), so the generic seedable-DRBG
+# sweep cannot construct it.  It ships its own battery instead.
+
+OS_GENERATORS = [
+    SecretsRandom, OSURandom, GetRandomRandom,
+    BCryptGenRandomRandom, SecRandomCopyBytesRandom,
+]
+
+HW_GENERATORS = [RDRANDRandom, RDSEEDRandom]
+
+__all__ = [
+    "SecretsRandom", "OSURandom", "GetRandomRandom",
+    "BCryptGenRandomRandom", "SecRandomCopyBytesRandom",
+    "CTR_DRBG", "HMAC_DRBG", "Hash_DRBG", "Dual_EC_DRBG",
+    "ChaCha20DRBG", "Salsa20DRBG", "FortunaRandom", "YarrowRandom", "ISAACRandom",
+    "SpongeDRBG", "AnsiX931DRBG", "BlumBlumShub",
+    "RDRANDRandom", "RDSEEDRandom",
+    "DRBG_GENERATORS", "OS_GENERATORS", "HW_GENERATORS",
+]

multirandom-0.1.5/src/multirandom/csprng/_aes.py

@@ -0,0 +1,148 @@
+"""
+Project: https://pypi.org/project/multirandom/
+Repo: https://github.com/BlackCatOfficialytb/multirandom
+License: Apache 2.0
+Module: multirandom.csprng._aes
+Description:
+The raw AES core shared by the csprng modules that need block-level AES
+(``CTR_DRBG``, ``FortunaRandom``, ``YarrowRandom``, and ANSI X9.31).
+
+The arithmetic -- key schedule, SubBytes/MixColumns, the ECB mode -- is
+delegated to an audited library implementation (``pycryptodome``, with
+``pycryptodomex`` or ``cryptography`` accepted as drop-in alternates),
+replacing the hand-rolled AES that used to live in ``secure_rand.py``.
+What survives here is only the *shape* the DRBG modules are specced
+against: ``encrypt_block(block)`` (one 16-byte ECB encryption -- the
+primitive CTR_DRBG's (K, V) iterator and ANSI X9.31 run on) and
+``ctr(counter, n)`` (big-endian-counter keystream, Fortuna's generator).
+
+FIPS-197 known-answer tests still run in ``__main__`` to prove the wiring::
+
+    py -3 -m multirandom.csprng._aes
+"""
+from __future__ import annotations
+
+# --- pick the AES library: pycryptodome > pycryptodomex > cryptography ------
+try:
+    from Crypto.Cipher import AES as _pyc_aes        # pycryptodome
+except ImportError:
+    try:
+        from Cryptodome.Cipher import AES as _pyc_aes  # pycryptodomex
+    except ImportError:
+        _pyc_aes = None
+
+if _pyc_aes is None:
+    try:                     # the cryptography package as the last resort
+        from cryptography.hazmat.primitives.ciphers import (
+            Cipher as _cipher, algorithms as _algorithms, modes as _modes)
+    except ImportError:
+        raise ImportError(
+            "multirandom.csprng needs an AES implementation: install "
+            "pycryptodome (pip install pycryptodome) or the cryptography "
+            "package") from None
+
+
+class _Aes:
+    """AES-128/192/256 single-block encryptor + CTR keystream helper.
+
+    Interface kept from the legacy hand-rolled AES so the DRBG modules
+    read exactly as before; the one-round-of-AES-per-call arithmetic is
+    now the installed library's (FIPS-validated implementation, no hand
+    transcription to get wrong).
+    """
+
+    def __init__(self, key):
+        key = bytes(key)
+        if len(key) not in (16, 24, 32):
+            raise ValueError("AES key must be 16, 24 or 32 bytes")
+        self._key = key
+        if _pyc_aes is not None:
+            # ECB is stateless: one cipher object serves every block.
+            self._ecb = _pyc_aes.new(key, _pyc_aes.MODE_ECB)
+            self._backend = "pycryptodome"
+        else:
+            self._ecb = _cipher(
+                _algorithms.AES(key), _modes.ECB()).encryptor()
+            self._backend = "cryptography"
+
+    def encrypt_block(self, block):
+        """AES-ECB of exactly one 16-byte block."""
+        block = bytes(block)
+        if len(block) != 16:
+            raise ValueError("AES blocks are 16 bytes")
+        if self._backend == "pycryptodome":
+            return self._ecb.encrypt(block)
+        return self._ecb.update(block)
+
+    def ctr(self, counter, n):
+        """``n`` bytes of AES-CTR keystream for a 128-bit big-endian counter."""
+        out = bytearray()
+        while len(out) < n:
+            out += self.encrypt_block(counter.to_bytes(16, "big"))
+            counter = (counter + 1) % (1 << 128)
+        return bytes(out[:n])
+
+
+
+def main():
+    print("=" * 70)
+    print("_aes - FIPS-197 wiring self-check battery")
+    print("=" * 70)
+
+    # --- 1. FIPS-197 appendix C known-answer tests ---------------------------
+    fips_pt = bytes.fromhex("00112233445566778899aabbccddeeff")
+    fips_key = bytes(range(16))
+    aes = _Aes(fips_key)
+    assert aes.encrypt_block(fips_pt) == \
+        bytes.fromhex("69c4e0d86a7b0430d8cdb78070b4c55a"), "AES-128 KAT failed"
+    assert _Aes(bytes(range(24))).encrypt_block(fips_pt) == \
+        bytes.fromhex("dda97ca4864cdfe06eaf70a0ec0d7191"), "AES-192 KAT failed"
+    assert _Aes(bytes(range(32))).encrypt_block(fips_pt) == \
+        bytes.fromhex("8ea2b7ca516745bfeafc49904b496089"), "AES-256 KAT failed"
+    print(f"[1] FIPS-197 AES-128/192/256 KATs ({aes._backend} core): OK")
+
+    # --- 2. ECB eats complete, and only complete, blocks ----------------------
+    for bad_len in (0, 1, 15, 17, 32):
+        try:
+            aes.encrypt_block(b"\x00" * bad_len)
+        except ValueError:
+            pass
+        else:
+            raise AssertionError(f"block of {bad_len} bytes accepted")
+    for bad_key_len in (0, 8, 17, 33):
+        try:
+            _Aes(b"\x00" * bad_key_len)
+        except ValueError:
+            pass
+        else:
+            raise AssertionError(f"key of {bad_key_len} bytes accepted")
+    print("[2] only 16-byte blocks and 16/24/32-byte keys accepted: OK")
+
+    # --- 3. the CTR keystream is the concatenation of ECB(counter + i) --------
+    key = bytes.fromhex("000102030405060708090a0b0c0d0e0f")
+    counter = int.from_bytes(
+        bytes.fromhex("00112233445566778899aabbccddeeff"), "big")
+    runs = _Aes(key)
+    manual = (runs.encrypt_block(counter.to_bytes(16, "big"))
+              + runs.encrypt_block(((counter + 1) % (1 << 128)).to_bytes(16, "big"))
+              + runs.encrypt_block(((counter + 2) % (1 << 128)).to_bytes(16, "big")))
+    assert runs.ctr(counter, 40) == manual[:40], "CTR keystream drifted"
+    assert runs.ctr(counter, 48) == manual, "CTR keystream wrong at block edges"
+    assert runs.ctr(counter, 1) == manual[:1], "CTR short request wrong"
+    block4 = runs.encrypt_block(((counter + 3) % (1 << 128)).to_bytes(16, "big"))
+    assert runs.ctr(counter, 49) == manual + block4[:1], "CTR carry-over wrong"
+    print("[3] ctr() == ECB on counter, counter+1, ... (block edges exact): OK")
+
+    # --- 4. CTR round trip through XOR (the way the DRBGs use it) -------------
+    stream = runs.ctr(counter, 64)
+    assert bytes(x ^ y for x, y in zip(stream, stream)) == bytes(64)
+    assert len({runs.ctr(counter, 32)[i] for i in range(32)}) > 12, \
+        "flat keystream?! the library AES looks broken"
+    print("[4] keystream XORs back to zero, byte spread sane: OK")
+
+    print("-" * 70)
+    print("All _aes checks passed!")
+
+
+if __name__ == "__main__":
+    main()