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