API Reference

ClassicCiphers is a Julia module that implements various classical cryptographic ciphers.

This module provides functionality for encrypting and decrypting messages using traditional cryptographic methods that were historically used before modern cryptography.

While these ciphers are not secure for modern use, they are valuable for educational purposes and understanding the fundamentals of cryptography.

Alphabet

A module containing alphabet-related functionality for classic ciphers.

This module provides various utilities and constants for handling alphabets in cryptographic operations, particularly for classic cipher implementations.

A module containing classic cipher implementations for text encryption and decryption.

This module provides functions to work with various historical and classic ciphers, allowing users to encrypt and decrypt text using different cipher algorithms.

Module Contents

• Cipher implementation functions
• Encryption and decryption utilities
• Helper functions for cipher operations

module Traits

A module containing type traits for classification and operations on classical ciphers.

This module provides a system of traits to define and categorize different types of classical cryptographic ciphers, their characteristics, and operations.

AlphabetParameters: Configuration for alphabet handling

Fields:

• alphabet: Set of valid characters

UPPERCASE_LETTERS

Standard uppercase Latin alphabet (A-Z).

LOWERCASE_LETTERS

Standard lowercase Latin alphabet (a-z).

DIGITS_LETTERS

Numeric digits (0-9).

AbstractCipher{ACTION}

Abstract type for all ciphers in the package.

Type parameters

• ACTION::Bool: true for encryption, false for decryption

AbstractStreamCipherConfiguration{ACTION} <: AbstractCipher{ACTION}

Abstract type for ciphers that process text as a continuous stream of characters.

abstract type AbstractCipherState end

Base abstract type for representing the internal state of a cipher. This type serves as the parent type for all concrete cipher state implementations.

All subtypes should maintain the necessary state information required for encryption and decryption operations in stream ciphers.

Extended help

Implementation

When implementing a new cipher state type:

• Create a concrete type that inherits from AbstractCipherState
• Define necessary fields to store the cipher's internal state
• Implement required methods for state manipulation

State(cipher::AbstractStreamCipherConfiguration)

Create an initial empty cipher state for a given stream cipher configuration.

Arguments

• cipher::AbstractStreamCipherConfiguration: The configuration of the stream cipher

Returns

• EmptyCipherState: An empty cipher state instance

This function serves as a default implementation for stream ciphers that don't require state initialization. For ciphers that need specific state initialization, this method should be overridden.

State(cipher::FormattingCipher)

Create initial state for formatting cipher operation. Returns a new FormattingState instance to track character accumulation.

EmptyCipherState <: AbstractCipherState

A concrete implementation of AbstractCipherState representing an empty cipher state.

This struct is used as a null object pattern for cipher states when no state information needs to be maintained during encryption/decryption operations.

A mutable struct representing character count tracking for stream ciphers.

Implements the AbstractCipherState interface to maintain state information about valid characters encountered during encryption/decryption operations.

InputCaseMode

Enumeration of input case handling modes.

Values

• NOT_CASE_SENSITIVE: Treat upper/lowercase as same (default)
• CASE_SENSITIVE: Distinguish between upper/lowercase

OutputCaseMode

Enumeration for output case handling modes.

InputCaseHandler{M} <: InputCaseHandlingTrait

Trait type for handling input case sensitivity.

Type parameters

• M: Type of case mode (usually InputCaseMode)

Fields

• mode::M: The case handling mode to use

CaseHandler{M} <: OutputCaseHandlingTrait

Concrete handler for output case transformations.

Type parameters

• M: Type of case mode (usually OutputCaseMode)

case_sensitive()

Create an InputCaseHandler that distinguishes between uppercase and lowercase letters.

Returns

• InputCaseHandler{InputCaseMode}: Handler with CASE_SENSITIVE mode

not_case_sensitive()

Create an InputCaseHandler that treats uppercase and lowercase letters as equivalent.

Returns

• InputCaseHandler{InputCaseMode}: Handler with NOT_CASE_SENSITIVE mode

See Also

• InputCaseMode
• case_sensitive

iscasesensitive(handler::InputCaseHandler)

Check if an input case handler distinguishes between uppercase and lowercase letters.

Arguments

• handler::InputCaseHandler: The case handler to check

Returns

• Bool: true if handler is case sensitive, false otherwise

See Also

• InputCaseMode
• case_sensitive
• not_case_sensitive

Returns a CaseHandler instance configured to preserve the case of characters during cipher operations.

This means the output will maintain the same case (uppercase/lowercase) as the input text.

Returns

• CaseHandler: A case handling object with PRESERVE_CASE behavior

is_preserve(handler::CaseHandler) -> Bool

Check if a CaseHandler is configured to preserve the original case of characters.

Returns true if the handler's mode is set to preserve case, false otherwise.

Arguments

• handler::CaseHandler: The case handler object to check

lowercase_case()

Create a CaseHandler instance that converts text to lowercase.

Returns

• CaseHandler: A case handler that processes text to ensure all characters are lowercase.

is_lowercase(handler::CaseHandler) -> Bool

Check if the case mode of the handler is set to lowercase.

Arguments

• handler::CaseHandler: The case handler to check

Returns

true if the handler's mode is lowercase, false otherwise.

uppercase_case()

Create a CaseHandler instance set to handle uppercase text output.

Returns

• CaseHandler: A case handler configured to convert output text to uppercase.

is_uppercase(handler::CaseHandler) -> Bool

Check if the CaseHandler is set to uppercase mode.

Returns true if the handler's mode is set to UPPERCASE_CASE, false otherwise.

Arguments

• handler::CaseHandler: The case handler to check

Returns

• Bool: true if uppercase mode is set, false otherwise

cccase()

Create a CaseHandler instance with the standard common case format (CCCASE).

Returns a CaseHandler object that maintains the case format of cryptographic operations using the common case convention.

is_cccase(handler::CaseHandler) -> Bool

Check if the given case handler uses 'CCCASE' mode.

Returns true if the case handler's mode is set to CCCASE, false otherwise.

Arguments

• handler::CaseHandler: The case handler object to check.

default_case()

Create a CaseHandler with the default case settings.

Returns a CaseHandler initialized with DEFAULT_CASE, which determines the letter case handling behavior for text processing operations.

Returns

• CaseHandler: A new case handler instance with default case settings.

is_default(handler::CaseHandler) -> Bool

Check if a case handler is in default case mode.

Arguments

• handler::CaseHandler: The case handler to check.

Returns

• Bool: true if the case handler is in default case mode, false otherwise.

apply_case(handler::CaseHandler, plain_char::Char, base_char::Char, enc::Bool)

Applies the case transformation to a character based on the provided CaseHandler.

Arguments

• handler::CaseHandler: The case handler that defines how the case transformation should be applied.
• plain_char::Char: The character to which the case transformation will be applied.
• base_char::Char: The base character used to determine the case transformation.
• enc::Bool: A boolean flag indicating whether the transformation is for encoding (true) or decoding (false).

Returns

• Char: The character after applying the case transformation.

UnknownSymbolHandlingTrait <: CipherTrait

Abstract type representing the handling behavior for unknown symbols in cipher operations.

This trait defines how a cipher should process symbols that are not part of its defined alphabet or symbol set. Concrete subtypes should specify specific handling strategies, such as ignoring, throwing errors, or substituting with default values.

Type Hierarchy

• Supertype: CipherTrait

Extended By

Concrete implementations should extend this type to define specific handling behaviors.

UnknownSymbolMode

Enumeration type defining possible modes for handling unknown symbols during cipher operations.

This enum specifies how the cipher should behave when encountering symbols that are not part of the defined cipher alphabet or symbol set.

SymbolHandler{M} <: UnknownSymbolHandlingTrait

A type that defines how unknown symbols should be handled during encryption/decryption operations.

The type parameter M specifies the mode of handling unknown symbols.

Type Parameters

• M: The mode of handling unknown symbols (e.g., error, ignore, replace)

Inheritance

Subtype of UnknownSymbolHandlingTrait

ignore_symbol()

Return a SymbolHandler instance configured to ignore symbols during cipher operations.

The returned handler is initialized with the IGNORE_SYMBOL constant, which defines the behavior of ignoring non-alphabetic characters in the text being processed.

Returns

• SymbolHandler: A handler instance configured for symbol ignoring behavior

is_ignore(handler::SymbolHandler)

Returns true if the SymbolHandler is set to ignore symbols, false otherwise.

When a handler is in ignore mode, it will pass through unknown symbols without modification during cipher operations.

Arguments

• handler::SymbolHandler: The symbol handler to check.

Returns

• Bool: true if the handler's mode is set to IGNORE_SYMBOL, false otherwise.

remove_symbol()

Create a SymbolHandler that removes symbols from text.

Returns a SymbolHandler instance configured to remove symbols during encryption or decryption operations.

Returns

• SymbolHandler: A symbol handler configured to remove symbols from text

is_remove(handler::SymbolHandler) -> Bool

Check if the mode of the SymbolHandler is set to remove symbols.

Returns

• true if the handler's mode is set to remove symbols
• false otherwise

replace_symbol()

Create a SymbolHandler with the REPLACE_SYMBOL strategy for handling symbols in text processing.

This function returns a SymbolHandler object configured to replace symbols according to the predefined REPLACE_SYMBOL behavior.

Returns

• SymbolHandler: A new symbol handler instance with replace strategy

is_replace(handler::SymbolHandler) -> Bool

Check if the SymbolHandler's mode is set to replace symbols.

Returns true if the handler's mode is REPLACE_SYMBOL, false otherwise.

transform_symbol(handler::SymbolHandler, plain_char::Char)

Transform a single plain character using the provided SymbolHandler.

Arguments

• handler::SymbolHandler: The handler responsible for symbol transformation
• plain_char::Char: The character to be transformed

Returns

A transformed character based on the handler's transformation rules.

abstract type CipherTrait end

A base abstract type representing cipher traits in the ClassicCiphers package.

This type serves as the root of the cipher trait type hierarchy, allowing for type-based dispatch and classification of different cipher algorithms and their characteristics.

Extended help

Subtypes of CipherTrait should represent specific properties or behaviors of cipher algorithms, enabling type-based dispatch for encryption and decryption operations.

An abstract type representing cipher categories.

CipherTypeTrait serves as a base type for traits that classify different types of ciphers. This trait hierarchy is used for dispatch and categorization of cipher algorithms.

SubstitutionTrait <: CipherTypeTrait

A trait type representing substitution ciphers.

This abstract type is used to classify ciphers that operate by substituting one character for another according to a defined pattern or key. It is a subtype of CipherTypeTrait, which is the base trait for all cipher type classifications.

ShiftSubstitution <: SubstitutionTrait

A trait type representing shift substitution ciphers.

Shift substitution is a type of substitution cipher where each letter in the plaintext is shifted a certain number of positions in the alphabet. The most famous example is the Caesar cipher, which uses a shift of 3.

InputCaseHandlingTrait <: CipherTrait

Abstract type for traits that control how ciphers handle letter case in input text.

OutputCaseHandlingTrait <: CipherTrait

Abstract type for traits controlling output case handling.

inv(cipher::FormattingCipher{ENC}) where {ENC}

Create an inverse formatting cipher that removes the formatting applied by the original cipher.

Returns

• FormattingCipher{!ENC}: A new formatting cipher for unformatting

Examples

# Create cipher and inverse
formatter = FormattingCipher()
unformatter = inv(formatter)

# They cancel each other out
message = "SECRETMESSAGE"
formatted = formatter(message)    # "SECRE TMESS AGE"
unformatted = unformatter(formatted)  # "SECRETMESSAGE"

inv(cipher::SubstitutionCipher{ENC}) where {ENC}

Create an inverse substitution cipher by reversing the character mapping.

The inverse cipher:

• Swaps each key-value pair in the mapping dictionary
• Preserves alphabet parameters
• Toggles the encryption flag

Arguments

• cipher::SubstitutionCipher{ENC}: The cipher to invert

Returns

• SubstitutionCipher{!ENC}: A new substitution cipher with reversed mapping

Examples

# Create cipher and inverse
mapping = Dict('A'=>'X', 'B'=>'Y', 'C'=>'Z')
cipher = SubstitutionCipher(mapping)
decipher = inv(cipher)

# They cancel each other out
plaintext = "ABC"
ciphertext = cipher(plaintext)    # "XYZ"
recovered_plaintext = decipher(ciphertext) # "ABC"

inv(cipher::ROT13Cipher{ENC}) where {ENC}

Create an inverse ROT13 cipher. Since ROT13 is self-inverse (shifting by 13 twice returns to the original position), the inverse only toggles the encryption flag while keeping the same shift.

Arguments

• cipher::ROT13Cipher{ENC}: The cipher to invert

Returns

• ROT13Cipher{!ENC}: A new ROT13 cipher with toggled encryption flag

Examples

# Create cipher and inverse
cipher = ROT13Cipher()
decipher = inv(cipher)

# Both perform the same transformation
plaintext = "HELLO"
ciphertext1 = cipher(plaintext)     # "URYYB"
ciphertext2 = decipher(plaintext)   # "URYYB"

# Applying either twice returns original
cipher(cipher(plaintext))  # "HELLO"

inv(cipher::CaesarCipher{ENC}) where {ENC}

Create an inverse cipher that decrypts messages encrypted with the original cipher.

The inverse cipher:

• Reverses the shift direction (-shift)
• Toggles the encryption flag
• Keeps the same alphabet parameters

Arguments

• cipher::CaesarCipher{ENC}: The cipher to invert

Returns

• CaesarCipher{!ENC}: A new Caesar cipher that decrypts messages encrypted with the input cipher

Examples

# Create a cipher and its inverse
cipher = CaesarCipher(shift=3)
decipher = inv(cipher)

# They cancel each other out
plaintext = "HELLO"
ciphertext = cipher(plaintext)    # "KHOOR"
recovered_plaintext = decipher(ciphertext) # "HELLO"

inv(cipher::AffineCipher{ENC}) where {ENC}

Create an inverse cipher that decrypts messages encrypted with the original cipher.

The inverse cipher:

• Uses the modular multiplicative inverse of 'a'
• Adjusts the shift parameter accordingly
• Preserves alphabet parameters

Arguments

• cipher::AffineCipher{ENC}: The cipher to invert

Returns

• AffineCipher{!ENC}: A new affine cipher for decryption

Examples

# Create cipher and inverse
cipher = AffineCipher(a=5, b=8)
decipher = inv(cipher)

# They cancel each other out
plaintext = "HELLO"
ciphertext = cipher(plaintext)
recovered_plaintext = decipher(ciphertext) # Returns "HELLO"

inv(cipher::XORCipher{ENC, T}) where {ENC, T}

Create an inverse XOR cipher. Since XOR is its own inverse, this only toggles the encryption flag while keeping the same key.

Returns

• XORCipher{!ENC, T}: A new XOR cipher with toggled encryption flag

inv(cipher::VigenereCipher{ENC}) where {ENC}

Create an inverse Vigenère cipher by keeping the same key but toggling encryption mode.

The inverse cipher:

• Uses the same key
• Toggles the encryption flag
• Keeps the same alphabet parameters

Arguments

• cipher::VigenereCipher{ENC}: The cipher to invert

Returns

• VigenereCipher{!ENC}: A new Vigenère cipher for decryption

Examples

# Create cipher and inverse
cipher = VigenereCipher("SECRET")
decipher = inv(cipher)

# They cancel each other out
plaintext = "HELLO"
ciphertext = cipher(plaintext)
recovered_plaintext = decipher(ciphertext) # Returns "HELLO"

inv(cipher::VernamCipher{ENC}) where {ENC}

Creates and returns a new Vernam cipher that is the inverse operation of the input cipher. For a Vernam cipher, the inverse operation uses the same key but with opposite encryption direction (encryption ↔ decryption).

Arguments

• cipher::VernamCipher{ENC}: The Vernam cipher to be inverted

Returns

• VernamCipher: A new Vernam cipher that performs the inverse operation

inv(morse::MorseCode{ENC}) where {ENC}

Create an inverse Morse code handler that decodes messages encoded with the original handler.

Arguments

• morse::MorseCode{ENC}: The Morse code handler to invert

Returns

• MorseCode{!ENC}: A new Morse code handler for the opposite operation

Examples

# Create encoder and decoder
morse = MorseCode()
demorse = inv(morse)

# They perform opposite operations
plaintext  = "HELLO WORLD"
codetext = morse(plaintext)     # ".... . .-.. .-.. --- / .-- --- .-. .-.. -.."
recovered_plaintext = demorse(codetext)   # "HELLO WORLD"

transform_index(cipher::SubstitutionCipher, index::Int)

Transforms a character index using the substitution mapping defined in the cipher.

Arguments

• cipher::SubstitutionCipher: The substitution cipher containing the mapping
• index::Int: The index of the character to transform (1-based indexing)

Returns

The transformed index according to the cipher's substitution mapping.

transform_index(cipher::CaesarCipher{ENC}, index::Int) where {ENC}

Transform a character position in the alphabet by shifting it according to the cipher's shift value.

Type parameters

• ENC::Bool: true for encryption, false for decryption

Arguments

• cipher::CaesarCipher{ENC}: The Caesar cipher instance
• index::Int: Original position in the alphabet (1-based)

Returns

• Int: New position after applying the shift (1-based)

Examples

cipher = CaesarCipher(shift=3)
transform_index(cipher, 1)  # Returns 4 (A -> D)
transform_index(cipher, 26) # Returns 3 (Z -> C)

transform_index(cipher::AffineCipher{ENC}, index::Int) where {ENC}

Transform a character position using the affine transformation E(x) = (ax + b) mod m for encryption or D(x) = a⁻¹(x - b) mod m for decryption.

The decryption formula uses the modular multiplicative inverse of 'a'.

Arguments

• cipher::AffineCipher{ENC}: The affine cipher instance
• index::Int: Original position in the alphabet (1-based)

Returns

• Int: New position after applying the transformation (1-based)

AbstractStreamCipher{T} <: OnlineStat{T}

Abstract type representing a stream cipher that implements the OnlineStat API.

This type serves as a base for implementing stream ciphers that process data sequentially using the online statistics framework. The type parameter T specifies the type of data being processed by the cipher.

Type Parameters

• T: The type of data being processed by the cipher

connect!(cipher2::C2, cipher1::C1) where {C2<:AbstractStreamCipher, C1<:AbstractStreamCipher}

Connect two stream ciphers, allowing the output of cipher1 to be sent as input to cipher2.

Comment

Be sure to call this function before using the ciphers to ensure proper data flow. By connecting ciphers, you can create complex cipher chains and data processing pipelines. But be careful to avoid circular dependencies or infinite loops.

ToDo: using a DAG (Directed Acyclic Graph) to manage the connections should be considered for more complex scenarios.

Consider following discussion: https://github.com/joshday/OnlineStats.jl/issues/272 about OnlineStat chaining

fit_listeners!(cipher::O) where {O<:AbstractStreamCipher}

Initialize and attach any required listeners to the given stream cipher implementation. This function should be called before using the cipher to ensure proper event handling.

Arguments

• cipher::O: A stream cipher instance that implements the AbstractStreamCipher interface

Returns

Nothing. Modifies the cipher object in place.

Note

This is an internal function used to set up event handling for stream ciphers. Specific cipher implementations may override this method to add custom listeners.

SubstitutionCipher{ENC} <: AbstractStreamCipherConfiguration{ENC}

General substitution cipher that maps each character to another using a provided mapping.

Type parameters

• ENC::Bool: true for encryption, false for decryption

Fields

• mapping::Dict{Char,Char}: Character substitution mapping
• alphabet_params::AlphabetParameters: Configuration for alphabet and case handling

CaesarCipher{ENC} <: AbstractStreamCipherConfiguration{ENC}

Implementation of the Caesar cipher that shifts each letter by a fixed amount.

Type parameters

• ENC::Bool: true for encryption, false for decryption

Fields

• shift::Int: Number of positions to shift letters in the alphabet
• alphabet_params::AlphabetParameters: Configuration for alphabet and case handling

ROT13Cipher{ENC} <: AbstractStreamCipherConfiguration{ENC}

ROT13 substitution cipher that shifts each letter by 13 positions.

A special case of the Caesar cipher with a fixed shift of 13, making it self-inverse (applying the cipher twice returns the original text).

Type parameters

• ENC::Bool: true for encryption, false for decryption

Fields

• alphabet_params::AlphabetParameters: Configuration for alphabet and case handling

AffineCipher{ENC} <: AbstractStreamCipherConfiguration{ENC}

Implementation of the Affine cipher that applies the transformation E(x) = (ax + b) mod m where m is the alphabet size, a and b are the key parameters.

Type parameters

• ENC::Bool: true for encryption, false for decryption

Fields

• a::Int: Multiplicative coefficient (must be coprime with alphabet size)
• b::Int: Shift amount like in Caesar cipher
• alphabet_params::AlphabetParameters: Configuration for alphabet and case handling

XORCipher{ENC, T} <: AbstractStreamCipherConfiguration{ENC}

Implementation of a XOR cipher that performs a bitwise XOR operation between message and key.

Type parameters

• ENC::Bool: true for encryption, false for decryption
• T: Type of elements in the key vector

Fields

• key::Vector{T}: The key used for XOR operation

VigenereCipher{ENC} <: AbstractStreamCipherConfiguration{ENC}

Vigenère cipher implementation that uses a keyword to encrypt/decrypt text. Each letter in the keyword determines the shift amount for the corresponding position in the text.

Type parameters

• ENC::Bool: true for encryption, false for decryption

Fields

• key::String: Keyword used for encryption/decryption
• alphabet_params::AlphabetParameters: Configuration for alphabet and case handling

get_shift(cipher::VigenereCipher, pos::Int)

Get the shift value for the Vigenère cipher at the specified position in the key.

VernamCipher{ENC} <: AbstractStreamCipherConfiguration{ENC}

A structure representing the Vernam cipher, also known as the one-time pad.

The Vernam cipher is a symmetric stream cipher where each character of the plaintext is combined with a character from a random key stream using bitwise XOR operation. When used with a truly random key the same length as the message, it provides perfect secrecy.

Type Parameters

• ENC: Encoding type parameter that specifies how the text should be encoded

Notes

• The key must be at least as long as the message to be encrypted
• Each key should be used only once
• The key should be truly random for perfect secrecy

See also: AbstractStreamCipherConfiguration

MorseCode{ENC} <: AbstractStreamCipherConfiguration{ENC}

Implementation of the Morse code that converts between alphanumeric text and Morse code. Uses "/" as a word separator and " " between letters.

Type parameters

• ENC::Bool: true for encoding to Morse, false for decoding from Morse

ToDo

• Add support for additional Morse code types
  • International Morse code ITU-R M.1677-1
  • American Morse code
  • Continental Morse code
  • Navy Morse code
  • Tap code