AbyssalLock

A modular, layered encryption engine built from scratch in Python.

AbyssalLock was designed as both a learning project and a functional encryption tool for personal use. Rather than wrapping an existing library, every component — from key derivation to the cipher pipeline — is implemented by hand.

⚠️ Security Notice: AbyssalLock is not a cryptographically audited algorithm. It is suitable for learning, experimentation, and light personal use. For sensitive data, use established solutions like AES-256-GCM.

---

How It Works

Encryption runs plaintext through a pipeline of four independent cipher layers, each fed its own key material derived from your passphrase + a random salt:

#	Layer	Technique	Role
1	XOR Stream	Key-derived byte XOR	Diffusion
2	S-Box Substitution	RC4-style key-scheduled lookup table	Confusion
3	Block Transposition	Fisher-Yates shuffle per 16-byte block	Positional scrambling
4	Bit Rotation	Per-byte bit rotation keyed by position	Sub-byte confusion

Decryption runs the layers in reverse order. A fresh 16-byte random salt is generated on every encryption call, so the same plaintext always produces a different ciphertext.

Key Derivation

Each layer gets 512 bytes of unique key material via a SHA-256 counter-mode KDF:

key = SHA-256(passphrase + ":layer" + index + salt)
    → fed into KDF → 512 bytes of pseudorandom key material

---

Installation

No external dependencies — standard library only.

Requirements: Python 3.7+

Clone the repository and navigate into it:

git clone https://github.com/StevenRyckeley/AbyssalLock.git
cd AbyssalLock

---

CLI Usage

Encrypt a file

python abyssallock.py encrypt <file> -p "yourpassphrase"

Example:

python abyssallock.py encrypt notes.txt -p "mypassphrase"
# Output: [✓] Encrypted notes.txt → notes.txt.enc

Decrypt a file

python abyssallock.py decrypt <file>.enc -p "yourpassphrase"

Example:

python abyssallock.py decrypt notes.txt.enc -p "mypassphrase"
# Output: [✓] Decrypted notes.txt.enc → notes.txt

⚠️ The passphrase used to decrypt must exactly match the one used to encrypt. There is no recovery mechanism, and if the passphrase is lost, the data is unrecoverable.

Supported file types

AbyssalLock operates on raw bytes, so it works on any file type: .txt, .pdf, .jpg, .docx, .mp3, etc.

---

Usage as a Module

from abyssallock import AbyssalLock

engine = AbyssalLock("your-passphrase")

ciphertext = engine.encrypt(b"Secret message")
plaintext  = engine.decrypt(ciphertext)

Extending the pipeline

AbyssalLock is designed to be modular. Add your own layer by subclassing Layer:

from abyssallock import Layer, AbyssalLock

class MyLayer(Layer):
    name = "My Custom Layer"
    description = "Does something interesting"

    def encrypt(self, data: bytes, key_bytes: bytes) -> bytes:
        # your transformation here
        return data

    def decrypt(self, data: bytes, key_bytes: bytes) -> bytes:
        # reverse your transformation here
        return data

engine = AbyssalLock("passphrase")
engine.layers.append(MyLayer())

---

Project Structure

abyssallock.py
├── _kdf()                   # Key Derivation Function (SHA-256 counter mode)
├── class Layer              # Abstract base class for all cipher layers
├── class XORStreamLayer     # Layer 1 — XOR stream cipher
├── class SubstitutionLayer  # Layer 2 — RC4-style S-Box substitution
├── class BlockTransposition # Layer 3 — Fisher-Yates block shuffle
├── class BitRotation        # Layer 4 — Keyed bit rotation
├── class AbyssalLock        # Pipeline engine
├── encrypt_file()           # CLI helper — encrypts a file on disk
├── decrypt_file()           # CLI helper — decrypts a file on disk
└── main()                   # Argument parser and CLI entry point

---

What I Learned

Building this from scratch meant actually understanding what each cryptographic primitive does and why it matters:

• XOR provides diffusion but is trivially reversible without a strong key stream
• S-Box substitution breaks frequency patterns. The same input byte maps to different output bytes depending entirely on the key
• Transposition separates where bytes live from what they are, defeating attacks that rely on positional patterns
• Layering means an attacker has to break all four transforms simultaneously rather than targeting any one weakness
• Random salting ensures that encrypting the same file twice always produces a different ciphertext, preventing pattern analysis across multiple encrypted outputs

---

Author

Steven Ryckeley — github.com/StevenRyckeley