RustCracker

A high-performance, cross-platform MD5 hash cracker powered by GPU acceleration and written entirely in Rust.

This project demonstrates modern GPGPU computing in Rust, using rust-gpu to write GPU compute shaders in pure Rust and wgpu for cross-platform GPU acceleration. Unlike traditional hash crackers that rely on platform-specific APIs (CUDA for NVIDIA, OpenCL, etc.), this implementation runs on any GPU that supports Vulkan, Metal, or DirectX 12.

The project showcases the power of Rust's ecosystem for GPU computing, providing memory safety guarantees while maintaining competitive performance across different GPU vendors.

Project Goals

100% Rust: The entire codebase, from the high-level application logic to the low-level GPU kernels, is written in Rust.
GPU Agnostic: Uses rust-gpu to compile kernels to SPIR-V and wgpu to execute them, enabling the application to run on any GPU that supports Vulkan, Metal, or DirectX 12.
Memory Safety: Leverages Rust's safety guarantees to eliminate entire classes of memory-related bugs.
Modern GPGPU: Serves as a practical, real-world example of General-Purpose GPU (GPGPU) programming in the Rust ecosystem.
Cross-Platform: Works on Linux, Windows, and macOS with NVIDIA, AMD, Intel, or Apple Silicon GPUs.

Current Status

✅ Project Complete! This is a fully functional GPU-agnostic MD5 hash cracker built entirely in Rust using rust-gpu and wgpu.

Project Structure

This repository is organized as follows:

/src: The main Rust application (the "host") that uses wgpu to manage the GPU, load wordlists, and dispatch the compute shaders.
- main.rs - Command-line interface
- lib.rs - Core GPU cracker implementation
/shader: A separate Rust crate containing the GPU kernel logic (the MD5 algorithm), compiled to SPIR-V by rust-gpu.
- src/lib.rs - MD5 compute shader implementation
/tests: Integration tests for the GPU cracker
/cudacracker: A submodule containing the original cudacracker project (reference implementation)
build.rs: Build script that compiles the shader to SPIR-V
test_wordlist.txt: Sample wordlist for testing

Features

✅ 100% Rust implementation - Both host and shader code
✅ GPU-agnostic - Runs on NVIDIA, AMD, Intel via Vulkan/Metal/DX12
✅ Batched processing - Processes 4096 hashes concurrently
✅ Memory safe - Leverages Rust's safety guarantees
✅ Comprehensive tests - Unit and integration tests included
✅ Easy to use - Simple command-line interface

Prerequisites

Before building this project, ensure you have:

Rust Toolchain: Install Rust using rustup
Nightly Rust: The shader crate requires nightly Rust (automatically managed via rust-toolchain.toml)
GPU Drivers: Up-to-date drivers for your GPU:
- AMD: Mesa drivers with Vulkan support (Linux) or Adrenalin drivers (Windows)
- NVIDIA: Latest proprietary drivers with Vulkan support
- Intel: Mesa drivers (Linux) or Intel Graphics drivers (Windows)
- Apple Silicon: Built-in Metal support (macOS)
Vulkan SDK (optional but recommended): For debugging and validation layers

Installing Vulkan Support

Linux (Arch/Manjaro):

# For AMD GPUs
sudo pacman -S vulkan-radeon vulkan-icd-loader vulkan-tools

# For NVIDIA GPUs
sudo pacman -S nvidia-utils vulkan-icd-loader vulkan-tools

# For Intel GPUs
sudo pacman -S vulkan-intel vulkan-icd-loader vulkan-tools

Linux (Ubuntu/Debian):

# For AMD GPUs
sudo apt install mesa-vulkan-drivers vulkan-tools

# For NVIDIA GPUs
sudo apt install nvidia-driver-535 vulkan-tools  # or latest version

# For Intel GPUs
sudo apt install mesa-vulkan-drivers vulkan-tools

Windows:

Ensure you have the latest GPU drivers from your manufacturer's website
Vulkan should be included with modern drivers

macOS:

Metal is built-in; no additional setup required

Verify GPU Support:

# Linux/Windows (with Vulkan)
vulkaninfo | grep "deviceName"

# Check if wgpu can detect your GPU
cargo run --release -- --help  # Will show GPU info during initialization

Building

Build the project with:

cargo build --release

This will:

Compile the shader crate to SPIR-V using rust-gpu
Build the main application with the embedded shader
Create an optimized release binary

The first build will take several minutes as it compiles the shader toolchain.

Usage

Run the cracker with a wordlist and target hash:

cargo run --release -- <wordlist_file> <md5_hash>

Examples

Try cracking the MD5 hash of "password":

cargo run --release -- test_wordlist.txt 5f4dcc3b5aa765d61d8327deb882cf99

Expected output:

Loading wordlist from test_wordlist.txt...
Loaded 30 passwords
Initializing GPU...
Using GPU: <Your GPU Name>
Cracking hash 5f4dcc3b5aa765d61d8327deb882cf99...
✓ Hash cracked!
  Password: password
  md5(password) = 5f4dcc3b5aa765d61d8327deb882cf99

More examples:

# md5("hello") = 5d41402abc4b2a76b9719d911017c592
cargo run --release -- test_wordlist.txt 5d41402abc4b2a76b9719d911017c592

# md5("123456") = e10adc3949ba59abbe56e057f20f883e
cargo run --release -- test_wordlist.txt e10adc3949ba59abbe56e057f20f883e

Testing

Run the test suite:

cargo test

The tests include:

Unit tests for hash conversion and validation
Integration tests with known password/hash pairs
GPU functionality tests
Batch processing tests
Edge case tests (empty passwords, long passwords, etc.)

Performance

The cracker processes passwords in batches of 4096 using GPU compute shaders. Performance depends on:

GPU compute capability and number of compute units
Password length and complexity
Wordlist size
GPU backend (Vulkan, Metal, or DX12)

Modern GPUs can process millions of hashes per second. Actual performance varies by hardware:

High-end GPUs (RTX 4090, RX 7900 XTX, etc.): 5-10+ billion hashes/sec
Mid-range GPUs (RTX 4060, RX 6600, etc.): 1-3 billion hashes/sec
Integrated GPUs (Intel Iris, Apple M-series): 100-500 million hashes/sec

Benchmarking

This project includes a comprehensive benchmark suite powered by Criterion.rs to measure and track performance across different aspects of the cracker.

Quick Start

Run all benchmarks:

./run_benchmarks.sh --all

Run with environment checks:

./run_benchmarks.sh --check-env
./run_benchmarks.sh --all

Run quick benchmarks (fewer samples):

./run_benchmarks.sh --quick --all

What's Benchmarked

The suite includes benchmarks for:

File I/O Performance - Wordlist loading and parsing (1K to 1M words)
Preprocessing Overhead - Data preparation before GPU submission
Batch Preparation - Message packing and encoding overhead
GPU Throughput - Raw GPU hashing performance with various batch sizes
End-to-End Cracking - Complete scenarios (password at start/middle/end, not found)
Variable Password Lengths - Impact of password length on performance (4-64 chars)
Pure GPU Timing - GPU-only execution time using timestamp queries (requires GPU support)

Viewing Results

After running benchmarks, open the HTML report:

# The report is generated at:
firefox target/criterion/report/index.html

The report includes:

Statistical analysis with confidence intervals
Violin plots showing performance distribution
Comparisons with previous runs
Regression detection

Performance Tracking

Save a baseline for comparison:

./run_benchmarks.sh --all --baseline v1.0

Compare current performance against baseline:

# After making optimizations
./run_benchmarks.sh --all --compare v1.0

Criterion will automatically detect performance improvements or regressions.

Advanced Benchmarking

Run specific benchmark groups:

# GPU throughput only
./run_benchmarks.sh --timing

# Specific group by name
cargo bench --bench cracker_benchmark -- "GPU Throughput"

Manual benchmark invocation:

# Run all benchmarks with cargo
cargo bench

# Run specific benchmark file
cargo bench --bench cracker_benchmark
cargo bench --bench gpu_timing_benchmark

Optimal Environment

For reproducible results:

Power: Plug laptop into AC power
CPU Governor: Set to performance mode (Linux)
```
sudo cpupower frequency-set -g performance
```
Background Processes: Close unnecessary applications
Cooling: Ensure adequate cooling to prevent thermal throttling
Consistency: Use same hardware and drivers for comparisons

The run_benchmarks.sh script automatically checks these conditions and warns you if the environment isn't optimal.

Documentation

For detailed benchmarking documentation, see benches/README.md, which includes:

Complete environment setup guide
Interpreting benchmark results
GPU timestamp query setup
Troubleshooting guide
Adding custom benchmarks
CI/CD integration examples

How It Works

Shader Compilation: The build.rs script uses spirv-builder to compile the /shader crate to SPIR-V bytecode
GPU Initialization: The main application initializes wgpu with the Vulkan backend (for AMD GPU support)
Batch Processing: Passwords are loaded in batches of 4096
GPU Execution: For each batch:
- Messages are preprocessed (MD5 padding)
- MD5 computation is performed in parallel on the GPU
- Results are compared with the target hash
Result Retrieval: If a match is found, the index is returned and the password is displayed

Troubleshooting

Build Issues

If you encounter rustup download errors during the first build:

rustup self update
rm -rf ~/.rustup/downloads/*
cargo build --release

GPU Not Found or Wrong GPU Selected

Check available GPUs:

# Linux with Vulkan
vulkaninfo | grep "deviceName"

# Run the program - it will display the GPU it's using
cargo run --release -- test_wordlist.txt 5f4dcc3b5aa765d61d8327deb882cf99

Common issues:

No GPU found: Ensure your GPU drivers are installed and up to date
Wrong GPU selected: wgpu automatically selects the most appropriate GPU. On multi-GPU systems, it prefers discrete GPUs over integrated ones
Vulkan not available: On Linux, ensure vulkan-icd-loader is installed

Tests Failing

Tests require a working GPU with compute shader support. Common causes:

Running in a headless/CI environment without GPU access
Outdated GPU drivers
GPU doesn't support required Vulkan/Metal/DX12 features

Platform-Specific Issues

Linux:

Ensure you're in the video or render group for GPU access
Check dmesg | grep -i gpu for driver issues