cryptor-cli 0.1.1
A CLI tool for secure file encryption using AES-256-GCM and Argon2.
Requires Python: >=3.7

# Cryptor CLI Tool

`cryptor-cli` is a secure command-line interface (CLI) tool for encrypting and decrypting files using robust cryptographic primitives. It employs **envelope encryption** with **AES-2256-GCM** for data, and a password-derived **Argon2id** key for master key protection, ensuring high levels of confidentiality, integrity, and authenticity.

## Features

*   **Strong Encryption**: Utilizes AES-256-GCM for authenticated encryption.
*   **Secure Key Derivation**: Employs Argon2id (the current industry standard) to derive cryptographic keys from your password, protecting against brute-force attacks.
*   **Envelope Encryption**: Each file is encrypted with a unique Data Encryption Key (DEK), which is then encrypted by a Master Key (KEK). This isolates the risk: compromise of one DEK does not affect other files.
*   **Key Wrapping**: Uses AES Key Wrap for secure management of encryption keys.
*   **Data Integrity**: Guarantees that any tampering with encrypted files will be detected during decryption.
*   **CLI**: Easy-to-use commands for key management, encryption, and decryption.
*   **Remote Key Management**: RSA asymmetric keys for master key recovery and secure backup.

## Installation

1.  **Clone the repository** (if you haven't already):
    ```bash
    # Assuming you are in the parent directory of your project
    git clone https://github.com/yourusername/cryptor-cli.git # Replace with your repo URL
    cd cryptor-cli
    ```

2.  **Create and activate a Python virtual environment**:
    It's highly recommended to use a virtual environment to manage dependencies:
    ```bash
    python3 -m venv venv
    source venv/bin/activate
    ```

3.  **Install the package**:
    Navigate to the directory containing `setup.py` and install in editable mode:
    ```bash
    pip install .
    ```

## Usage

Once installed, the `cryptor` command will be available in your activated virtual environment.

### 1. Generate a Master Key

Before you can encrypt or decrypt any files, you need to generate a master key. This key will be encrypted by a password you provide and stored in `master.key`.

```bash
cryptor manage-keys generate
```
You will be prompted to enter and confirm a strong password.

### 2. Add Remote Unlock Key (Recommended!)

To enhance security and enable password recovery, you can generate an RSA key pair. The public key will be embedded in `master.key`, and the private key will be saved offline for recovery.

```bash
cryptor manage-keys add-remote-key my_remote_private_key.pem
```
You will be prompted for your current master key password. The private key (`my_remote_private_key.pem`) should be stored **extremely securely and offline**.

### 3. Create Encrypted Master Key Backup

Once you have added a remote key, you can create a securely encrypted backup of your entire `master.key` file. This backup is encrypted with the remote public key and can only be decrypted with your offline remote private key.

```bash
cryptor manage-keys backup-master-key cryptor_master.key.enc
```
This will create `cryptor_master.key.enc`. Follow the instructions provided by the command for secure offline storage.

### 4. Encrypt a File

To encrypt a file, specify the input (plaintext) file and the desired output (encrypted) file.

```bash
cryptor encrypt my_secret_document.txt my_secret_document.crpt
```
You will be prompted for your master key password.

### 5. Decrypt a File

To decrypt an encrypted file, specify the input (encrypted) file and the desired output (plaintext) file.

```bash
cryptor decrypt my_secret_document.crpt my_secret_document_decrypted.txt
```
You will be prompted for your master key password. The decrypted content will be written to `my_secret_document_decrypted.txt`.

### 6. Change Master Key Password

If you need to change the password protecting your master key:

```bash
cryptor manage-keys change-password
```
You will be prompted for your current password, and then for your new password (twice for confirmation).

### 7. Reset Master Key Password Using Remote Key

If you forget your master key password, you can use your offline remote private key to reset it.

```bash
cryptor manage-keys reset-password-remote my_remote_private_key.pem
```
You will be prompted for a new password to protect your master key.

## Security Notes

*   **Strong Passwords are Crucial**: The security of your encrypted files ultimately depends on the strength of your master key password. Use a long, complex, and unique password.
*   **Protect `master.key`**: The `master.key` file contains your encrypted master key (and potentially your remote public key). While it's protected by your password, it should be treated as highly sensitive. Back it up securely, and ensure it's not accidentally deleted or exposed.
*   **Remote Private Key is PARAMOUNT**: The private key generated by `add-remote-key` (e.g., `my_remote_private_key.pem`) is your ultimate recovery mechanism.
    *   **Keep it OFFLINE**: Never store it on the same computer as your `master.key` or its encrypted backups.
    *   **Keep it SECURE**: Store it on an encrypted USB drive, a secure cloud vault, or even a physically printed QR code of its contents in a safe.
    *   **Loss of this private key** means you *cannot* recover your master key if you forget your password and `master.key` is damaged/lost.
*   **Encrypted Backups**: The `cryptor_master.key.enc` backup is only useful if you also have the corresponding remote private key. Store both separately and securely.
*   **Nonce Reuse (Prevented)**: This tool uses a unique, randomly generated nonce for every encryption operation, which is critical for the security of AES-GCM. Never manually encrypt data with a reused nonce and the same key.
*   **No Tampering (Detected)**: Due to the use of Authenticated Encryption (AES-GCM), any attempt to tamper with the encrypted data will result in a decryption failure (an `InvalidTag` error), protecting you from malicious modifications.
*   **Key Storage**: The master key is stored on your local filesystem, encrypted by your password. For scenarios requiring extreme security or multi-user access, consider integrating with Hardware Security Modules (HSMs) or cloud Key Management Services (KMS).

## Contributing

Contributions are welcome! Please feel free to open issues or submit pull requests.

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.