Using a Custom Master Seed
Relevant source files
The following files were used as context for generating this wiki page:
The Master Seed is the core component of the qib13 system, serving as the root of trust for all cryptographic operations. It is a user-provided string of any length that deterministically generates the entire set of encoding and decoding systems. Using a unique, secret, and custom master seed is critical for ensuring the security and reproducibility of the seed generation and recovery process.
This document outlines the role of the master seed, how to use a custom one within the application, the underlying generation mechanism it powers, and the security implications associated with its use. The security of the entire qib13 system relies on the secrecy of the master seed.
Sources: README.md
The Role of the Master Seed
The master seed is the foundation for generating all encoding systems. It is the primary source of entropy for the system. While a default master seed is provided for convenience, users must use their own custom master seed to ensure the security of their generated seeds.
| Property | Description |
|---|---|
| Type | String of any length. |
| Function | Serves as the root seed for a cryptographically secure deterministic random number generator (RNG). |
| Security | The secrecy of the master seed is paramount. If compromised, system security reduces to the entropy of the 13-character generator code. |
| Reproducibility | The same master seed will always generate the exact same set of encoding systems, ensuring that a generated seed can be recovered later. |
Sources: README.md, index.html:105-108
System Generation Workflow
When a user provides a custom master seed and requests to generate systems, a deterministic process is initiated to create one "original" system and a specified number of "deviation" systems.
The following diagram illustrates the flow when a user clicks the "Generate Systems" button.
This diagram shows the process of generating encoding systems from a master seed.
Sources: index.html:815-866
User Interface and Interaction
The user interacts with the system generation feature through the "Generate Reproducible Systems" section on the "Generate Systems" tab.
| UI Element | ID | Description |
|---|---|---|
| Master Seed Input | masterSeed | A text field for the user to enter their custom master seed. |
| Number of Systems Input | numSystems | A number input to specify how many deviation systems to generate. |
| Generate Button | (onclick="generateSystems()") | The button that triggers the system generation process using the provided inputs. |
| Use Default Button | (onclick="useDefaultSystems()") | A secondary button to load the default systems using the hardcoded default master seed. |
The following sequence diagram shows the user interaction to generate systems with a custom master seed.
Sources: index.html:99-108, 815-827
Deterministic Generation from Master Seed
The core of the reproducible system is the CryptoSeededRandom class, a cryptographically secure deterministic random number generator (RNG) based on HMAC-SHA256. The master seed is used to initialize this RNG, and every subsequent random number is derived deterministically from it.
To ensure each encoding system is unique yet reproducible, a specific seeding strategy is employed:
- Original System: The RNG is seeded with
masterSeed + "-original-1". - Deviation Systems: The RNG for the i-th system is seeded with
masterSeed + "-deviation-" + i.
This process is visualized below.
This diagram shows how a single master seed is used to generate seeds for multiple unique, deterministic RNGs, which in turn create the encoding systems.
Sources: index.html:902-905, 915-918, README.md
The CryptoSeededRandom Class
This class is the key to deterministic generation. It uses an HMAC-SHA256 implementation in counter mode to produce a stream of random numbers from an initial seed string. The implementation includes a fallback pure-JS SHA-256 and HMAC for environments where the Web Crypto API is not available.
// index.html:426-432
class CryptoSeededRandom {
constructor(seedStr) {
this.seedStr = seedStr || "";
this.counter = 0;
this.buffer = new Uint8Array(32); // SHA-256 produces 32 bytes
this.bufferIndex = 32; // Start with empty buffer
this.initialized = false;
this.useWebCrypto = false;
// Initialize synchronously for compatibility
this._initializeSync();
}
The constructor takes the seedStr (derived from the master seed) and initializes the RNG state.
Sources: index.html:426-474, README.md
Creating Encoding Systems
The createOriginalSystem and createDeviationSystem functions orchestrate the creation of each system. They instantiate the CryptoSeededRandom class with the appropriate derived seed string and then use the RNG instance to generate the required matrices and permutations.
// index.html:901-913
function createOriginalSystem(id, seed) {
const rng = new CryptoSeedenRandom(seed + "-original-" + id);
const matrixP = generateRandomMatrix(42, 13, rng);
const permutation = generateRandomPermutation(55, rng);
const inversePermutation = generateInversePermutation(permutation);
return new EncodingSystem(
id,
'original',
{ P: matrixP },
permutation,
inversePermutation
);
}
Sources: index.html:901-926
Security Implications
The security of the entire qib13 system is anchored to the secrecy of the master seed. The README.md file provides a clear security model.
- With Master Seed Secrecy: The system's total entropy is the sum of the master seed's entropy, the generator code's entropy (61.1 bits), and the deviation index's entropy. A long, random master seed makes the system computationally infeasible to brute-force.
- With Master Seed Compromise: If an attacker obtains the master seed, the security reduces to just the entropy of the generator code and the deviation index. This makes the 13-character generator code vulnerable to brute-force attacks.
Therefore, users must treat their custom master seed as a high-value secret, equivalent to a primary password or private key.
Sources: README.md
Conclusion
Using a custom master seed is a non-negotiable practice for any real-world application of qib13. It transforms the tool from a demonstration into a secure, reproducible system for seed management. By providing a long, unique, and secret string as the master seed, users can leverage the full cryptographic strength of the system's deterministic HMAC-SHA256-based generator to protect their underlying generator codes while benefiting from the memorability and reliability that qib13 offers.