Skip to content

user_guide.md

Latest commit

 

History

History
114 lines (89 loc) · 4.66 KB

user_guide.md

File metadata and controls

114 lines (89 loc) · 4.66 KB
Raw

User Guide

This is the practical "how do I actually run this" guide. For the design rationale, see architecture.md and security_analysis.md.

1. Install

git clone https://github.com/krishnavarma024/cryptbox-2.0.git
cd cryptbox-2.0
python3 -m venv venv
source venv/bin/activate          # Windows: venv\Scripts\activate
pip install -r requirements.txt

FUSE mounting (cryptbox mount) additionally needs a system-level FUSE library, which is not installed by pip:

  • macOS: install macFUSE first.
  • Linux: sudo apt-get install libfuse2 (Debian/Ubuntu) or your distro's equivalent.
  • Windows: FUSE mounting isn't supported; use the web dashboard instead.

You do not need FUSE to use the web dashboard or the encrypt/decrypt/share CLI commands - only cryptbox mount requires it.

2. The fastest way to see it work: the web dashboard

python gui/dashboard.py

Open http://localhost:5000. On first load it checks /api/status; if Cryptbox isn't initialized yet, enter a master password in the "Initialize Cryptbox" box and click Initialize. That generates an RSA keypair under ~/.cryptbox/keys/ and stores your password (for encryption, not shown in plaintext to the browser after this point).

From there:

  1. Encrypt & Upload - pick a file, optionally give it its own password (otherwise it uses your default password), click Encrypt & Upload.
  2. Encrypted Files table - see everything currently in encrypted storage, with size, last-modified time, and signature status.
    • Decrypt & Download prompts for the password and streams back the original file.
    • Download Encrypted downloads the raw .enc blob (useful for backing it up or moving it to another machine).
    • Delete removes the .enc and its .sig.
  3. Secure Sharing - export your public key (top right), send it to a collaborator, and have them send you theirs. Pick a file + its password + their public key JSON to create a <file>.sharing_bundle.json you can send them over any channel. They upload that bundle + a target path in Receive Bundle and Cryptbox configures the password locally for them
    • no plaintext password ever crosses the wire.

3. The CLI

cryptbox init                 # generate keys + set your default password
cryptbox status                # see current config / mount state
cryptbox export-key my_key.json --name "Ada Lovelace" --email ada@example.com
cryptbox share secret.txt.enc bob_public_key.json -o secret.bundle.json
cryptbox receive secret.bundle.json /path/to/secret.txt.enc
cryptbox mount                 # requires FUSE - see step 1
cryptbox unmount

If cryptbox isn't on your PATH, either run pip install -e . first (uses the entry point defined in setup.py) or call the module directly:

python -m cryptbox.main status

4. Mounting the encrypted filesystem

cryptbox init --mount-point ~/cryptbox_mount --storage ~/Dropbox/cryptbox/__enc__
cryptbox mount

Now anything you drop into ~/cryptbox_mount is transparently written as ciphertext into the --storage path (point that at a Dropbox/iCloud-synced folder to get encrypted cloud backup). cryptbox unmount when you're done.

5. Running the test suite

pip install -r requirements.txt   # includes pytest
pytest -v

35 tests cover crypto primitives, encryption round-trips, RSA key management, digital signatures, metadata, the FUSE Operations layer (via pytest.importorskip, so it's skipped gracefully without libfuse), and the full multi-user sharing workflow.

6. Try it without installing anything

The live demo reimplements the AES-256-GCM encryption core in pure browser JavaScript (Web Crypto API). It's byte-format-compatible with cryptbox/encryption.py - encrypt a file there and decrypt it with the real Python FileEncryptor, or vice versa.

Troubleshooting

Symptom Likely cause
ModuleNotFoundError: No module named 'flask' pip install -r requirements.txt - Flask is bundled in there now.
cryptbox mount fails immediately FUSE isn't installed at the OS level (see step 1) - pip install fusepy alone is not enough.
Dashboard hangs forever after uploading a file You're on an older checkout - upgrade; this was a real deadlock in OpenDecryptedFile.close() (non-reentrant lock) fixed in cryptbox/file_manager.py.
"Decryption failed - wrong password or corrupted file" Either the password is wrong, or the .enc file's bytes were altered (AES-GCM's authentication tag caught it - that's it working correctly).