cryptan 0.4.2

# Cryptan

Cryptan is a comprehensive Rust toolkit and CLI for experimenting with various classical ciphers, modern encryption methods, and encoding schemes. It provides both a command-line binary and a reusable library API for cryptographic operations.

This toolkit aims to implement all major types of ciphers and encoding methods, making it a complete resource for learning, experimenting with, and using cryptographic algorithms.

## Requirements

- Rust (edition 2021). Recent rustup-stable releases work (1.70+ is sufficient).

## Build and install

From the repository root:

```powershell
# build & run locally
cargo run -- <subcommand> [args...]

# or install the binary into your cargo bin directory
cargo install --path .
```

When installed, the binary name comes from `Cargo.toml` ([[bin]] name = "cryptan").

## CLI usage

Examples:

```powershell
# encrypt: cargo run -- encrypt <key:i16> "plain text"
cargo run caesar -- encrypt 3 "attack at dawn"

# decrypt: cargo run -- decrypt <key:i16> "encrypted text"
cargo run caesar -- decrypt 3 "dwwdfn dw gdzq"

# brute-force: cargo run -- brute "encoded text" [threshold:f32]
# threshold is optional; if omitted all candidates are returned (threshold defaults to 0.0)
cargo run caesar -- brute "ftue rcjj" 0.6
```

Note: `cargo run --` passes the following tokens to the binary. If you installed the package with `cargo install`, run the `cryptan` binary directly (e.g. `cryptan caesar brute "ftue rcjj"`).

## Library usage

### Basic Example

```rust
use cryptan::{CaesarCipher, ClassicalCipher};

fn main() {
    let c = CaesarCipher::from_key(3);
    let secret = c.encrypt("attack at dawn");
    println!("Encrypted: {}", secret);
    assert_eq!(secret, "dwwdfn dw gdzq");

    let recovered = c.decrypt(&secret);
    println!("Decrypted: {}", recovered);
    assert_eq!(recovered, "attack at dawn");

    println!("✅ Caesar cipher test passed!");
}
```

For brute-force you get a `Vec<DecodedResult>` (see `src/utils/utils_struct.rs`) where each `DecodedResult` includes `text`, `key`, and optional `meaningful_ratio`.

### Brute-force Example

```rust
use cryptan::{CaesarCipher, BruteForce};

fn main() {
    let ciphertext = "dwwdfn dw gdzq";
    let mut cipher = CaesarCipher::from_key(0);

    println!("Attempting brute-force attack on: {}", ciphertext);
    let candidates = cipher.bruteforce(ciphertext, Some(0.3));

    for (i, candidate) in candidates.iter().enumerate() {
        println!("{:02}. Key: {}, Text: '{}', Confidence: {:.3}",
                i + 1,
                candidate.key,
                candidate.text,
                candidate.meaningful_ratio.unwrap_or(0.0));
    }
}
```

## Project Structure

```
Cipher-helper/
├── Cargo.toml
├── LICENSE
├── README.md
├── public/
│   └── words.txt
├── src/
│   ├── lib.rs
│   ├── main.rs
│   ├── traits.rs
│   ├── classical/
│   │   └── caesar/
│   ├── encoding/
│   │   └── morse/
│   └── utils/
└── target/
   └── ...
```

## Supported Cipher Types & Encodings

### Classical Ciphers (Currently Implemented)
- **Caesar Cipher**: Simple substitution cipher that shifts letters by a fixed number of positions

### Encoding Schemes (Currently Implemented)
- **Morse Code**: Encoding system using dots, dashes, and spaces to represent text

### Planned Implementations

*This toolkit is designed to eventually support all major cipher types and encoding schemes. The following are planned for future releases:*

#### Classical Ciphers (Mathematical)
- **Affine Cipher**: Uses the function `E(x) = (ax + b) mod m` for encryption
- **Substitution Cipher**: Maps each letter to another letter using a key table
- **Vigenère Cipher**: Uses a keyword to determine shift values for poly-alphabetic substitution
- **Hill Cipher**: Matrix-based cipher using linear algebra
- **Playfair Cipher**: Digraph substitution cipher using a 5x5 grid
- **Enigma Machine**: Simulation of the famous German encryption device

#### Modern Symmetric Ciphers
- **AES (Rijndael)**: Advanced Encryption Standard, the current global standard
- **DES/3DES**: Data Encryption Standard and its triple form
- **Blowfish**: Fast block cipher designed by Bruce Schneier
- **Twofish**: AES competition finalist developed by Counterpane Labs
- **Serpent**: Another AES finalist known for its security margin
- **RC4**: Stream cipher (deprecated for security reasons)
- **ChaCha20**: Modern stream cipher with excellent performance

#### Asymmetric Ciphers
- **RSA**: Rivest-Shamir-Adleman, the most widely used public-key cryptosystem
- **ECC (Elliptic Curve Cryptography)**: More efficient alternative to RSA
- **Diffie-Hellman**: Key exchange protocol for secure communications

#### Hash Functions
- **SHA-256/SHA-512**: Secure Hash Algorithm family
- **MD5**: Message Digest (deprecated for security reasons)
- **BLAKE2**: Fast and secure hash function

#### Additional Encoding Schemes
- **Base64/Base32**: Binary-to-text encoding for data transmission
- **Hex Encoding**: Binary data to hexadecimal representation
- **URL Encoding**: Percent-encoding for web-safe transmission
- **Binary Encoding**: Text to binary representation
- **ROT13**: Simple Caesar cipher variant with 13-character rotation
- **Atbash**: Ancient Hebrew cipher that reverses the alphabet

Contributions welcome. Follow repository conventions:

- Format code with `cargo fmt`.
Primary crates used in this project:

- [clap](https://crates.io/crates/clap) — Command-line argument parsing and subcommand parsing for the binary (declares CLI, derives parsers from structs).
- [colored](https://crates.io/crates/colored) — Adds ANSI color helpers for terminal output (used by `DecodedResult` Display impl).
- [env_logger](https://crates.io/crates/env_logger) — A logger implementation that reads log level from environment variables (integrates with `log`).

Special thanks to the maintainers and contributors of the linked projects for their time and open-source work — this project benefits from your efforts.

---

> [!WARNING]
> See [DISCLAIMER](./DISCLAIMER.md) and [RESPONSIBLE_USE](./RESPONSIBLE_USE.md) for usage guidelines.