Aller au contenu

E2EE architecture

Ce contenu n’est pas encore disponible dans votre langue.

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.

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.

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.

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

  1. Client generates UMK + ECDH (P-256) + ECDSA (P-256) keypairs.
  2. Client registers the device via /devices/register. Server creates the ServerDevice row in Active status, because the account has no other active device and no recovery copy yet.
  3. Client self-wraps the UMK using its own ECDH agreement key and stores it via /devices/{deviceId}/wrapped-umk.
  4. 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.
  5. Client uploads the recovery proof key via /recovery/proof-key.
  1. New device registers as Pending (uploads public keys).
  2. Server creates an onboarding session — 10-min expiry, fresh 32-byte challenge.
  3. An existing Active device 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.
  4. Server verifies the signature against the approver’s stored SigningPublicKey (ECDSA P-256 over SHA-256, IEEE P1363) and answers 400 without writing anything when it is missing or does not verify. It stores signature, signature version and onboarding session with the ServerWrappedUmk and marks the new device Active.
  5. New device fetches its wrapped UMK and the signature via /devices/{deviceId}/wrapped-umk and unwraps locally.
  1. User enters recovery code on a fresh device, which registers as Pending and gets an onboarding session.
  2. Client derives KEK via Argon2id using the salt and parameters fetched from the server.
  3. Client unwraps the UMK from /recovery/wrapped-umk.
  4. Client computes the proof of possession from the UMK and posts it, with the UMK wrapped for this device, to /recovery/activate.
  5. Server marks a new device Active; client self-wraps the UMK for ongoing use.
  • 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. DeviceApprovalSignature in Pia.Shared builds both, so server and client check the same bytes. Storing a new wrap via POST /devices/{deviceId}/wrapped-umk drops 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_revoked on sync, chats and the E2EE write routes. The device list, the status routes and register stay 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. register accepts 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 after PendingDevices:RetentionDays without 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.