215 lines
9.5 KiB
Markdown
215 lines
9.5 KiB
Markdown
# Postbox End-To-End Encryption Architecture
|
|
|
|
This document records the encryption boundary for GovOPlaN postboxes. Postbox
|
|
now implements the server-side contracts for three selectable profiles:
|
|
unencrypted content, institution-managed server envelopes, and externally
|
|
produced E2EE envelopes. The E2EE contract is operational—the server rejects
|
|
plaintext and retains ciphertext, signed manifests, wrapped keys, and digest
|
|
evidence—but a reviewed browser/device client and private-key custody provider
|
|
remain separately deployed responsibilities.
|
|
|
|
The core principle is that a postbox can become a trusted administrative
|
|
communication channel without requiring the server to see plaintext content.
|
|
The server may route, store, authorize, audit, retain, and expire messages while
|
|
message bodies and attachments remain client-encrypted.
|
|
|
|
## Goals
|
|
|
|
- asynchronous encrypted delivery for internal and portal-facing postboxes
|
|
- personal, organizational, role-bound, and function-bound postboxes
|
|
- attachments encrypted with the message
|
|
- access based on current role/function membership when configured
|
|
- honest retraction and expiry semantics
|
|
- auditable key access, delivery, and fetch events
|
|
- support for external recipients without platform accounts
|
|
- replaceable identity and trust providers
|
|
|
|
## Envelope Model
|
|
|
|
The target model is envelope encryption:
|
|
|
|
- Generate one random data encryption key per message or attachment set.
|
|
- Encrypt content with an authenticated encryption algorithm.
|
|
- Wrap the data encryption key for each authorized recipient or role mailbox.
|
|
- Store only ciphertext, wrapped keys, signed manifests, and governed metadata
|
|
on the server.
|
|
|
|
Algorithm choices should remain replaceable behind a crypto profile. The first
|
|
profile should prefer standard, reviewed primitives such as HPKE for key
|
|
wrapping and AEAD encryption for content.
|
|
|
|
## Product Profiles And Default
|
|
|
|
The content-protection policy is configurable per exact Postbox or immutable
|
|
template revision:
|
|
|
|
- `server_envelope_v1` is the recommended default. An institution-selected
|
|
Encryption vault controls server-readable envelopes and their migration
|
|
evidence. It is not end-to-end encryption.
|
|
- `external_e2ee_v1` is server-blind. An approved client or producer supplies
|
|
the ciphertext reference, signed manifest, wrapped recipient keys, key epoch,
|
|
and SHA-256 plaintext digest. GovOPlaN has no private key that can decrypt it.
|
|
- `plaintext_v1` stores clear content for institutions that explicitly choose
|
|
that boundary.
|
|
|
|
Operational metadata—including subject, routing, participants,
|
|
classifications, timestamps, attachment references, receipts, and retention
|
|
state—remains visible under every profile. Administrators therefore choose a
|
|
content-protection boundary, not a metadata-anonymity profile.
|
|
|
|
The standard policy grants new incumbents history since assignment, uses key
|
|
rewrapping for ordinary rotation and content re-encryption after compromise,
|
|
requires two-person institutional recovery and dual-control hand-over,
|
|
emergency, export, and destruction, requires strong external identity, and
|
|
limits vacancy escalation to metadata. Deployments may select other policy
|
|
values rather than inheriting a decision from GovOPlaN.
|
|
|
|
## Governed Profile Changes
|
|
|
|
A profile transition applies to new messages immediately and increments the
|
|
Postbox key epoch. Retained history can remain under the previous profile or be
|
|
migrated. The transition ledger records source and target profiles/vaults,
|
|
authority route, consent and key-holder evidence, quorum, reason, immutable
|
|
configuration snapshot, per-message source and target digest, and outcome.
|
|
|
|
Plaintext and managed-envelope migrations can use the server-side Encryption
|
|
capability. Managed decrypt, export, and re-encryption operations also create
|
|
Encryption migration records so old envelopes are disposed of through the
|
|
governed provider contract. Any transition to or from E2EE pauses each retained
|
|
message for an approved client transform. The client must return plaintext or
|
|
ciphertext as appropriate, plus evidence and the original content digest;
|
|
Postbox verifies digest continuity before changing the stored representation.
|
|
Leaving E2EE requires user-consent evidence, while changing managed history
|
|
requires institutional key-holder evidence. Dual control can require both.
|
|
|
|
This transition mechanism cannot revoke plaintext already decrypted, copied,
|
|
printed, or exported. Administrators must explicitly acknowledge that residual
|
|
disclosure before a transition is accepted.
|
|
|
|
## Identity And Device Keys
|
|
|
|
The platform should distinguish:
|
|
|
|
- account identity
|
|
- tenant membership
|
|
- role/function assignment
|
|
- device key
|
|
- postbox binding
|
|
|
|
Identity providers and directories can authenticate users and provide membership
|
|
facts, but they must not see postbox private keys or message plaintext.
|
|
|
|
The trust layer should provide:
|
|
|
|
- public key directory
|
|
- account or identity signing keys
|
|
- per-device encryption keys
|
|
- device registration and revocation
|
|
- key rotation and epoch tracking
|
|
- recovery policy hooks
|
|
|
|
Recovery must be organizationally governed. A server-held universal plaintext
|
|
key would defeat the E2EE claim; any escrow, threshold recovery, or emergency
|
|
grant needs an explicit assurance profile, authority/quorum, audit trail, and
|
|
user-visible consequence.
|
|
|
|
## Role And Function Postboxes
|
|
|
|
Role-bound access needs special handling. A postbox can be bound to an
|
|
organizational unit and a role or function. Current members can access current
|
|
messages according to policy; former members should lose access to not-yet
|
|
fetched material when revocation is still technically enforceable.
|
|
|
|
The target design should support role encryption keys or an equivalent
|
|
rewrapping service:
|
|
|
|
- sender encrypts the content key for the role/function postbox
|
|
- access service verifies current membership and required assurance
|
|
- trust service rewraps the content key to the actor's current device key
|
|
- audit records the key access decision and fetch event
|
|
|
|
Key epochs are required when role membership changes. Older messages may remain
|
|
readable according to policy, but new access must use the current epoch.
|
|
|
|
The function-bound container exists independently of membership. It may remain
|
|
vacant and continue to receive ciphertext without falling back to an unrelated
|
|
personal mailbox. Zero, one, or several incumbents are valid states. Each
|
|
incumbent receives an independently auditable, device-bound wrapped-key path;
|
|
the postbox is never copied into their account ownership.
|
|
|
|
A new assignment or hand-over rotates the function/postbox key epoch. Envelope
|
|
encryption permits the normal rotation path to rewrap per-message data keys
|
|
rather than rewrite large ciphertext objects; a security policy may require
|
|
full content re-encryption for selected compromise or cryptographic-profile
|
|
events. The history available to a new incumbent must be selected policy (all
|
|
retained history, a bounded historical window, or assignment-time content) and
|
|
recorded with the grant.
|
|
|
|
Delegation is a time-bounded represented-function grant, not a copy or
|
|
substitution of the postbox. Expiry or withdrawal stops future key release and
|
|
actions. It cannot revoke plaintext already decrypted, printed, exported, or
|
|
captured outside the platform. Multiple simultaneous incumbents and delegates
|
|
remain distinguishable in key-fetch and action evidence.
|
|
|
|
Postbox content and signed manifests are immutable. Correction or replacement
|
|
creates a linked new object/version; it never silently substitutes ciphertext
|
|
or evidence that another actor may already have inspected.
|
|
|
|
## External Recipients
|
|
|
|
External recipients may need one-time or time-limited access without a full
|
|
platform account. The target model should support capability links or invitation
|
|
tokens that are:
|
|
|
|
- scoped to specific message or attachment resources
|
|
- time-limited
|
|
- optionally one-time
|
|
- protected by an out-of-band secret, passphrase, or stronger external identity
|
|
proof
|
|
- revocable before key fetch
|
|
- fully audited
|
|
|
|
## Retraction Semantics
|
|
|
|
GovOPlaN should be honest about retraction.
|
|
|
|
Before a recipient fetches a key or decrypts content, the system can revoke
|
|
tokens, remove wrapped-key access, expire links, and delete ciphertext according
|
|
to retention policy.
|
|
|
|
After a recipient has decrypted or copied plaintext, the system cannot make the
|
|
recipient forget it. The platform can only record access, revoke future access,
|
|
notify parties, and apply legal or organizational controls.
|
|
|
|
The UI must explain this distinction whenever it offers expiry, retraction, or
|
|
message withdrawal.
|
|
|
|
## Server Responsibilities
|
|
|
|
The server remains important even when content is encrypted:
|
|
|
|
- store ciphertext and signed manifests
|
|
- store routing and policy metadata
|
|
- enforce access before key release or rewrapping
|
|
- provide public key directory access
|
|
- emit notifications without plaintext content
|
|
- record audit events
|
|
- enforce retention and expiry where possible
|
|
- expose diagnostics for delivery and key-access failures
|
|
|
|
## Module Ownership
|
|
|
|
- `govoplan-postbox` owns postbox bindings, postbox messages, message metadata,
|
|
and postbox UI.
|
|
- `govoplan-identity-trust` owns device keys, public key directory, key epochs,
|
|
and assurance integration.
|
|
- `govoplan-access` owns current identity, membership, function, delegation, and
|
|
permission decisions.
|
|
- `govoplan-policy` owns retention, retraction, and security policy decisions.
|
|
- `govoplan-audit` owns durable audit traces.
|
|
- `govoplan-files` owns managed file storage when encrypted postbox attachments
|
|
are backed by file objects.
|
|
|
|
No module should import another module's internals to decrypt content. All
|
|
interaction must use capabilities, DTOs, and audited service contracts.
|