🔐 Cryptograph

Educational cryptography library in Rust

📦 Overview

cryptograph is a Rust library that implements fundamental concepts from cryptography and number theory, with a focus on clarity, learning, and low-level understanding.

It includes:

• Classical ciphers (Caesar, Affine)
• Stream cipher primitives
• Pseudorandom bit generators (FlipFlop & LFSR)
• Bit-level utilities
• Number theory algorithms (Euclidean algorithm, Bézout, modular inverse)

🚀 Features

🔑 Cryptography

• Caesar Cipher
• Affine Cipher
• Stream Cipher (XOR-based)

🧠 Mathematics

• Euclidean Algorithm (GCD)
• Extended Euclidean Algorithm (Bézout)
• Modular Multiplicative Inverse

⚙️ Bit Manipulation

• bytes ↔ bits conversion
• Bitwise operations utilities

🔄 Pseudorandom Generators

• FlipFlop: a single 1-bit memory cell that can be toggled or set
• Lsfr: Linear Feedback Shift Register, classical pseudorandom bit generator

📥 Installation

Add this to your Cargo.toml:

[dependencies]
cryptograph = "0.1"

🧪 Usage

Caesar Cipher

use cryptograph::cryptography::cesar::encrypt;

let encrypted = encrypt("HELLO", 3);
println!("{}", encrypted); // KHOOR

Affine Cipher

use cryptograph::cryptography::affine::encrypt;

let encrypted = encrypt("HELLO", 5, 8);
println!("{}", encrypted);

Stream Cipher (XOR)

use cryptograph::cryptography::streams_ciphers::encrypt;

let msg = b"hello";
let key = b"key";

let encrypted = encrypt(msg, key);
let decrypted = encrypt(&encrypted, key); // XOR is symmetric

assert_eq!(msg, decrypted);

Bit Manipulation

use cryptograph::utils::bits::{bytes_to_bits, bits_to_bytes};

let bytes = vec![0b10100001];

let bits = bytes_to_bits(&bytes);
let reconstructed = bits_to_bytes(&bits).unwrap();

assert_eq!(bytes, reconstructed);

Modular Inverse

use cryptograph::math::multiplicative_inverse;

let inv = multiplicative_inverse(5, 7).unwrap();

assert_eq!((5 * inv) % 7, 1);

LFSR

// Create a 4-bit LFSR
let ff = vec![
    FlipFlop::new(true),
    FlipFlop::new(false),
    FlipFlop::new(true),
    FlipFlop::new(false),
];

// Initialize the LFSR
let mut lfsr = Lsfr::new(ff);

// Rotate the LFSR (advance one step)
lfsr.rotate();

// Get the current state of the flip-flops
let state = lfsr.get();

// Calculate the total number of possible LFSR states
let possibilities = lfsr.calculate_possibilities();
println!("Possible states: {}", possibilities);

⚠️ Security Notice

This library is intended for educational purposes only.

• ❌ Not audited
• ❌ Not constant-time
• ❌ Not safe for production cryptography

For real-world use, consider libraries like:

• RustCrypto
• ring

🧠 Design Goals

• Simplicity over performance
• Explicit bit-level control
• Clear mathematical foundations
• Modular architecture

📁 Project Structure

cryptograph/
├── cryptography/
│   ├── cesar/
│   ├── affine/
│   └── streams_ciphers/
│
├── math/
│   ├── euclides/
│   ├── bezout/
│   └── multiplicative_inverse/
│
├── tools/
│   └── flip_flop.rs
│
└── pseudorandom_generator/
    └── lfsr.rs

🛠 Future Improvements

• Replace Vec<bool> with bit-packed representations
• Add more secure stream cipher implementations
• Improve UTF-8 handling
• Add benchmarks and optimizations

🤝 Contributing

Contributions are welcome!

You can help by:

• Improving documentation
• Adding tests
• Optimizing implementations
• Extending cryptographic primitives

📄 License

MIT

💡 Author Notes

This project is built to deeply understand:

• Bitwise operations
• Modular arithmetic
• Cipher design

If you're learning cryptography or low-level Rust, this crate is for you.