Architecture¶

Overview of the components, data flows and trust boundaries. Formats and protocols in detail: Boxcryptor format (SPEC.md), Cryptomator format, Hub protocol. Security model: Security.

Components¶

flowchart LR
  subgraph Desktop["User's computer"]
    GUI["krywerk<br/>desktop app (Tauri)"]
    MNT["krywerk-mount<br/>drive (CLI)"]
    HCLI["krywerk-hub<br/>team folders (CLI)"]
    REC["krywerk-recover<br/>Boxcryptor files (CLI)"]
    subgraph Libs["Libraries"]
      BCM["kw-mount<br/>WinFsp · FUSE-T · libfuse"]
      VAULT["kw-vault<br/>plaintext view, migration"]
      CMF["kw-format<br/>Cryptomator format 8"]
      BCC["kw-legacy<br/>Boxcryptor format"]
      HUB["kw-hub-client<br/>Hub client"]
      JOSE["kw-jose<br/>JWE/JWS P-384"]
    end
  end
  subgraph Server["Organization"]
    KS["krywerk-server<br/>key server + web administration"]
    DB[("SQLite")]
    IDP["Identity provider (OIDC)<br/>Keycloak / Entra ID"]
  end
  CLOUD[("Sync folder<br/>OneDrive · Nextcloud · NAS …")]

  GUI --> BCM & HUB
  MNT --> BCM & HUB
  HCLI --> HUB
  REC --> BCC
  BCM --> VAULT --> CMF & BCC
  HUB --> JOSE
  HUB -- HTTPS --> KS
  GUI -. Browser sign-in .-> IDP
  KS --> DB
  KS -- JWKS --> IDP
  VAULT -- "ciphertext only" --> CLOUD

Crate	Kind	Purpose
`kw-legacy`	Library	Boxcryptor format (clean room): key file, file content, file names
`kw-vault`	Library	Plaintext view of Boxcryptor folders and Cryptomator vaults, overlay for the migration
`kw-format`	Library	Cryptomator vault format 8 (master key, content, names)
`kw-jose`	Library	JWE (ECDH-ES, PBES2) and JWS (ES384) on P-384 for team folders
`kw-hub-client`	Library	Client for the Hub protocol: sign-in (OIDC + PKCE), devices, vault keys, management, emergency access
`kw-mount`	Library + `krywerk-mount`	Drive adapter: WinFsp (Windows), FUSE-T (macOS), libfuse 3 (Linux) via a shared C bridge
`kw-app`	`krywerk`	Desktop app: drives, team folders, migration, system tray, context menu
`kw-hub`	`krywerk-hub`	Manage team folders from the command line
`kw-recover`	`krywerk-recover`	Decrypt/encrypt Boxcryptor files without a drive
`krywerk-server`	`krywerk-server`	Hub-compatible key server (axum, SQLite), web administration, emergency access, audit log

Drive: no kernel driver of our own¶

Krywerk implements a user-mode file system. The driver comes from a maintained, signed framework on each platform: WinFsp on Windows, FUSE-T (no kernel extension) on macOS, libfuse 3 on Linux. Each read decrypts only the affected blocks; writes happen block by block with a fresh random nonce.

sequenceDiagram
  participant App as Program (Word, Finder …)
  participant FS as WinFsp / FUSE
  participant M as kw-mount
  participant V as kw-vault / kw-format
  participant D as Sync folder (ciphertext)
  App->>FS: read("Report.docx", 0..64 KiB)
  FS->>M: read(path, offset, length)
  M->>V: plaintext path → encrypted path
  V->>D: read ciphertext blocks
  V-->>M: verify and decrypt blocks with AES-GCM
  M-->>FS: plaintext
  FS-->>App: data

Team folders: keys without a shared password¶

The server stores a team folder's vault key only in encrypted form – separately for each person (ECDH P-384, JWE). A person's private keys are stored on the server encrypted with their unlock code, and on each of their devices encrypted with the device key, which never leaves the device (Windows DPAPI, macOS keychain, Linux Secret Service).

sequenceDiagram
  participant U as Krywerk app
  participant I as Identity provider (OIDC)
  participant S as Krywerk Server
  U->>I: sign-in in the browser (PKCE)
  I-->>U: access token
  U->>S: GET /api/vaults/{id}/access-token (token, device ID)
  S->>S: check access (person, group, role)
  S-->>U: vault key, encrypted for this person
  U->>U: decrypt with device key → personal key → vault key
  U->>U: mount drive

Trust boundaries:

Server: sees names, email addresses, groups, shares and encrypted keys – never files, file names or decrypted keys.
Storage location (cloud, NAS): sees only ciphertext, encrypted names, and the number and approximate size of the files.
Identity provider: confirms who signs in; receives no keys.

Migration from Boxcryptor¶

During the migration, an overlay (kw-vault::overlay) shows the old Boxcryptor folder and the new vault as one drive. New and changed files go into the vault; the rest is transferred at the push of a button or folder by folder. After that, the Boxcryptor folder is no longer needed.

Platforms¶

	Windows	macOS	Linux
Drive	WinFsp	FUSE-T	libfuse 3
Passwords, device keys	DPAPI	Keychain	Secret Service (KWallet, GNOME)
Context menu	Explorer	Finder Quick Actions	Dolphin, Nautilus
Window content	WebView2	WKWebView	WebKitGTK