RusCrypt

⚡ Lightning-fast cryptography toolkit built with Rust ⚡

Modern cryptographic operations made simple and blazingly fast

📖 Documentation • 🚀 Quick Start • 💡 Examples • 🤝 Contributing • 📚 API Docs

📑 Table of Contents

• 🎯 Overview
• ✨ Features
• 📦 Installation
• 📸 Screenshot
• 🚀 Quick Start
• 📖 Documentation
• 💡 Examples
• 🧪 Testing
• 🔒 Security
• 🤝 Contributing
• 📄 License

📸 Screenshot

Below is a screenshot of the interactive usage of ruscrypt:

Example: Interactive help and encryption prompt.

🎯 Overview

ruscrypt is a powerful command-line cryptography toolkit that brings together classical and modern cryptographic algorithms in one unified interface. Built with Rust for maximum performance, memory safety, and security.

🎓 Perfect for: Learning cryptography, educational purposes, quick encryption tasks, and understanding algorithm implementations.

Why ruscrypt?

✨ Features

🏗️ Architecture Overview

The RusCrypt toolkit follows a modular architecture designed for extensibility and maintainability

Data Flow Architecture

sequenceDiagram
    participant User
    participant CLI
    participant Dispatcher
    participant Interactive
    participant Algorithm
    participant Utils

    User->>CLI: Command with flags
    CLI->>Dispatcher: Parsed arguments
    Dispatcher->>Interactive: Prompt for inputs
    Interactive->>User: Request parameters
    User->>Interactive: Provide inputs
    Interactive->>Dispatcher: User data
    Dispatcher->>Algorithm: Execute operation
    Algorithm->>Utils: Helper functions
    Utils->>Algorithm: Processed data
    Algorithm->>Dispatcher: Result
    Dispatcher->>User: Formatted output

🏗️ Project Structure

ruscrypt/
├── Cargo.toml                  # Project manifest
├── README.md                   # Documentation
├── src/
│   ├── main.rs                 # Entry point
│   ├── lib.rs                  # Library exports
│   ├── cli.rs                  # CLI parsing
│   ├── dispatcher.rs           # Command routing
│   ├── interactive.rs          # User prompts
│   ├── utils.rs                # Shared utilities
│   │
│   ├── classical/              # Classical ciphers
│   ├── stream/                 # Stream ciphers
│   ├── block/                  # Block ciphers
│   ├── asym/                   # Asymmetric crypto
│   ├── hash/                   # Hash functions
│   └── tests/                  # Test modules
│       ├── mod.rs
│       ├── classical.rs
│       ├── stream.rs
│       ├── block.rs
│       ├── hash.rs
│       ├── asym.rs

📦 Installation

Prerequisites

• Rust: 1.70.0 or higher

Install from crates.io (Recommended)

# 📥 Install the CLI tool globally
cargo install ruscrypt

# 🎯 Binary will be available in your PATH
ruscrypt --help

Use as a Library

# 📚 Add to your Cargo.toml dependencies
cargo add ruscrypt

# Or manually add to Cargo.toml:
# [dependencies]
# ruscrypt = "0.1.0"

Build from Source

# 📥 Clone the repository
git clone https://github.com/Adel2411/ruscrypt.git
cd ruscrypt

# 🔨 Build in release mode for optimal performance
cargo build --release

# 🎯 Binary will be available at
./target/release/ruscrypt

🚀 Quick Start

Command Format

# Show help information (any of these commands):
ruscrypt
ruscrypt --help
ruscrypt <encrypt|decrypt|hash|exchange|keygen|sign|verify> --help

# Check version
ruscrypt --version

# For encryption and decryption
ruscrypt <encrypt|decrypt> --<algorithm>

# For hashing operations
ruscrypt hash --<algorithm>

# For key exchange protocols
ruscrypt exchange --<protocol>

# For key generation
ruscrypt keygen --<algorithm>

# For digital signatures (new!)
ruscrypt sign --<algorithm>
ruscrypt verify --<algorithm>

Interactive Experience

All operations are interactive - the tool will prompt you for required inputs:

# Example: Caesar cipher encryption
$ ruscrypt encrypt --caesar
Enter text to encrypt: Hello World
Enter shift value (1-25): 3
Encrypted text: Khoor Zruog

# Example: AES encryption
$ ruscrypt encrypt --aes
Enter text to encrypt: Secret message
Enter password: ********
Select AES key size: 256
Select encryption mode: CBC
Select output encoding: base64
Encrypted text: [base64 encoded result]

# Example: SHA-256 hashing
$ ruscrypt hash --sha256
Enter text to hash: password123
SHA-256 hash: ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f

# Example: RSA key generation (new!)
$ ruscrypt keygen --rsa
Select RSA key size: 1024
Select key output format: n:e / PEM
Public Key: ...
Private Key: ...

# Example: RSA digital signature (new!)
$ ruscrypt sign --rsa
Enter message to sign: This is a test message
Enter private key (n:d format or PEM): 12345:67890
Select output encoding: base64
Digital signature: SGVsbG8gV29ybGQ=

# Example: RSA signature verification (new!)
$ ruscrypt verify --rsa
Enter original message: This is a test message
Enter signature to verify: SGVsbG8gV29ybGQ=
Enter public key (n:e format or PEM): 12345:65537
Select signature encoding: base64
✅ VALID: The signature is authentic!

📖 Documentation

Algorithm Reference

🏛️ Classical Ciphers

# Encrypt
ruscrypt encrypt --caesar
# Prompts:
# - Text to encrypt
# - Shift value (1-25)

# Decrypt
ruscrypt decrypt --caesar
# Prompts:
# - Text to decrypt
# - Shift value (1-25)

# Encrypt
ruscrypt encrypt --vigenere
# Prompts:
# - Text to encrypt
# - Keyword

# Decrypt
ruscrypt decrypt --vigenere
# Prompts:
# - Text to decrypt
# - Keyword

# Encrypt
ruscrypt encrypt --playfair
# Prompts:
# - Text to encrypt
# - Keyword for matrix

# Decrypt
ruscrypt decrypt --playfair
# Prompts:
# - Text to decrypt
# - Keyword for matrix

# Encrypt
ruscrypt encrypt --railfence
# Prompts:
# - Text to encrypt
# - Number of rails (2-10)

# Decrypt
ruscrypt decrypt --railfence
# Prompts:
# - Text to decrypt
# - Number of rails (2-10)

🔐 Stream & Block Ciphers

# Encrypt
ruscrypt encrypt --rc4
# Prompts:
# - Text to encrypt
# - Key (variable length)
# - Output encoding (base64/hex)

# Decrypt
ruscrypt decrypt --rc4
# Prompts:
# - Text to decrypt
# - Key (same as encryption)
# - Input encoding (base64/hex)

# Encrypt
ruscrypt encrypt --aes
# Prompts:
# - Text to encrypt
# - Password
# - Key size (128/192/256)
# - Mode (ECB/CBC)
# - Output encoding (base64/hex)

# Decrypt
ruscrypt decrypt --aes
# Prompts:
# - Text to decrypt
# - Password (same as encryption)
# - Key size (same as encryption)
# - Mode (same as encryption)
# - Input encoding (same as encryption)

# Encrypt
ruscrypt encrypt --des
# Prompts:
# - Text to encrypt
# - Key (exactly 8 characters)
# - Mode (ECB/CBC)
# - Output encoding (base64/hex)

# Decrypt
ruscrypt decrypt --des
# Prompts:
# - Text to decrypt
# - Key (same as encryption)
# - Mode (same as encryption)
# - Input encoding (same as encryption)

🔑 Asymmetric Encryption

# Encrypt
ruscrypt encrypt --rsa
# Prompts:
# - Text to encrypt
# - Key size (512/1024/2048)
# - Output encoding (base64/hex)
# Tool generates key pair automatically

# Decrypt
ruscrypt decrypt --rsa
# Prompts:
# - Text to decrypt
# - Private key (format: n:d or PEM)
# - Input encoding (base64/hex)

# Key generation
ruscrypt keygen --rsa
# Prompts:
# - Key size (512/1024/2048)
# - Output format (n:e or PEM)
# Prints public and private key in selected format

# Digital signature (new!)
ruscrypt sign --rsa
# Prompts:
# - Message to sign
# - Private key (format: n:d or PEM)
# - Output encoding (base64/hex)
# Creates digital signature for message

# Signature verification (new!)
ruscrypt verify --rsa
# Prompts:
# - Original message
# - Signature to verify
# - Public key (format: n:e or PEM)
# - Signature encoding (base64/hex)
# Verifies signature authenticity

# Key exchange operations
ruscrypt exchange --dh
# Options:
# - Interactive Simulation (Alice & Bob)
# - Manual Exchange - Start Session
# - Manual Exchange - Complete with Other's Key
# - Mathematical Concept Demo

🔢 Hash Functions

ruscrypt hash --md5
# Prompts:
# - Text to hash
# Output: 32-character hexadecimal hash

ruscrypt hash --sha1
# Prompts:
# - Text to hash
# Output: 40-character hexadecimal hash

ruscrypt hash --sha256
# Prompts:
# - Text to hash
# Output: 64-character hexadecimal hash

💡 Examples

Classical Cipher Examples

# 🏛️ Caesar cipher example
$ ruscrypt encrypt --caesar
Enter text to encrypt: HELLO WORLD
Enter shift value (1-25): 5
Encrypted text: MJQQT BTWQI

$ ruscrypt decrypt --caesar
Enter text to decrypt: MJQQT BTWQI
Enter shift value (1-25): 5
Decrypted text: HELLO WORLD

# 🏛️ Vigenère cipher example
$ ruscrypt encrypt --vigenere
Enter text to encrypt: ATTACKATDAWN
Enter keyword: LEMON
Encrypted text: LXFOPVEFRNHR

Modern Encryption Examples

# 🔐 AES encryption example
$ ruscrypt encrypt --aes
Enter text to encrypt: This is a secret message
Enter password: mySecurePassword123
Select AES key size: 256
Select encryption mode: CBC
Select output encoding: base64
Encrypted text (AES-256, CBC, base64): U2FsdGVkX1+vupppZksvRf5pq5g5XjFRlipRkwB0K1Y96Qsv2Lm+31cmzaAILwyt

# 🔐 RSA encryption example
$ ruscrypt encrypt --rsa
Enter text to encrypt: Hello RSA
Select RSA key size: 1024
Select output encoding: base64

🔐 RSA Encryption Complete!
📤 Encrypted data: SGVsbG8gUlNB...
🔑 Private key (SAVE THIS!): 12345678:98765432
⚠️  Keep your private key secure - you'll need it for decryption!

Hash Function Examples

# 🔢 Hash function examples
$ ruscrypt hash --sha256
Enter text to hash: password123
SHA-256 hash: ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f

$ ruscrypt hash --md5
Enter text to hash: hello world
MD5 hash: 5d41402abc4b2a76b9719d911017c592

$ ruscrypt hash --sha1
Enter text to hash: test
SHA-1 hash: a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

Key Exchange Example

# 🔑 Diffie-Hellman key exchange
$ ruscrypt exchange --dh
Select Diffie-Hellman operation: Interactive Simulation (Alice & Bob)

🔑 Diffie-Hellman Key Exchange Simulation
==========================================

👩 Alice (You):
  Prime (p):     2147483647
  Generator (g): 2
  Private key:   12345 (keep secret!)
  Public key:    987654321 (share with Bob)

👨 Bob (Simulated):
  Private key:   67890 (Bob keeps secret)
  Public key:    123456789 (Bob shares with you)

🤝 Key Exchange Result:
  Alice computed shared secret: 555666777
  Bob computed shared secret:   555666777
  ✅ SUCCESS: Both parties have the same shared secret!

RSA Digital Signature Examples

# 🔏 RSA digital signature creation
$ ruscrypt sign --rsa
Enter message to sign: This document is authentic
Enter private key (n:d format or PEM): 12345678901234567890:98765432109876543210
Select output encoding: base64
✅ Digital signature created successfully!
📝 Original message: This document is authentic
🔏 Digital signature (BASE64): SGVsbG8gV29ybGQ=...

# 🔍 RSA signature verification
$ ruscrypt verify --rsa
Enter original message: This document is authentic
Enter signature to verify: SGVsbG8gV29ybGQ=...
Enter public key (n:e format or PEM): 12345678901234567890:65537
Select signature encoding: base64
✅ VALID: The signature is authentic!
🔒 The message integrity is verified and the signature is genuine.

🧪 Testing

Run Test Suite

# 🧪 Run all tests
cargo test

# ⚡ Run specific test files
cargo test classical      # Test classical ciphers
cargo test stream        # Test stream ciphers
cargo test block         # Test block ciphers
cargo test hash          # Test hash functions
cargo test asym          # Test asymmetric crypto

# 🎯 Run specific algorithm tests
cargo test caesar_tests        # Test Caesar cipher
cargo test vigenere_tests      # Test Vigenère cipher
cargo test aes_tests          # Test AES encryption
cargo test rsa_tests           # Test RSA encryption
cargo test sha256_tests        # Test SHA-256 hashing
cargo test dh_tests            # Test Diffie-Hellman

Manual Testing

Test each algorithm interactively:

# Check available commands
ruscrypt --help

# Test classical ciphers
ruscrypt encrypt --caesar
ruscrypt encrypt --vigenere
ruscrypt encrypt --playfair
ruscrypt encrypt --railfence

# Test stream & block ciphers
ruscrypt encrypt --rc4
ruscrypt encrypt --aes
ruscrypt encrypt --des

# Test asymmetric encryption
ruscrypt encrypt --rsa
ruscrypt exchange --dh

# Test key generation
ruscrypt keygen --rsa

# Test digital signatures (new!)
ruscrypt sign --rsa
ruscrypt verify --rsa

# Test hash functions
ruscrypt hash --md5
ruscrypt hash --sha1
ruscrypt hash --sha256

🔒 Security

⚠️ Important Security Considerations

🛡️ Recommended Algorithms

# ✅ Secure for modern use
ruscrypt encrypt --aes      # Symmetric encryption (AES-256, CBC mode)
ruscrypt encrypt --rsa      # Asymmetric encryption (2048+ bit keys)
ruscrypt hash --sha256      # Cryptographic hashing

# ❌ Educational/legacy only
ruscrypt encrypt --caesar   # Easily broken
ruscrypt encrypt --des      # 56-bit key, deprecated
ruscrypt encrypt --rc4      # Known vulnerabilities
ruscrypt hash --md5         # Collision attacks possible
ruscrypt hash --sha1        # Deprecated by NIST

🔐 Key Management Best Practices

• AES: Use strong passwords (12+ characters, mixed case, numbers, symbols)
• DES: Use exactly 8 characters as required by the algorithm
• RSA: Use 2048+ bit keys for real applications (512/1024 for education only)
• RC4: Use random keys of appropriate length

🤝 Contributing

We welcome contributions! Here's how to get started:

🚀 Quick Contribution Guide

1. 🍴 Fork the repository
2. 🌿 Create a feature branch:

   git checkout -b feature/new-algorithm
   

3. ✨ Make your changes
4. 🧪 Test thoroughly:

   cargo test
   cargo clippy
   cargo fmt
   

5. 📝 Commit and create a Pull Request

🎯 Contribution Areas

🔧 Development Setup

# Clone and setup
git clone https://github.com/Adel2411/ruscrypt.git
cd ruscrypt

# Install dependencies
cargo build

# Run tests
cargo test

# Format code
cargo fmt

# Check for issues
cargo clippy

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.