How vgough/encfs works
1. What this repository is
- This is a Rust reimplementation of EncFS, a userspace encrypted filesystem built on FUSE.
- The architectural boundary is clear: the process sits between a plaintext mount point and an on-disk encrypted backing directory, translating filesystem operations in both directions.
2. Top-level execution model
- The repo produces three user-facing binaries:
- encfs: mounts an encrypted directory as a read/write plaintext filesystem.
- encfsctl: administrative tool for creating, inspecting, and upgrading configs.
- encfsr: reverse mode, which exposes an encrypted view of a plaintext source directory.
- The core logic is shared in the library crate rather than duplicated across binaries.
3. FUSE filesystem layer
- src/fs.rs is the normal filesystem implementation that handles FUSE callbacks and maps VFS operations to encrypted storage operations.
- src/reverse_fs.rs is a separate filesystem implementation for reverse mode; it presents the encrypted projection of a plaintext tree and is explicitly read-only.
- This is the main runtime boundary: kernel VFS requests enter via FUSE, and the Rust process translates them into backend file operations.
4. Data flow in normal mode
- For encfs, plaintext reads/writes happen at the mount point.
- The filesystem layer:
1. resolves the requested path,
2. maps names and metadata through EncFS rules,
3. encrypts or decrypts file contents via the crypto layer,
4. stores/retrieves encrypted bytes on the raw directory backing store.
- Directory entries, filenames, xattrs, truncation, and symlinks are all part of the translation boundary, not just file content.
5. Data flow in reverse mode
- For encfsr, the source directory is plaintext, but the mounted view is the encrypted representation.
- This is intended for backup/sync workflows where the destination should receive only encrypted data.
- The reverse filesystem reuses the same crypto and config concepts, but inverts the mapping direction and forbids writes, so the mount acts as a deterministic export layer.
6. Cryptography subsystem
- src/crypto/ contains the encryption primitives and file-format logic:
- aead.rs, cipher.rs, block.rs, file.rs, ssl.rs
- The readme indicates modern support for Argon2id key derivation and aes-gcm-siv block encryption.
- This layer is responsible for content protection, filename encryption, IV handling, and tamper resistance, and it is separate from filesystem mechanics.
7. Configuration architecture
- src/config.rs, src/config_binary.rs, and src/config_proto.rs suggest multiple config representations and compatibility handling.
- proto/encfs_config.proto and the presence of both binary/proto config modules indicate a structured config format rather than ad hoc parsing.
- The repository supports migration from older EncFS configs, with the readme calling out a V7 tamper-safe config and upgrade tooling.
8. Configuration lifecycle and admin tooling
- encfsctl is the configuration-management boundary:
- create new encrypted volumes,
- upgrade older volumes,
- potentially inspect and validate configuration state.
- The readme’s upgrade flow writes a new config file while leaving old configs in place, so config migration is an explicit admin operation rather than an automatic mount-time mutation.
9. Security and policy boundaries
- src/security.rs likely centralizes security-sensitive checks such as permissions, ownership, and mount-related constraints.
- The project emphasizes password handling via stdin or external password helper programs, and it supports non-interactive use for scripted setups.
- In architecture terms, password acquisition is a separate boundary from filesystem access and from crypto key derivation.
10. Compatibility and legacy support
- The test tree shows strong emphasis on compatibility with older EncFS variants and on preserving behavior across config versions.
- Fixtures for older .encfs5/XML configs and tests like config_compatibility, legacy, and write_compat_test indicate that the code must parse and honor legacy on-disk formats.
- This means the architecture includes a compatibility layer between modern Rust internals and historical EncFS data formats.
11. Observability and correctness focus
- The repository leans heavily on automated verification:
- integration tests for Argon2 calibration and password upgrades,
- live mount tests,
- permission, symlink, truncate, xattr, and rename behavior tests.
- These tests imply the filesystem semantics are a major architectural concern, especially around edge cases that interact with FUSE and encrypted metadata.
12. Build, tooling, and generated assets
- The project is Rust-based (Cargo.toml), with build.rs and a proto/ definition suggesting generated code during build.
- CI is wired through GitHub Actions and Cirrus, with fuzzing support in fuzz/ for file-operation robustness.
- Locale files under locales/ indicate the binaries have user-facing messages/help text with multilingual support, though this does not affect core data flow.
13. How to diagram it
- A good architecture diagram should show:
- the three binaries at the top,
- a shared core library underneath,
- the FUSE boundary between kernel and userspace,
- the filesystem engines (fs and reverse_fs) in the middle,
- crypto/config/security modules as support services,
- and the encrypted backing directory or plaintext source directory as the external storage boundary depending on mode.
- The key distinction is that normal mode encrypts/decrypts data in transit to storage, while reverse mode exports an encrypted view from plaintext storage.
Main entry points: lib.rs Library · fs.rs Normal FS · reverse_fs.rs Reverse FS · tests Tests
Components 20
Binaries
User-facing executables for mounting and admin tasks.
Core
Shared library and major runtime subsystems.
- Library · Shared crate entry point used by all binaries.
src/lib.rs - Normal FS · FUSE filesystem that maps plaintext operations to encrypted backing storage.
src/fs.rs - Reverse FS · Read-only FUSE filesystem that exports encrypted views from plaintext sources.
src/reverse_fs.rs - Config · High-level configuration model shared across runtime and tooling.
src/config.rs - Binary config · Binary/compatibility representation for older EncFS configurations.
src/config_binary.rs - Proto config · Protobuf-backed configuration representation and compatibility support.
src/config_proto.rs - Crypto · Cryptographic subsystem for content, filename, and file-format protection.
src/crypto/mod.rs - AEAD · Authenticated encryption primitives for blocks and records.
src/crypto/aead.rs - File crypto · Per-file encryption format, IV handling, and data framing.
src/crypto/file.rs - Security · Security-sensitive checks and mount-related constraints.
src/security.rs - Proto schema · Source schema for generated configuration compatibility code.
proto/encfs_config.proto
Boundaries
External filesystem and mount targets around the FUSE process.
- Kernel VFS · FUSE request source entering the userspace filesystem.
- Plaintext mount · User-visible plaintext filesystem view in normal mode.
- Encrypted store · On-disk encrypted backing directory used by normal mode.
- Plain source · Plaintext source directory used by reverse mode.
Connections 24
- encfs → Library: uses · Main binary links shared library functionality.
- encfsctl → Library: uses · Admin binary uses shared config and crypto logic.
- encfsr → Library: uses · Reverse binary reuses the shared library core.
- Library → Normal FS: exports · Shared library exposes normal filesystem implementation.
- Library → Reverse FS: exports · Shared library exposes reverse filesystem implementation.
- Library → Config: owns · Library defines the main configuration model.
- Config → Binary config: compat · Configuration model supports legacy binary representation.
- Config → Proto config: compat · Configuration model supports protobuf-backed representation.
- Proto config → Proto schema: derived from · Protobuf module is generated from the schema.
- Library → Crypto: uses · Filesystem and tooling depend on crypto services.
- Crypto → AEAD: contains · AEAD primitives are a core crypto component.
- Crypto → File crypto: contains · File-format encryption logic lives in crypto.
- Normal FS → Kernel VFS: serves · Normal filesystem receives FUSE operations from the kernel.
- Normal FS → Plaintext mount: exposes · Normal mode presents a plaintext mount point.
- Normal FS → Encrypted store: reads/writes · Normal mode translates to encrypted backing storage.
- Reverse FS → Kernel VFS: serves · Reverse filesystem receives FUSE operations from the kernel.
- Reverse FS → Plain source: reads · Reverse mode reads from the plaintext source directory.
- Reverse FS → Plaintext mount: exposes · Reverse mode mounts an encrypted view for export.
- Library → Security: uses · Core runtime applies security and policy checks.
- Build → Proto schema: generates · Build script participates in generated config support.
- Tests → Normal FS: verifies · Integration tests exercise normal filesystem behavior.
- Tests → Reverse FS: verifies · Integration tests exercise reverse mode behavior.
- Tests → Config: verifies · Tests cover config compatibility and upgrades.
- Tests → Crypto: verifies · Tests cover crypto and password upgrade behavior.