Metadata-Version: 2.4
Name: sha67
Version: 0.1.1
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Security :: Cryptography
Summary: Premium SHA-67 Hashing Cryptographic Module in Rust
Requires-Python: >=3.7
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# SHA-67: Cryptographic Modulo Hash Library

[![PyPI Version](https://img.shields.io/pypi/v/sha67.svg)](https://pypi.org/project/sha67/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/rust-stable-brightgreen.svg)](https://www.rust-lang.org/)

A premium, high-performance cryptographic hashing library written in Rust and packaged as a native Python extension.

Instead of standard binary-based hashing algorithms (like SHA-256 with $2^{256}$ keyspace), **SHA-67** hashes inputs into a base-67 number system represented by exactly 67 digits, providing a keyspace of $67^{67}$ possible values.

---

## 📐 Mathematical Foundations

### Why $67^{67}$?
In traditional computer science, data is structured in powers of two. However, by using a **67-symbol alphabet** and generating hashes that are exactly **67 characters long**, we unlock a keyspace of:
$$\text{Keyspace Size} = 67^{67} \approx 1.54 \times 10^{122}$$

This is equivalent to a **$\approx 406.4$-bit cryptographic keyspace** (since $\log_2(67^{67}) = 67 \log_2(67) \approx 406.42$ bits of entropy). This space is astronomically large, making brute-force attacks mathematically impossible.

### Base-67 Alphabet
SHA-67 utilizes a curated alphabet of 67 printable, unreserved, and highly readable ASCII characters:
```
0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_.~!
```
*   `0-9` (10 symbols)
*   `a-z` (26 symbols)
*   `A-Z` (26 symbols)
*   `-`, `_`, `.`, `~` (4 RFC-3986 unreserved symbols)
*   `!` (1 safe exclamation symbol)

### The Algorithm
Inputs are hashed using **SHA-512** (producing 512 bits of high-quality entropy). This 512-bit value is interpreted as a large unsigned integer, reduced modulo $67^{67}$, and mapped onto our 67-character base-67 alphabet. Because SHA-512's output space ($2^{512}$) is much larger than $67^{67}$, the modulo reduction introduces practically zero modulo bias ($< 1$ part in $2^{105}$), ensuring cryptographic integrity.

---

## 📥 Installation

Install the package directly from PyPI:
```bash
pip install sha67
```

*Note: For macOS Apple Silicon users, precompiled binary wheels are available for instant installation. On other systems, pip will compile the Rust extension in the background automatically (requires the Rust toolchain installed).*

---

## 🐍 Python Usage

The Python module is designed to accept both standard strings (`str`) and byte sequences (`bytes` / `bytearray`).

### 1. Simple Single-Pass Hashing
Compute a 67-character hash instantly:
```python
import sha67

# Hashing a string
hash_str = sha67.sha67("Hello, World!")
print(hash_str)
# Output: 1XHwYd8ki-_mtxzjb1HbXtT4V!xaxDwNqN7CFk!4zOtxqICIJ6o1Q16YztNWyl_AACF

# Hashing bytes
hash_from_bytes = sha67.sha67(b"Hello, World!")
```

### 2. Large Integer & Byte Digests
You can retrieve the underlying reduced big integer or raw bytes:
```python
# Get the hash as a large Python integer (modulo 67^67)
hash_int = sha67.sha67_int("Hello, World!")
print(hash_int)
# Output: 6272842035196...

# Get the hash as a 51-byte representation
hash_bytes = sha67.sha67_bytes("Hello, World!")
print(hash_bytes.hex())
```

### 3. Hashlib-style Incremental Hashing
SHA-67 provides an incremental hasher class that mimics Python's standard `hashlib` interface:
```python
hasher = sha67.SHA67()
hasher.update("Hello, ")
hasher.update("World!")

# Obtain digests in multiple formats
print("Base67 Digest: ", hasher.base67digest())
print("Hex Digest:    ", hasher.hexdigest())
print("Int Digest:    ", hasher.intdigest())
print("Raw Bytes:     ", hasher.digest())
```

### 4. Custom Key Derivation (PBKDF-SHA67)
Strengthen password keys against offline dictionary attacks using iterative hashing with salt stretching:
```python
password = "supersecretpassword"
salt = "random_salt_123"
iterations = 10000

derived_key = sha67.pbkdf_sha67(password, salt, iterations)
print("Derived Key: ", derived_key)
# Output: zNHbKgeEnRP~2frOpVbceCUfTsQ_Sr3pY1YJM9CMi!tT0Qjn.oZYDrO_nYWRl0OxAlP
```

---

## 🦀 Standalone Rust CLI Usage

The package also compiles into a standalone, high-performance UNIX command-line utility.

### Compile the CLI:
```bash
cargo build --release
```

### Hashing inputs via CLI:
```bash
# Hash a string directly
./target/release/sha67 -s "Hello, World!"

# Hash a file
./target/release/sha67 Cargo.toml

# Stream and hash from standard input
echo -n "cryptography" | ./target/release/sha67
```

---

## 📄 License

This project is licensed under the MIT License.

