lockstr is a secure, minimal, command-line file encryption tool built on Fernet symmetric cryptography. It encrypts and decrypts files and directories in place, without ever exposing the encryption key on screen.
⚠️ Without the key, encrypted files are permanently unrecoverable.
- 🔒 Strong symmetric encryption (Fernet / AES + HMAC)
- 📁 Encrypt files or entire directories (recursive)
- 🧠 Magic header prevents accidental double-encryption
- 🧪 Dry-run mode (preview without changes)
- 📋 Encryption keys copied to clipboard (never printed)
- ⌨️ Secure key input (hidden input)
- 🔁 Atomic file replacement (no partial corruption)
- 🧰 Cross-platform (Linux, macOS, Windows)
- 🚫 No network access, no key storage, no telemetry
lockstr uses Fernet from the cryptography library:
- AES-128-CBC encryption
- HMAC-SHA256 authentication
- Built-in integrity verification
- Tamper detection
- Symmetric key model
The same key is used to encrypt and decrypt data.
-
Python 3.6+
-
Required packages:
pip install cryptography pyperclip
sudo apt install xclip # X11
sudo apt install wl-clipboard # WaylandClone the project with:
git clone https://github.com/urdev4ever/lockstr.git
cd lockstrFrom the project directory:
python installer.pyThis will:
- Copy
lockstr.pyto an appropriate system directory - Create a
lockstrcommand wrapper - Add instructions if your PATH needs updating
lockstr encrypt <path>
lockstr decrypt <path>Where <path> can be:
- A single file
- A directory (processed recursively)
lockstr encrypt secret.txt- Generates a new encryption key
- Copies it to your clipboard
- Encrypts the file in place
lockstr decrypt secret.txt- Prompts for the key (hidden input)
- Restores the original file
lockstr encrypt ./documents/All files inside the directory will be encrypted recursively.
Preview what will be encrypted or decrypted without modifying anything:
lockstr encrypt ./backup/ --dry-runThis displays:
- File tree
- Number of files affected
- No changes are made
| Option | Description |
|---|---|
--dry-run |
Show what would be processed without changes |
--confirm |
Ask for confirmation before processing |
--include-hidden |
Include hidden files (.filename) |
--continue-on-error |
Continue even if some files fail |
-h, --help |
Show help message |
lockstr prepends a magic header to encrypted files:
LOCKSTR1\0
This allows lockstr to:
- Detect already-encrypted files
- Prevent double encryption
- Reject decryption attempts on plain files
- Keys are never printed
- Keys are copied to the clipboard once
- Keys are not saved or logged
- Decryption requires manual key entry (hidden input)
📌 Save your key immediately in a password manager.
- 🔥 If you lose the key, files are unrecoverable
- 🧠 lockstr does not store backups
- 🧪 Always test with
--dry-run - 💾 Backup important files before encryption
- 🦠 Does not protect against malware or keyloggers
- 📋 Clipboard contents may be readable by other applications
lockstr safely handles:
- Invalid or corrupted ciphertext
- Wrong keys
- Permission errors
- Partial failures (optional continuation)
- Interrupted execution (Ctrl+C)
Atomic writes prevent file corruption.
lockstr/
├── lockstr.py # Main CLI application
├── installer.py # System installer
├── README.md
└── README_ES.md
lockstr is designed to be:
- Explicit — no hidden behavior
- Safe-by-default — dry-run and confirmation options
- Local-only — no networking
- Hard to misuse — magic headers and validation
- Minimal — does one thing well
It is not intended to be:
- A backup solution
- A password manager
- A cloud encryption tool
- Linux (X11 / Wayland)
- Windows 10+
- macOS (zsh / bash)
If you encrypt files and lose the key, there is no recovery, be extra careful
This is by design.
Made with <3 by URDev.