Metadata-Version: 2.4
Name: ecs-cipher
Version: 0.1.0
Summary: Ethiopian Indigenous Cryptographic System (ECS) on top of the Ethiopian Base-47 Numeral System (EB47NS)
Author-email: Ezra Destaw <ezradestaw@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Ezradestaw/ECS
Project-URL: Repository, https://github.com/Ezradestaw/ECS
Project-URL: Issues, https://github.com/Ezradestaw/ECS/issues
Keywords: cryptography,symmetric-cipher,block-cipher,base-47,ethiopian,mulatu-sequence,galois-field,matrix-encryption
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: eb47ns>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# Ethiopian Indigenous Cryptographic System (ECS)

[![PyPI Version](https://img.shields.io/pypi/v/ecs-cipher.svg)](https://pypi.org/project/ecs-cipher/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-35%20passed-brightgreen.svg)]()
[![GitHub](https://img.shields.io/badge/github-Ezradestaw%2FECS-blue?logo=github)](https://github.com/Ezradestaw/ECS)

An original, indigenous symmetric block cipher engineered on top of the **Ethiopian Base-47 Numeral System (EB47NS)**. Designed for high-assurance cloud storage and secure transmission of **text, images, PDFs, audio, and video files**, operating natively over prime field $\mathbb{F}_{47}$ linear algebra and recurrence sequences.

---

## Table of Contents

1. [Architectural Overview](#architectural-overview)
2. [Cryptographic Pipeline](#cryptographic-pipeline)
   - [1. Message Framing & Mulatu Padding](#1-message-framing--mulatu-padding)
   - [2. Base-47 4×4 Matrix Representation](#2-base-47-44-matrix-representation)
   - [3. Key Derivation & Invertible Matrix $AX = B$](#3-key-derivation--invertible-matrix-ax--b)
   - [4. Chaining & Vector Generator ($t=1\dots99$)](#4-chaining--vector-generator-t1dots99)
   - [5. Affine Coordinate Reflector $f(x) = mx + ny + qz$](#5-affine-coordinate-reflector-fx--mx--ny--qz)
   - [6. Multi-Segment Processing ($2^{32}$-Bit Windows)](#6-multi-segment-processing-232-bit-windows)
3. [Installation](#installation)
4. [Quickstart Guide](#quickstart-guide)
   - [String Encryption & Decryption](#string-encryption--decryption)
   - [File Encryption & Decryption (Cloud Storage)](#file-encryption--decryption-cloud-storage)
   - [Object-Oriented API](#object-oriented-api)
5. [Command-Line Interface (CLI)](#command-line-interface-cli)
6. [Mathematical Specification](#mathematical-specification)
7. [Automated Verification & Test Suite](#automated-verification--test-suite)
8. [Authorship & License](#authorship--license)

---

## Architectural Overview

ECS bridges modern symmetric cipher design with classical and modern Ethiopian mathematical innovations:

* **Foundation on EB47NS:** Operates over the prime radix $R = 47$. All core linear transformations and reflector operations are evaluated in the Galois Field $\mathbb{F}_{47} \cong \mathbb{Z}/47\mathbb{Z}$, exploiting the complete absence of non-trivial subfields to defeat algebraic shortcut attacks.
* **Ethiopian Mulatu Sequence:** Employs the generalized Fibonacci recurrence introduced by Prof. Mulatu Lemma ($M_0=4, M_1=1, M_n=M_{n-1}+M_{n-2}$) to synthesize the Initial Vector (IV) and construct non-ambiguous end-of-block padding.
* **Dynamic Invertible Matrix Keying:** Transforms 128 bits of SHA-256 key material into an invertible $4 \times 4$ matrix $A \in \mathcal{M}_{4 \times 4}(\mathbb{F}_{47})$ via systematic determinant regularisation.
* **Affine Coordinate-Dependent Reflector:** Evaluates $f(x) = (m x + n y + q z) \pmod{47}$ parameterized by a 120-bit double SHA-256 key stream.
* **Vector Generator & Parallel Windows:** Features a stateful vector generator producing distinct IVs for $t \in [1, 99]$ every 32 blocks, enabling secure parallel processing and eliminating sequential CBC stalls.
* **Arbitrary Media Support:** Natively encrypts and decrypts strings, `.txt` files, `.pdf` documents, images (`.png`, `.jpg`), audio (`.mp3`, `.wav`), and video (`.mp4`, `.mkv`) with guaranteed 100% loss-free reconstruction.

---

## Cryptographic Pipeline

```text
Plaintext (Media / Binary / Text)
        │
        ▼
Segment Splitter (<= 2^32 bits / 512 MiB chunks)
        │
        ▼
128-Bit Framing & Mulatu Padding (0x01 pad + 32-bit Length + Mulatu M_n)
        │
        ▼
CBC Chaining with Vector Generator (IV_0 = Mulatu Matrix; t=1..99)
        │
        ▼
Base-47 Decomposition: 16 Bytes -> (X_H, X_L) in M_4x4(F_47)
        │
        ▼
Matrix Encryption: B = A * X mod 47 (where A is invertible in F_47)
        │
        ▼
Coordinate Reflector: f(x) = (m*x + n*y + q*z) mod 47
        │
        ▼
EB47NS Glyph Encoding (32 Base-47 Characters per Block)
```

### 1. Message Framing & Mulatu Padding
* Input data is segmented into 128-bit (16-byte) blocks.
* If a block has fewer than 16 bytes, it is completed by appending `0x01` bytes until 16 bytes are reached (forming the block before the last block).
* The final block is appended containing:
  * **Bytes 0–3:** 32-bit big-endian unsigned integer indicating the exact payload length in bytes.
  * **Bytes 4–15:** 12 bytes of Mulatu sequence terms $(M_0, M_1, \dots, M_{11}) \bmod 256$.
* When decrypting, the 32-bit length header is extracted, ensuring 100% exact truncation back to the original plaintext.

### 2. Base-47 4×4 Matrix Representation
Each 16-byte block contains 16 eight-bit integers $b \in [0, 255]$. Each byte is uniquely mapped into two Base-47 digits:
$$q_i = \lfloor b_i / 47 \rfloor \in [0, 5], \quad r_i = b_i \bmod 47 \in [0, 46]$$
These 16 pairs form two $4 \times 4$ matrices over $\mathbb{F}_{47}$:
* $X_H$: Matrix of high digits $q_{4r + c}$
* $X_L$: Matrix of low digits $r_{4r + c}$

Original bytes are recovered bijectively via:
$$b_i = X_H[r, c] \cdot 47 + X_L[r, c]$$

### 3. Key Derivation & Invertible Matrix $AX = B$
* Key matrix $A$ is initialized from the first 128 bits of $\operatorname{SHA-256}(\text{password})$.
* If $\det(A) \equiv 0 \pmod{47}$ (singular), constants are iteratively added along the main diagonal until $\det(A) \not\equiv 0 \pmod{47}$.
* The inverse matrix $A^{-1} \pmod{47}$ is computed via Gauss-Jordan elimination over $\mathbb{F}_{47}$.
* Encryption: $B_H = A \cdot X_H \pmod{47}$, $B_L = A \cdot X_L \pmod{47}$.
* Decryption: $X_H = A^{-1} \cdot B_H \pmod{47}$, $X_L = A^{-1} \cdot B_L \pmod{47}$.

### 4. Chaining & Vector Generator ($t=1\dots99$)
* **Initial Vector ($t=1$):** Constructed from the first 16 terms of the Mulatu sequence placed along bottom-left to top-right diagonal stripes ($m_{41}, m_{31}, m_{42}, m_{21}, \dots$).
* **Window Chaining:** Blocks $0 \dots 31$ chain using previous ciphertext feedback.
* **Vector Generator ($t \ge 2$):** At block 33 ($i=32$) and every subsequent 32 blocks, a new vector generator matrix is calculated from the product of previous blocks:
$$\text{IV}_{\text{new}} = \text{block}_{i-31} \times \text{block}_{i-32} \pmod{256}$$

### 5. Affine Coordinate Reflector $f(x) = mx + ny + qz$
* Second key: $\text{key}_2 = \operatorname{SHA-256}(\operatorname{SHA-256}(\text{password}))$.
* The first 120 bits are split into three 40-bit integers: $m, n, q$.
* Reduced modulo 47 with $m \in [1, 46]$ (coprime to 47).
* Reflection on matrix entry at coordinate $(y, z)$ with value $x \in \mathbb{F}_{47}$:
$$x' = f(x) = (m \cdot x + n \cdot y + q \cdot z) \pmod{47}$$
* Decryption inversion:
$$x = f^{-1}(x') = m^{-1} \cdot (x' - n \cdot y - q \cdot z) \pmod{47}$$
where $m^{-1} = m^{45} \bmod 47$.

### 6. Multi-Segment Processing ($2^{32}$-Bit Windows)
* ECS processes messages up to $2^{32}$ bits (512 MiB) per segment.
* Messages exceeding $2^{32}$ bits are automatically divided into independent segments, each resetting the vector generator and starting fresh, allowing multi-gigabyte media to be encrypted with bounded memory.

---

## Installation

### From PyPI

```bash
pip install --upgrade ecs-cipher
```

*(The package installs under the distribution name `ecs-cipher` and imports natively as `ecs`)*.

### From Source

```bash
git clone https://github.com/Ezradestaw/ECS.git
cd ECS
pip install -e .
```

---

## Quickstart Guide

### String Encryption & Decryption

```python
import ecs

key = "my_ethiopian_master_key_2026"
plaintext = "Salam! Encrypting with ECS on top of EB47NS."

# Encrypt to Base-47 string
ciphertext = ecs.encrypt_string(plaintext, key)
print("Ciphertext:", ciphertext)

# Decrypt back to original string
recovered = ecs.decrypt_string(ciphertext, key)
print("Decrypted:", recovered)
assert recovered == plaintext
```

### File Encryption & Decryption (Cloud Storage)

```python
import ecs

key = "cloud_upload_secret_key"

# Encrypt any media file (Image, Video, Audio, PDF, Text)
ecs.encrypt_file("family_video.mp4", "family_video.mp4.ecs", key)
ecs.encrypt_file("contract.pdf", "contract.pdf.ecs", key)

# Decrypt back to identical binary files
ecs.decrypt_file("family_video.mp4.ecs", "restored_video.mp4", key)
ecs.decrypt_file("contract.pdf.ecs", "restored_contract.pdf", key)
```

### Object-Oriented API

```python
from ecs import ECSCipher

cipher = ECSCipher("high_entropy_passphrase")

# Stream or batch encryption
data = b"\x00\x01\x02\x03\xff\xfe\xfd"
encrypted = cipher.encrypt(data)
decrypted = cipher.decrypt(encrypted)

assert decrypted == data
```

---

## Command-Line Interface (CLI)

The package provides a command-line tool `ecs`:

### String Mode

```bash
# Encrypt
ecs encrypt -k "my_secret_key" -m "Confidential cloud data"

# Decrypt
ecs decrypt -k "my_secret_key" -c "<base47_ciphertext>"
```

### File Mode

```bash
# Encrypt an image, PDF, or video file
ecs encrypt -k "my_secret_key" -i presentation.pdf -o presentation.pdf.ecs

# Decrypt the encrypted file
ecs decrypt -k "my_secret_key" -i presentation.pdf.ecs -o presentation_restored.pdf
```

---

## Mathematical Specification

| Parameter | Specification | Purpose |
| :--- | :--- | :--- |
| **Radix ($R$)** | $47$ (Prime) | Finite Field $\mathbb{F}_{47}$; no subfields; optimal diffusion |
| **Block Size** | 128 bits (16 bytes) | 4×4 byte layout compatible with hardware word sizes |
| **State Encoding** | $2 \times \mathcal{M}_{4\times 4}(\mathbb{F}_{47})$ | High & low digit matrices preserving 4×4 spatial symmetry |
| **Recurrence Relation** | $M_0=4, M_1=1, M_n=M_{n-1}+M_{n-2}$ | Mulatu sequence for IV generation and padding |
| **Key Matrix ($A$)** | $\det(A) \not\equiv 0 \pmod{47}$ | Linear transformation over $\mathbb{F}_{47}$ |
| **Vector Generator** | $t=1\dots99$, period = 32 blocks | Prevents CBC pipeline stalls for parallel processing |
| **Reflector ($f$)** | $f(x) = (mx + ny + qz) \pmod{47}$ | Affine coordinate-dependent non-linear permutation |
| **Segment Ceiling** | $2^{32}$ bits (512 MiB) | Auto-reset boundary for streaming arbitrarily large files |

---

## Automated Verification & Test Suite

The test suite validates 100% of the mathematical, cipher, and media subsystems:

```bash
pytest -v
```

```text
tests/test_cipher.py::test_cipher_string_roundtrip PASSED
tests/test_cipher.py::test_cipher_convenience_functions PASSED
tests/test_cipher.py::test_cipher_empty_string PASSED
tests/test_cipher.py::test_cipher_different_block_boundaries PASSED
tests/test_cipher.py::test_cipher_32_block_chaining_boundary PASSED
tests/test_cipher.py::test_cipher_wrong_key_fails PASSED
tests/test_cli.py::test_cli_encrypt_decrypt_string PASSED
tests/test_cli.py::test_cli_encrypt_decrypt_files PASSED
tests/test_files.py::test_encrypt_decrypt_text_file PASSED
tests/test_files.py::test_encrypt_decrypt_pdf_file PASSED
tests/test_files.py::test_encrypt_decrypt_image_file PASSED
tests/test_files.py::test_encrypt_decrypt_audio_file PASSED
tests/test_files.py::test_encrypt_decrypt_video_file PASSED
tests/test_framing.py::test_pad_exact_multiple_16 PASSED
tests/test_framing.py::test_pad_incomplete_block PASSED
tests/test_matrix_ops.py::test_derive_key_matrix PASSED
tests/test_matrix_ops.py::test_bytes_to_base47_matrices_and_back PASSED
tests/test_mulatu.py::test_mulatu_sequence_initial_terms PASSED
tests/test_mulatu.py::test_mulatu_iv_matrix_coordinates PASSED
tests/test_reflector.py::test_reflector_roundtrip PASSED
tests/test_vector_generator.py::test_vector_generator_progression PASSED
============================== 35 passed in 0.45s ==============================
```

---

## Authorship & License

* **Author:** Ezra Destaw
* **Email:** ezradestaw@gmail.com
* **Repository:** [https://github.com/Ezradestaw/ECS](https://github.com/Ezradestaw/ECS)
* **PyPI Distribution:** [https://pypi.org/project/ecs-cipher/](https://pypi.org/project/ecs-cipher/)
* **License:** [MIT License](LICENSE) — Copyright (c) 2026 Ezra Destaw
