How CryFS Works
Learn how CryFS protects your data with advanced encryption techniques.
This page explains the technical details of CryFS. If you're looking to get started quickly, check out the CryFS Tutorial instead.
At a Glance
CryFS is designed to encrypt your files for cloud storage while hiding not just the content, but also the structure and metadata of your data.
On This Page
| Threat Model | What CryFS protects against and its security boundaries |
| Block-Based Storage | How files are split into encrypted blocks to hide metadata |
| Configuration File | Two-layer encryption and key derivation |
| Integrity Protection | Version tree and rollback protection |
| Security Analysis | Academic publications and proven security properties |
Threat Model
Before diving into the technical details, it's important to understand what CryFS protects against and its security boundaries.
What CryFS Protects Against
CryFS is designed to protect your data when stored on untrusted storage, such as cloud providers. It defends against:
- Curious cloud providers: Employees or systems at your cloud provider cannot read your files
- Data breaches: If hackers gain access to your cloud storage, they see only encrypted blocks
- Metadata analysis: Attackers cannot determine file sizes, names, types, permission bits, timestamps, or directory structure
- Tampering: Modifications to encrypted blocks are detected and rejected
- Rollback attacks: Attackers cannot replace files with older versions without detection
Security Boundaries
CryFS assumes your local machine is secure. It does not protect against:
- Compromised local systems: If malware has access to your mounted filesystem, it can read your files
- Weak passwords: Security depends on using a strong password for the configuration file (alternatively, you can store the configuration file locally using
--configto remain secure even with a weak password) - Denial of service: An attacker with access to your cloud storage could delete your encrypted blocks
Block-Based Storage
Why Block-Based?
Traditional file-based encryption (like EncFS or gocryptfs) creates one encrypted file for each of your files. This reveals information: an attacker can see how many files you have, how large each one is, and how they're organized into directories. This metadata can reveal a surprising amount about what you're storing.
CryFS takes a different approach. Instead of encrypting files individually, it splits all data into fixed-size blocks (typically 32KB). These blocks are then encrypted and stored with random IDs as filenames.
How It Works
- File content is split into same-size blocks
- Directory structure is stored as additional encrypted blocks
- Metadata (file names, sizes, timestamps) is stored in encrypted blocks
- A tree structure connects the blocks, allowing CryFS to reconstruct your files
Crucially, all these block types—file content, directory entries, metadata, and tree structure—are encrypted identically and are completely indistinguishable from each other. An attacker cannot tell whether a block contains part of a file, a directory listing, or internal tree structure.
The result: an attacker with access to your cloud storage sees only a collection of identically-sized encrypted blocks with random names. They cannot determine:
- How many files you have
- The size of any individual file
- Your directory structure
- File names, types, or modification times
Block Encryption
Each block is encrypted using an authenticated encryption cipher (default: XChaCha20-Poly1305). This provides:
- Confidentiality: The content cannot be read without the key
- Integrity: Any modification to a block is detected
- Authentication: Blocks can only be created by someone with the key
A unique encryption key is generated when you create a CryFS filesystem. This key is stored in the configuration file, protected by your password.
Configuration File
When you create a CryFS filesystem, it generates a configuration file (typically named cryfs.config) in the vault directory. This file contains everything CryFS needs to decrypt your data.
Stored Information
The configuration file includes:
- Cipher: The encryption algorithm used (e.g.,
xchacha20-poly1305) - Encryption key: The master key for encrypting all blocks
- Root block ID: The entry point to your encrypted filesystem
- Filesystem ID: A unique identifier for integrity verification
Two-Layer Encryption
The configuration file itself is encrypted with two layers to ensure maximum security:
- Inner layer: Encrypted with your chosen cipher and a key derived from your password
- Outer layer: Encrypted with AES-256-GCM and a separate derived key
This dual encryption means:
- If you don't trust AES-256-GCM, you can choose another cipher for additional protection
- An attacker cannot even see which cipher you selected
- The cipher name cannot be tampered with to force a weaker algorithm
Key Derivation
Both encryption keys are derived from your password using scrypt, a memory-hard key derivation function designed to be resistant to brute-force attacks. The scrypt parameters are stored (unencrypted) at the beginning of the configuration file so CryFS knows how to regenerate the keys.
Security Recommendations
For maximum security, consider these options:
- Use a strong password: The security of your encrypted data depends on it
- Keep config locally: Use
--config /local/pathto store the configuration file outside your cloud storage - Verify cipher on mount: The AES-256-GCM outer layer already protects against configuration tampering. If you don't trust AES-256-GCM, use
--cipher xchacha20-poly1305to explicitly verify the cipher on each mount
Integrity Protection
CryFS provides comprehensive integrity protection beyond just authenticated encryption of individual blocks.
Version Tree
CryFS maintains a version tree that tracks the expected version of each block. This prevents:
- Block rollback: Replacing a block with an earlier valid version
- Block deletion: Removing blocks from the filesystem
- Block reordering: Rearranging the structure of your data
How It Works
Each time a block is modified, its version number is incremented. CryFS stores these version numbers locally on your machine (not in the cloud), which allows it to detect if any block has been rolled back or if the version information itself has been tampered with.
Each time a block is loaded, CryFS verifies that its version number matches what it expects. If there's a mismatch, CryFS alerts you to the tampering.
Limitations
Integrity protection requires state to be maintained about what versions are expected. This state is stored on your local machine. If you access the filesystem from a new machine, CryFS will need to trust the current state of the cloud storage as a baseline for rollback detection. However, the authenticated encryption scheme still ensures that attackers cannot arbitrarily modify block contents—only rollback protection is affected when accessing from a new device.
Security Analysis
The security of CryFS has been formally analyzed and proven using game-based security proofs.
Academic Publications
- Master's Thesis (2015): CryFS: Design and Implementation of a Provably Secure Encrypted Cloud Filesystem - Contains detailed security definitions and proofs
- DBSec 2017: A Novel Cryptographic Framework for Cloud File Systems and CryFS, a Provably-Secure Construction (PDF) - Peer-reviewed publication at the 31st Annual IFIP WG 11.3 Conference on Data and Applications Security and Privacy
Proven Security Properties
The security analysis proves that CryFS achieves:
Confidentiality:
- IND-aCCFA security: An adaptation of IND-CCA (indistinguishability under adaptive chosen ciphertext attacks) to file systems, proving that encrypted data reveals nothing about the plaintext (except the total size of the whole file system)
- File content: Cannot be read without the key
- File sizes: Hidden by fixed-size blocks
- Directory structure: Indistinguishable from random data
- Metadata: File names, timestamps, and counts are encrypted
Integrity:
- Block integrity: Modified blocks are detected and rejected
- Rollback protection: Old versions of blocks cannot be substituted
- Structural integrity: The filesystem structure cannot be tampered with
Comparison with Other Tools
As far as we know, CryFS is the only cloud filesystem encryption tool with published, peer-reviewed security proofs. Other tools may be secure, but their security properties have not been formally analyzed and documented.
Ready to get started?