E2EE architecture
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
The server is intentionally blind to plaintext when E2EE is enabled. It stores ciphertext payloads, wrapped key material, and metadata needed to route those bytes — nothing more. All encryption and decryption happens on the client.
For the user-facing model (key hierarchy, recovery codes, formats), see End-to-end encryption. This page focuses on the server side.
Server-side components
Section titled “Server-side components”The E2EE controllers live under src/Pia.Server/Controllers/E2EE/, the logic behind them under src/Pia.Server/E2EE/.
| File | Responsibility |
|---|---|
Controllers/E2EE/E2EEDevicesController.cs |
REST API for device register, list, approve, revoke; get/set wrapped UMK |
Controllers/E2EE/E2EERecoveryController.cs |
Store / retrieve recovery-wrapped UMK, activate via recovery code, store the recovery proof key |
Controllers/E2EE/E2EEStatusController.cs |
The account’s E2EE status and one device’s status |
E2EE/E2EEDeviceService.cs |
Registration rules, approval, wrapped-UMK access, tying a session to its device |
E2EE/E2EERecoveryService.cs |
Recovery copy, proof check, recovery activation |
E2EE/DeviceRevocation.cs |
Revoke, and the part of delete that ends a device’s access |
E2EE/OnboardingSessionService.cs |
In-memory session store for device pairing — 10-minute expiry, 32-byte random server challenges |
Controllers/Filters/RejectRevokedDeviceAttribute.cs |
Refuses a revoked device’s session on sync, chats and the E2EE write routes |
OnboardingSessionService is registered as Singleton and is in-memory by design: pairing sessions are short-lived and don’t need to survive a restart. In a load-balanced deployment, route all /api/e2ee/* traffic for a given pairing to one node, or replace the implementation with a shared store.
Server entities
Section titled “Server entities”| Entity | Key | What it holds |
|---|---|---|
ServerDevice |
Id, unique per (UserId, DeviceId) |
Device name, public agreement key, public signing key, status (Pending / Active / Revoked), OS and app version, when it was created, last registered, activated and revoked |
ServerWrappedUmk |
Id, unique per (UserId, DeviceId) |
UMK wrapped for one specific device via ECDH-derived KEK, with the approving device’s signature |
PiaUser (E2EE columns) |
— | IsE2EEEnabled, UmkVersion, RecoveryWrappedUmkCiphertext, RecoveryKdf*, RecoveryWrapVersion, RecoveryProofKey |
Device IDs are chosen by the client, so two accounts can hold the same one; every lookup is keyed by account and device ID. Note what isn’t there: no plaintext UMK, no plaintext DEKs, no plaintext per-record payloads.
Endpoints
Section titled “Endpoints”Device endpoints
Section titled “Device endpoints”| Method | Path | Purpose |
|---|---|---|
POST |
/api/e2ee/devices/register |
Register a device, or register it again with new keys. It is Active only while the account has no other active device and no recovery copy, otherwise Pending |
GET |
/api/e2ee/status |
The account’s E2EE status |
GET |
/api/e2ee/devices |
List the user’s devices |
GET |
/api/e2ee/devices/{deviceId}/status |
Poll one device’s status while it waits for approval |
POST |
/api/e2ee/devices/approve |
Existing device wraps UMK for a target device |
POST |
/api/e2ee/devices/{deviceId}/revoke |
Revoke a device |
GET |
/api/e2ee/devices/{deviceId}/wrapped-umk |
Fetch the UMK wrapped for that device |
POST |
/api/e2ee/devices/{deviceId}/wrapped-umk |
Store a UMK wrapped for that device |
Recovery endpoints
Section titled “Recovery endpoints”| Method | Path | Purpose |
|---|---|---|
POST |
/api/e2ee/recovery/wrapped-umk |
Store recovery-wrapped UMK (Argon2id-derived KEK) |
GET |
/api/e2ee/recovery/wrapped-umk |
Retrieve it |
POST |
/api/e2ee/recovery/activate |
Activate a pending device with the UMK unwrapped from the recovery code |
PUT |
/api/e2ee/recovery/proof-key |
Store the key that recovery proofs are checked against; the first write wins |
/recovery/activate takes the UMK wrapped for the new device together with a proof of possession derived from the UMK, and accepts them only for the caller’s own pending device inside a live onboarding session. The UMK never leaves the device in plaintext during this exchange.
Onboarding workflows
Section titled “Onboarding workflows”First device
Section titled “First device”- Client generates UMK + ECDH (P-256) + ECDSA (P-256) keypairs.
- Client registers the device via
/devices/register. Server creates theServerDevicerow inActivestatus, because the account has no other active device and no recovery copy yet. - Client self-wraps the UMK using its own ECDH agreement key and stores it via
/devices/{deviceId}/wrapped-umk. - Client generates a recovery code (Base32, 128-bit entropy), wraps the UMK with the recovery-derived KEK (Argon2id + AES-GCM) and uploads the blob via
/recovery/wrapped-umk. The server takes it only from an account with an active device. - Client uploads the recovery proof key via
/recovery/proof-key.
Additional devices
Section titled “Additional devices”- New device registers as
Pending(uploads public keys). - Server creates an onboarding session — 10-min expiry, fresh 32-byte challenge.
- An existing
Activedevice approves the request: ECDH-wraps the UMK for the new device’s public agreement key, signs the handover with its ECDSA key and uploads both via/devices/approve. - Server verifies the signature against the approver’s stored
SigningPublicKey(ECDSA P-256 over SHA-256, IEEE P1363) and answers400without writing anything when it is missing or does not verify. It stores signature, signature version and onboarding session with theServerWrappedUmkand marks the new deviceActive. - New device fetches its wrapped UMK and the signature via
/devices/{deviceId}/wrapped-umkand unwraps locally.
Recovery activation
Section titled “Recovery activation”- User enters recovery code on a fresh device, which registers as
Pendingand gets an onboarding session. - Client derives KEK via Argon2id using the salt and parameters fetched from the server.
- Client unwraps the UMK from
/recovery/wrapped-umk. - Client computes the proof of possession from the UMK and posts it, with the UMK wrapped for this device, to
/recovery/activate. - Server marks a new device
Active; client self-wraps the UMK for ongoing use.
Security invariants the server enforces
Section titled “Security invariants the server enforces”- The UMK is never accepted in plaintext on any endpoint — only as wrapped blobs.
- All wrapped blobs include AAD that binds them to a context (
pia-umk-wrap-v1:{targetDeviceId}for device wraps,pia-dek-wrap-v1:{entityType}:{entityId}for record DEKs). A blob from one context can’t be replayed in another. - An approval activates a device only with a valid signature of the approving device. Version 1 covers the onboarding session, the target device and its agreement key; version 2 adds the wrapped UMK and its HKDF salt.
DeviceApprovalSignatureinPia.Sharedbuilds both, so server and client check the same bytes. Storing a new wrap viaPOST /devices/{deviceId}/wrapped-umkdrops the stored signature. - Onboarding sessions are bound to one account and one device and expire after 10 minutes.
- Revoking a device ends its server access: its wrapped UMK, the sessions tied to it and its pairing sessions are deleted, its refresh is refused, and a session that carries its ID gets
403 device_revokedon sync, chats and the E2EE write routes. The device list, the status routes andregisterstay open, so a revoked desktop app can notice the revoke and enrol again. The UMK is not rotated. Details and limits: Devices. - A session tied to one device cannot change the keys of another.
registeraccepts only well-formed P-256 public keys, bounded field lengths and a version number as the app version, keeps at most 5 devices per account waiting for approval, and the server deletes a waiting device afterPendingDevices:RetentionDayswithout a new registration. - Device fingerprint = SHA-256(AgreementPublicKey) truncated to 64 bits, displayed as
XXXX-XXXX-XXXX-XXXX. Used in the admin Devices view and in the desktop’s pairing UI.