Security Best Practices

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• index.html
• js/crypto.js (derived from index.html)
• js/encoding.js (derived from index.html)
• js/app.js (derived from index.html)

The qib13 tool is a mnemonic-like system for reproducible seed recovery. Its security architecture is designed to protect a low-entropy, memorable generatorCode by leveraging a high-entropy, secret masterSeed. The core security principle is the deterministic generation of encoding systems from this master seed, ensuring that while the generator code is easy to remember, the final seed is cryptographically secure as long as the master seed remains confidential.

A primary security recommendation is to run the index.html file offline to minimize exposure to online threats. The security of the entire system is critically dependent on the secrecy of the master seed. If the master seed is compromised, the security is reduced to the entropy of the 13-character generator code, which is vulnerable to brute-force attacks.

Sources: README.md:3, 23-26, 80-87

Core Security Components

The system's security relies on two main user-provided inputs: the masterSeed and the generatorCode.

Component	Description	Security Role
Master Seed	A string of any length that serves as the root of trust. It is used to deterministically generate all encoding systems.	The primary source of entropy. Its secrecy is paramount. A longer, more complex master seed significantly increases the system's security.
Generator Code	A 13-character string (a-z) that is encoded into a 55-character seed.	A low-entropy, memorable input. It is not intended to be the primary security component. Its entropy is approximately 61.1 bits.
Deviation Index	The index of the specific encoding system used.	Adds a small amount of entropy, making it harder to identify patterns if the master seed is compromised.

Sources: README.md:20-22, 30-36, 70-78

Entropy Analysis

The total entropy of the system is a combination of its components. The security is fundamentally tied to the master seed's entropy.

This diagram shows the components contributing to the system's total entropy.

• Master Seed Entropy: L × log₂(26) bits, where L is the length. For an 80-character seed, this is ~376 bits.
• Generator Code Entropy: 13 × log₂(26) bits, which is ~61.1 bits.
• Total Entropy: With an 80-character master seed and 10 deviation systems, the total entropy is approximately 440.4 bits, making brute-force attacks computationally infeasible.

Sources: README.md:70-78

Cryptographically Secure Deterministic RNG

A critical security feature is the use of a cryptographically secure, deterministic random number generator (RNG) for creating the encoding systems. This ensures that the systems are reproducible from the master seed but unpredictable without it. The implementation uses HMAC-SHA256 in counter mode.

Sources: README.md:10, 108-110, js/crypto.js (from index.html:400-456)

CryptoSeededRandom Class

The CryptoSeededRandom class is responsible for generating all random data needed for system creation.

This diagram shows the structure of the CryptoSeededRandom class.

Sources: js/crypto.js (from index.html:400-456)

RNG Generation Flow

The RNG is initialized with a seed string (derived from the master seed) and generates a stream of random numbers.

1. The seedStr is hashed using SHA-256 to create a secret key.
2. To generate random bytes, the HMAC-SHA256 of the key and an incrementing counter is computed.
3. The result is stored in a buffer.
4. Numbers are drawn from this buffer. When the buffer is empty, step 2 is repeated with an incremented counter.

This flow ensures that the sequence of random numbers is deterministic for a given master seed but computationally difficult to predict otherwise.

This flowchart illustrates the process of generating a random number from the master seed.

Sources: js/crypto.js (from index.html:413-441)

A fallback SHA-256 and HMAC implementation is included for environments where the Web Crypto API is not available.

Sources: js/crypto.js (from index.html:191-398)

System Generation and Security

The security of the encoding/decoding process is rooted in the deterministic but unpredictable generation of encoding systems.

System Generation Flow

The generateSystems function orchestrates the creation of one "original" system and multiple "deviation" systems using the masterSeed.

This sequence diagram shows how user interaction leads to the creation of secure, deterministic encoding systems.

Sources: js/app.js (from index.html:664-718), js/encoding.js (from index.html:720-766)

EncodingSystem Class

Each system encapsulates the matrices and permutations required for encoding and decoding. The recoverGeneratorCode method includes a parity check, which validates that the seed was created by that specific system. A failure in this check prevents incorrect recovery and indicates that the wrong system was used.

// From js/encoding.js (derived from index.html)
recoverGeneratorCodeOriginal(seed) {
    // ... (initial processing) ...
    const expectedParity = this.matrixVectorMultiplyMod26(this.matrices.P, message);
    const negatedExpectedParity = expectedParity.map(x => (-x + 26) % 26);
    
    for (let i = 0; i < 42; i++) {
        if (parity[i] !== negatedExpectedParity[i]) {
            throw new Error("Invalid seed for original mode: parity check failed");
        }
    }
    
    return this.numbersToLetters(message);
}

Sources: js/encoding.js (from index.html:550-567)

Threat Model and Mitigation

The primary threat is the compromise of the masterSeed. The system's design assumes the master seed is kept secret.

Threat	Description	Mitigation
External Attacker	An attacker without the master seed attempts to find the generator code from a seed.	Computationally infeasible due to the high entropy provided by the unknown master seed.
Internal Attacker	An attacker gains access to the master seed.	The attacker can now brute-force the 13-character generator code. Security is reduced to ~61.1 bits of entropy, which is vulnerable.
Data Corruption	The 55-character seed is partially corrupted or stored incorrectly.	The multi-deviation system provides resilience. If one system fails recovery due to corruption, other systems can be tried. The parity check within each system detects corruption.

Sources: README.md:89-97

Security Dependency Diagram

The security hierarchy clearly shows that the master seed is the single point of failure.

This diagram illustrates the two primary security states of the system based on master seed confidentiality.

Sources: README.md:80-87

Recommended Practices and Limitations

Best Practices

1. Run Offline: For maximum security, download index.html and run it locally in a web browser. This prevents potential interception of the master seed or generator code over the network.
   Sources: README.md:3
2. Use a Strong Master Seed: Do not use the default master seed. Provide a long, random, and unique masterSeed to maximize the system's entropy. The UI prompts the user to enter a custom seed.
   Sources: README.md:23-26, js/app.js (from index.html:665-672)
3. Secure the Master Seed: The master seed must be kept secret and stored securely. Its compromise renders the entire system vulnerable.
   Sources: README.md:140-143
4. Avoid Predictable Generator Codes: In high-security scenarios where master seed compromise is a possibility, avoid using simple or predictable generatorCode strings like aaaaaaaaaaaaa.
   Sources: README.md:6, 150-152

Limitations

• Master Seed Dependency: The entire security model hinges on the secrecy of the master seed. It is a single point of failure.
• Limited Generator Code Entropy: The generator code itself has only ~61.1 bits of entropy, making it a weak point if the master seed is exposed.
• Computational Overhead: Recovering a code by sequentially trying all generated systems can be computationally intensive, though the UI is designed to handle this asynchronously for larger system counts.

Sources: README.md:140-152, js/app.js (from index.html:686-718)

Conclusion

The qib13 system offers a practical balance between usability and security by separating a memorable, low-entropy input from a secret, high-entropy master seed. Its security is robust, provided that best practices are followed. The use of a cryptographically secure, deterministic RNG based on HMAC-SHA256 is a cornerstone of its design, ensuring reproducible yet unpredictable system generation. The most critical security measure for any user is to choose a strong, unique master seed and protect it diligently.

Sources: README.md:154-161