cryptor-cli 0.1.1

A CLI tool for secure file encryption using AES-256-GCM and Argon2.

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):

   # 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:

   python3 -m venv venv
   source venv/bin/activate
   

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

   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.

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.

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.

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.

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.

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:

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.

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.