Metadata-Version: 2.4
Name: kinetic-cipher
Version: 1.0.0
Summary: Dual Physics Stream Cipher — elastic collision + FPU lattice keystream generators
Author: Kinetic Cipher Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/urokiurotsuki/Kinetic-Cipher
Project-URL: Issues, https://github.com/urokiurotsuki/Kinetic-Cipher/issues
Keywords: encryption,cipher,cryptography,physics,stream-cipher
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Kinetic Cipher

**Dual Physics Stream Cipher — Zero dependencies, pure Python.**

A novel symmetric encryption scheme that uses two independent physics simulations as keystream generators:

- **Skeleton layer**: Elastic collision of 14 particles on a 1D ring (346-bit state)
- **Armor layer**: Fermi-Pasta-Ulam nonlinear lattice with 32 nodes (1024-bit state)

No prior art found for either physics-to-keystream mechanism.

> ⚠ **Educational / Experimental** — No formal mathematical security proof exists.
> For production systems, use AES-256-GCM.

## Install

```
pip install kinetic-cipher
```

**Zero dependencies.** Uses only Python standard library (`hashlib`, `hmac`, `os`, `struct`).

## Quick Start

### Python API

```python
from kinetic_cipher import encrypt, decrypt

# Encrypt
ciphertext = encrypt(b"Hello, Kinetic Cipher!", "my-secret-passphrase")

# Decrypt
plaintext = decrypt(ciphertext, "my-secret-passphrase")
print(plaintext)  # b"Hello, Kinetic Cipher!"
```

### File Encryption

```python
from kinetic_cipher import encrypt_file, decrypt_file

# Encrypt a file (original filename is preserved)
encrypt_file("report.pdf", "report.pdf.kc", "my-passphrase")

# Decrypt (original filename is restored automatically)
decrypt_file("report.pdf.kc", "./output/", "my-passphrase")
# → ./output/report.pdf
```

### Command Line

```bash
# Encrypt a file
kinetic-cipher enc secret.txt -o secret.txt.kc

# Decrypt a file
kinetic-cipher dec secret.txt.kc -o ./decrypted/

# Encrypt text directly
kinetic-cipher enc -t "Hello World"

# Run self-test
kinetic-cipher test

# Benchmark
kinetic-cipher bench
```

## Wire Format

```
[version 1B][salt 16B][iv 8B][ciphertext NB][hmac-sha256 32B]
```

- **Version**: `0x05` (Kinetic Cipher v1.0)
- **Salt**: 16 random bytes for PBKDF2 key derivation
- **IV**: 8 random bytes, unique per message
- **HMAC**: Encrypt-then-MAC authentication

## Security Properties

| Property | Value |
|---|---|
| Key derivation | PBKDF2-SHA256, 100,000 iterations |
| Authentication | HMAC-SHA256, Encrypt-then-MAC |
| Skeleton state space | 346 bits (post-Grover: 2¹⁷³) |
| Armor state space | 1024 bits (post-Grover: 2⁵¹²) |
| Byte distribution χ² | 271.9 (pass) |
| Key avalanche | 49.9% |
| IV avalanche | 49.9% |
| Known-plaintext prediction | 0% success |
| Autocorrelation | All lags |r| < 0.03 |
| Compression ratio | 100.0% (= true random) |

## Performance

Pure Python, single-threaded:

| Size | Time | Speed |
|---|---|---|
| 1 KB | ~0.2s | ~5 KB/s |
| 10 KB | ~1.5s | ~7 KB/s |
| 100 KB | ~14s | ~7 KB/s |

For higher performance, use the Rust/WASM implementation (~23 MB/s) or the JS implementation included in the repository.

## How It Works

1. **Key Derivation**: Passphrase → PBKDF2-SHA256 (100K iterations) → 104-byte key material
2. **Particle Init**: First 56 bytes seed 14 particles with position, velocity, and mass on a ring of size 16,384
3. **Lattice Init**: Remaining 48 bytes seed a 32-node FPU nonlinear lattice
4. **Warmup**: 64 collision steps + 32 lattice steps to mix initial state
5. **Encryption**: Per 64-byte block:
   - CC generates 16 keystream bytes (particle state hash)
   - LS generates 48 keystream bytes (3 × lattice state hash)
   - XOR plaintext with 64-byte combined keystream
   - Hash all cipher bytes back into CC state (feedback)
6. **Authentication**: HMAC-SHA256 over version + salt + IV + ciphertext

## Cross-Platform Compatibility

The algorithm uses only integer arithmetic (no floating point), so implementations in any language produce identical ciphertext for the same inputs. Test vectors are provided in `tests/test_vectors.json`.

Implementations:
- **Python** (this package) — reference implementation
- **Rust/WASM** — ~23 MB/s, 13.5 KB binary (in repository)
- **JavaScript/React** — browser app (in repository)

## Limitations

- **No security proof**: Strength is empirically tested, not mathematically proven
- **Speed**: Pure Python is ~7 KB/s (use Rust/WASM for performance-critical applications)
- **Novel algorithm**: Has not been subjected to years of public cryptanalysis like AES

## License

MIT

## Citation

If you use Kinetic Cipher in academic work:

```
Kinetic Cipher: A Dual Physics Stream Cipher Using Elastic Collision
and Fermi-Pasta-Ulam Lattice Keystream Generators. 2026.
Designed with AI assistance (Claude, Anthropic; reviewed by Gemini, Google).
https://github.com/kinetic-cipher/kinetic-cipher
```
