# vgough/encfs architecture

> Architecture diagram of the GitHub repository vgough/encfs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vgough/encfs
- Repository: https://github.com/vgough/encfs

## Overview

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: [`src/lib.rs`](https://github.com/vgough/encfs/blob/master/src/lib.rs) (Library), [`src/fs.rs`](https://github.com/vgough/encfs/blob/master/src/fs.rs) (Normal FS), [`src/reverse_fs.rs`](https://github.com/vgough/encfs/blob/master/src/reverse_fs.rs) (Reverse FS), [`tests`](https://github.com/vgough/encfs/tree/master/tests) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_binaries["Binaries"]
  node_node_main["encfs<br/>binary mount<br/>[main.rs]"]
  node_node_ctl["encfsctl<br/>binary admin<br/>[encfsctl.rs]"]
  node_node_revbin["encfsr<br/>binary reverse<br/>[encfsr.rs]"]
end

subgraph group_grp_core["Core"]
  node_node_lib["Library<br/>shared core<br/>[lib.rs]"]
  node_node_fs["Normal FS<br/>fuse rw<br/>[fs.rs]"]
  node_node_rfs["Reverse FS<br/>fuse ro<br/>[reverse_fs.rs]"]
  node_node_cfg["Config<br/>settings<br/>[config.rs]"]
  node_node_cfgbin["Binary config<br/>legacy format<br/>[config_binary.rs]"]
  node_node_cfgproto["Proto config<br/>schema codec<br/>[config_proto.rs]"]
  node_node_crypto{{"Crypto<br/>[mod.rs]"}}
  node_node_aead["AEAD<br/>content cipher<br/>[aead.rs]"]
  node_node_filecrypto["File crypto<br/>file format<br/>[file.rs]"]
  node_node_sec["Security<br/>policy checks<br/>[security.rs]"]
  node_node_proto["Proto schema<br/>[encfs_config.proto]"]
end

subgraph group_grp_boundary["Boundaries"]
  node_node_kernel(("Kernel VFS<br/>external kernel"))
  node_node_plainmount(("Plaintext mount<br/>external mount"))
  node_node_encbacking[("Encrypted store<br/>external storage")]
  node_node_plainsrc[("Plain source<br/>external storage")]
end

subgraph group_grp_tooling["Tooling"]
  node_node_build["Build<br/>generated code<br/>[build.rs]"]
  node_node_tests["Tests<br/>integration suite"]
end

node_node_main -->|"uses"| node_node_lib
node_node_ctl -->|"uses"| node_node_lib
node_node_revbin -->|"uses"| node_node_lib
node_node_lib -->|"exports"| node_node_fs
node_node_lib -->|"exports"| node_node_rfs
node_node_lib -->|"owns"| node_node_cfg
node_node_cfg -->|"compat"| node_node_cfgbin
node_node_cfg -->|"compat"| node_node_cfgproto
node_node_cfgproto -.->|"derived from"| node_node_proto
node_node_lib -->|"uses"| node_node_crypto
node_node_crypto -->|"contains"| node_node_aead
node_node_crypto -->|"contains"| node_node_filecrypto
node_node_fs -->|"serves"| node_node_kernel
node_node_fs -->|"exposes"| node_node_plainmount
node_node_fs -->|"reads/writes"| node_node_encbacking
node_node_rfs -->|"serves"| node_node_kernel
node_node_rfs -->|"reads"| node_node_plainsrc
node_node_rfs -->|"exposes"| node_node_plainmount
node_node_lib -->|"uses"| node_node_sec
node_node_build -.->|"generates"| node_node_proto
node_node_tests -.->|"verifies"| node_node_fs
node_node_tests -.->|"verifies"| node_node_rfs
node_node_tests -.->|"verifies"| node_node_cfg
node_node_tests -.->|"verifies"| node_node_crypto

click node_node_main "https://github.com/vgough/encfs/blob/master/src/main.rs"
click node_node_ctl "https://github.com/vgough/encfs/blob/master/src/encfsctl.rs"
click node_node_revbin "https://github.com/vgough/encfs/blob/master/src/encfsr.rs"
click node_node_lib "https://github.com/vgough/encfs/blob/master/src/lib.rs"
click node_node_fs "https://github.com/vgough/encfs/blob/master/src/fs.rs"
click node_node_rfs "https://github.com/vgough/encfs/blob/master/src/reverse_fs.rs"
click node_node_cfg "https://github.com/vgough/encfs/blob/master/src/config.rs"
click node_node_cfgbin "https://github.com/vgough/encfs/blob/master/src/config_binary.rs"
click node_node_cfgproto "https://github.com/vgough/encfs/blob/master/src/config_proto.rs"
click node_node_crypto "https://github.com/vgough/encfs/blob/master/src/crypto/mod.rs"
click node_node_aead "https://github.com/vgough/encfs/blob/master/src/crypto/aead.rs"
click node_node_filecrypto "https://github.com/vgough/encfs/blob/master/src/crypto/file.rs"
click node_node_sec "https://github.com/vgough/encfs/blob/master/src/security.rs"
click node_node_proto "https://github.com/vgough/encfs/blob/master/proto/encfs_config.proto"
click node_node_build "https://github.com/vgough/encfs/blob/master/build.rs"
click node_node_tests "https://github.com/vgough/encfs/tree/master/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_main,node_node_ctl,node_node_revbin toneBlue
class node_node_lib,node_node_fs,node_node_rfs,node_node_cfg,node_node_cfgbin,node_node_cfgproto,node_node_crypto,node_node_aead,node_node_filecrypto,node_node_sec,node_node_proto toneAmber
class node_node_kernel,node_node_plainmount,node_node_encbacking,node_node_plainsrc toneMint
class node_node_build,node_node_tests toneRose
```

## Components

### Binaries

User-facing executables for mounting and admin tasks.

- [encfs](https://github.com/vgough/encfs/blob/master/src/main.rs): binary mount · Main mount binary for normal encrypted filesystem mode. · `src/main.rs`
- [encfsctl](https://github.com/vgough/encfs/blob/master/src/encfsctl.rs): binary admin · Administrative CLI for config creation, inspection, and upgrades. · `src/encfsctl.rs`
- [encfsr](https://github.com/vgough/encfs/blob/master/src/encfsr.rs): binary reverse · Reverse-mode CLI exposing an encrypted view of plaintext data. · `src/encfsr.rs`

### Core

Shared library and major runtime subsystems.

- [Library](https://github.com/vgough/encfs/blob/master/src/lib.rs): shared core · Shared crate entry point used by all binaries. · `src/lib.rs`
- [Normal FS](https://github.com/vgough/encfs/blob/master/src/fs.rs): fuse rw · FUSE filesystem that maps plaintext operations to encrypted backing storage. · `src/fs.rs`
- [Reverse FS](https://github.com/vgough/encfs/blob/master/src/reverse_fs.rs): fuse ro · Read-only FUSE filesystem that exports encrypted views from plaintext sources. · `src/reverse_fs.rs`
- [Config](https://github.com/vgough/encfs/blob/master/src/config.rs): settings · High-level configuration model shared across runtime and tooling. · `src/config.rs`
- [Binary config](https://github.com/vgough/encfs/blob/master/src/config_binary.rs): legacy format · Binary/compatibility representation for older EncFS configurations. · `src/config_binary.rs`
- [Proto config](https://github.com/vgough/encfs/blob/master/src/config_proto.rs): schema codec · Protobuf-backed configuration representation and compatibility support. · `src/config_proto.rs`
- [Crypto](https://github.com/vgough/encfs/blob/master/src/crypto/mod.rs): crypto suite · Cryptographic subsystem for content, filename, and file-format protection. · `src/crypto/mod.rs`
- [AEAD](https://github.com/vgough/encfs/blob/master/src/crypto/aead.rs): content cipher · Authenticated encryption primitives for blocks and records. · `src/crypto/aead.rs`
- [File crypto](https://github.com/vgough/encfs/blob/master/src/crypto/file.rs): file format · Per-file encryption format, IV handling, and data framing. · `src/crypto/file.rs`
- [Security](https://github.com/vgough/encfs/blob/master/src/security.rs): policy checks · Security-sensitive checks and mount-related constraints. · `src/security.rs`
- [Proto schema](https://github.com/vgough/encfs/blob/master/proto/encfs_config.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**: external kernel · FUSE request source entering the userspace filesystem.
- **Plaintext mount**: external mount · User-visible plaintext filesystem view in normal mode.
- **Encrypted store**: external storage · On-disk encrypted backing directory used by normal mode.
- **Plain source**: external storage · Plaintext source directory used by reverse mode.

### Tooling

Build-time and verification support.

- [Build](https://github.com/vgough/encfs/blob/master/build.rs): generated code · Build script that likely drives code generation and setup. · `build.rs`
- [Tests](https://github.com/vgough/encfs/tree/master/tests): integration suite · End-to-end and compatibility tests covering mounts, legacy configs, and file operations. · `tests`

## Connections

- 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.
