Cryptoolsec: Secure CLI & GUI Encryption Tool

1. Description

Cryptoolsec is a versatile tool providing both a Command-Line Interface (CLI) and a Graphical User Interface (GUI) for strong file and data stream encryption/decryption on Windows, macOS, and Linux.

It leverages the robust AES-256-GCM authenticated encryption standard, ensuring confidentiality, integrity, and authenticity. For password-based operations, keys are securely derived using Argon2id with unique salts per encryption. Alternatively, raw 32-byte AES keys can be used directly via key files.

The application is built with Python and PySide6 (for the GUI), featuring streaming I/O for handling large files efficiently and a threaded GUI for a responsive user experience.

2. Key Features

• Dual Interface: Functional CLI (cryptoolsec) and modern GUI (cryptoolsec-gui).
• Strong Encryption: AES-256-GCM standard.
• Secure Key Derivation: Argon2id with unique salts for passwords.
• Flexible Secret Handling: Supports interactive passwords, password files, password via stdin, and raw key files.
• Large File Support: Uses streaming I/O (chunked processing) for low memory usage.
• Responsive GUI: Background threading prevents UI freezing during operations.
• GUI Enhancements: Progress bar, status messages, platform icon, intelligent output filename suggestion, automatic field clearing.
• Cross-Platform: Python codebase designed for Windows, macOS, and Linux. Packaged builds available (starting with Windows).

3. Index

• 1. Description
• 2. Key Features
• 3. Index
• 4. Installation
• 5. Usage
  • 5.1. Launching
  • 5.2. CLI Usage
    • 5.2.1. General Syntax
    • 5.2.2. Commands
    • 5.2.3. Common Options
    • 5.2.4. Secret Options
    • 5.2.5. CLI Examples
  • 5.3. GUI Usage
• 6. File Format
• 7. Technologies Used
• 8. License
• 9. Project Status
• 10. Contribution
• 11. Contact

4. Installation

1. Prerequisites:

   • Python (>= 3.10 recommended, as specified in pyproject.toml).
   • pip (Python package installer).

2. Clone or Download:

   • Obtain the project source code.

   # Example using Git
   git clone https://github.com/victorvernier/Cryptoolsec.git
   # cd Cryptoolsec

3. Create & Activate Virtual Environment (Recommended):

   • Navigate to the project root directory in your terminal.

   # Create venv
   python -m venv .venv
   # Activate venv
   # Windows: .\.venv\Scripts\activate
   # Linux/macOS: source .venv/bin/activate

4. Install Project and Dependencies:

   • With the virtual environment activated, install Cryptoolsec and its dependencies using pip and the pyproject.toml file. Using the editable (-e) flag is recommended for development.

   # Installs dependencies and creates the 'cryptoolsec' and 'cryptoolsec-gui' commands
   pip install -e .

   • This command reads pyproject.toml, installs the packages listed under dependencies (PySide6, pycryptodome, argon2-cffi), and makes the entry points available.

5. Usage

5.1. Launching

After installation (pip install -e .), the following commands become available in your terminal (while the virtual environment is active):

• Launch GUI:

  cryptoolsec-gui

• Use CLI:

  cryptoolsec <command> [options...]

5.2. CLI Usage

5.2.1. General Syntax

cryptoolsec <command> [options...]

5.2.2. Commands

• encrypt: Encrypt input file/stream to output file/stream.
• decrypt: Decrypt input file/stream to output file/stream.

5.2.3. Common Options

• -i FILE, --input FILE: Input file path. Reads from stdin if omitted.
• -o FILE, --output FILE: Output file path. Writes to stdout if omitted.
• --verbose: Show detailed debug messages.
• -q, --quiet: Show only error messages.
• -V, --version: Show program version.
• -h, --help: Show help message (use after command for specific help, e.g., cryptoolsec encrypt -h).

5.2.4. Secret Options

One of these mutually exclusive options is required for both encrypt and decrypt:

• --password-interactive: Securely prompts for password entry.
• --password-file FILE: Reads password from the first line of FILE.
• --password-stdin: Reads password from the first line of stdin (for piping).
• --keyfile FILE: Uses the raw 32-byte AES key from FILE.

5.2.5. CLI Examples

• Encrypt doc.txt to doc.enc using interactive password:

cryptoolsec encrypt -i doc.txt -o doc.enc --password-interactive

• Decrypt pic.jpg.enc to pic.jpg using password from key.txt:

cryptoolsec decrypt -i pic.jpg.enc -o pic.jpg --password-file key.txt

• Encrypt large archive.zip using secret.key file, show verbose logs:

cryptoolsec --verbose encrypt --keyfile secret.key -i archive.zip -o archive.zip.enc

• Compress, encrypt, and upload a folder using pipes:

tar czf - /my/folder | cryptoolsec encrypt --keyfile secret.key > backup.tar.gz.enc
# (Upload backup.tar.gz.enc)

• Download, decrypt, and extract using pipes:

# (Download backup.tar.gz.enc first)
cat backup.tar.gz.enc | cryptoolsec decrypt --keyfile secret.key | tar xzf - -C /restore/here

5.3. GUI Usage

1. Launch: Run cryptoolsec-gui in your terminal (after installation and with venv active).

2. Select Files: Use the "Select..." buttons to choose your Input File and define your Output File path. The output filename will be suggested automatically based on the input file (adding/removing .enc).

3. ** Secret Method:** Select either "Use Password" or "Use Key File".

4. Enter Secret:

   • If "Use Password", type the password in both fields (input is masked).
   • If "Use Key File", click "Select Key File..." and choose your raw 32-byte key file.

5. Click Action: Click "Encrypt" or "Decrypt".

6. Monitor: The UI will disable, and the progress bar will show activity (it might be indeterminate if reading from stdin, not yet implemented in GUI). A success or error message will appear upon completion.

7. Repeat: Input fields will clear automatically after the operation finishes.

6. File Format

The encrypted output (.enc file) format depends on the secret method used:

• Password Mode: [16-byte Salt][12-byte IV][Ciphertext][16-byte GCM Tag]

• Key File Mode: [12-byte IV][Ciphertext][16-byte GCM Tag] (No Salt is stored as none was needed for key derivation)

7. Technologies Used

• Python (>= 3.10)
• PySide6 (for the GUI)
• pycryptodome (for AES-GCM implementation)
• argon2-cffi (for Argon2id key derivation)
• PyInstaller (for packaging)

8. License

Distributed under the GPL-3.0 license. See LICENSE file or LICENSE for more information.

9. Project Status

v0.2.0 - Beta / Pre-release: Core functionality for both CLI and GUI is implemented. Successfully passed initial manual tests and a core suite of automated end-to-end CLI tests covering main encryption/decryption workflows (password file, keyfile) and common error conditions (wrong password, file not found). Comprehensive automated test coverage (more CLI scenarios, unit tests, GUI tests) is pending. Not recommended for production use with critical data until further testing.

10. Contribution

Contributions, bug reports, and feature requests are welcome! Please open an issues to discuss changes or report problems.

11. Contact

Victor Oliveira (L0g0rhythm) - Connect via the links on the profile site: l0g0rhythm.github.io