mcrypt

mcrypt is a small end-to-end file encryption tool that provides both a command-line interface (CLI) and a graphical user interface (GUI). It supports optional zlib compression and optional Reed–Solomon parity bytes for basic corruption recovery.

This README documents the project's architecture, data flow, file format, usage examples, security considerations, and development notes.

Contents

• Project overview
• Architecture & data flow
• Encrypted file format
• CLI usage
• GUI usage
• Security considerations
• Dependencies & installation
• License

Project overview

mcrypt encrypts and decrypts files using a password-derived key. The main features:

• AES-GCM authenticated encryption (256-bit key)
• PBKDF2-HMAC-SHA256 key derivation (configurable iterations in code)
• Optional zlib compression (levels 1–9)
• Optional Reed–Solomon encoding/decoding to add parity bytes
• Small JSON-based container stored as UTF-8 bytes (default file extension: .mcv)
• Both CLI and GUI frontends included

The project layout (relevant files):

• mcrypt.py — entry point (CLI vs GUI chooser)
• encrypt_tool/cli.py — command-line interface and argument parsing
• encrypt_tool/gui.py — CustomTkinter-based GUI frontend
• encrypt_tool/crypto.py — core cryptographic operations (KDF, encrypt/decrypt)
• encrypt_tool/compress.py — zlib compression helpers
• encrypt_tool/rs.py — Reed–Solomon wrappers (uses reedsolo)
• encrypt_tool/utils.py — helpers (password generation)

Architecture & data flow

High-level flow for encryption:

1. Plaintext (file bytes) optionally compressed via zlib.

2. A random 16-byte salt is generated and used with PBKDF2-HMAC-SHA256 to derive a 32-byte key (AES-256). The code uses 200,000 PBKDF2 iterations.

3. A random 12-byte nonce is generated for AES-GCM.

4. Data is encrypted with AESGCM.encrypt(nonce, plaintext, None) producing ciphertext that includes the authentication tag.

5. Optionally, the ciphertext is Reed–Solomon encoded to add parity (configurable number of parity bytes rs_nsym).

6. The following JSON metadata container is created and written as UTF-8 bytes:

   • version: container version (integer)
   • salt: base64-encoded salt
   • nonce: base64-encoded AES-GCM nonce
   • rs_nsym: number of RS parity bytes used (0 if none)
   • compressed: boolean flag if compression was used
   • comp_level: compression level used (or null)
   • ciphertext: base64-encoded bytes (either raw AES-GCM output or RS-encoded bytes)

Decryption reverses the process: parse JSON, base64-decode fields, RS-decode if needed, derive key with the stored salt and provided password, perform AES-GCM decryption (which verifies authenticity), then optionally decompress.

Encrypted file format (JSON example)

Example JSON structure stored as UTF-8 bytes (fields shown with human-readable values):

{
	"version": 1,
	"salt": "<base64>",
	"nonce": "<base64>",
	"rs_nsym": 32,
	"compressed": true,
	"comp_level": 6,
	"ciphertext": "<base64>"
}

Notes:

• ciphertext contains the AES-GCM ciphertext (including the tag). If rs_nsym > 0, it contains the RS-encoded bytes instead.
• Base64 encoding keeps the container JSON-safe and human-inspectable.

CLI usage

Run the CLI mode by invoking with arguments, e.g.:

python3 mcrypt.py encrypt --infile secret.txt --password "mypwd" --compress --comp-level 6 --rs 32
python3 mcrypt.py decrypt --infile secret.txt.mcv --password "mypwd"
python3 mcrypt.py genpass --length 20

Subcommands and options are implemented in encrypt_tool/cli.py.

Default behavior:

• encrypt writes output to <infile>.mcv unless --outfile is provided.
• decrypt will strip .mcv from the filename by default, writing plaintext to the original filename; otherwise it will append .dec.

If --password is not provided on the command line, the CLI prompts securely via getpass.

GUI usage

Run GUI mode by launching without CLI arguments:

python3 mcrypt.py

The GUI supports file browsing, autodetection of encrypt/decrypt mode (based on .mcv extension or JSON headers), password generation/copying, RS and compression option selection, and Run/Quit controls. The GUI is implemented in encrypt_tool/gui.py using customtkinter.

Security considerations

• KDF: PBKDF2-HMAC-SHA256 with 200,000 iterations is used to derive a 32-byte key from the password. For higher resistance to GPU/ASIC attacks consider Argon2 (memory-hard KDF) as an alternative.
• AEAD: AES-GCM provides authenticated encryption; the implementation uses a random 12-byte nonce and includes the GCM authentication tag. AES-GCM will detect tampering and raise an error on decryption.
• Compression: When compression is enabled, data is compressed before encryption. Compressing before encryption is OK, but avoid adding secret-dependent metadata that could leak via size differences if the threat model requires constant-size ciphertexts.
• Reed–Solomon: RS parity can help recover from certain corruption types (e.g., partial storage damage) but cannot defeat AES-GCM authentication — if ciphertext is modified beyond RS correction capability, AES-GCM will fail to authenticate.
• File format: The JSON container is convenient for debugging and extensibility, but larger than compact binary containers. It embeds version to allow future format changes.
• Memory hygiene: Python does not provide easy secure-zeroing of sensitive memory; if you need stronger guarantees, consider languages/environments with explicit memory control or external helpers.

Dependencies & installation

Required Python packages are listed in requirements.txt:

• cryptography (AES-GCM, PBKDF2)
• reedsolo (optional, for Reed–Solomon parity)
• customtkinter (GUI)
• pyperclip (clipboard copy in GUI)

Install via pip:

python3 -m pip install -r requirements.txt

Note: Reed–Solomon support requires reedsolo; if it's not installed or the --no-rs flag is used, RS encoding/decoding will be skipped.

Suggestions & future work

• Switch PBKDF2 -> Argon2 for stronger password stretching.
• Add stream/chunked encryption for very large files (avoid reading entire file into memory).
• Provide an option for a compact binary container to reduce file size.
• Add automated unit/integration tests and CI configuration.

License

See the LICENSE file in the repository for licensing details.