Deterministic Generation
Relevant source files
The following files were used as context for generating this wiki page:
- index.html
- README.md
- I was unable to find 3 more relevant source files.
Introduction
Deterministic generation is the core principle of the qib13 system. It ensures that the entire set of encoding and decoding systems can be reliably and reproducibly generated from a single "Master Seed". This allows a user to work with a simple, memorable 13-character generator code, while the system's security and complexity are derived from the master seed. The same master seed will always generate the exact same set of encoding systems, which is critical for recovering a generator code from a 55-character seed at any point in the future.
The system uses a cryptographically secure pseudo-random number generator (CSPRNG) seeded by the master seed to create all variable components, including matrices and permutations for multiple encoding systems. This ensures that while the components appear random, they are entirely predictable and reproducible given the initial master seed.
Sources: README.md:10-14, 102-104, index.html:175-178
System Architecture
The deterministic generation process is founded on a few key components that work together to create the reproducible encoding environment.
| Component | Description | Source File |
|---|---|---|
| Master Seed | A string of any length that acts as the root of trust. It is the primary source of entropy and the sole input needed to regenerate all encoding systems. | README.md:17-18 |
CryptoSeededRandom | A custom HMAC-SHA256 based CSPRNG. It takes the master seed to produce a deterministic sequence of random numbers. | index.html:418-483 |
| Encoding Systems | A set of objects, each containing matrices and permutations for encoding/decoding. An "original" system and N "deviation" systems are generated. | README.md:21-23 |
Master Seed
The master seed is the foundation of the entire system. It is a user-provided string of any length which is used to seed the random number generator. The security of the system is directly tied to the secrecy and entropy of this master seed. A default master seed is provided for initial use, but users are expected to provide their own for security.
- Default Master Seed:
xtphkxlzrkleosumdxykzmmhzdtaqdsfbzimlwglctrcezpffqtbfhbiakksgwauprtbhfflulpnrbhghbvpnwqhyozkjgsavudi - Custom Master Seed: Can be any string, e.g.,
my-custom-secret-key-2023.
Sources: README.md:30-32, 110-112, index.html:177, 803-805
Cryptographically Secure RNG
The system's determinism is managed by a custom seeded random number generator, CryptoSeededRandom. This class uses an HMAC-SHA256 algorithm in counter mode to produce a sequence of pseudo-random numbers from an initial seed string.
Implementation Details
- Initialization: The
CryptoSeededRandomclass is instantiated with a seed string (derived from the master seed). - Key Derivation: A key for the HMAC function is derived by hashing the seed string with SHA-256.
- Byte Generation: To generate random bytes, the HMAC-SHA256 function is computed on an incrementing counter, using the derived key. This produces a 32-byte buffer of pseudo-random data.
- Number Generation: Integers and floats are extracted from this buffer. When the buffer is exhausted, a new one is generated by incrementing the counter and re-running the HMAC function.
This diagram illustrates the structure of the CryptoSeedenRandom class and its fallback SeededRandom wrapper.
The system includes a fallback pure JavaScript implementation of SHA-256 and HMAC for environments where the Web Crypto API is not available.
Sources: README.md:78-80, index.html:180-483
Encoding System Generation
The generateSystems() function orchestrates the creation of all encoding systems. It takes the master seed and the desired number of deviation systems as input and produces an array of EncodingSystem objects.
This flowchart shows the process of generating the full set of encoding systems from a master seed.
Sources: index.html:800-848
System Creation Functions
Two key functions are responsible for creating the different types of systems:
| Function | Description | Source File |
|---|---|---|
createOriginalSystem(id, seed) | Creates the first system (type 'original'). It uses the seeded RNG to generate one 42x13 matrix (P) and a permutation of 55 elements. | index.html:892-903 |
createDeviationSystem(id, seed) | Creates subsequent systems (type 'deviation'). It uses the seeded RNG to generate two matrices, 15x13 (P1) and 27x13 (P2), and a permutation of 55 elements. | index.html:905-916 |
The seeds passed to these functions are derived from the master seed with a unique suffix for each system, ensuring each system is unique but still deterministically generated from the single master seed.
Sources: README.md:36-39, index.html:821, 832-835
The EncodingSystem Class
This class encapsulates the logic and data for a single encoding/decoding system.
Each instance holds the deterministically generated matrices and permutations required to perform its transformations.
Sources: index.html:488-630
Encoding and Decoding Flow
The deterministic components are used in a precise sequence to transform a generator code into a seed and back.
This sequence diagram shows the encoding process.
The decoding process reverses these steps, using the inverse permutation and verifying the parity data to ensure the seed is valid for the given system.
Sources: README.md:92-100, index.html:514-531, 551-571
Conclusion
The deterministic generation model is the cornerstone of qib13's design. It allows for a "reproducible multi-deviation seed recovery system" where complex encoding schemes can be recreated from a single, memorable master seed. By using a cryptographically secure, seeded RNG, the system guarantees that a user can always recover their original 13-character generator code, provided they have the correct 55-character seed and the original master seed used to create it. This provides a balance of user-friendliness, security, and high reliability for data recovery.
Sources: README.md:10-14, 102-104