Encryption

Crabdrop provides optional client-side encryption. Files are encrypted before they leave your machine and decrypted after download. Your storage provider never sees the plaintext data.

Algorithm

How It Works

Encryption (upload)

1. Your passphrase and the filename are fed into Argon2 to derive a 256-bit key
2. The file is split into 1 MB chunks
3. Each chunk gets a random 24-byte nonce
4. Each chunk is encrypted with XChaCha20-Poly1305
5. Output per chunk: nonce (24 bytes) || ciphertext || tag (16 bytes)
6. A UUID is generated as the S3 object key
7. The mapping UUID → original filename is added to the encrypted metadata file

Decryption (download)

1. The same passphrase + filename derive the same key via Argon2
2. Each chunk’s nonce is extracted (first 24 bytes)
3. The ciphertext is decrypted and authenticated
4. If the tag doesn’t match (wrong passphrase), decryption fails with an error

Metadata File

Crabdrop stores a special file in your bucket called CRABDROP_METADATA_DO_NOT_DELETE. This file:

• Contains a JSON map of UUID → original filename for every encrypted file
• Is itself encrypted with your passphrase
• Is updated on every encrypted upload
• Is protected by a mutex to prevent race conditions during concurrent uploads

Do not delete this file. Without it, Crabdrop cannot resolve encrypted filenames.

Changing Your Passphrase

When you change your encryption passphrase in settings, Crabdrop re-encrypts the metadata file with the new passphrase. Previously encrypted files remain encrypted with the old key derivation (since the filename salt doesn’t change). The metadata mapping is the only thing re-encrypted.

Important Notes

• Encryption is per-file — you choose on each upload whether to encrypt
• The encryption passphrase is stored in your OS keychain
• Encrypted files appear with a lock icon in the file browser
• Presigned URLs for encrypted files will serve the encrypted (unusable) data — the recipient cannot decrypt without the passphrase and Crabdrop