CipherLab

CipherLab is an educational Python project for implementing and exploring classical ciphers and cryptanalysis without relying heavily on existing cryptography packages. The current version provides an interactive command-line Caesar cipher with encryption, decryption, and brute-force modes.

The project is intended for learning and experimentation, not for protecting real-world sensitive information. See ROADMAP.md for planned ciphers, analysis tools, interfaces, and project improvements.

Current Features

• Caesar cipher encryption and decryption
• Custom integer shifts, including zero, negative, and large values
• Preservation of ASCII letter casing, spaces, numbers, and punctuation
• Brute-force output for all 26 possible Caesar shifts
• Interactive terminal interface
• Automated tests for cipher behavior and terminal input

Only the English ASCII letters A-Z and a-z are shifted. Other characters, including letters such as å, é, and ß, are preserved unchanged.

Quick Start

Requires Python 3.10 or newer. The project is currently developed with Python 3.14.6.

Clone or download the project, open its directory, and install it in editable mode with the development dependencies:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

The cipherlab command is now available while this virtual environment is active. Running it without arguments opens the interactive menu:

cipherlab

The same interactive menu can also be started with:

python3 -m cipherlab

Examples

Encrypt from the terminal

Run a direct command:

cipherlab caesar encrypt --shift 5 "Caesar Cipher 101!"

Output:

Hfjxfw Hnumjw 101!

Or run cipherlab without arguments to use the interactive menu:

Please choose one of the following ciphers
1 = Caesar
2 = Vigenere
3 = Coming soon...
1

1 = Encryption
2 = Decryption
3 = Bruteforce
1

Shift value: 5
Ciphertext/Plaintext:
Caesar Cipher 101!

Hfjxfw Hnumjw 101!

Decrypt from the terminal

cipherlab caesar decrypt --shift 5 "Hfjxfw Hnumjw 101!"

Output:

Caesar Cipher 101!

Brute-force from the terminal

cipherlab caesar bruteforce "Hfjxfw Hnumjw 101!"

This prints all 26 possible decryptions.

Use the functions directly

from cipherlab.ciphers.caesar import caesar_decrypt, caesar_encrypt

encrypted = caesar_encrypt("Hello, World! 123", 1)
print(encrypted)
# Ifmmp, Xpsme! 123

decrypted = caesar_decrypt(encrypted, 1)
print(decrypted)
# Hello, World! 123

Negative and large shifts are supported:

caesar_encrypt("abc", -1)  # "zab"
caesar_encrypt("abc", 27)  # "bcd"
caesar_encrypt("abc", 52)  # "abc"

Shift values repeat every 26 positions, so shifts of 1, 27, and 53 produce the same result.

Brute-force a Caesar ciphertext

from cipherlab.ciphers.caesar import caesar_bruteforce

results = caesar_bruteforce("Hfjxfw Hnumjw 101!")

for shift, plaintext in results.items():
    print(f"Shift {shift}: {plaintext}")

The output contains all 26 possible shifts. In this example, shift 5 produces Caesar Cipher 101!.

Invalid Input

The terminal interface explains invalid menu selections and asks again when a shift is not a whole number. Valid shift examples include 3, -1, and 29.

When calling the functions directly, text must be a string and the shift must be an integer. Invalid types raise TypeError.

Running the Tests

Install the development dependency:

python -m pip install -e ".[dev]"

Run the test suite:

python3 -m pytest

Project Direction

The current focus is completing a reliable, readable Caesar cipher before adding Vigenère and other classical ciphers. Longer-term ideas include cryptanalysis, steganography experiments, toy modern-cryptography implementations, and optional graphical interfaces.

The detailed plans and open tasks are maintained in ROADMAP.md.