> ## Documentation Index > Fetch the complete documentation index at: https://docs.memvid.com/llms.txt > Use this file to discover all available pages before exploring further. # Encryption > Encrypt memory files with password-based protection using AES-256-GCM Memvid supports encrypting memory files into secure capsules using industry-standard encryption. Encrypted files use the `.mv2e` extension and require a password to access. *** ## Overview | Feature | Specification | | ------------------ | -------------------------------------- | | **Cipher** | AES-256-GCM (authenticated encryption) | | **Key Derivation** | Argon2id (memory-hard, GPU-resistant) | | **File Extension** | `.mv2e` (encrypted capsule) | | **Compatibility** | Decrypt to use with any Memvid command | *** ## Encrypting a Memory File ### Interactive Password ```bash theme={null} # Encrypt with interactive password prompt memvid lock memory.mv2 --out memory.mv2e ``` ``` Enter password: •••••••••••••••• Confirm password: •••••••••••••••• ✓ Encrypted memory.mv2 → memory.mv2e Original size: 52.4 MB Encrypted size: 52.5 MB Cipher: AES-256-GCM ``` ### Password from Stdin (for Scripts) ```bash theme={null} # For automation and CI/CD echo "your-secure-password" | memvid lock memory.mv2 --password-stdin --out memory.mv2e # From environment variable echo "$MEMVID_PASSWORD" | memvid lock memory.mv2 --password-stdin --out memory.mv2e # From file cat /path/to/password-file | memvid lock memory.mv2 --password-stdin --out memory.mv2e ``` ### Options ```bash theme={null} # Keep original file (default: deletes original) memvid lock memory.mv2 --out memory.mv2e --keep-original # Overwrite existing encrypted file memvid lock memory.mv2 --out memory.mv2e --force # JSON output for scripting memvid lock memory.mv2 --out memory.mv2e --json ``` JSON output: ```json theme={null} { "status": "success", "source": "memory.mv2", "destination": "memory.mv2e", "original_size": 54938189, "encrypted_size": 54938301, "cipher": "AES-256-GCM", "kdf": "Argon2id" } ``` *** ## Decrypting a Capsule ### Interactive Password ```bash theme={null} # Decrypt with interactive password prompt memvid unlock memory.mv2e --out memory.mv2 ``` ``` Enter password: •••••••••••••••• ✓ Decrypted memory.mv2e → memory.mv2 Size: 52.4 MB ``` ### Password from Stdin ```bash theme={null} # For automation echo "your-secure-password" | memvid unlock memory.mv2e --password-stdin --out memory.mv2 # From environment variable echo "$MEMVID_PASSWORD" | memvid unlock memory.mv2e --password-stdin --out memory.mv2 ``` ### Options ```bash theme={null} # Overwrite existing file memvid unlock memory.mv2e --out memory.mv2 --force # JSON output memvid unlock memory.mv2e --out memory.mv2 --json ``` *** ## Working with Encrypted Files Encrypted files must be decrypted before use: ```bash theme={null} # This won't work directly memvid find memory.mv2e --query "search" # Error: Cannot read encrypted file # Decrypt first memvid unlock memory.mv2e --out memory.mv2 memvid find memory.mv2 --query "search" # Re-encrypt when done memvid lock memory.mv2 --out memory.mv2e ``` ### Workflow: Edit and Re-encrypt ```bash theme={null} # 1. Decrypt echo "$PASSWORD" | memvid unlock memory.mv2e --password-stdin --out memory.mv2 # 2. Make changes memvid put memory.mv2 --input new-document.pdf # 3. Re-encrypt echo "$PASSWORD" | memvid lock memory.mv2 --password-stdin --out memory.mv2e # 4. Original .mv2 is deleted (default behavior) ``` *** ## Security Details ### AES-256-GCM * **256-bit key**: Derived from your password via Argon2id * **Authenticated**: Detects tampering or corruption * **Unique nonce**: Each encryption uses a fresh random nonce * **No metadata leakage**: File size is only indicator of content size ### Argon2id Key Derivation * **Memory-hard**: Requires significant RAM, resists GPU attacks * **Time-hard**: Configurable iterations for speed/security tradeoff * **Salt**: Unique random salt per encryption * **Winner**: Password Hashing Competition (2015) Default parameters: | Parameter | Value | | ----------- | ----- | | Memory | 64 MB | | Iterations | 3 | | Parallelism | 4 | These parameters make brute-force attacks extremely expensive. *** ## Password Requirements ### Recommendations | Requirement | Recommendation | | ------------------ | ---------------------------- | | **Minimum length** | 12 characters | | **Recommended** | 16+ characters | | **Best** | 20+ characters or passphrase | ### Strong Password Examples ``` # Random characters (use password manager) Kj#9mP$2xL@nQ5vR # Passphrase (easier to remember) correct-horse-battery-staple-42 # Generated (most secure) openssl rand -base64 24 # → "X7kP2mN9qR3sT6vY8wA1bC4d" ``` ### Weak Passwords to Avoid * Dictionary words: `password`, `memory`, `secret` * Simple patterns: `123456`, `qwerty`, `abcdef` * Personal info: birthdays, names, addresses * Short passwords: anything under 12 characters *** ## Automation & CI/CD ### Environment Variables ```bash theme={null} # Set password in environment export MEMVID_ENCRYPTION_KEY="your-secure-password" # Use in scripts echo "$MEMVID_ENCRYPTION_KEY" | memvid lock memory.mv2 --password-stdin --out memory.mv2e echo "$MEMVID_ENCRYPTION_KEY" | memvid unlock memory.mv2e --password-stdin --out memory.mv2 ``` ### GitHub Actions Example ```yaml theme={null} name: Backup Memory on: schedule: - cron: '0 0 * * *' # Daily jobs: backup: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install Memvid run: curl -fsSL https://get.memvid.com | sh - name: Decrypt, update, re-encrypt env: MEMVID_PASSWORD: ${{ secrets.MEMVID_PASSWORD }} run: | echo "$MEMVID_PASSWORD" | memvid unlock memory.mv2e --password-stdin --out memory.mv2 memvid put memory.mv2 --input ./new-data/ echo "$MEMVID_PASSWORD" | memvid lock memory.mv2 --password-stdin --out memory.mv2e - name: Upload encrypted backup uses: actions/upload-artifact@v4 with: name: encrypted-memory path: memory.mv2e ``` ### Docker Example ```dockerfile theme={null} FROM memvid/cli:latest # Password passed at runtime ENV MEMVID_PASSWORD="" COPY memory.mv2e /data/ CMD echo "$MEMVID_PASSWORD" | memvid unlock /data/memory.mv2e --password-stdin --out /data/memory.mv2 && \ memvid find /data/memory.mv2 --query "$QUERY" ``` ```bash theme={null} docker run -e MEMVID_PASSWORD="secret" -e QUERY="search term" myimage ``` *** ## Use Cases ### Sensitive Documents Encrypt memories containing confidential information: ```bash theme={null} # HR documents memvid create hr.mv2 memvid put hr.mv2 --input employee-records/ memvid lock hr.mv2 --out hr.mv2e # Medical records memvid lock patient-notes.mv2 --out patient-notes.mv2e # Financial data memvid lock finances.mv2 --out finances.mv2e ``` ### Backup & Archive Secure long-term storage: ```bash theme={null} # Create encrypted backup memvid lock knowledge.mv2 --out backups/knowledge-$(date +%Y%m%d).mv2e --keep-original # Store password securely (password manager, vault, etc.) ``` ### Sharing Encrypted Memories Share with password communicated separately: ```bash theme={null} # Sender memvid lock shared-docs.mv2 --out shared-docs.mv2e # Send shared-docs.mv2e via email/cloud # Send password via separate secure channel # Recipient memvid unlock shared-docs.mv2e --out shared-docs.mv2 memvid find shared-docs.mv2 --query "search" ``` ### Compliance Requirements For HIPAA, GDPR, SOC2, etc.: ```bash theme={null} # Encrypt at rest memvid lock phi-data.mv2 --out phi-data.mv2e # Log access echo "$(date): Decrypting phi-data for user $USER" >> audit.log memvid unlock phi-data.mv2e --out phi-data.mv2 # Re-encrypt after use memvid lock phi-data.mv2 --out phi-data.mv2e echo "$(date): Re-encrypted phi-data" >> audit.log ``` *** ## Error Handling ### Wrong Password ```bash theme={null} memvid unlock memory.mv2e --out memory.mv2 # Enter password: •••••••• # Error: Decryption failed - incorrect password or corrupted file ``` ### Corrupted File ```bash theme={null} memvid unlock corrupted.mv2e --out memory.mv2 # Error: Authentication failed - file may be corrupted or tampered with ``` AES-GCM detects any modification to the encrypted file. ### File Already Exists ```bash theme={null} memvid unlock memory.mv2e --out memory.mv2 # Error: memory.mv2 already exists. Use --force to overwrite. # Solution memvid unlock memory.mv2e --out memory.mv2 --force ``` *** ## Best Practices ### 1. Use Strong Passwords ```bash theme={null} # Generate secure password openssl rand -base64 24 # Store in password manager # Never commit passwords to version control ``` ### 2. Keep Backups of Unencrypted Data If you lose the password, data is **unrecoverable**: ```bash theme={null} # Keep secure backup before encrypting cp memory.mv2 /secure-backup-location/ # Then encrypt for distribution memvid lock memory.mv2 --out memory.mv2e ``` ### 3. Separate Password from Encrypted File * Never store password in same location as encrypted file * Use different channels (email file, text password) * Use secrets managers (Vault, 1Password, etc.) ### 4. Rotate Passwords Periodically ```bash theme={null} # Decrypt with old password echo "$OLD_PASSWORD" | memvid unlock memory.mv2e --password-stdin --out memory.mv2 # Re-encrypt with new password echo "$NEW_PASSWORD" | memvid lock memory.mv2 --password-stdin --out memory.mv2e ``` ### 5. Verify After Encryption ```bash theme={null} # Encrypt memvid lock memory.mv2 --out memory.mv2e # Verify by decrypting to temp location memvid unlock memory.mv2e --out /tmp/verify.mv2 memvid stats /tmp/verify.mv2 # Should match original rm /tmp/verify.mv2 ``` *** ## Limitations | Limitation | Description | | --------------------- | ------------------------------------------------- | | **No streaming** | Must decrypt entire file to access | | **No partial access** | Can't read individual frames without full decrypt | | **Password only** | No key file or hardware key support (yet) | | **No key escrow** | Lost password = lost data | *** ## Future Features Coming soon: * Key file support (in addition to password) * Hardware security module (HSM) integration * Partial decryption for large files * Key rotation without full re-encryption *** ## Next Steps Security FAQ and compliance info Full CLI command reference