From 69d4feaa07b23ba7f51bafabb24731a8c8dd428b Mon Sep 17 00:00:00 2001 From: Nils Pukropp Date: Mon, 12 Oct 2026 00:07:18 +0200 Subject: [PATCH] docs: add a security model page for users Readers asked whether the client can be trusted with their files. The threat model in ARCHITECTURE.md is written for contributors, so docs/SECURITY_MODEL.md summarises it for users: encryption comes from the SDK and rPGP, sign-in uses SRP, what is stored where and how it is protected, who can reach the daemon, every network connection, what the client does not protect against, and how each package is built and signed. It says that there has been no independent audit. It is linked from the README, the documentation index and SECURITY.md. --- README.md | 1 + SECURITY.md | 3 ++ docs/README.md | 1 + docs/SECURITY_MODEL.md | 83 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 88 insertions(+) create mode 100644 docs/SECURITY_MODEL.md diff --git a/README.md b/README.md index 342e702..04a592c 100644 --- a/README.md +++ b/README.md @@ -109,6 +109,7 @@ video thumbnails), headless use and uninstalling. | [Configuration](docs/CONFIGURATION.md) | `config.json`, file locations, environment variables, the service | | [Troubleshooting](docs/TROUBLESHOOTING.md) | Diagnosing problems and fixing common ones | | [Recovering on a new computer](docs/RECOVERY.md) | Getting your synced folders back after a reinstall or a lost machine | +| [Security model](docs/SECURITY_MODEL.md) | What protects your files, what stays on this computer, what the client connects to | | [Changelog](docs/CHANGELOG.md) | What changed in each release | For contributors: [development guide](docs/DEVELOPMENT.md), [architecture](docs/ARCHITECTURE.md), diff --git a/SECURITY.md b/SECURITY.md index 3106ba4..39aece9 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,6 +4,9 @@ Fixes land on the latest release. Please reproduce on the most recent version before reporting. +For what the client protects and what it does not, written for users, see the +[security model](docs/SECURITY_MODEL.md). + ## Reporting a vulnerability **Do not open a public issue.** Report privately through GitHub's diff --git a/docs/README.md b/docs/README.md index a691cdf..afe77f7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,7 @@ | [Configuration](CONFIGURATION.md) | `config.json`, environment variables, file locations, the systemd service | | [Troubleshooting](TROUBLESHOOTING.md) | Diagnosing problems, common symptoms, starting over, reporting a bug | | [Recovering on a new computer](RECOVERY.md) | What survives a lost machine and how to restore your synced folders | +| [Security model](SECURITY_MODEL.md) | What protects your files, what is kept on this computer, what the client connects to | | [Changelog](CHANGELOG.md) | What changed in each release | ## For contributors diff --git a/docs/SECURITY_MODEL.md b/docs/SECURITY_MODEL.md new file mode 100644 index 0000000..89be444 --- /dev/null +++ b/docs/SECURITY_MODEL.md @@ -0,0 +1,83 @@ +# Security model + +This page explains what protects your files and account when you use this client, what it keeps +on your computer, and what it does not protect against. It is a summary for users. The details, +with references to the code, are in the +[threat model](ARCHITECTURE.md#10-threat-model-what-this-client-writes-to-disk-in-plaintext). To +report a vulnerability, see [SECURITY.md](../SECURITY.md). + +This is an unofficial hobby project, not a Proton product. It has had no independent security +audit. The source is open under the MIT license, so you can read and build all of it yourself. + +## Encryption + +Proton Drive is end-to-end encrypted, and this client does not change that: + +- **Files are encrypted on this computer before they are uploaded,** and decrypted on this + computer after they are downloaded. Proton never receives your keys or the content of your + files. +- **The cryptography comes from the SDK, not from this client.** The client uses + [`proton-sdk` and `proton-drive-rs`](https://github.com/narrrl/proton-sdk-rs), a Rust port of + Proton's official C# and TypeScript Drive SDKs. OpenPGP is done by the + [rPGP](https://github.com/rpgp/rpgp) library. The client itself does not implement any + encryption. +- **Your password is not sent to Proton.** Sign-in uses Proton's SRP protocol, which proves that + you know the password without sending it. + +## What is kept on this computer + +| What | Where | Protected by | +|---|---|---| +| Session tokens and the key passphrases | The system keyring (Secret Service: GNOME Keyring, KWallet, KeePassXC) | The keyring's own encryption and your login | +| Your password | Nowhere | — | +| Cached files, thumbnails and changes waiting to upload | `~/.cache/proton-drive-linux/content/` | File modes only: **not encrypted** | +| File and folder names, the folder tree, the activity log | `~/.local/state/proton-drive-linux/cache.db` | File modes only: **not encrypted** | +| The SDK's metadata cache | `~/.local/state/proton-drive-linux/sdk_cache.db` | Encrypted with a key derived from your mailbox password | +| Settings | `~/.config/proton-drive-linux/config.json` | No secrets are stored here | + +The cache holds decrypted content so that files open fast and work offline. **The client assumes +that your disk is encrypted** (LUKS, or an encrypted home directory). On an unencrypted disk, +someone who has the powered-off computer can read the cached files and the names in your Drive. + +Accounts with a separate mailbox password (two-password mode) are locked by default. Their key +passphrases are kept in the kernel keyring for your login session only, and you unlock again +after each login. Storing them in the system keyring is an opt-in. + +## Who can use the client + +- The state, cache and config directories must belong to you and have mode `0700`. The daemon + checks this at every start and refuses to run otherwise. +- The control socket that the app, tray and `pdfs` use has mode `0600`. Only your user account + can connect to it. +- Any program that runs as your user can read, change and delete files in `~/ProtonDrive`, the same + as in any other folder you own. It is your Proton Drive, not a copy: a deleted file is moved to + the Proton Drive trash, where you can restore it. + +## Network connections + +The client connects only to: + +- **Proton**, for the Drive and account API, and for the CAPTCHA page when Proton asks for one. +- **OpenFreeMap**, for the street map of Places in Photos, only if you turn it on in Preferences. It is off by default, because the tile server learns which parts of the + world you look at. The default map is drawn from data shipped with the app. + +There is no telemetry, no analytics and no update check. The SDK can report timings of its own +operations, and the client only writes them to its local log. + +## What this client does not protect against + +- **Malware running as your user.** It can read the cache, connect to the control socket, and use + your Drive through the mount, as it can with any data you have access to. +- **Swap.** Keys and decrypted data are in ordinary memory and can be written to swap. Use + encrypted swap. +- **The kernel page cache.** File content read through the mount is cached by the kernel like any + other file. + +## Packages + +- The `.rpm` is signed with GPG. +- The `.deb` and the `.tar.gz` are built by GitHub Actions from the tagged source, and are not + signed. +- The AUR packages build from the tagged source or from `main`, or install the release binaries + checked against their SHA-256 sums. +- The Nix flake builds from source. The binary cache on Cachix holds builds made by CI.