Implement governed encryption lifecycle
This commit is contained in:
+203
-41
@@ -1,50 +1,212 @@
|
||||
# Encryption Boundary
|
||||
# Encryption Boundary and Threat Model
|
||||
|
||||
## Purpose
|
||||
## Status
|
||||
|
||||
`govoplan-encryption` is an optional cryptographic service module. It supplies
|
||||
key and content-protection capabilities to modules that choose to use them. It
|
||||
does not own feature data, normal authorization, retention, or business
|
||||
ownership.
|
||||
`govoplan-encryption` is the optional governance and lifecycle boundary for
|
||||
cryptographic protection. It persists opaque provider references, versioned
|
||||
content-protection envelopes, idempotent operation state, recovery decisions,
|
||||
and disable-preflight evidence. It does not ship a cipher, a raw key store, a
|
||||
KMS/HSM driver, or a client E2EE protocol.
|
||||
|
||||
## Initial Invariants
|
||||
Enabling the module is therefore not an encryption or E2EE claim. A deployment
|
||||
may make such a claim only for a named protection profile whose concrete
|
||||
provider, clients, algorithms, backup procedure, and failure tests have passed
|
||||
the profile's conformance and security review.
|
||||
|
||||
1. Resource ownership and cryptographic key custody are independent.
|
||||
2. Administrative ownership recovery does not grant encryption keys.
|
||||
3. Key recovery is a separate, high-assurance, auditable ceremony.
|
||||
4. Every ciphertext carries a stable protection profile, key version, algorithm
|
||||
suite, and authenticated context reference.
|
||||
5. Rotation and rewrapping are resumable and idempotent.
|
||||
6. Protected content cannot silently fall back to plaintext.
|
||||
7. Provider loss, disabled modules, unavailable devices, and recovery delay are
|
||||
visible states, not generic read failures.
|
||||
8. Disabling or uninstalling is blocked while unresolved protected content
|
||||
remains.
|
||||
## Ownership Boundary
|
||||
|
||||
## Planned Capability Families
|
||||
Encryption owns:
|
||||
|
||||
- **Key vault:** create and resolve key hierarchies without exposing raw key
|
||||
material to feature modules.
|
||||
- **Content protection:** authenticated envelope encryption and decryption for
|
||||
authorized feature-owned payloads.
|
||||
- **E2EE profiles:** recipient/device key envelopes where the server cannot
|
||||
decrypt normal content.
|
||||
- **Rotation:** rewrap keys and migrate algorithm suites with bounded progress
|
||||
and evidence.
|
||||
- **Recovery ceremony:** quorum, delay, recent authentication, custody evidence,
|
||||
and explicit scope.
|
||||
- **Disable preflight:** inventory protection references and produce a blocking
|
||||
migration plan.
|
||||
- vault and opaque provider-key reference metadata;
|
||||
- key-version and provider-operation lifecycle state;
|
||||
- versioned protection envelopes and migration evidence;
|
||||
- high-assurance, quorum-based recovery authorization;
|
||||
- disable and uninstall preflight.
|
||||
|
||||
## Decisions Deferred Until Threat Modeling
|
||||
Feature modules still own domain content, access policy, retention, legal-hold
|
||||
meaning, and normal resource ownership. Identity Trust owns public device keys,
|
||||
key epochs, and recent-assurance evidence. Access decides whether an account may
|
||||
perform a resource action. A positive Access decision does not release a key;
|
||||
an ownership transfer does not transfer cryptographic custody.
|
||||
|
||||
- cryptographic libraries and external KMS/HSM providers
|
||||
- server-managed versus client-managed profile suites
|
||||
- per-object, per-vault, and per-recipient data-key granularity
|
||||
- device enrollment and revocation protocol
|
||||
- external-recipient key discovery and trust
|
||||
- recovery quorum defaults for each assurance profile
|
||||
- ciphertext portability and offline export format
|
||||
No capability in this module accepts or returns plaintext key material.
|
||||
|
||||
These decisions require explicit threat models and interoperability fixtures.
|
||||
They must not be inferred from ordinary resource-ownership workflows.
|
||||
## Assets and Threat Actors
|
||||
|
||||
Protected assets include content plaintext, data-encryption keys, wrapping keys,
|
||||
recipient/device private keys, authenticated context, recovery authority, and
|
||||
the integrity and provenance of lifecycle decisions.
|
||||
|
||||
The threat model includes:
|
||||
|
||||
- an unauthorized user or tenant attempting cross-tenant access;
|
||||
- a compromised account, API key, worker, or application node;
|
||||
- a malicious or mistaken tenant/platform administrator;
|
||||
- a compromised storage service, database backup, queue, log collector, or
|
||||
observability system;
|
||||
- a lost or revoked device and a former function holder;
|
||||
- a malicious or unavailable key provider;
|
||||
- replay, race, partial failure, rollback, and outcome-unknown provider calls;
|
||||
- ciphertext substitution, context confusion, algorithm downgrade, and mixed
|
||||
migration state;
|
||||
- backup restoration without matching provider keys, or key restoration without
|
||||
matching metadata.
|
||||
|
||||
The initial model does not claim protection against endpoint compromise while a
|
||||
legitimate client has plaintext open, coercion of all configured recovery
|
||||
custodians, traffic analysis, or denial of service by a provider that controls
|
||||
required keys.
|
||||
|
||||
## Observable Metadata
|
||||
|
||||
Unless an independently reviewed profile says otherwise, the server and its
|
||||
database can observe tenant, owner module, resource type and stable id, profile,
|
||||
vault and key version, algorithm suite, ciphertext location and digest,
|
||||
authenticated-context digest, wrapped-key references, timestamps, migration
|
||||
state, policy references, recovery scope, and actor/evidence references.
|
||||
|
||||
Titles, recipient identities, content length, access patterns, and relationship
|
||||
graphs may also leak through the owning module or storage provider even when the
|
||||
payload is encrypted. Product UI and documentation must not imply that payload
|
||||
encryption hides this metadata.
|
||||
|
||||
## Deployment Profiles
|
||||
|
||||
### Server-side envelope encryption
|
||||
|
||||
The application or a deployment KMS/HSM can unwrap data keys after normal
|
||||
authorization. This protects backups and storage media but not plaintext from a
|
||||
compromised authorized application tier. Provider credentials and key policy are
|
||||
deployment secrets, not envelope metadata. Legal hold can preserve ciphertext
|
||||
and key availability under separately authorized policy.
|
||||
|
||||
### Tenant-held key provider
|
||||
|
||||
The tenant controls an external KMS/HSM or equivalent provider. GovOPlaN holds
|
||||
only references and invokes the provider under tenant policy. The provider may
|
||||
allow server-side processing, but tenant revocation or provider outage can make
|
||||
content unavailable. Backup recovery requires both GovOPlaN state and the
|
||||
tenant's provider recovery procedure.
|
||||
|
||||
### End-to-end encryption
|
||||
|
||||
Only authorized clients possess usable recipient/device private keys; ordinary
|
||||
servers cannot decrypt payloads. Search, preview, server-side Dataflow,
|
||||
virus/content inspection, reporting, legal-hold export, and recovery degrade or
|
||||
become impossible unless the selected profile deliberately adds an authorized
|
||||
recipient or escrow mechanism. Such a mechanism changes the threat model and
|
||||
must be displayed as part of the profile.
|
||||
|
||||
The current code can label and track an `end_to_end` envelope, but it does not
|
||||
implement the client protocol. That label alone is never evidence of E2EE.
|
||||
|
||||
## Profile Consequences
|
||||
|
||||
| Concern | Server envelope | Tenant-held | End-to-end |
|
||||
| --- | --- | --- | --- |
|
||||
| Normal server processing | Available after authorization | Provider-policy dependent | Unavailable unless a client performs it |
|
||||
| Provider outage | Decryption unavailable | Decryption unavailable | Existing enrolled clients may remain usable |
|
||||
| Platform admin can obtain plaintext | Possible under governed server policy | Tenant/provider dependent | Not from ordinary server custody |
|
||||
| Legal hold | Preserve ciphertext and governed keys | Requires tenant/provider cooperation | Ciphertext only unless the profile has a hold recipient |
|
||||
| Export | Governed plaintext or portable encrypted export | Provider cooperation required | Client-produced or recipient-key export |
|
||||
| Recovery | Provider recovery plus GovOPlaN quorum | Tenant provider recovery plus quorum | Device/recipient recovery defined by the client profile |
|
||||
| Ownership transfer | Separate reauthorization/rewrap | Separate reauthorization/rewrap | Explicit recipient change and re-encryption |
|
||||
| Revocation | Stops future provider use; cannot erase prior plaintext | Provider enforced | New key epoch; cannot erase prior client plaintext |
|
||||
|
||||
## Algorithms, Libraries, and Agility
|
||||
|
||||
Concrete providers must declare a versioned suite id and pass conformance tests.
|
||||
The initial allowlist for reviewed profiles is:
|
||||
|
||||
- AES-256-GCM through a deployment KMS/HSM or a maintained OpenSSL-backed
|
||||
cryptographic library;
|
||||
- XChaCha20-Poly1305 through a maintained libsodium implementation where the
|
||||
provider/profile requires extended nonces;
|
||||
- RFC 9180 HPKE suites for a future reviewed recipient-envelope protocol.
|
||||
|
||||
Selection from this list is not automatic approval. A provider profile must
|
||||
also define nonce generation and uniqueness, associated-data construction, key
|
||||
separation, limits, error handling, and test vectors. Home-grown primitives,
|
||||
unauthenticated encryption, AES-ECB, bare AES-CBC, static/reused nonces, raw RSA
|
||||
encryption, SHA-1 integrity, provider-supplied secret values in logs, and silent
|
||||
algorithm fallback are prohibited.
|
||||
|
||||
Every envelope fixes its profile, algorithm suite, vault, key version,
|
||||
ciphertext digest, and authenticated-context digest. Changing any of these is a
|
||||
new, evidence-backed migration. Readers never infer an algorithm from current
|
||||
defaults. Old readers fail closed on unknown suites or contract versions.
|
||||
|
||||
## Durable Operation Semantics
|
||||
|
||||
Key-provider operations use a stable idempotency key. GovOPlaN records an
|
||||
operation as `prepared`, `succeeded`, or `outcome_unknown`. If a provider call
|
||||
raises or a process dies around the external side effect, absence of an error is
|
||||
never treated as success. Reconciliation repeats the exact idempotent provider
|
||||
request and records only bounded error class codes.
|
||||
|
||||
Content migrations are explicit records. Rewrap and re-encryption succeed only
|
||||
when an exact target envelope references the authorized source and migration.
|
||||
Decrypt, export, and destruction require evidence references. Until an outcome
|
||||
is known, the source remains `migration_pending`; no implicit plaintext fallback
|
||||
is allowed.
|
||||
|
||||
All runtime state is in the shared database or an external provider/object
|
||||
store reference. Application and worker nodes require no local encryption state,
|
||||
so multiple nodes can retry the same operation safely when the provider honors
|
||||
the idempotency contract.
|
||||
|
||||
## Recovery Ceremony
|
||||
|
||||
Recovery requires current Identity Trust assurance at the `high` level, a
|
||||
policy-decision reference, expiry, distinct custodian accounts, and the vault's
|
||||
configured quorum. The requester cannot approve their own ceremony; one
|
||||
rejection rejects the current ceremony. Decisions are optimistic-concurrency
|
||||
protected and replay safe.
|
||||
|
||||
An `approved` ceremony authorizes a later provider-specific recovery action. It
|
||||
does not return a key, change resource ownership, or prove that recovery has
|
||||
executed. A production provider must add separately auditable execution and
|
||||
post-recovery rotation/rewrap evidence.
|
||||
|
||||
## Disable and Uninstall
|
||||
|
||||
Disabling or uninstalling never deletes keys or silently makes ciphertext look
|
||||
like ordinary unreadable content. Preflight inventories all envelopes. It blocks
|
||||
while any envelope is active, pending, migrating, unavailable, or otherwise
|
||||
unresolved. An envelope is locally terminal only after it is:
|
||||
|
||||
- migrated to another registered protection envelope;
|
||||
- decrypted by an authorized workflow;
|
||||
- explicitly exported with documented custody; or
|
||||
- cryptographically destroyed with evidence.
|
||||
|
||||
A migrated target remains an active protected envelope and therefore still
|
||||
blocks removal of the module/provider that owns it. Destructive table retirement
|
||||
is permitted only after this proof.
|
||||
|
||||
## Backup, Restore, and Key Loss
|
||||
|
||||
A recoverable backup set consists of the shared database, ciphertext/object
|
||||
storage, provider configuration references, provider-side key backups or HSM
|
||||
replication, and audit evidence. These materials must be backed up separately
|
||||
according to their trust boundaries. Database restore without matching provider
|
||||
keys produces an explicit unavailable state; it must never create replacement
|
||||
keys under an old reference.
|
||||
|
||||
Before production use, each concrete provider/profile needs automated restore,
|
||||
provider-loss, stale-backup, partial-migration, network-failure, and permanent
|
||||
key-loss exercises. Permanent key loss is data loss for the affected ciphertext
|
||||
and must be reported as such.
|
||||
|
||||
## Current Integration Contract
|
||||
|
||||
Files, Postbox, Campaign, Calendar, and connector credentials may store an
|
||||
envelope id and ciphertext reference while retaining their own resource model.
|
||||
They resolve Encryption through optional capabilities and must fail closed when
|
||||
an encrypted record is encountered without the capability. Unencrypted module
|
||||
combinations continue to operate without Encryption.
|
||||
|
||||
Focused fixtures currently validate Files- and Postbox-owned envelope records.
|
||||
Concrete feature adapters and production provider conformance remain tracked
|
||||
work; direct imports of Encryption database models from feature modules are not
|
||||
allowed.
|
||||
|
||||
Reference in New Issue
Block a user