Metadata-Version: 2.4
Name: PyHashi
Version: 1.2.0
Summary: Hikari Advanced Secure Helix Integration (HASHI) & Variable Helix Encryption (VHE)
Author-email: AbdulRahman Muhammad Rabie Ahmed <abdulrahman@nanosoft.qzz.io>
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# PyHashi: Genomic-Inspired Cryptography Suite

PyHashi is an advanced, high-entropy cryptographic framework designed for secure data transformation and key exchange. The suite utilizes a unique genomic-inspired algorithmic approach combined with state-of-the-art Elliptic Curve Cryptography to provide robust data confidentiality, integrity verification, and secure asynchronous communication.

PyHashi is architected to operate efficiently on Linux-based environments, including Android (via Termux) and Windows Subsystem for Linux (WSL).

For comprehensive technical analysis, whitepapers, and benchmarks, please refer to the official documentation provided by Collepedia Media Agency, a subsidiary of Nanosoft Technologies Agency: [www.collepedia.qzz.io/news/hashi](http://www.collepedia.qzz.io/news/hashi)

## Core Modules

1. **HASHI (Hikari Advanced Secure Helix Integration):** A dynamic, variable symmetric encryption engine leveraging ARX (Add-Rotate-XOR) operations combined with a dynamic S-Box driven by genomic sequences (DNA) and a passphrase.
2. **VHE (Variable Helix Encryption):** A hybrid asymmetric cryptographic system based on X25519 Elliptic Curves and Ephemeral Diffie-Hellman. It provides both Key Exchange Mechanisms (KEM) and direct Asymmetric Encryption (ECIES).



## Prerequisites

PyHashi requires system-level cryptographic primitives to function optimally. Ensure the following dependencies are installed on your Linux-based system:

```bash
apt update && apt install libssl-dev libargon2-dev
```

## Installation

Install the package using standard Python distribution methods:

```bash
pip install PyHashi
```

---

## 1. HASHI: Symmetric Encryption Usage

PyHashi provides a straightforward interface for standard symmetric data encryption and decryption, utilizing a user-defined key and a genomic-sequence-based bias (DNA).

### Initializing and Encrypting
```python
from hashi import Hashi, to_hex

# Initialize with a key and DNA sequence
cipher = Hashi(key="your-secret-key", dna="ATGC...")

# Encrypting data
encrypted_data = cipher.encrypt("Data to be secured")
print(f"Ciphertext (Hex): {to_hex(encrypted_data)}")
```

### Decrypting and Vault Management
```python
# Decrypting data
decrypted_data = cipher.decrypt(encrypted_data)
print(f"Decrypted: {decrypted_data.decode('utf-8')}")

# Storing credentials securely in a local JSON vault
cipher.save_vault("hashi_vault.json")

# Loading credentials directly from the vault
cipher_from_vault = Hashi.from_vault("hashi_vault.json")
```

---

## 2. VHE: Asymmetric Encryption & Key Exchange

The VHE module handles public/private key pairs, allowing secure communication between parties without pre-sharing passwords.

### Generating VHE Keypairs
```python
from hashi import VHE, to_hex

vhe = VHE()

# Generate keys for Alice and Bob
alice_keys = vhe.getKeys()
bob_keys = vhe.getKeys()

print(f"Bob's Public Key: {to_hex(bob_keys.public)}")
```

### Scenario A: Secure Key Exchange (Deriving HASHI Credentials)
Used when two parties want to establish a secure shared state over an insecure channel.

```python
# Alice uses Bob's Public Key and her Private Key to compute the shared secret
alice_creds = vhe.getHashiCredentials(peer_pub=bob_keys.public, my_priv=alice_keys.private)

print(f"Derived Shared DNA: {alice_creds.DNA}")
print(f"Derived Shared Passphrase: {alice_creds.passphrase}")

# The derived credentials can now be securely plugged directly into HASHI
secure_session = Hashi(key=alice_creds.passphrase, dna=alice_creds.DNA)
```

### Scenario B: Asymmetric Encryption (ECIES)
Used to encrypt a message directly using the receiver's Public Key. The receiver can decrypt it even if they were offline during transmission.

```python
message = "Top Secret: Operation Kurohane"

# Alice encrypts the message for Bob using ONLY his Public Key
encrypted_payload = vhe.encrypt(receiver_pub=bob_keys.public, plaintext=message)

print(f"Ephemeral Public Key: {to_hex(encrypted_payload.ephemeral_public)}")
print(f"Ciphertext + MAC: {to_hex(encrypted_payload.ciphertext)}")

# Bob decrypts the message using his Private Key and the received Ephemeral Key
decrypted_msg = vhe.decrypt(
    my_priv=bob_keys.private, 
    ephemeral_pub=encrypted_payload.ephemeral_public, 
    ciphertext=encrypted_payload.ciphertext
)

print(f"Bob reads: {decrypted_msg.decode('utf-8')}")
```

---

## Command Line Interface (CLI)

PyHashi includes a built-in CLI utility for rapid file-based cryptographic operations.

### 1. Generating Credentials
Generates a random high-entropy key and a biologically valid DNA sequence.
```bash
hashi gen
```

### 2. Encrypting a File
```bash
hashi enc -k "your-secret-key" -d "ATGC..." -i plaintext.txt -o encrypted.bin
```

### 3. Decrypting a File
```bash
hashi dec -k "your-secret-key" -d "ATGC..." -i encrypted.bin -o decrypted.txt
```

---

## Technical Specifications

The implementation relies on an underlying architectural state containing multiple internal registers:
* **HASHI Core State:** A 16-element dynamic state vector updated via complex ARX operations.
* **Dynamic S-Box:** A deterministic substitution box seeded by Argon2 KDF and HMAC.
* **Genomic Entropy:** A 32-byte biological sequence (`dna_bias`) providing continuous mutation to the transformation process.
* **VHE Curve:** Utilizes the highly secure `X25519` curve for Elliptic-Curve Diffie-Hellman (ECDH) operations.
* **Authentication:** Built-in Encrypt-then-MAC architecture ensuring perfect ciphertext integrity.

## Compatibility Notice
* **Supported Systems:** Linux, Termux (Android), WSL.
* **MacOS Support:** Planned for upcoming release cycles.
* **Windows:** Not natively supported (WSL is strongly recommended for Windows environments).

---
*PyHashi is developed and maintained by Nanosoft Technologies Agency. All technical auditing and cryptographic reviews are conducted by Collepedia Media Agency.*
