Metadata-Version: 2.4
Name: pycrpt
Version: 0.2.0
Summary: A pure Python cryptography library implementing symmetric block/stream ciphers, public-key primitives, cryptographic hash functions, key exchange protocols, and cryptanalysis auditing.
Author: Thomas
License-Expression: MIT
Project-URL: Homepage, https://github.com/thomas-mit26/pycrpt
Project-URL: Bug Tracker, https://github.com/thomas-mit26/pycrpt/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# pycrpt

[![PyPI version](https://img.shields.io/badge/pypi-v0.2.0-blue.svg)](https://pypi.org/project/pycrpt/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/thomas-mit26/pycrpt)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

`pycrpt` is an expressive, zero-dependency Python cryptography library designed to provide clean, accessible, and mathematically transparent implementations of modern and classical cryptographic algorithms. 

Whether you need symmetric block ciphers like **AES**, high-performance stream ciphers like **ChaCha20** and **RC4**, asymmetric primitives like **RSA**, secure message hashing (**SHA-512**, **HMAC**), or advanced cryptographic protocols (**Diffie-Hellman Key Exchange**, **Schnorr Zero-Knowledge Proofs**), `pycrpt` delivers a unified, pythonic API.

---

## Table of Contents

- [Key Architecture & Design Goals](#key-architecture--design-goals)
- [Feature Matrix](#feature-matrix)
- [Installation](#installation)
- [Detailed API Guide](#detailed-api-guide)
  - [Symmetric Block Ciphers (AES, DES, 3DES)](#1-symmetric-block-ciphers-aes-des-3des)
  - [Stream Ciphers (RC4, ChaCha20)](#2-stream-ciphers-rc4-chacha20)
  - [Classical Cryptography](#3-classical-cryptography)
  - [Public-Key Cryptography (RSA)](#4-public-key-cryptography-rsa)
  - [Cryptographic Hashes & Message Authentication (SHA, HMAC)](#5-cryptographic-hashes--message-authentication-sha-hmac)
  - [Key Exchange & Authentication Protocols](#6-key-exchange--authentication-protocols)
  - [Cryptanalysis & Auditing Tools](#7-cryptanalysis--auditing-tools)
- [Security Considerations](#security-considerations)
- [License](#license)

---

## Key Architecture & Design Goals

1. **Zero External Dependencies**: Implemented entirely using standard Python modules (`math`, `hashlib`, `secrets`, `hmac`), eliminating binary C-extension compilation issues across target platforms.
2. **Transparent Mathematical Primitives**: Low-level intermediate states (such as AES S-Box substitutions, ShiftRows, MixColumns Galois Field arithmetic, and key expansion round keys) are exposed for research, educational inspection, and custom protocol construction.
3. **Constant-Time Verification**: High-level comparison routines utilize time-constant byte evaluation to prevent side-channel timing leaks during digest verification.

---

## Feature Matrix

| Domain | Algorithm / Primitives | Key Sizes / Modes Supported |
| :--- | :--- | :--- |
| **Block Ciphers** | AES (FIPS 197), DES, Triple-DES (3DES) | 128 / 192 / 256-bit (ECB, CBC, CTR) |
| **Stream Ciphers** | RC4, ChaCha20 | Variable (40 to 256 bits) |
| **Classical Ciphers** | Additive, Multiplicative, Affine, Autokey, Vigenère, Transposition | Modulo 26 alphabet transformations |
| **Public Key** | RSA, Digital Signatures, Key Generation | 1024 / 2048 / 4096-bit (Arbitrary prime $p, q$) |
| **Hashing & MAC** | SHA-256, SHA-512, HMAC-SHA512 | Constant-time message digest generation |
| **Protocols** | Diffie-Hellman (RFC 3526), Challenge-Response, Schnorr ZKP | Finite Field & Group Modulo Arithmetic |
| **Cryptanalysis** | Kasiski examination, Chi-squared frequency analysis, Brute-force | Automated key length estimation & plaintext recovery |

---

## Installation

Install `pycrpt` using `pip`:

```bash
pip install pycrpt
```

Or install from source for development:

```bash
git clone https://github.com/thomas-mit26/pycrpt.git
cd pycrpt
pip install -e .
```

---

## Detailed API Guide

### 1. Symmetric Block Ciphers (AES, DES, 3DES)

`pycrpt` provides high-level block encryption alongside deep inspection APIs for internal AES state transformations.

```python
from pycrpt.cipher import AES
from pycrpt.util import pad, unpad

# 128-bit key (16 bytes)
key = b'SecretKey128Bit!' 
data = b'Top-secret payload data requiring encryption'

# Initialize AES in ECB mode
cipher = AES.new(key, AES.MODE_ECB)

# Encrypt with PKCS#7 padding
padded_data = pad(data, block_size=16)
ciphertext = cipher.encrypt(padded_data)
print("Ciphertext (hex):", ciphertext.hex().upper())

# Decrypt
decrypted_padded = cipher.decrypt(ciphertext)
plaintext = unpad(decrypted_padded, block_size=16)
assert plaintext == data

# Inspect AES State Operations (FIPS 197 Standard)
state = AES.text_to_state("AESUSESAMATRIX  ")
subbed_state = AES.sub_bytes(state)
shifted_state = AES.shift_rows(subbed_state)
mixed_state = AES.mix_columns(shifted_state)
print("State matrix after MixColumns:", AES.format_state(mixed_state))
```

### 2. Stream Ciphers (RC4 & ChaCha20)

High-speed stream encryption for arbitrary text and binary buffers.

```python
from pycrpt.cipher import RC4, ChaCha20

# RC4 Stream Cipher Usage
rc4_key = "SuperSecretRC4Passphrase"
encrypted_hex = RC4.encrypt_text(rc4_key, "Sensitive real-time stream data")
decrypted_text = RC4.decrypt_text(rc4_key, encrypted_hex)
print("RC4 Decrypted:", decrypted_text)

# ChaCha20 Cipher Usage
key = b'0123456789abcdef0123456789abcdef' # 32 bytes
nonce = b'0123456789ab' # 12 bytes
chacha = ChaCha20.new(key=key, nonce=nonce)
ciphertext = chacha.encrypt(b"High throughput data stream")
```

### 3. Classical Cryptography

Implementations of modular arithmetic ciphers with automated key inversion.

```python
from pycrpt.cipher import Affine, Autokey, Transposition

# Affine Cipher: E(x) = (15*x + 20) mod 26
cipher_text = Affine.encrypt("thisisanexercise", a=15, b=20)
plain_text  = Affine.decrypt(cipher_text, a=15, b=20)

# Transposition Cipher Key Inversion
enc_key = (3, 2, 6, 1, 5, 4)
dec_key = Transposition.invert_key(enc_key) # (4, 2, 1, 6, 5, 3)
```

### 4. Public-Key Cryptography (RSA)

Full RSA lifecycle support including key generation, modular exponentiation, private key recovery from public parameters, and digital signatures.

```python
from pycrpt.public_key import RSA

# Generate RSA keypair from primes p and q
keypair = RSA.generate(p=11, q=13, e=7)
print("Public Key:", keypair.public_key)   # (7, 143)
print("Private Key:", keypair.private_key) # (103, 143)

# Encrypt text string
cipher_ints = RSA.encrypt_text("CONFIDENTIAL", keypair.public_key)
decrypted   = RSA.decrypt_text(cipher_ints, keypair.private_key)

# Sign and Verify Digital Signatures
signature = RSA.sign("Authentication Message", keypair.private_key)
is_valid  = RSA.verify("Authentication Message", signature, keypair.public_key)
print("Signature Validated:", is_valid)
```

### 5. Cryptographic Hashes & Message Authentication (SHA, HMAC)

```python
from pycrpt.hash import SHA512, HMAC

# Generate SHA-512 Hash Digest
digest = SHA512.hash("Authentication Payload")
print("SHA-512:", digest)

# Compute HMAC-SHA512 MAC
mac_tag = HMAC.new(key="SharedSecretKey", message="Payload", digestmod=SHA512)
is_valid = HMAC.verify(message="Payload", tag=mac_tag, key="SharedSecretKey")
```

### 6. Key Exchange & Authentication Protocols

Simulate secure multi-party protocols directly in Python.

```python
from pycrpt.protocol import DiffieHellman, ZeroKnowledgeProof, ChallengeResponse

# Diffie-Hellman Key Exchange (RFC 3526 Group)
alice_pub, bob_pub, shared_secret = DiffieHellman.simulate_exchange()
print("Established Shared Secret:", shared_secret)

# Schnorr Zero-Knowledge Proof (ZKP)
zkp_status = ZeroKnowledgeProof.simulate(secret_s=987654)
print("Zero-Knowledge Identity Verified:", zkp_status)
```

### 7. Cryptanalysis & Auditing Tools

Automated frequency analysis, Kasiski examination, and vulnerability auditing.

```python
from pycrpt.attack import AdditiveBruteForce, VigenereCryptanalysis

# Brute-force Additive Cipher around expected heuristic key
results = AdditiveBruteForce.attack(
    ciphertext="NCJAEZRCLASJLYODEPRLYZRCLASJLCPEHZDTOPDZQLNZTY",
    heuristic_key=13
)
print("Top Decrypted Candidate:", results[0]["decrypted_text"])
```

---

## Security Considerations

`pycrpt` is built primarily for educational clarity, architectural transparency, and lightweight applications where external native dependencies cannot be compiled. For production applications handling high-concurrency TLS workloads, hardware acceleration (AES-NI) provided by C/Rust bindings may be preferred.

---

## License

Distributed under the **MIT License**. See `LICENSE` for details.
