Client-Side Encryption

GhostFS supports optional client-side encryption using XChaCha20-Poly1305. When enabled, the server only sees encrypted data.

Generate an Encryption Key

ghostfs admin generate-key ~/.ghostfs/encryption.key

Keep this key safe! Without it, you cannot decrypt your files.

Mount with Encryption

ghostfs mount /mnt/remote \
  --host server.local \
  --user alice \
  --token xxx \
  --encrypt \
  --encryption-key ~/.ghostfs/encryption.key

How It Works

• Each file has a random 16-byte file ID
• Each 4KB block is encrypted with a unique nonce
• The server stores only ciphertext
• Decryption happens entirely on the client

Important Notes

• Back up your key — Lost keys mean lost data
• Same key for all mounts — Use the same key to access your encrypted files
• Performance — Encryption adds minimal overhead due to hardware AES-NI support