Cryptography and Randomness
Relevant source files
The following files were used as context for generating this wiki page:
The cryptographic and random number generation components are the foundation of qib13. They ensure that the encoding systems are both unpredictable without the master seed and perfectly reproducible with it. The system uses a cryptographically secure, deterministic Random Number Generator (RNG) based on HMAC-SHA256 to derive all necessary components, such as matrices and permutations, from a single master seed.
This deterministic approach is critical for the project's goal of creating a "reproducible multi-deviation seed recovery system." The security of the entire system hinges on the secrecy of the master seed, which acts as the primary source of entropy.
Sources: README.md:14-17, README.md:121-122, index.html:184-185
Deterministic Random Number Generation
The core of the system's reproducibility is the CryptoSeededRandom class, which implements a cryptographically secure deterministic RNG. It uses HMAC-SHA256 in counter mode to generate a stream of random bytes from an initial seed string.
Sources: index.html:422-506, README.md:121-122
Architecture
The RNG is initialized with a seed string (derived from the master seed). It maintains an internal counter and a buffer of random bytes. When random numbers are requested, it draws from the buffer. If the buffer is empty, it generates a new block of 32 random bytes by computing HMAC-SHA256(key, counter), where the key is derived from the initial seed. The counter is then incremented for the next generation.
The implementation attempts to use the browser's native Web Crypto API for performance but includes a pure JavaScript fallback for SHA-256 and HMAC to ensure compatibility in environments where the API is unavailable.
Sources: index.html:187-188, index.html:214-420, index.html:422-453
Class Diagram
This diagram shows the structure of the RNG classes. SeededRandom acts as a compatibility wrapper for CryptoSeededRandom.
Sources: index.html:422-506, index.html:509-521
nextInt() Generation Flow
The nextInt(min, max) method is designed to provide an unbiased random integer within a specified range. It uses rejection sampling to avoid the modulo bias that can occur when mapping a large random number to a smaller range.
This flow ensures a uniform distribution of generated integers, which is critical for creating unbiased random permutations and matrices.
Sources: index.html:488-505
HMAC-SHA256 Byte Generation
The _generateMoreBytesSync method is responsible for refilling the random byte buffer.
This sequence diagram illustrates how a new block of random bytes is generated using the HMAC-SHA256 fallback implementation.
Sources: index.html:455-470, index.html:381-418
System Component Generation
The deterministic RNG is the engine that drives the generation of all EncodingSystem instances. Each system, whether "original" or "deviation," is created by seeding the RNG with a unique string derived from the master seed and a system-specific identifier.
Sources: index.html:774-783, index.html:785-796
Generation Process
The following diagram shows how a master seed is used to generate a complete EncodingSystem.
This process ensures that as long as the master seed is the same, the exact same matrices and permutations will be generated every time.
Sources: index.html:774-796
Key Generation Functions
| Function | Description | Source File | Line Numbers |
|---|---|---|---|
createOriginalSystem(id, seed) | Creates the primary encoding system using a 42x13 matrix P. | index.html | 774-783 |
createDeviationSystem(id, seed) | Creates a deviation system using two matrices: 15x13 P1 and 27x13 P2. | index.html | 785-796 |
generateRandomMatrix(r, c, rng) | Generates a matrix of size r x c with elements from 0-25 using the provided RNG instance. | index.html | 798-807 |
generateRandomPermutation(n, rng) | Generates a permutation of n elements using the Fisher-Yates shuffle algorithm with the provided RNG. | index.html | 809-818 |
These functions are the building blocks for creating the reproducible encoding systems.
Security and Entropy
The security of qib13 is directly tied to the secrecy of the master seed and the entropy it provides. The cryptographic RNG ensures that without the master seed, the generated encoding systems are computationally infeasible to predict.
Sources: README.md:83-86
Entropy Sources
The total entropy of the system is a combination of the master seed, the generator code, and the selected deviation system.
| Component | Entropy Calculation | Example (80-char master, 10 systems) |
|---|---|---|
| Master Seed | L × log₂(26) bits | 80 × log₂(26) ≈ 376 bits |
| Generator Code | 13 × log₂(26) bits | ≈ 61.1 bits |
| Deviation Index | log₂(N) bits | log₂(10) ≈ 3.3 bits |
| Total System | Sum of above | ≈ 440.4 bits |
If the master seed is compromised, the security reduces to the generator code and deviation index entropy (~64.4 bits in the example), which could be vulnerable to brute-force attacks.
Sources: README.md:68-81, README.md:83-89
Fallback Implementations
For environments without the Web Crypto API, index.html includes full JavaScript implementations of SHA-256 and HMAC.
sha256(message): A standard implementation of the SHA-256 hashing algorithm. It follows the standard process of padding, message scheduling, and compression using the defined constants and initial hash values.hmac(key, message): Implements HMAC using thesha256function as its core hash primitive. It handles key padding and performs the double-hashing process withipadandopad.
These fallbacks are crucial for ensuring the tool works offline or in older browsers, but the Web Crypto API is preferred for performance.
Sources: index.html:214-379, index.html:381-418
Conclusion
The cryptographic and randomness features of qib13 are robustly designed around a deterministic HMAC-SHA256 based RNG. This allows for the reproducible generation of complex encoding systems from a single master seed, fulfilling the project's core requirement. The security model is transparent, with its strength founded on the secrecy of the master seed. The inclusion of fallback crypto implementations ensures wide compatibility, making the tool versatile for its intended offline use.