Matrix and Permutation Logic

The matrix and permutation logic is the core of the qib13 system, providing a deterministic method for transforming a 13-character generator code into a 55-character seed and recovering it. This process relies on randomly generated matrices and permutations derived from a master seed, ensuring that the encoding is both reproducible and secure. The system supports two types of encoding schemes: an 'original' system and multiple 'deviation' systems, each with distinct matrix structures.

This logic is encapsulated within the EncodingSystem class, which handles all operations related to seed generation and code recovery. The generation of these systems is seeded by the CryptoSeedenRandom class, which uses an HMAC-SHA256 implementation to ensure cryptographically secure and deterministic random number generation.

Sources: README.md:10-15, 41-49, index.html:518-524

EncodingSystem Class

The EncodingSystem class is the central component that manages the entire encoding and decoding process for a single system. Each instance holds the matrices, permutation, and inverse permutation required for its specific transformation logic.

Sources: index.html:518-524

Class Structure

The diagram below illustrates the structure of the EncodingSystem class and its key methods.

System Types and Matrix Configurations

There are two types of encoding systems, 'original' and 'deviation', which differ in their matrix configuration. These configurations are generated deterministically based on the master seed.

Sources: README.md:45-47, index.html:540-541, 555-559, 991-996, 1002-1008

Deterministic Generation

All matrices and permutations are generated deterministically from a master seed using a seeded random number generator. The qib13 tool uses CryptoSeededRandom, which is an HMAC-SHA256 based RNG operating in counter mode. This ensures that the same master seed will always produce the exact same set of encoding systems.

Sources: README.md:118-119, index.html:199-202, 417-423

System Generation Flow

The following diagram shows how an EncodingSystem instance is created.

Matrix Operations

Matrices are fundamental to generating the parity information that validates the integrity of the seed during recovery.

Matrix Generation

Matrices are created by the generateRandomMatrix function. It populates a matrix of specified dimensions with random integers between 0 and 25, inclusive, using the seeded RNG.

// Source: index.html:1010-1019
function generateRandomMatrix(rows, cols, rng) {
    const matrix = [];
    for (let i = 0; i < rows; i++) {
        const row = [];
        for (let j = 0; j < cols; j++) {
            row.push(rng.nextInt(0, 26));
        }
        matrix.push(row);
    }
    return matrix;
}

Sources: README.md:121-131, index.html:1010-1019

Matrix Multiplication

The matrixVectorMultiplyMod26 function multiplies a matrix by a vector (the numeric representation of the generator code). Each element of the resulting vector is the dot product of a matrix row and the input vector, computed modulo 26. This result forms the parity data.

Sources: index.html:656-667

The process is as follows:

1. Initialize an empty result vector.
2. For each row in the matrix:
   a. Calculate the dot product with the input vector.
   b. Compute the result modulo 26.
   c. Push the result to the result vector.
3. Return the result vector.

Sources: index.html:656-667

Permutation Operations

Permutations are used to shuffle the codeword (message + parity) to obscure the original data within the final seed.

Permutation Generation

A random permutation of 55 elements is generated using the generateRandomPermutation function, which implements the Fisher-Yates shuffle algorithm with the seeded RNG.

// Source: index.html:1021-1030
function generateRandomPermutation(n, rng) {
    const perm = Array.from({length: n}, (_, i) => i);
    
    for (let i = n - 1; i > 0; i--) {
        const j = rng.nextInt(0, i + 1);
        [perm[i], perm[j]] = [perm[j], perm[i]];
    }
    
    return perm;
}

Sources: README.md:133-143, index.html:1021-1030

An inverse permutation is also computed by the generateInversePermutation function, which is essential for the decoding process.

Sources: index.html:1032-1038

Data Flow

Encoding Process

The encoding process transforms a 13-letter generator code into a 55-letter seed.

Decoding Process

The decoding process recovers the generator code from a seed and verifies its integrity using the stored parity information.

Conclusion

The matrix and permutation logic forms the cryptographic foundation of the qib13 tool. By using deterministically generated matrices for parity creation and permutations for data obfuscation, the system provides a reliable and reproducible method for encoding a simple generator code into a complex seed. The separation of concerns between 'original' and 'deviation' systems, distinguished by their matrix structures, adds a layer of flexibility and robustness for data recovery.

Sources: README.md:10-15, 185-192