From 02e97578d5824c503aadf6731fb468b647fc1580 Mon Sep 17 00:00:00 2001 From: isanmaz Date: Tue, 16 Jun 2026 15:41:04 +0200 Subject: [PATCH 1/6] docs: add CMK product vision and tenancy model Signed-off-by: isanmaz --- product-vision/cmk-product-vision.md | 318 +++++++++++++++++++++++++++ product-vision/cmk-tenancy-model.md | 290 ++++++++++++++++++++++++ 2 files changed, 608 insertions(+) create mode 100644 product-vision/cmk-product-vision.md create mode 100644 product-vision/cmk-tenancy-model.md diff --git a/product-vision/cmk-product-vision.md b/product-vision/cmk-product-vision.md new file mode 100644 index 0000000..2abbe68 --- /dev/null +++ b/product-vision/cmk-product-vision.md @@ -0,0 +1,318 @@ +--- +status: Draft +last_updated: 2026-06-16 +audience: Open Source Community, Contributors, Stakeholders +--- + +# OpenKCM Product Vision + +## What is OpenKCM CMK? + +OpenKCM CMK is an open source Customer Managed Key (CMK) layer for cloud-native platforms. It gives organizations cryptographic control over their own encryption keys — so that no platform operator, cloud provider, or managed service can access customer data without the customer's explicit consent. + +OpenKCM CMK governs encryption keys. The actual cryptographic operations are performed by [Krypton](https://github.com/openkcm/krypton) — the crypto execution engine that OpenKCM CMK sits on top of. + +--- + +## The Problem + +When an organization runs workloads on a cloud platform, their data is typically encrypted — but by a key the platform controls. The organization trusts the platform not to look. That trust is implicit, unverifiable, and often not sufficient for regulated industries. + +Customer Managed Keys solve this by inverting control: the customer owns the root key, the platform never has access to key material, and the customer can revoke access at any time — including instantly, for all workloads at once. + +This is not a theoretical requirement. Defense agencies, government authorities, utilities, financial institutions, and any organization subject to data residency or sovereignty regulation needs this guarantee by law. + +--- + +## Who OpenKCM CMK is for + +**Sovereign and private cloud operators** +Organizations running their own infrastructure in a specific jurisdiction — air-gapped, on-premise, or in a regulated data center. Keys must never leave their environment. Examples: national defense agencies, government authorities, critical infrastructure operators. + +**Managed service providers** +Companies offering services (databases, runtimes, platforms) to other organizations. They need to tell their customers: your data is encrypted under your key, not ours. OpenKCM CMK gives them the integration point to make that guarantee. + +**Platform builders** +Teams building cloud-native platforms who want to offer CMK as a first-class capability without building key governance from scratch. + +**Application and service developers** +Teams deploying workloads who should never need to think about key management — but whose applications must handle key revocation gracefully when the Red Button is pressed. + +--- + +## Two Products + +OpenKCM CMK is offered in two variants, both sharing the same CMK Core. + +--- + +### OpenKCM CMK + +The full-featured, standalone CMK product. Runs on any Kubernetes environment — no platform dependency required. Designed for organizations that operate their own infrastructure and need complete key governance under their own control. + +**Target deployment:** Any Kubernetes cluster the customer operates themselves — on-premise, sovereign cloud, air-gapped, or any cloud provider. + +**Key capabilities:** + +- L1 Root Key registration and lifecycle management (enable, disable, rotate, delete) +- BYOK (Bring Your Own Key) and HYOK (Hold Your Own Key) — customer key material never touches the platform +- Pluggable keystore backends: OpenBao, AWS KMS, Azure Key Vault, GCP KMS, HSM via PKCS#11 +- Kill switch (Red Button) — instant revocation of all workloads across the deployment +- Multi-party approval (Four-Eyes) — high-stakes operations require a second authorized approver +- Full audit trail — tamper-evident log of every key operation, exportable for compliance +- Tenant onboarding and offboarding +- Role-based access control via OIDC / RBAC +- Full CMK UI — own web interface, not embedded in any platform portal + +**Key hierarchy:** + +| Level | Name | Scope | Managed by | +|---|---|---|---| +| L1 | Root Key | Tenant | Customer — registered via OpenKCM CMK | +| L2 | Domain Key | Workspace | OpenKCM CMK — internal | +| L3 | Service Key | Service | Krypton — internal | +| L4 | Data Encryption Key | Workload | Krypton — internal | + +The customer only ever registers and manages the L1 key. Everything below is derived and managed internally by OpenKCM CMK and Krypton. + +--- + +### OpenKCM CMK Platform Mesh + +A lightweight CMK integration embedded in the Platform Mesh portal. Designed for Platform Mesh operators and tenants who need customer-managed encryption without running a separate CMK product. + +**Target deployment:** Platform Mesh — running as a Kubernetes controller in the platform-admin namespace, with cross-namespace RBAC authority over the entire workspace. + +**Key capabilities:** + +- L1 Root Key registration at account level — one registration covers all namespaces in the account +- BYOK and HYOK — same guarantee as OpenKCM CMK; OpenBao is the priority backend +- Kill switch — one action revokes access across all namespaces in the workspace +- Zero-touch encryption — workloads deployed from the marketplace are automatically encrypted without developer intervention +- Audit trail — via Platform Mesh audit infrastructure +- Access control — via Platform Mesh RBAC +- Lightweight embedded UI — microfrontend in the Platform Mesh portal via Luigi; no separate web interface + +**What the security admin sees:** + +The OpenKCM section appears at account level in the Platform Mesh portal — not inside a namespace. Each account has one workspace, and that workspace contains multiple namespaces. When OpenKCM is enabled, Platform Mesh automatically provisions one L2 Domain Key per namespace. + +The security admin registers the organization's L1 root key at account level. She then binds that L1 key to the L2 Domain Keys that Platform Mesh has provisioned — one binding per namespace. Once bound, all workloads running in that namespace are encrypted under the L1→L2 key chain. + +**One unified UI — access gated by key level** + +All key levels (L1, L2, L3) are managed from a single account-level UI. What actions are available depends on the key level and the user's role: + +| Key level | Generated by | Admin actions | +|---|---|---| +| L1 Root Key | Customer (via OpenKCM CMK) | Register, bind to L2, rotate, revoke, kill switch | +| L2 Domain Key | Platform Mesh (automatic) | View, bind L1 to L2 — cannot create or delete | +| L3 Service Key | Krypton (automatic) | View status — see open question below | + +The security admin sees the full key chain for the account in one place. Actions are only available where the admin has authority — Platform Mesh-generated and Krypton-generated keys are visible but not creatable or deletable by the admin. + +**What developers see:** + +Nothing. Zero-touch encryption means workloads come up encrypted without any key configuration on the developer's part. + +**L3 Service Key visibility — open question** + +L3 keys are generated by Krypton automatically when a service is deployed, wrapped under the L2 of that namespace. Three options are under consideration for how L3 keys are handled in the UI: + +- **Option A — L3 fully internal, never shown.** Krypton generates and manages L3 silently. The security admin only sees L1 and L2. The kill switch at L1 level cascades down through L2 and L3 automatically. Simplest model. + +- **Option B — L3 visible but not manageable.** The account-level UI shows a breakdown: workspace → namespace → services → each with their L3 key status. Read-only. Useful for the security admin to verify that each service (MongoDB, Postgres, etc.) is actually encrypted. No actions at L3 level. + +- **Option C — L3 has its own actions (selective revocation).** The kill switch can be triggered at L3 level — revoke only a specific service (e.g. MongoDB only), not the entire workspace. This requires UI at service level and introduces the question of who owns selective service revocation: OpenKCM CMK Platform Mesh or Krypton. This is an open architectural question to be resolved. + +> **Current direction:** Option B for the initial release — L3 visible, not manageable. Option C is a future feature pending resolution of the selective revocation ownership question. + +--- + +**Option A — L3 fully internal** + +``` +Account: ACME Corp +└── OpenKCM CMK Platform Mesh (account level) + │ + ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages + │ + ├── Namespace: default + │ └── L2 Domain Key: acme-default-domain [Bound] ← admin binds L1→L2 + │ + ├── Namespace: db-a + │ └── L2 Domain Key: acme-dba-domain [Bound] + │ + └── Namespace: db-b + └── L2 Domain Key: acme-dbb-domain [Bound] + +L3 Service Keys and L4 Data Keys are managed internally by Krypton. +Admin never sees them. Kill switch at L1 cascades automatically. + +Kill switch: +L1 revoked → L2 revoked → L3 revoked → all workloads inaccessible +``` + +--- + +**Option B — L3 visible, not manageable** + +``` +Account: ACME Corp +└── OpenKCM CMK Platform Mesh (account level) + │ + ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages + │ + ├── Namespace: default + │ ├── L2 Domain Key: acme-default-domain [Bound] ← admin binds L1→L2 + │ └── Services (read-only): + │ └── mongodb → L3: acme-default-mongodb-key [Active] + │ + ├── Namespace: db-a + │ ├── L2 Domain Key: acme-dba-domain [Bound] + │ └── Services (read-only): + │ └── postgres → L3: acme-dba-postgres-key [Active] + │ + └── Namespace: db-b + ├── L2 Domain Key: acme-dbb-domain [Bound] + └── Services (read-only): + └── redis → L3: acme-dbb-redis-key [Active] + +Admin can see all L3 keys and their status. No actions available at L3 level. +Kill switch at L1 still cascades automatically across all L2 and L3. +``` + +--- + +**Option C — L3 with selective revocation (future / open question)** + +``` +Account: ACME Corp +└── OpenKCM CMK Platform Mesh (account level) + │ + ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages + │ + ├── Namespace: default + │ ├── L2 Domain Key: acme-default-domain [Bound] + │ └── Services: + │ └── mongodb → L3: acme-default-mongodb-key [Active] [Revoke] + │ + ├── Namespace: db-a + │ ├── L2 Domain Key: acme-dba-domain [Bound] + │ └── Services: + │ └── postgres → L3: acme-dba-postgres-key [Active] [Revoke] + │ + └── Namespace: db-b + ├── L2 Domain Key: acme-dbb-domain [Bound] + └── Services: + └── redis → L3: acme-dbb-redis-key [Active] [Revoke] + +Admin can revoke individual service keys without triggering the full kill switch. +Example: revoke MongoDB only → MongoDB data inaccessible, Postgres and Redis unaffected. + +⚠ Open question: who owns selective revocation — OpenKCM CMK Platform Mesh or Krypton? +``` + +**Platform Mesh account model:** + +``` +Account (e.g. ACME Corp) ← administrative boundary, CMK governed here + │ + └── Workspace: acme-prod + │ + ├── Namespace: default → Application + ├── Namespace: db-a → Database A + ├── Namespace: db-b → Database B + └── Namespace: platform-admin → OpenKCM Controller +``` + +One L1 key at account level governs all workspaces and namespaces. Pressing the kill switch at account level locks everything — not just one namespace. + +--- + +## What the two products share — CMK Core + +Both products are built on **CMK Core** — the shared business logic library that contains: + +- Key lifecycle state machine (NIST SP 800-57: PreActivation → Active → Suspended → Deactivated → Destroyed) +- L1 key validation logic +- Kill switch execution logic +- Tenant registry and onboarding/offboarding +- Audit trail logic +- Multi-party approval logic + +CMK Core is deployment-agnostic. It has no dependency on Platform Mesh, any cloud provider, or any specific keystore. Both OpenKCM CMK and OpenKCM CMK Platform Mesh consume it as a shared library. + +--- + +## What OpenKCM CMK does not do + +- Perform cryptographic operations — that is Krypton's responsibility +- Store key material — keys live in the customer's own keystore (OpenBao, AWS KMS, HSM, etc.) +- Replace a secrets manager — OpenKCM CMK governs encryption keys, not application secrets +- Manage platform-controlled keys — platform-managed keys are out of scope; OpenKCM CMK only governs customer-owned keys + +--- + +## Red Button / Kill Switch + +The kill switch is a customer-initiated action that immediately revokes access to all data in the governed scope. It works by revoking the L1 root key — since all L2, L3, and L4 keys are derived from it, every encrypted workload becomes inaccessible within the propagation window. + +This is a one-way, destructive action. It is not a pause — it is a cryptographic lock. Once executed, data cannot be recovered without a new key registration and an approval cycle. + +For OpenKCM CMK: the kill switch scope is the tenant. +For OpenKCM CMK Platform Mesh: the kill switch scope is the account/workspace — all namespaces within it. + +--- + +## BYOK and HYOK + +OpenKCM CMK prioritizes **HYOK (Hold Your Own Key)**. The customer's L1 key material never touches the OpenKCM CMK platform. OpenKCM CMK holds only a reference — a pointer to the key in the customer's own keystore. At runtime, Krypton calls out to that keystore to use the key. + +**BYOK (Bring Your Own Key)** is also supported — the customer imports key material into the platform's keystore. HYOK is the stronger sovereignty guarantee. + +--- + +## Supported keystore backends + +| Backend | Type | Status | +|---|---|---| +| OpenBao | Open source Vault fork | Priority | +| AWS KMS | Cloud KMS | Supported | +| Azure Key Vault | Cloud KMS | Supported | +| GCP KMS | Cloud KMS | Supported | +| HSM via PKCS#11 | Hardware Security Module | Supported | + +--- + +## Non-functional requirements + +Every OpenKCM CMK component — regardless of deployment variant — must meet the following bar: + +- **Testability** — independently testable without a full stack; integration points abstracted +- **Observability** — structured logging, metrics, and tracing built in from day one +- **API stability** — published APIs are contracts; new capabilities extend, never break +- **Security by default** — authentication, authorization, and audit logging are requirements, not features added later +- **Operability** — operable by someone who did not build it; health endpoints, runbooks, graceful degradation + +--- + +## Terminology + +**OpenKCM** +The open source project and repository. The umbrella under which all components are developed and maintained — including OpenKCM CMK, OpenKCM CMK Platform Mesh, and Krypton. + +**OpenKCM CMK** +The full-featured, standalone Customer Managed Key product. Runs on any Kubernetes environment with no platform dependency. Includes the full CMK UI, CMK Application, and CMK Core. Designed for organizations operating their own infrastructure who need complete key governance under their own control. + +**OpenKCM CMK Platform Mesh** +The lightweight CMK layer for Platform Mesh. Includes an embedded microfrontend (via Luigi) and a CMK Controller for tenant onboarding and key lifecycle management within a Platform Mesh deployment. Relies on Platform Mesh for audit, RBAC, and notifications — does not require a separate CMK Application deployment. + +**CMK Core** +The shared business logic library consumed by both OpenKCM CMK and OpenKCM CMK Platform Mesh. Contains the key lifecycle state machine (NIST SP 800-57), L1 key validation, kill switch execution logic, tenant registry, audit trail logic, and multi-party approval logic. Deployment-agnostic — no dependency on any platform or cloud provider. + +**CMK Controller** +A Kubernetes controller that runs inside Platform Mesh (in the platform-admin namespace). Watches OpenKCM CRDs and reconciles key state across the workspace. Used exclusively by OpenKCM CMK Platform Mesh — not part of the standalone OpenKCM CMK deployment. + +**Krypton** +The cryptographic execution engine. Performs key derivation, encryption, decryption, and KMIP services. Operates independently of OpenKCM CMK — it can run without CMK governance on top. OpenKCM CMK governs; Krypton executes. diff --git a/product-vision/cmk-tenancy-model.md b/product-vision/cmk-tenancy-model.md new file mode 100644 index 0000000..fddf2c8 --- /dev/null +++ b/product-vision/cmk-tenancy-model.md @@ -0,0 +1,290 @@ +--- +status: Draft +last_updated: 2026-06-16 +audience: Open Source Community, Contributors, Stakeholders +--- + +# OpenKCM CMK Platform Mesh — Tenancy Model + +## Overview + +This document defines the tenancy model for OpenKCM CMK Platform Mesh. It describes the entities, their relationships, and the key binding model that governs how customer-owned encryption keys are applied across a Platform Mesh deployment. + +--- + +## Entity Relationship Model + +``` ++------------------+ +| Account | ++------------------+ +| AccountID | +| Name | +| Status | ++------------------+ + | 1 + | + | 1 ++------------------+ +| Workspace | ++------------------+ +| WorkspaceID | +| AccountID | +| Status | ++------------------+ + | 1 + | + | N ++------------------+ +| Namespace | ++------------------+ +| NamespaceID | +| WorkspaceID | +| Name | +| Status | ++------------------+ + | 1 + | + | 1 ++----------------------+ +| L2 Domain Key | ++----------------------+ +| L2KeyID | +| NamespaceID | +| Status | +| ProvisionedBy | ← Platform Mesh (automatic) ++----------------------+ + | 1 + | + | 1 (key binding — admin assigns) ++----------------------+ +| L1 Root Key | ++----------------------+ +| L1KeyID | +| AccountID | +| Name | +| Status | +| KeystoreType | ← OpenBao, AWS KMS, Azure KV, HSM... +| KeystoreRef | ← reference only, no key material stored +| RegisteredBy | ← Security Admin ++----------------------+ + | 1 + | + | N ++----------------------+ +| External Keystore | ++----------------------+ +| KeystoreID | +| Type | +| URL | +| Status | ++----------------------+ + + ++------------------+ +------------------+ +| Namespace | | L2 Domain Key | ++------------------+ +------------------+ + | 1 | 1 + | | + | N | N ++------------------+ +------------------+ +| Service | | Key Binding | ++------------------+ +------------------+ +| ServiceID | | BindingID | +| NamespaceID | | L2KeyID | +| Name | | L1KeyID | +| Status | | BoundBy | ← Security Admin ++------------------+ | BoundAt | + | 1 +------------------+ + | + | 1 ++------------------+ +| L3 Service Key | ++------------------+ +| L3KeyID | +| ServiceID | +| L2KeyID | +| Status | +| GeneratedBy | ← Krypton (automatic) ++------------------+ + + ++------------------+ +| Security Admin | ++------------------+ +| UserID | +| AccountID | +| Role | ++------------------+ + | + | registers L1 keys + | binds L1 → L2 + | triggers kill switch +``` + +--- + +## Entities + +### Account +The top-level administrative boundary. Represents one customer organization. One account has exactly one workspace. The account is the tenant — pressing the kill switch at account level locks the entire account. + +### Security Admin +A user with account-level permissions in Platform Mesh. Responsible for registering L1 root keys, binding them to L2 domain keys, and triggering the kill switch. The security admin operates from the account-level OpenKCM CMK UI. + +### CMK Controller +A Kubernetes controller running in the platform-admin namespace of the workspace. Watches OpenKCM CRDs and reconciles key state across all namespaces. One controller per Platform Mesh installation — shared across all accounts. + +### Workspace +The deployment environment within an account. One account has one workspace. Contains multiple namespaces where applications and services run. + +### Namespace +A Kubernetes namespace within the workspace. Each namespace has exactly one L2 Domain Key, provisioned automatically by Platform Mesh when OpenKCM CMK Platform Mesh is enabled. + +### L1 Root Key +A customer-owned root encryption key. Registered by the security admin at account level. Key material never leaves the customer's external keystore — OpenKCM CMK holds only a reference. One account can have multiple L1 root keys. Each L1 key is backed by one external keystore. + +### External Keystore +The customer's own key management system where L1 key material lives. Supported backends: OpenBao, AWS KMS, Azure Key Vault, GCP KMS, HSM via PKCS#11. OpenKCM CMK never stores key material — it holds a pointer and calls the keystore at runtime via Krypton. + +### Key Binding +The association between an L1 Root Key and an L2 Domain Key. Created by the security admin. One L2 Domain Key is bound to exactly one L1 Root Key. One L1 Root Key can be bound to multiple L2 Domain Keys (multiple namespaces can share the same L1 key). Different namespaces can be bound to different L1 keys — the admin decides. + +### L2 Domain Key +Provisioned automatically by Platform Mesh when OpenKCM CMK Platform Mesh is enabled — one per namespace. The security admin cannot create or delete L2 keys. The admin can bind an L1 key to an L2 key. All services in a namespace are encrypted under that namespace's L2 key. + +### L3 Service Key +Generated automatically by Krypton when a service is deployed in a namespace. Wrapped under the L2 Domain Key of that namespace. One L3 key per service instance. Not created or managed by the security admin. + +### Service +An application or workload running inside a namespace (e.g. MongoDB, Postgres, Redis). Has one L3 Service Key. Encrypted automatically — no key configuration required from the developer. + +--- + +## Key Binding Rules + +| Rule | Description | +|---|---| +| One L2 per namespace | Platform Mesh provisions exactly one L2 Domain Key per namespace | +| Admin registers L1 | The security admin registers one or more L1 keys at account level | +| Admin binds L1 → L2 | The security admin decides which L1 key governs which namespace | +| One L1 per L2 | Each L2 Domain Key is bound to exactly one L1 Root Key at a time | +| One L1 → many L2s | One L1 Root Key can be bound to multiple namespaces | +| Different L1s per namespace | Different namespaces can be governed by different L1 keys | +| Unbound namespace | A namespace with no L1 binding is not customer-governed — it uses platform-managed encryption until the admin binds an L1 key | + +--- + +## Kill Switch Scope + +| Action | Scope | Effect | +|---|---|---| +| Revoke L1 Root Key | All namespaces bound to that L1 | All services in those namespaces become inaccessible | +| Kill switch (account level) | Entire account | All namespaces, all services inaccessible — regardless of which L1 they are bound to | + +If an account has multiple L1 keys bound to different namespaces, revoking one L1 key affects only the namespaces bound to it. The full account kill switch revokes everything. + +--- + +## Lifecycle States + +### L1 Root Key lifecycle + +``` +Registered → Active → Suspended → Revoked + ↑ │ + └──────────┘ (re-activated by admin) +``` + +- **Registered** — key reference created in OpenKCM CMK, not yet validated +- **Active** — key reachable and validated by Krypton; workloads are encrypted +- **Suspended** — key temporarily unavailable; grace period begins; workloads inaccessible after grace period expires +- **Revoked** — kill switch executed; all bound workloads inaccessible; irreversible without new key registration and approval + +### L2 Domain Key lifecycle + +Managed by Platform Mesh and OpenKCM CMK Controller. Follows the state of the bound L1 key — if L1 is revoked, L2 is revoked automatically. + +### L3 Service Key lifecycle + +Managed by Krypton. Created when a service is deployed, revoked when the L2 above it is revoked. + +--- + +## Deployment Scenarios + +### Scenario 1 — SaaS Tenant on shared Platform Mesh + +A customer organization (e.g. ACME Corp) runs workloads on a shared Platform Mesh installation operated by someone else. They are one of many tenants on the platform. + +- OpenKCM CMK Platform Mesh is the right product +- UI sits at **account level** — the tenant manages their own keys within their account +- Kill switch scope: the account — does not affect other tenants +- CMK Controller is shared platform infrastructure, but key governance is per-tenant + +``` +Platform Mesh (shared installation) +│ +├── Account: ACME Corp ← OpenKCM CMK UI here +│ └── Workspace → Namespaces → Services +│ +├── Account: VW ← OpenKCM CMK UI here +│ └── Workspace → Namespaces → Services +│ +└── Account: Siemens ← OpenKCM CMK UI here + └── Workspace → Namespaces → Services +``` + +--- + +### Scenario 2 — Air-gapped / sovereign deployment + +An organization runs their own Platform Mesh installation in their own data center. They are both the platform operator and the only tenant. No shared platform, no other tenants. + +- **OpenKCM CMK (standalone) is the right product** — not the Platform Mesh lightweight variant +- The lightweight UI is designed for tenant-level governance within a shared platform; at deployment/operator level it effectively becomes the full CMK feature set +- Standalone gives the operator full governance: own UI, multi-party approval, full audit trail, platform-level kill switch — without depending on a shared platform portal +- The operator manages keys for their entire installation, not just one account within it + +``` +Air-gapped deployment (single organization) +│ +├── Platform Mesh (operator-owned) +│ └── Account: Operator Org +│ └── Workspace → Namespaces → Services +│ +└── OpenKCM CMK (standalone) ← full product, own UI, platform-level governance +``` + +--- + +## Open Questions + +**1. SaaS Tenant — is the current UI scope sufficient?** +The current OpenKCM CMK Platform Mesh UI design sits at account level. For the SaaS Tenant scenario this is correct. But does Platform Mesh support account-level microfrontend registration today, or does the UI need to move there from namespace level first? + +--- + +**2. Air-gapped — standalone or extend the lightweight UI?** +The current direction is to use OpenKCM CMK (standalone) for air-gapped deployments rather than extending the lightweight UI one level up to platform level. The alternative — extending the lightweight UI to platform level — risks replicating the full CMK feature set inside the Platform Mesh portal, eliminating the "lightweight" distinction. + +> **Proposal:** Air-gapped / sovereign deployments use **OpenKCM CMK (standalone)**, not OpenKCM CMK Platform Mesh. The lightweight variant is explicitly scoped to the SaaS Tenant scenario. This keeps a clean product boundary and avoids feature creep in the Platform Mesh integration. + +--- + +**3. Platform-level kill switch in air-gapped deployments** +In an air-gapped deployment, who triggers the kill switch — the platform operator or a designated security admin? Is there a platform-level role in Platform Mesh that maps to this, or does the standalone CMK product own this entirely? + +> **Proposal:** In air-gapped deployments using OpenKCM CMK (standalone), the kill switch is owned entirely by the standalone product — no dependency on Platform Mesh roles. The designated security admin in the standalone UI triggers it, subject to multi-party approval. Platform Mesh roles are irrelevant in this scenario. + +--- + +**4. Multi-party approval — SaaS Tenant** +For the SaaS Tenant scenario, does Platform Mesh provide a native four-eyes approval mechanism that OpenKCM CMK Platform Mesh can integrate with, or does the lightweight variant skip multi-party approval entirely and rely on the tenant's own processes? + +--- + +**5. L3 visibility scope** +Which L3 option (A, B, or C) applies to each deployment scenario? The air-gapped operator may have different requirements from a SaaS tenant. + +> **Proposal:** SaaS Tenant → Option B (L3 visible, not manageable) for initial release. Air-gapped / standalone → Option C (selective revocation) as a target feature, since sovereign operators are more likely to need granular service-level revocation. Option C remains an open architectural question pending resolution of who owns selective revocation — OpenKCM CMK or Krypton. \ No newline at end of file From 51b3407d95d479704801caafa08d9537e25fc299 Mon Sep 17 00:00:00 2001 From: isanmaz Date: Wed, 24 Jun 2026 18:35:45 +0200 Subject: [PATCH 2/6] docs: fix coherency and clarify dual deployment model in cmk-platform-mesh-vision Signed-off-by: isanmaz --- product-vision/cmk-platform-mesh-vision.md | 335 +++++++++++++++++++++ 1 file changed, 335 insertions(+) create mode 100644 product-vision/cmk-platform-mesh-vision.md diff --git a/product-vision/cmk-platform-mesh-vision.md b/product-vision/cmk-platform-mesh-vision.md new file mode 100644 index 0000000..aef8ffc --- /dev/null +++ b/product-vision/cmk-platform-mesh-vision.md @@ -0,0 +1,335 @@ +--- +status: Draft +last_updated: 2026-06-24 +audience: Open Source Community, Contributors, Stakeholders +--- + +# OpenKCM CMK — Platform Mesh + +## Overview + +OpenKCM CMK Platform Mesh is a lightweight CMK integration embedded in the Platform Mesh portal. Designed for Platform Mesh operators and tenants who need customer-managed encryption without running a separate CMK product. + +OpenKCM is a **service provider** on Platform Mesh. It publishes its key management API through the Platform Mesh provider-consumer model. When an operator enables OpenKCM from the marketplace — at either org level or account level — an APIBinding is created and key lifecycle operations become available in that workspace without any direct access to the OpenKCM provider infrastructure. + +**Target deployment:** Platform Mesh — running as a Kubernetes controller, with placement at org level or account level depending on the chosen deployment model (see Deployment Models below). + +--- + +## Platform Mesh architecture — what OpenKCM builds on + +Platform Mesh is built on **kcp**, a Kubernetes control plane without container scheduling. Every account maps to an isolated kcp workspace. OpenKCM integrates with four platform primitives: + +| Primitive | What it does | How OpenKCM uses it | +|---|---|---| +| **APIExport** | Provider publishes its service API | OpenKCM publishes the CMK API (key registration, binding, kill switch) from its provider workspace | +| **APIBinding** | Consumer subscribes to a provider API | When an account enables OpenKCM from the marketplace, it creates an APIBinding — the CMK API appears in their workspace | +| **Virtual workspaces** | Aggregated view of all bound consumer objects | The CMK Controller watches all consumer workspaces from one virtual endpoint — no per-workspace polling | +| **OpenFGA (ReBAC)** | Relationship-based authorization derived from org hierarchy | Role separation between security admin and developer is handled automatically — no custom role logic needed in OpenKCM | + +**Placement and governance scope:** Where OpenKCM is placed determines what it can govern. At org level, it has a single aggregated view across all accounts and workspaces — required for cross-workspace kill switch and single pane of glass L1 management (Model 1). At account level, it governs only that account's workspace — the account holder sees and controls only their own keys, and cross-account visibility is intentionally absent (Model 2). Both placements are valid; the customer chooses by where they enable OpenKCM from the marketplace. + +--- + +## Key capabilities + +- L1 Root Key registration at org level — one registration covers all accounts and all their workspaces +- BYOK and HYOK — customer key material never touches the platform; OpenBao is the priority backend +- Kill switch — one action revokes access across all accounts and all their workspaces in the organization +- Zero-touch encryption — workloads deployed from the marketplace are automatically encrypted without developer intervention +- Audit trail — via Platform Mesh audit infrastructure +- Access control — via Platform Mesh OpenFGA (no custom role logic in OpenKCM) +- Lightweight embedded UI — microfrontend in the Platform Mesh portal via Luigi; no separate web interface + +--- + +## Key hierarchy + +| Level | Name | Provisioned by | Admin actions | +|---|---|---|---| +| L1 | Root Key | Security admin (via OpenKCM UI at org level) | Register, rotate, revoke, kill switch | +| L2 | Domain Key | CMK Controller — automatic, one per account/workspace | View only — bind L1→L2 done by security admin at org level; cannot create or delete | +| L3 | Service Key | Security admin (via OpenKCM UI) | Create, view status — see open question below | +| L4 | Data Encryption Key | Consuming service (via Krypton Gateway KMIP) | Not visible to admin | + +### How L2 is provisioned + +L2 provisioning is triggered by an APIBinding being created in an account's workspace. The CMK Controller — watching all consumer workspaces via the virtual workspace endpoint — detects the new binding and calls the Krypton gRPC API to provision one L2 domain key for that account. One account = one L2. L2 is not provisioned per namespace — it is provisioned once at account level and covers all namespaces within that account. + +**Model 1 (org-level enablement):** OpenKCM enabled at org level → CMK Controller provisions one L2 for every existing account in the org. Every new account created afterwards gets an L2 automatically. + +**Model 2 (account-level enablement):** Each account enables OpenKCM independently → CMK Controller scoped to that account provisions one L2 for that account only. + +The security admin does not create L2 keys — they only bind an L1 key to the existing L2. An unbound account is not customer-governed — it uses platform-managed encryption until the admin binds an L1 key. + +### How L4 is handled + +L4 (Data Encryption Keys) are managed entirely by consuming services (e.g. MongoDB, PostgreSQL) via the Krypton Gateway KMIP interface. Platform Mesh injects the KMIP endpoint and the relevant key ID into workload pods as environment variables or Kubernetes Secrets at deploy time — this is what makes encryption zero-touch for developers. L4 is not visible in the admin UI. The kill switch at L1 cascades automatically through L2, L3, and L4 — the admin does not need to act at L4 level. + +--- + +## Deployment models + +The tenant boundary is always the account/workspace. L2 is always one per account. These two facts are constant across both deployment models. + +**The difference between the two models is how many L2s the CMK Controller governs** — and therefore how many accounts fall under a single security admin's key governance. + +| | Model 1 (org level) | Model 2 (account level) | +|---|---|---| +| Controller scope | All accounts in the org | One account only | +| L2s governed | N — one per account | 1 | +| L1 → L2 bindings | N — one per account | 1 | +| Kill switch scope | All accounts in the org | That account only | +| Who operates OpenKCM | Customer (= platform provider = org owner) | Account holder independently | + +OpenKCM on Platform Mesh covers two deployment scenarios. The deployment model is **self-selecting** — it is determined by where the customer enables OpenKCM from the marketplace, not by a configuration flag or a separate product. This gives customers full flexibility to choose their own sovereignty model. + +### How the self-selection works + +| Where OpenKCM is enabled | Deployment model | Who operates OpenKCM | +|---|---|---| +| **Org level** | Air-gapped / sovereign | Customer (= platform provider = org owner) | +| **Account level** | Enterprise / managed platform | Account holder independently | + +The customer makes this choice once at enablement time. Platform Mesh APIExport/APIBinding supports enablement at different levels of the hierarchy — OpenKCM publishes two APIExports, one at org level and one at account level. The customer binds to whichever fits their sovereignty requirement. + +> **Open question (for RFC meeting):** Can one OpenKCM deployment serve both models simultaneously via two APIExports — one at org level, one at account level? To be validated with the Platform Mesh team. + +--- + +### Model 1 — Org level enablement (air-gapped / sovereign) + +The customer enables OpenKCM from the marketplace at **org level**. OpenKCM operates across the entire organization. The org-level super admin has full cross-workspace visibility and control — single pane of glass, cross-workspace kill switch, full governance. The platform provider and the account holder are the same entity. + +``` +Customer enables OpenKCM at org level + │ + ▼ +CMK Controller at org level +└── Provisions L2 automatically for every account in the org +└── Provisions L2 for every new account created afterwards +└── Super admin sees all accounts, all keys, full kill switch +└── No external party in the loop +``` + +**L2 provisioning trigger:** OpenKCM enabled at org level → CMK Controller provisions one L2 for every existing account. New account created → L2 provisioned automatically. + +--- + +### Model 2 — Account level enablement (enterprise / managed platform) + +The customer enables OpenKCM from the marketplace at **account level**. OpenKCM operates within that account only. The account holder manages their own keys independently — the platform provider has zero visibility into that account's key governance. Different accounts can each enable their own OpenKCM instance independently. + +``` +Account Holder A enables OpenKCM at account level + │ + ▼ +CMK Controller scoped to Account A +└── Provisions L2 for Account A only +└── Account Holder A sees only their own keys +└── Platform provider has no visibility into Account A's key governance + +Account Holder B enables OpenKCM at account level (independently) + │ + ▼ +CMK Controller scoped to Account B +└── Provisions L2 for Account B only +└── Completely isolated from Account A +``` + +**L2 provisioning trigger:** Account enables OpenKCM → CMK Controller provisions one L2 for that account. + +**The sovereignty guarantee:** the platform provider operates the infrastructure but is completely outside the key governance boundary. Each account holder owns and operates their own OpenKCM instance. + +--- + +**The critical boundary in Model 2:** even though the platform provider operates Platform Mesh, they cannot see key material, key bindings, or trigger key operations for any account that has enabled OpenKCM at account level. OpenFGA enforces this — account-level enablement means the account holder owns the OpenKCM workspace, not the platform provider. + +--- + +## Role separation — how authorization works + +Platform Mesh uses **OpenFGA** (relationship-based access control) to derive permissions from the organizational hierarchy. OpenKCM does not need to build custom role logic — the platform handles it. + +| Role | Scope | What they can do in OpenKCM | +|---|---|---| +| Super Admin | Org level — air-gapped model | Full access — all accounts, all keys, cross-workspace kill switch | +| Platform Operator | Org level — enterprise model | Infrastructure health only — no key material, no key operations | +| Security Admin | Org level | Register L1 keys, bind L1→L2, trigger kill switch, view full key chain across all accounts | +| Workspace Admin | Workspace level | View key status for their workspace — no key management actions | +| Developer | Namespace level | Nothing — zero-touch encryption; no key visibility | + +OpenFGA derives the permission boundary from the organizational relationship graph automatically. No per-user configuration needed in OpenKCM. + +--- + +## Platform Mesh account model + +``` +Organization (e.g. ACME Corp) ← OpenKCM lives here (org level) + │ + ├── CMK Controller ← org level, watches all account workspaces + │ + └── Account: acme-prod ← workspace, APIBinding to OpenKCM here + │ + ├── Namespace: default → Application workloads + ├── Namespace: db-a → Database A + └── Namespace: db-b → Database B +``` + +One organization has one or more accounts. Each account maps to a kcp workspace. The CMK Controller provisions one L2 domain key per account workspace automatically. The security admin registers one or more L1 keys at org level and binds each L1 key to the relevant account workspaces. + +One L1 key can be bound to multiple workspaces. Different workspaces can be bound to different L1 keys. Pressing the kill switch at org level locks everything — all workspaces, all namespaces, all workloads, regardless of which L1 key they are bound to. + +--- + +## OpenBao — provider-to-provider integration + +OpenKCM does not connect to OpenBao directly as an external dependency. On Platform Mesh, OpenBao is itself a **service provider** — it publishes its API through the same APIExport/APIBinding model. OpenKCM is a **composing provider** — it binds to OpenBao's API to store key material, then exposes the CMK API to end consumers. + +The security admin never touches OpenBao directly. They register their L1 key in the OpenKCM UI — OpenKCM resolves the OpenBao binding underneath. This is the HYOK guarantee: key material stays in OpenBao (customer-controlled), OpenKCM holds only the reference. + +--- + +## What the security admin sees + +The security admin operates from the OpenKCM CMK UI — a microfrontend embedded in the Platform Mesh portal. In Model 1 (org-level enablement), they see the full key chain for the entire organization in one place. In Model 2 (account-level enablement), each account's security admin sees only their own account's key chain. + +On enabling OpenKCM from the Platform Mesh marketplace, the CMK Controller automatically provisions L2 domain keys for all relevant account workspaces. These L2 keys appear in the UI immediately. The admin then registers their L1 root key and binds it to each account's L2 key. They also create L3 service keys for each service that needs to be encrypted under that account's L2. + +Actions are only available where the admin has authority — CMK Controller-provisioned L2 keys are visible but cannot be created or deleted by the admin. + +--- + +## What developers see + +Nothing. Zero-touch encryption means workloads come up encrypted without any key configuration on the developer's part. The developer deploys to a namespace — Platform Mesh injects the KMIP endpoint and key ID into the pod at deploy time. Encryption is handled automatically once the security admin has bound an L1 key to that workspace. + +--- + +## L3 Service Key visibility — open question + +L3 keys are service-level keys, one per service (e.g. MongoDB, PostgreSQL), created by the security admin via the OpenKCM UI and wrapped under the L2 of that account. Three options are under consideration for how L3 is surfaced in the UI: + +- **Option A — L3 fully internal, never shown.** The security admin creates L3 keys via the UI but they are not displayed after creation. The kill switch at L1 cascades down through L2 and L3 automatically. Simplest model. + +- **Option B — L3 visible and manageable.** The org-level UI shows a breakdown: account → services → each with their L3 key status. The security admin creates and views L3 keys. Useful for verifying that each service is actually encrypted. + +- **Option C — L3 with selective revocation.** In addition to Option B, the kill switch can be triggered at L3 level — revoke only a specific service, not the entire account. Open architectural question: who owns selective service revocation — OpenKCM CMK Platform Mesh or Krypton? + +> **Current direction:** Option B for the initial release — L3 visible and manageable by the security admin. Option C is a future feature pending resolution of the selective revocation ownership question. + +### Option A — L3 fully internal + +``` +Organization: ACME Corp +└── OpenKCM CMK (org level) + │ + ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages + │ + ├── Account Workspace: acme-prod + │ └── L2 Domain Key: acme-prod-domain [Bound] ← admin binds L1→L2 + │ + └── Account Workspace: acme-dev + └── L2 Domain Key: acme-dev-domain [Bound] + +L3 and L4 keys exist but are never shown in the UI. +Kill switch: L1 revoked → L2 revoked → L3 revoked → all workloads inaccessible. +``` + +### Option B — L3 visible and manageable + +``` +Organization: ACME Corp +└── OpenKCM CMK (org level) + │ + ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages + │ + ├── Account Workspace: acme-prod + │ ├── L2 Domain Key: acme-prod-domain [Bound] ← admin binds L1→L2 + │ └── Services: + │ ├── mongodb → L3: acme-prod-mongodb-key [Active] ← admin creates + │ └── postgres → L3: acme-prod-postgres-key [Active] ← admin creates + │ + └── Account Workspace: acme-dev + ├── L2 Domain Key: acme-dev-domain [Bound] + └── Services: + └── redis → L3: acme-dev-redis-key [Active] ← admin creates + +Admin can see and create L3 keys. No delete or revoke actions at L3 level. +Kill switch at L1 still cascades automatically across all L2 and L3. +``` + +### Option C — L3 with selective revocation (future / open question) + +``` +Organization: ACME Corp +└── OpenKCM CMK (org level) + │ + ├── L1 Root Key: openbao/acme-l1-master [Active] + │ + ├── Account Workspace: acme-prod + │ ├── L2 Domain Key: acme-prod-domain [Bound] + │ └── Services: + │ ├── mongodb → L3: acme-prod-mongodb-key [Active] [Revoke] + │ └── postgres → L3: acme-prod-postgres-key [Active] [Revoke] + │ + └── Account Workspace: acme-dev + ├── L2 Domain Key: acme-dev-domain [Bound] + └── Services: + └── redis → L3: acme-dev-redis-key [Active] [Revoke] + +Admin can revoke individual service keys without triggering the full kill switch. +Example: revoke MongoDB only → MongoDB data inaccessible, Postgres and Redis unaffected. + +⚠ Open question: who owns selective revocation — OpenKCM CMK Platform Mesh or Krypton? +``` + +--- + +## Kill switch scope + +| Action | Scope | Effect | +|---|---|---| +| Revoke L1 Root Key | All workspaces bound to that L1 | All services in those workspaces become inaccessible | +| Kill switch (org level) | Entire organization | All workspaces, all namespaces, all services inaccessible — regardless of which L1 they are bound to | + +--- + +## Integration path — how OpenKCM connects to Platform Mesh + +OpenKCM uses the **multicluster-runtime** integration path. The CMK Controller is a custom controller with its own reconciliation logic — not a passive sync agent. This is required because: + +- Kill switch propagation is cross-workspace and must cascade through L2 → L3 → L4 in a controlled sequence +- L2 provisioning requires calling the Krypton gRPC API, not just syncing CRD state +- Authorization decisions (which admin can act on which workspace) require custom logic on top of OpenFGA + +The CMK Controller connects to Platform Mesh via outbound HTTPS to kcp — no inbound access to the OpenKCM provider cluster is required. + +--- + +## Deployment scenario + +``` +Platform Mesh +│ +├── kcp (control plane) +│ ├── Organization workspace: root:acme ← OpenKCM lives here +│ │ └── OpenKCM APIBinding → CMK API available to all accounts +│ └── Virtual workspace: aggregated view of all bound account objects +│ +├── OpenKCM provider cluster (org level) +│ ├── CMK Controller ← watches virtual workspace, provisions L2, manages lifecycle +│ ├── CMK UI (microfrontend via Luigi, embedded in Platform Mesh portal) +│ └── OpenBao binding ← provider-to-provider, key material stays in customer keystore +│ +├── Account workspace: acme-prod +│ ├── L2 Domain Key CR ← auto-provisioned by CMK Controller +│ ├── L3 Service Key CRs ← created by security admin via OpenKCM UI +│ └── Workload namespaces → KMIP endpoint + key ID injected into pods at deploy time +│ +└── Account workspace: acme-dev + ├── L2 Domain Key CR ← auto-provisioned by CMK Controller + ├── L3 Service Key CRs ← created by security admin via OpenKCM UI + └── Workload namespaces → KMIP endpoint + key ID injected into pods at deploy time +``` From 2085f4b71c2e78ba0afe60cb9ea7397f73cf1f24 Mon Sep 17 00:00:00 2001 From: isanmaz Date: Wed, 24 Jun 2026 19:01:14 +0200 Subject: [PATCH 3/6] docs: flag unconfirmed standalone assumptions and align tenancy model with dual deployment model Signed-off-by: isanmaz --- product-vision/cmk-product-vision.md | 206 +++-------------------- product-vision/cmk-standalone-vision.md | 209 ++++++++++++++++++++++++ product-vision/cmk-tenancy-model.md | 130 +++++++-------- 3 files changed, 290 insertions(+), 255 deletions(-) create mode 100644 product-vision/cmk-standalone-vision.md diff --git a/product-vision/cmk-product-vision.md b/product-vision/cmk-product-vision.md index 2abbe68..ea76f69 100644 --- a/product-vision/cmk-product-vision.md +++ b/product-vision/cmk-product-vision.md @@ -1,6 +1,6 @@ --- status: Draft -last_updated: 2026-06-16 +last_updated: 2026-06-24 audience: Open Source Community, Contributors, Stakeholders --- @@ -18,7 +18,11 @@ OpenKCM CMK governs encryption keys. The actual cryptographic operations are per When an organization runs workloads on a cloud platform, their data is typically encrypted — but by a key the platform controls. The organization trusts the platform not to look. That trust is implicit, unverifiable, and often not sufficient for regulated industries. -Customer Managed Keys solve this by inverting control: the customer owns the root key, the platform never has access to key material, and the customer can revoke access at any time — including instantly, for all workloads at once. +Most organizations also operate across multiple cloud providers, on-premise systems, and HSMs — each with its own key management interface. Keys end up scattered with no unified view, no single audit trail, and no single point of revocation. + +OpenKCM CMK solves both: it inverts control so the customer owns the root key and the platform never touches key material, and it acts as a single control plane across all keystores — AWS KMS, Azure Key Vault, GCP KMS, OpenBao, HSMs — managed from one UI, one audit trail, one kill switch. + +When access needs to be revoked, it is immediate. No waiting periods, no platform approval, no delay — the customer triggers the kill switch and all governed workloads become inaccessible instantly. Most commercial KMS products enforce mandatory delays of 7 to 90 days before key destruction. OpenKCM CMK does not. This is not a theoretical requirement. Defense agencies, government authorities, utilities, financial institutions, and any organization subject to data residency or sovereignty regulation needs this guarantee by law. @@ -44,189 +48,21 @@ Teams deploying workloads who should never need to think about key management OpenKCM CMK is offered in two variants, both sharing the same CMK Core. ---- - -### OpenKCM CMK - -The full-featured, standalone CMK product. Runs on any Kubernetes environment — no platform dependency required. Designed for organizations that operate their own infrastructure and need complete key governance under their own control. - -**Target deployment:** Any Kubernetes cluster the customer operates themselves — on-premise, sovereign cloud, air-gapped, or any cloud provider. - -**Key capabilities:** - -- L1 Root Key registration and lifecycle management (enable, disable, rotate, delete) -- BYOK (Bring Your Own Key) and HYOK (Hold Your Own Key) — customer key material never touches the platform -- Pluggable keystore backends: OpenBao, AWS KMS, Azure Key Vault, GCP KMS, HSM via PKCS#11 -- Kill switch (Red Button) — instant revocation of all workloads across the deployment -- Multi-party approval (Four-Eyes) — high-stakes operations require a second authorized approver -- Full audit trail — tamper-evident log of every key operation, exportable for compliance -- Tenant onboarding and offboarding -- Role-based access control via OIDC / RBAC -- Full CMK UI — own web interface, not embedded in any platform portal - -**Key hierarchy:** - -| Level | Name | Scope | Managed by | -|---|---|---|---| -| L1 | Root Key | Tenant | Customer — registered via OpenKCM CMK | -| L2 | Domain Key | Workspace | OpenKCM CMK — internal | -| L3 | Service Key | Service | Krypton — internal | -| L4 | Data Encryption Key | Workload | Krypton — internal | - -The customer only ever registers and manages the L1 key. Everything below is derived and managed internally by OpenKCM CMK and Krypton. - ---- - -### OpenKCM CMK Platform Mesh - -A lightweight CMK integration embedded in the Platform Mesh portal. Designed for Platform Mesh operators and tenants who need customer-managed encryption without running a separate CMK product. - -**Target deployment:** Platform Mesh — running as a Kubernetes controller in the platform-admin namespace, with cross-namespace RBAC authority over the entire workspace. - -**Key capabilities:** - -- L1 Root Key registration at account level — one registration covers all namespaces in the account -- BYOK and HYOK — same guarantee as OpenKCM CMK; OpenBao is the priority backend -- Kill switch — one action revokes access across all namespaces in the workspace -- Zero-touch encryption — workloads deployed from the marketplace are automatically encrypted without developer intervention -- Audit trail — via Platform Mesh audit infrastructure -- Access control — via Platform Mesh RBAC -- Lightweight embedded UI — microfrontend in the Platform Mesh portal via Luigi; no separate web interface - -**What the security admin sees:** - -The OpenKCM section appears at account level in the Platform Mesh portal — not inside a namespace. Each account has one workspace, and that workspace contains multiple namespaces. When OpenKCM is enabled, Platform Mesh automatically provisions one L2 Domain Key per namespace. - -The security admin registers the organization's L1 root key at account level. She then binds that L1 key to the L2 Domain Keys that Platform Mesh has provisioned — one binding per namespace. Once bound, all workloads running in that namespace are encrypted under the L1→L2 key chain. - -**One unified UI — access gated by key level** - -All key levels (L1, L2, L3) are managed from a single account-level UI. What actions are available depends on the key level and the user's role: - -| Key level | Generated by | Admin actions | +| | OpenKCM CMK | OpenKCM CMK Platform Mesh | |---|---|---| -| L1 Root Key | Customer (via OpenKCM CMK) | Register, bind to L2, rotate, revoke, kill switch | -| L2 Domain Key | Platform Mesh (automatic) | View, bind L1 to L2 — cannot create or delete | -| L3 Service Key | Krypton (automatic) | View status — see open question below | - -The security admin sees the full key chain for the account in one place. Actions are only available where the admin has authority — Platform Mesh-generated and Krypton-generated keys are visible but not creatable or deletable by the admin. - -**What developers see:** - -Nothing. Zero-touch encryption means workloads come up encrypted without any key configuration on the developer's part. - -**L3 Service Key visibility — open question** - -L3 keys are generated by Krypton automatically when a service is deployed, wrapped under the L2 of that namespace. Three options are under consideration for how L3 keys are handled in the UI: - -- **Option A — L3 fully internal, never shown.** Krypton generates and manages L3 silently. The security admin only sees L1 and L2. The kill switch at L1 level cascades down through L2 and L3 automatically. Simplest model. - -- **Option B — L3 visible but not manageable.** The account-level UI shows a breakdown: workspace → namespace → services → each with their L3 key status. Read-only. Useful for the security admin to verify that each service (MongoDB, Postgres, etc.) is actually encrypted. No actions at L3 level. - -- **Option C — L3 has its own actions (selective revocation).** The kill switch can be triggered at L3 level — revoke only a specific service (e.g. MongoDB only), not the entire workspace. This requires UI at service level and introduces the question of who owns selective service revocation: OpenKCM CMK Platform Mesh or Krypton. This is an open architectural question to be resolved. - -> **Current direction:** Option B for the initial release — L3 visible, not manageable. Option C is a future feature pending resolution of the selective revocation ownership question. - ---- - -**Option A — L3 fully internal** - -``` -Account: ACME Corp -└── OpenKCM CMK Platform Mesh (account level) - │ - ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages - │ - ├── Namespace: default - │ └── L2 Domain Key: acme-default-domain [Bound] ← admin binds L1→L2 - │ - ├── Namespace: db-a - │ └── L2 Domain Key: acme-dba-domain [Bound] - │ - └── Namespace: db-b - └── L2 Domain Key: acme-dbb-domain [Bound] - -L3 Service Keys and L4 Data Keys are managed internally by Krypton. -Admin never sees them. Kill switch at L1 cascades automatically. - -Kill switch: -L1 revoked → L2 revoked → L3 revoked → all workloads inaccessible -``` - ---- - -**Option B — L3 visible, not manageable** - -``` -Account: ACME Corp -└── OpenKCM CMK Platform Mesh (account level) - │ - ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages - │ - ├── Namespace: default - │ ├── L2 Domain Key: acme-default-domain [Bound] ← admin binds L1→L2 - │ └── Services (read-only): - │ └── mongodb → L3: acme-default-mongodb-key [Active] - │ - ├── Namespace: db-a - │ ├── L2 Domain Key: acme-dba-domain [Bound] - │ └── Services (read-only): - │ └── postgres → L3: acme-dba-postgres-key [Active] - │ - └── Namespace: db-b - ├── L2 Domain Key: acme-dbb-domain [Bound] - └── Services (read-only): - └── redis → L3: acme-dbb-redis-key [Active] - -Admin can see all L3 keys and their status. No actions available at L3 level. -Kill switch at L1 still cascades automatically across all L2 and L3. -``` - ---- +| Deployment | Any Kubernetes cluster | Platform Mesh only | +| UI | Full standalone web interface | Embedded microfrontend in Platform Mesh portal | +| L2 provisioning | Customer via UI | CMK Controller (automatic, one per account/workspace) | +| L3 management | Customer via UI | Security admin via UI | +| L4 management | Customer via UI or consuming service via KMIP | Consuming service via KMIP only | +| Tenant management | Customer via UI | Platform Mesh account model | +| Audit | Built-in audit trail | Via Platform Mesh audit infrastructure | +| RBAC | OIDC / RBAC | Via Platform Mesh OpenFGA | +| Kill switch scope | Tenant | Org (Model 1) or account (Model 2) — see deployment models | -**Option C — L3 with selective revocation (future / open question)** - -``` -Account: ACME Corp -└── OpenKCM CMK Platform Mesh (account level) - │ - ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages - │ - ├── Namespace: default - │ ├── L2 Domain Key: acme-default-domain [Bound] - │ └── Services: - │ └── mongodb → L3: acme-default-mongodb-key [Active] [Revoke] - │ - ├── Namespace: db-a - │ ├── L2 Domain Key: acme-dba-domain [Bound] - │ └── Services: - │ └── postgres → L3: acme-dba-postgres-key [Active] [Revoke] - │ - └── Namespace: db-b - ├── L2 Domain Key: acme-dbb-domain [Bound] - └── Services: - └── redis → L3: acme-dbb-redis-key [Active] [Revoke] - -Admin can revoke individual service keys without triggering the full kill switch. -Example: revoke MongoDB only → MongoDB data inaccessible, Postgres and Redis unaffected. - -⚠ Open question: who owns selective revocation — OpenKCM CMK Platform Mesh or Krypton? -``` - -**Platform Mesh account model:** - -``` -Account (e.g. ACME Corp) ← administrative boundary, CMK governed here - │ - └── Workspace: acme-prod - │ - ├── Namespace: default → Application - ├── Namespace: db-a → Database A - ├── Namespace: db-b → Database B - └── Namespace: platform-admin → OpenKCM Controller -``` - -One L1 key at account level governs all workspaces and namespaces. Pressing the kill switch at account level locks everything — not just one namespace. +Full product details: +- [OpenKCM CMK — Standalone](cmk-standalone-vision.md) +- [OpenKCM CMK — Platform Mesh](cmk-platform-mesh-vision.md) --- @@ -261,7 +97,7 @@ The kill switch is a customer-initiated action that immediately revokes access t This is a one-way, destructive action. It is not a pause — it is a cryptographic lock. Once executed, data cannot be recovered without a new key registration and an approval cycle. For OpenKCM CMK: the kill switch scope is the tenant. -For OpenKCM CMK Platform Mesh: the kill switch scope is the account/workspace — all namespaces within it. +For OpenKCM CMK Platform Mesh: the kill switch scope depends on the deployment model — org level (all accounts in the organization) when enabled at org level, or account level (all namespaces in that account) when enabled at account level. --- @@ -312,7 +148,7 @@ The lightweight CMK layer for Platform Mesh. Includes an embedded microfrontend The shared business logic library consumed by both OpenKCM CMK and OpenKCM CMK Platform Mesh. Contains the key lifecycle state machine (NIST SP 800-57), L1 key validation, kill switch execution logic, tenant registry, audit trail logic, and multi-party approval logic. Deployment-agnostic — no dependency on any platform or cloud provider. **CMK Controller** -A Kubernetes controller that runs inside Platform Mesh (in the platform-admin namespace). Watches OpenKCM CRDs and reconciles key state across the workspace. Used exclusively by OpenKCM CMK Platform Mesh — not part of the standalone OpenKCM CMK deployment. +A Kubernetes controller that watches OpenKCM CRDs and reconciles key state. Placement depends on the deployment model — at org level when OpenKCM is enabled at org level (governs all accounts), or at account level when enabled at account level (governs that account only). Used exclusively by OpenKCM CMK Platform Mesh — not part of the standalone OpenKCM CMK deployment. **Krypton** The cryptographic execution engine. Performs key derivation, encryption, decryption, and KMIP services. Operates independently of OpenKCM CMK — it can run without CMK governance on top. OpenKCM CMK governs; Krypton executes. diff --git a/product-vision/cmk-standalone-vision.md b/product-vision/cmk-standalone-vision.md new file mode 100644 index 0000000..6a6bb51 --- /dev/null +++ b/product-vision/cmk-standalone-vision.md @@ -0,0 +1,209 @@ +--- +status: Draft +last_updated: 2026-06-24 +audience: Open Source Community, Contributors, Stakeholders +--- + +# OpenKCM CMK — Standalone + +## Overview + +OpenKCM CMK is the full-featured, standalone Customer Managed Key product. It runs on any Kubernetes environment with no platform dependency. Designed for organizations that operate their own infrastructure and need complete key governance under their own control. + +This is an open source product. The customer — whether a government authority, a large enterprise, or a managed service provider — downloads, deploys, and operates it themselves. There is no vendor running it on their behalf, no managed service, no external dependency. The customer owns the deployment end to end. + +**Target deployment:** Any Kubernetes cluster the customer operates themselves — on-premise, sovereign cloud, air-gapped, or any cloud provider. + +--- + +## Key capabilities + +- L1 Root Key registration and lifecycle management (enable, disable, rotate, delete) +- BYOK (Bring Your Own Key) and HYOK (Hold Your Own Key) — customer key material never touches the platform +- Pluggable keystore backends: OpenBao, AWS KMS, Azure Key Vault, GCP KMS, HSM via PKCS#11 +- Kill switch (Red Button) — instant revocation of all workloads across the deployment +- Multi-party approval (Four-Eyes) — high-stakes operations require a second authorized approver +- Full audit trail — tamper-evident log of every key operation, exportable for compliance +- Tenant onboarding and offboarding +- Region and tenant management — region → tenant → key hierarchy ❓ — not confirmed +- Role-based access control via OIDC / RBAC +- Full CMK UI — own web interface, not embedded in any platform portal + +--- + +## Key hierarchy + +Krypton (crypto layer) knows nothing by default. Every key at every level must be explicitly registered via the Krypton API. The CMK UI is the management surface for the full key hierarchy — there is no platform controller to automate any part of this. + +| Level | Name | Scope | Managed by | +|---|---|---|---| +| L1 | Root Key | Tenant | Customer — registered via OpenKCM CMK UI | +| L2 | Domain Key | Domain | Customer via OpenKCM CMK UI ❓ — in Platform Mesh this is auto-provisioned by CMK Controller; in standalone there is no controller, so manual creation is assumed but not confirmed | +| L3 | Service Key | Service | Customer via OpenKCM CMK UI ❓ — assumed manual creation by security admin, but whether this is via UI, CLI, or API is not confirmed | +| L4 | Data Encryption Key | Workload | Consuming service via Krypton Gateway KMIP (when KMIP-capable) ❓ — or customer via UI when no KMIP service present; both paths assumed, neither confirmed as built | + +> **Open question:** L2, L3, and L4 management in standalone is not yet validated with Krypton or engineering. The table above reflects the current assumption — all levels are manually managed by the customer via UI when no consuming service handles it via KMIP. This needs to be confirmed before any UI work starts. + +The standalone UI is expected to support all four key levels (L1–L4) ❓ — the full scope of the standalone UI is not yet confirmed. Unlike Platform Mesh — where L2 is provisioned automatically and L4 is handled by consuming services via KMIP — standalone cannot make either assumption. The customer may be the only actor managing the full key chain. + +### L4 — two modes + +When a KMIP-capable consuming service is present (e.g. MongoDB, PostgreSQL), it manages L4 directly via the Krypton Gateway KMIP interface: +- **Option A:** the consuming service provides its own DEKs; Krypton wraps them under L3 and returns the wrapped blob. The consuming service owns and stores the wrapped DEK. +- **Option B:** the consuming service requests Krypton to create, manage, and store the DEKs entirely. + +When no KMIP-capable consuming service is present, the customer manages L4 through the CMK UI. The UI registers the DEK, wraps it under the appropriate L3 key, and the key material can be injected into workloads via Kubernetes Secrets. + +--- + +## Region and tenant model + +The standalone deployment is organized as: + +``` +Region +└── Tenant + └── L1 Root Key + └── L2 Domain Key (one per domain boundary) + └── L3 Service Key (one per service) + └── L4 Data Encryption Key (one per workload) +``` + +A default region and default tenant are provisioned at deployment time so the customer has a starting point ❓ — whether this auto-provisioning is actually implemented or just assumed needs confirmation. The customer then creates their own domain boundaries (L2) and service keys (L3) according to their own business structure — the platform makes no assumptions about domain organization ❓ — this flexibility is assumed but the actual onboarding flow is not defined. + +Multiple tenants within a region are supported ❓ — not confirmed. Multiple regions are supported for multi-region sovereign deployments ❓ — not confirmed. + +> **Open question:** The region and tenant model described here is a proposal, not a confirmed design. Default provisioning, multi-tenant support, and multi-region support all need to be validated with engineering before being treated as committed scope. + +--- + +## What the security admin manages + +The security admin is the single operator of the CMK UI. The responsibilities below reflect the current assumption — not all of these are confirmed as built or in scope. + +- Register one or more L1 root keys (pointing to external keystores — no key material imported) +- Define domain boundaries and create L2 domain keys ❓ +- Define service keys (L3) within each domain ❓ +- Register L4 DEKs for workloads where no consuming service handles this via KMIP ❓ +- Bind L1 → L2 to bring domains under customer-managed encryption ❓ +- Trigger the kill switch at tenant level when required +- Manage tenant onboarding and offboarding ❓ +- Manage regions if running a multi-region deployment ❓ + +--- + +## Kill switch + +Triggering the kill switch at tenant level revokes the L1 root key. Since all L2, L3, and L4 keys are derived from L1, every encrypted workload in the tenant becomes inaccessible within the propagation window. + +This is irreversible without a new key registration and approval cycle. Multi-party approval (Four-Eyes) is required before the kill switch executes. + +--- + +## Deployment scenario + +``` +Sovereign / air-gapped deployment +│ +├── OpenKCM CMK (standalone) +│ ├── CMK UI ← full web interface, operator-owned +│ ├── CMK Application +│ └── CMK Core +│ +└── Krypton + ├── Krypton Core (gRPC API — used by CMK for L1/L2/L3 management) + └── Krypton Gateway (KMIP — used by consuming services for L4) +``` + +The customer operates both OpenKCM CMK and Krypton. No dependency on any external platform or managed service. + +--- + +## Sovereign cloud use case + +A sovereign cloud customer — a government authority, defense agency, or regulated enterprise — controls their own infrastructure entirely. They decide where deployments live, what crosses borders, and who has physical access. No cloud provider, no managed service, no external dependency is acceptable. + +### Target customers + +**National defense and intelligence agencies** +Organizations where data sovereignty is a legal and operational non-negotiable. Key material must remain within national borders, under direct physical control. Any third-party dependency in the encryption path is unacceptable. + +**Government authorities and public sector** +Ministries, regulatory bodies, and public administration operating under data residency laws (e.g. GDPR, national cybersecurity frameworks). Required to demonstrate cryptographic control over citizen and state data. + +**Critical infrastructure operators** +Energy grids, water systems, transportation networks, telecommunications. Subject to NIS2, KRITIS, or equivalent national frameworks requiring strong data protection and operational independence from foreign cloud providers. + +**Regulated financial institutions** +Banks, insurers, and financial market infrastructures operating under strict data residency and auditability requirements. Need to demonstrate to regulators that encryption keys are under their exclusive control. + +**Managed service providers offering sovereign cloud** +Companies building sovereign cloud platforms for the above customers. They need CMK as a first-class capability to offer their own customers the same guarantees — your data is encrypted under your key, not ours. + +--- + +**Deployment model:** + +The customer deploys Krypton in each of their own data centers. They deploy OpenKCM CMK once and connect it to all their Krypton instances. All key management happens from one UI — but key material never leaves the data center it was created in. + +``` +OpenKCM CMK (one instance — e.g. central data center) + │ + ├── Connected to: Krypton — Frankfurt data center (EU keys stay here) + └── Connected to: Krypton — Virginia data center (US keys stay here) +``` + +The customer registers their Krypton deployments in OpenKCM CMK once. From that point, every time they create a domain key or service key, they select which deployment it lives on. OpenKCM CMK talks to the right Krypton instance. The key material never moves. + +**Why this model satisfies sovereign cloud requirements:** + +- Key material stays physically in the customer's own server room — never crosses to a third party +- No cloud provider dependency — no AWS, no Azure, no GCP in the data path +- No routing layer deciding where keys live — the customer decides explicitly, at creation time +- One UI, one audit trail, one kill switch — across all deployments +- Kill switch is immediate — no mandatory delays, no platform approval required + +**What the admin does:** + +1. Deploys Krypton in each data center +2. Registers each Krypton deployment in OpenKCM CMK (name + endpoint) +3. Registers L1 root key (pointing to their HSM or OpenBao instance in that data center) +4. Creates domain keys (L2) — selecting which deployment each domain lives on +5. Creates service keys (L3) within each domain +6. From that point — workloads in that domain are encrypted, kill switch is armed + +**Multi-region key visibility:** + +The admin sees all keys across all connected deployments in one place. The region is just a label for which Krypton endpoint a key lives on — not a routing abstraction, not a tenant boundary. The customer defined those regions themselves by choosing where to deploy Krypton. + +--- + +## Enterprise use case + +A large enterprise — a manufacturer, financial institution, or technology company — typically runs workloads across multiple environments: on-premise data centers, one or more cloud providers, and potentially air-gapped systems. They need encryption key governance across all of these from one place, without handing control to any single vendor. + +OpenKCM CMK is open source. The enterprise downloads it, deploys it on their own infrastructure, and operates it themselves. No vendor has access to their deployment. No managed service is involved. The enterprise's own security team owns the full stack. + +### Target customers + +**Large enterprises running hybrid infrastructure** +Organizations running workloads across on-premise, cloud, and air-gapped environments simultaneously. They need one key management control plane that spans all of it — without being locked into a single cloud provider's KMS. + +**Enterprises with strict compliance requirements** +Organizations subject to ISO 27001, SOC 2, PCI-DSS, HIPAA, or similar frameworks that require demonstrable control over encryption keys, a tamper-evident audit trail, and the ability to revoke access immediately. + +**Organizations replacing fragmented KMS setups** +Enterprises currently managing keys separately in AWS KMS, Azure Key Vault, and on-premise HSMs — with no unified view, no single audit trail, and no single kill switch. OpenKCM CMK connects to all of them from one UI. + +**Teams building internal platforms** +Platform engineering teams within large organizations who want to offer encryption key governance as a self-service capability to internal development teams — without building key management from scratch. + +### Why self-deployment matters + +The enterprise deploys and operates OpenKCM CMK themselves. This means: + +- **No vendor lock-in** — the software is open source; the enterprise can fork it, extend it, or replace it +- **No external access** — no vendor has visibility into the enterprise's key operations or audit trail +- **Full control over upgrades** — the enterprise decides when to upgrade, not a managed service provider +- **Runs anywhere** — on their own Kubernetes cluster, on any cloud, or air-gapped; no infrastructure dependency + diff --git a/product-vision/cmk-tenancy-model.md b/product-vision/cmk-tenancy-model.md index fddf2c8..8e743b4 100644 --- a/product-vision/cmk-tenancy-model.md +++ b/product-vision/cmk-tenancy-model.md @@ -1,6 +1,6 @@ --- status: Draft -last_updated: 2026-06-16 +last_updated: 2026-06-24 audience: Open Source Community, Contributors, Stakeholders --- @@ -43,16 +43,14 @@ This document defines the tenancy model for OpenKCM CMK Platform Mesh. It descri | Name | | Status | +------------------+ - | 1 - | - | 1 + +----------------------+ | L2 Domain Key | +----------------------+ | L2KeyID | -| NamespaceID | +| WorkspaceID | ← one per account/workspace, not per namespace | Status | -| ProvisionedBy | ← Platform Mesh (automatic) +| ProvisionedBy | ← CMK Controller (automatic, via Krypton API) +----------------------+ | 1 | @@ -61,7 +59,7 @@ This document defines the tenancy model for OpenKCM CMK Platform Mesh. It descri | L1 Root Key | +----------------------+ | L1KeyID | -| AccountID | +| OrgID / AccountID | ← org level (Model 1) or account level (Model 2) | Name | | Status | | KeystoreType | ← OpenBao, AWS KMS, Azure KV, HSM... @@ -105,7 +103,7 @@ This document defines the tenancy model for OpenKCM CMK Platform Mesh. It descri | ServiceID | | L2KeyID | | Status | -| GeneratedBy | ← Krypton (automatic) +| CreatedBy | ← Security Admin (via OpenKCM CMK UI) +------------------+ @@ -113,12 +111,13 @@ This document defines the tenancy model for OpenKCM CMK Platform Mesh. It descri | Security Admin | +------------------+ | UserID | -| AccountID | +| OrgID / AccountID| ← org level (Model 1) or account level (Model 2) | Role | +------------------+ | | registers L1 keys | binds L1 → L2 + | creates L3 keys | triggers kill switch ``` @@ -130,31 +129,31 @@ This document defines the tenancy model for OpenKCM CMK Platform Mesh. It descri The top-level administrative boundary. Represents one customer organization. One account has exactly one workspace. The account is the tenant — pressing the kill switch at account level locks the entire account. ### Security Admin -A user with account-level permissions in Platform Mesh. Responsible for registering L1 root keys, binding them to L2 domain keys, and triggering the kill switch. The security admin operates from the account-level OpenKCM CMK UI. +A user responsible for registering L1 root keys, binding them to L2 domain keys, creating L3 service keys, and triggering the kill switch. In Model 1 (org-level enablement), the security admin operates at org level and has visibility across all accounts. In Model 2 (account-level enablement), the security admin operates within their own account only. ### CMK Controller -A Kubernetes controller running in the platform-admin namespace of the workspace. Watches OpenKCM CRDs and reconciles key state across all namespaces. One controller per Platform Mesh installation — shared across all accounts. +A Kubernetes controller that watches OpenKCM CRDs and reconciles key state. In Model 1, it runs at org level and governs all accounts in the organization. In Model 2, it is scoped to a single account. One controller per OpenKCM deployment. ### Workspace The deployment environment within an account. One account has one workspace. Contains multiple namespaces where applications and services run. ### Namespace -A Kubernetes namespace within the workspace. Each namespace has exactly one L2 Domain Key, provisioned automatically by Platform Mesh when OpenKCM CMK Platform Mesh is enabled. +A Kubernetes namespace within the workspace. Applications and services run here. Namespace-level encryption separation is achieved through L3 Service Keys — one per service — all wrapped under the account's single L2 Domain Key. ### L1 Root Key -A customer-owned root encryption key. Registered by the security admin at account level. Key material never leaves the customer's external keystore — OpenKCM CMK holds only a reference. One account can have multiple L1 root keys. Each L1 key is backed by one external keystore. +A customer-owned root encryption key. Registered by the security admin at org level (Model 1) or account level (Model 2). Key material never leaves the customer's external keystore — OpenKCM CMK holds only a reference. One L1 key can be bound to multiple accounts (Model 1). Each L1 key is backed by one external keystore. ### External Keystore The customer's own key management system where L1 key material lives. Supported backends: OpenBao, AWS KMS, Azure Key Vault, GCP KMS, HSM via PKCS#11. OpenKCM CMK never stores key material — it holds a pointer and calls the keystore at runtime via Krypton. ### Key Binding -The association between an L1 Root Key and an L2 Domain Key. Created by the security admin. One L2 Domain Key is bound to exactly one L1 Root Key. One L1 Root Key can be bound to multiple L2 Domain Keys (multiple namespaces can share the same L1 key). Different namespaces can be bound to different L1 keys — the admin decides. +The association between an L1 Root Key and an L2 Domain Key. Created by the security admin. One L2 Domain Key is bound to exactly one L1 Root Key. One L1 Root Key can be bound to multiple L2 Domain Keys (multiple accounts can share the same L1 key). Different accounts can be bound to different L1 keys — the admin decides. ### L2 Domain Key -Provisioned automatically by Platform Mesh when OpenKCM CMK Platform Mesh is enabled — one per namespace. The security admin cannot create or delete L2 keys. The admin can bind an L1 key to an L2 key. All services in a namespace are encrypted under that namespace's L2 key. +Provisioned automatically by the CMK Controller when OpenKCM is enabled on Platform Mesh — **one per account/workspace**. The CMK Controller calls Krypton explicitly via API to create it. The security admin cannot create or delete L2 keys. The admin binds an L1 key to the account's L2 key. All services across all namespaces in that account are encrypted under the single L2 key. ### L3 Service Key -Generated automatically by Krypton when a service is deployed in a namespace. Wrapped under the L2 Domain Key of that namespace. One L3 key per service instance. Not created or managed by the security admin. +Created by the security admin via the OpenKCM CMK UI. Wrapped under the L2 Domain Key of that account. One L3 key per service instance. Not provisioned automatically — the security admin defines the service boundaries. ### Service An application or workload running inside a namespace (e.g. MongoDB, Postgres, Redis). Has one L3 Service Key. Encrypted automatically — no key configuration required from the developer. @@ -165,13 +164,14 @@ An application or workload running inside a namespace (e.g. MongoDB, Postgres, R | Rule | Description | |---|---| -| One L2 per namespace | Platform Mesh provisions exactly one L2 Domain Key per namespace | -| Admin registers L1 | The security admin registers one or more L1 keys at account level | -| Admin binds L1 → L2 | The security admin decides which L1 key governs which namespace | +| One L2 per account | CMK Controller provisions exactly one L2 Domain Key per account/workspace via Krypton API | +| Admin registers L1 | The security admin registers one or more L1 keys at org level (Model 1) or account level (Model 2) | +| Admin binds L1 → L2 | The security admin decides which L1 key governs which account | | One L1 per L2 | Each L2 Domain Key is bound to exactly one L1 Root Key at a time | -| One L1 → many L2s | One L1 Root Key can be bound to multiple namespaces | -| Different L1s per namespace | Different namespaces can be governed by different L1 keys | -| Unbound namespace | A namespace with no L1 binding is not customer-governed — it uses platform-managed encryption until the admin binds an L1 key | +| One L1 → many L2s | One L1 Root Key can be bound to multiple accounts (Model 1) | +| Different L1s per account | Different accounts can be governed by different L1 keys | +| Admin creates L3 | The security admin creates one L3 Service Key per service via the OpenKCM CMK UI | +| Unbound account | An account with no L1 binding is not customer-governed — it uses platform-managed encryption until the admin binds an L1 key | --- @@ -179,10 +179,11 @@ An application or workload running inside a namespace (e.g. MongoDB, Postgres, R | Action | Scope | Effect | |---|---|---| -| Revoke L1 Root Key | All namespaces bound to that L1 | All services in those namespaces become inaccessible | -| Kill switch (account level) | Entire account | All namespaces, all services inaccessible — regardless of which L1 they are bound to | +| Revoke L1 Root Key | All accounts bound to that L1 | All services in those accounts become inaccessible | +| Kill switch — Model 1 (org level) | Entire organization | All accounts, all namespaces, all services inaccessible — regardless of which L1 they are bound to | +| Kill switch — Model 2 (account level) | That account only | All namespaces and services in that account become inaccessible | -If an account has multiple L1 keys bound to different namespaces, revoking one L1 key affects only the namespaces bound to it. The full account kill switch revokes everything. +In Model 1, if different accounts are bound to different L1 keys, revoking one L1 affects only the accounts bound to it. The org-level kill switch revokes everything across all accounts. --- @@ -203,88 +204,77 @@ Registered → Active → Suspended → Revoked ### L2 Domain Key lifecycle -Managed by Platform Mesh and OpenKCM CMK Controller. Follows the state of the bound L1 key — if L1 is revoked, L2 is revoked automatically. +Managed by the CMK Controller. Follows the state of the bound L1 key — if L1 is revoked, L2 is revoked automatically. ### L3 Service Key lifecycle -Managed by Krypton. Created when a service is deployed, revoked when the L2 above it is revoked. +Created by the security admin via the OpenKCM CMK UI. Revoked when the L2 above it is revoked. --- ## Deployment Scenarios -### Scenario 1 — SaaS Tenant on shared Platform Mesh +These scenarios map directly to the two deployment models defined in `cmk-platform-mesh-vision.md`. The self-selecting mechanism — where the customer enables OpenKCM from the marketplace at org level or account level — determines which scenario applies. + +### Scenario 1 — Enterprise / managed platform (Model 2: account-level enablement) -A customer organization (e.g. ACME Corp) runs workloads on a shared Platform Mesh installation operated by someone else. They are one of many tenants on the platform. +A customer organization (e.g. ACME Corp) runs workloads on a shared Platform Mesh installation operated by a platform provider. They are one of many tenants on the platform. Each account holder enables OpenKCM independently at account level and manages their own keys in isolation. - OpenKCM CMK Platform Mesh is the right product -- UI sits at **account level** — the tenant manages their own keys within their account -- Kill switch scope: the account — does not affect other tenants -- CMK Controller is shared platform infrastructure, but key governance is per-tenant +- CMK Controller scoped to that account — one L2 provisioned for that account +- Kill switch scope: that account only — does not affect other tenants +- Platform provider has no visibility into any account's key governance ``` Platform Mesh (shared installation) │ -├── Account: ACME Corp ← OpenKCM CMK UI here -│ └── Workspace → Namespaces → Services +├── Account: ACME Corp ← enables OpenKCM at account level, manages own keys +│ └── Workspace → L2 → Namespaces → L3 per service │ -├── Account: VW ← OpenKCM CMK UI here -│ └── Workspace → Namespaces → Services +├── Account: VW ← enables OpenKCM at account level, independently +│ └── Workspace → L2 → Namespaces → L3 per service │ -└── Account: Siemens ← OpenKCM CMK UI here - └── Workspace → Namespaces → Services +└── Account: Siemens ← enables OpenKCM at account level, independently + └── Workspace → L2 → Namespaces → L3 per service ``` --- -### Scenario 2 — Air-gapped / sovereign deployment +### Scenario 2 — Air-gapped / sovereign deployment (Model 1: org-level enablement) -An organization runs their own Platform Mesh installation in their own data center. They are both the platform operator and the only tenant. No shared platform, no other tenants. +An organization runs their own Platform Mesh installation. They are both the platform operator and the org owner. They enable OpenKCM at org level — the CMK Controller governs all accounts across the entire organization from one place. -- **OpenKCM CMK (standalone) is the right product** — not the Platform Mesh lightweight variant -- The lightweight UI is designed for tenant-level governance within a shared platform; at deployment/operator level it effectively becomes the full CMK feature set -- Standalone gives the operator full governance: own UI, multi-party approval, full audit trail, platform-level kill switch — without depending on a shared platform portal -- The operator manages keys for their entire installation, not just one account within it +- OpenKCM CMK Platform Mesh is the right product — org-level enablement +- CMK Controller at org level — provisions L2 for every account automatically +- Security admin has single pane of glass across all accounts +- Kill switch scope: entire organization — all accounts, all namespaces, all services +- No external platform provider in the loop ``` -Air-gapped deployment (single organization) +Air-gapped deployment (single organization owns and operates everything) │ -├── Platform Mesh (operator-owned) -│ └── Account: Operator Org -│ └── Workspace → Namespaces → Services +├── Org level: OpenKCM enabled here → CMK Controller governs all accounts │ -└── OpenKCM CMK (standalone) ← full product, own UI, platform-level governance +├── Account: prod → L2 auto-provisioned → security admin binds L1 → L3 per service +├── Account: dev → L2 auto-provisioned → security admin binds L1 → L3 per service +└── Account: staging → L2 auto-provisioned → security admin binds L1 → L3 per service ``` --- ## Open Questions -**1. SaaS Tenant — is the current UI scope sufficient?** -The current OpenKCM CMK Platform Mesh UI design sits at account level. For the SaaS Tenant scenario this is correct. But does Platform Mesh support account-level microfrontend registration today, or does the UI need to move there from namespace level first? - ---- - -**2. Air-gapped — standalone or extend the lightweight UI?** -The current direction is to use OpenKCM CMK (standalone) for air-gapped deployments rather than extending the lightweight UI one level up to platform level. The alternative — extending the lightweight UI to platform level — risks replicating the full CMK feature set inside the Platform Mesh portal, eliminating the "lightweight" distinction. - -> **Proposal:** Air-gapped / sovereign deployments use **OpenKCM CMK (standalone)**, not OpenKCM CMK Platform Mesh. The lightweight variant is explicitly scoped to the SaaS Tenant scenario. This keeps a clean product boundary and avoids feature creep in the Platform Mesh integration. - ---- - -**3. Platform-level kill switch in air-gapped deployments** -In an air-gapped deployment, who triggers the kill switch — the platform operator or a designated security admin? Is there a platform-level role in Platform Mesh that maps to this, or does the standalone CMK product own this entirely? - -> **Proposal:** In air-gapped deployments using OpenKCM CMK (standalone), the kill switch is owned entirely by the standalone product — no dependency on Platform Mesh roles. The designated security admin in the standalone UI triggers it, subject to multi-party approval. Platform Mesh roles are irrelevant in this scenario. +**1. Two APIExports — can one OpenKCM deployment serve both models?** +Can a single OpenKCM deployment publish two APIExports — one at org level and one at account level — so customers can choose their model at enablement time without deploying a separate instance? To be validated with the Platform Mesh team. --- -**4. Multi-party approval — SaaS Tenant** -For the SaaS Tenant scenario, does Platform Mesh provide a native four-eyes approval mechanism that OpenKCM CMK Platform Mesh can integrate with, or does the lightweight variant skip multi-party approval entirely and rely on the tenant's own processes? +**2. Multi-party approval — Platform Mesh integration** +Does Platform Mesh provide a native four-eyes approval mechanism that OpenKCM CMK Platform Mesh can integrate with, or does the lightweight variant rely on the tenant's own processes? --- -**5. L3 visibility scope** -Which L3 option (A, B, or C) applies to each deployment scenario? The air-gapped operator may have different requirements from a SaaS tenant. +**3. L3 visibility scope** +Which L3 option (A, B, or C) applies to each deployment scenario? -> **Proposal:** SaaS Tenant → Option B (L3 visible, not manageable) for initial release. Air-gapped / standalone → Option C (selective revocation) as a target feature, since sovereign operators are more likely to need granular service-level revocation. Option C remains an open architectural question pending resolution of who owns selective revocation — OpenKCM CMK or Krypton. \ No newline at end of file +> **Current direction:** Option B for initial release — L3 visible and manageable by the security admin in both scenarios. Option C (selective service-level revocation) is a future feature pending resolution of who owns selective revocation — OpenKCM CMK or Krypton. \ No newline at end of file From 1ddd3d86345fad5d9309678fe0dfbb762bb6ed95 Mon Sep 17 00:00:00 2001 From: isanmaz Date: Thu, 9 Jul 2026 13:14:09 +0200 Subject: [PATCH 4/6] docs: flag Model 1 as future-state pending Platform Mesh org-level API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Based on 2026-07-09 alignment meeting with Platform Mesh team. kcp does not track account-to-organization relationships as a structural primitive — the workspace tree is visual only. Model 1 (org-level OpenKCM) requires Platform Mesh to build an org-level provider API first. - Add platform dependency callout at top of both documents - Mark Model 1 as future-state / blocked throughout - Confirm Model 2 (account-level) as only currently deliverable model - Correct role separation section: Platform Mesh is not opinionated about authorization — OpenKCM defines its own role model via provider permissions - Update last_updated dates to 2026-07-09 --- product-vision/cmk-platform-mesh-vision.md | 58 +++++++++++++--------- product-vision/cmk-tenancy-model.md | 15 +++++- 2 files changed, 47 insertions(+), 26 deletions(-) diff --git a/product-vision/cmk-platform-mesh-vision.md b/product-vision/cmk-platform-mesh-vision.md index aef8ffc..3d819a7 100644 --- a/product-vision/cmk-platform-mesh-vision.md +++ b/product-vision/cmk-platform-mesh-vision.md @@ -1,18 +1,27 @@ --- status: Draft -last_updated: 2026-06-24 +last_updated: 2026-07-09 audience: Open Source Community, Contributors, Stakeholders --- # OpenKCM CMK — Platform Mesh +## Platform dependency — Model 1 not yet deliverable + +> **As of 2026-07-09 (confirmed with Platform Mesh team):** +> kcp does not track the relationship between accounts and organizations as a structural platform primitive. The workspace tree is a visual representation only — there is no org-level API that OpenKCM can build on for cross-account governance. +> +> **Model 1 (org-level OpenKCM) is blocked** until Platform Mesh builds an org-level provider API or dedicated virtual workspace. This document describes both models as target architecture. **Model 2 (account-level) is the only currently deliverable model.** + +--- + ## Overview OpenKCM CMK Platform Mesh is a lightweight CMK integration embedded in the Platform Mesh portal. Designed for Platform Mesh operators and tenants who need customer-managed encryption without running a separate CMK product. -OpenKCM is a **service provider** on Platform Mesh. It publishes its key management API through the Platform Mesh provider-consumer model. When an operator enables OpenKCM from the marketplace — at either org level or account level — an APIBinding is created and key lifecycle operations become available in that workspace without any direct access to the OpenKCM provider infrastructure. +OpenKCM is a **service provider** on Platform Mesh. It publishes its key management API through the Platform Mesh provider-consumer model. When an operator enables OpenKCM from the marketplace at account level — an APIBinding is created and key lifecycle operations become available in that workspace without any direct access to the OpenKCM provider infrastructure. -**Target deployment:** Platform Mesh — running as a Kubernetes controller, with placement at org level or account level depending on the chosen deployment model (see Deployment Models below). +**Target deployment:** Platform Mesh — running as a Kubernetes controller at account level (Model 2, current) or org level (Model 1, future — see platform dependency above). --- @@ -25,9 +34,9 @@ Platform Mesh is built on **kcp**, a Kubernetes control plane without container | **APIExport** | Provider publishes its service API | OpenKCM publishes the CMK API (key registration, binding, kill switch) from its provider workspace | | **APIBinding** | Consumer subscribes to a provider API | When an account enables OpenKCM from the marketplace, it creates an APIBinding — the CMK API appears in their workspace | | **Virtual workspaces** | Aggregated view of all bound consumer objects | The CMK Controller watches all consumer workspaces from one virtual endpoint — no per-workspace polling | -| **OpenFGA (ReBAC)** | Relationship-based authorization derived from org hierarchy | Role separation between security admin and developer is handled automatically — no custom role logic needed in OpenKCM | +| **OpenFGA (ReBAC)** | Relationship-based authorization within an account | OpenKCM defines its own role model via Platform Mesh provider permissions — Platform Mesh is not opinionated about authorization | -**Placement and governance scope:** Where OpenKCM is placed determines what it can govern. At org level, it has a single aggregated view across all accounts and workspaces — required for cross-workspace kill switch and single pane of glass L1 management (Model 1). At account level, it governs only that account's workspace — the account holder sees and controls only their own keys, and cross-account visibility is intentionally absent (Model 2). Both placements are valid; the customer chooses by where they enable OpenKCM from the marketplace. +**Placement and governance scope:** Where OpenKCM is placed determines what it can govern. At account level (Model 2 — current), it governs only that account's workspace — the account holder sees and controls only their own keys, and cross-account visibility is intentionally absent. At org level (Model 1 — future, platform dependency not yet met), it would have a single aggregated view across all accounts — required for cross-workspace kill switch and single pane of glass L1 management. Model 1 requires Platform Mesh to build an org-level provider API first. --- @@ -74,30 +83,31 @@ The tenant boundary is always the account/workspace. L2 is always one per accoun **The difference between the two models is how many L2s the CMK Controller governs** — and therefore how many accounts fall under a single security admin's key governance. -| | Model 1 (org level) | Model 2 (account level) | +| | Model 1 (org level) ⚠ future | Model 2 (account level) ✓ current | |---|---|---| | Controller scope | All accounts in the org | One account only | | L2s governed | N — one per account | 1 | | L1 → L2 bindings | N — one per account | 1 | | Kill switch scope | All accounts in the org | That account only | | Who operates OpenKCM | Customer (= platform provider = org owner) | Account holder independently | +| Platform dependency | Requires org-level provider API — not yet available in Platform Mesh | None — available today | -OpenKCM on Platform Mesh covers two deployment scenarios. The deployment model is **self-selecting** — it is determined by where the customer enables OpenKCM from the marketplace, not by a configuration flag or a separate product. This gives customers full flexibility to choose their own sovereignty model. +OpenKCM on Platform Mesh covers two deployment scenarios. **Model 2 is the currently deliverable model.** Model 1 is documented as target architecture pending Platform Mesh building an org-level provider primitive. -### How the self-selection works +### How the self-selection works (target state) -| Where OpenKCM is enabled | Deployment model | Who operates OpenKCM | +| Where OpenKCM is enabled | Deployment model | Status | |---|---|---| -| **Org level** | Air-gapped / sovereign | Customer (= platform provider = org owner) | -| **Account level** | Enterprise / managed platform | Account holder independently | +| **Account level** | Enterprise / managed platform | ✓ Deliverable today | +| **Org level** | Air-gapped / sovereign | ⚠ Blocked — requires Platform Mesh org-level provider API | -The customer makes this choice once at enablement time. Platform Mesh APIExport/APIBinding supports enablement at different levels of the hierarchy — OpenKCM publishes two APIExports, one at org level and one at account level. The customer binds to whichever fits their sovereignty requirement. - -> **Open question (for RFC meeting):** Can one OpenKCM deployment serve both models simultaneously via two APIExports — one at org level, one at account level? To be validated with the Platform Mesh team. +> **Open question (confirmed with Platform Mesh team 2026-07-09):** kcp does not expose an org-level structural primitive today. The workspace tree is visual only. Platform Mesh would need to build a dedicated org-level provider API or virtual workspace for Model 1 to be possible. Timeline unknown. --- -### Model 1 — Org level enablement (air-gapped / sovereign) +### Model 1 — Org level enablement (air-gapped / sovereign) ⚠ Future state + +> **Platform dependency not yet met.** This model requires an org-level provider API from Platform Mesh that does not exist today. Documented here as target architecture only. The customer enables OpenKCM from the marketplace at **org level**. OpenKCM operates across the entire organization. The org-level super admin has full cross-workspace visibility and control — single pane of glass, cross-workspace kill switch, full governance. The platform provider and the account holder are the same entity. @@ -116,7 +126,7 @@ CMK Controller at org level --- -### Model 2 — Account level enablement (enterprise / managed platform) +### Model 2 — Account level enablement (enterprise / managed platform) ✓ Current The customer enables OpenKCM from the marketplace at **account level**. OpenKCM operates within that account only. The account holder manages their own keys independently — the platform provider has zero visibility into that account's key governance. Different accounts can each enable their own OpenKCM instance independently. @@ -149,17 +159,17 @@ CMK Controller scoped to Account B ## Role separation — how authorization works -Platform Mesh uses **OpenFGA** (relationship-based access control) to derive permissions from the organizational hierarchy. OpenKCM does not need to build custom role logic — the platform handles it. +Platform Mesh is **not opinionated about authorization** — it delegates role definition to the provider via the provider permissions feature. OpenKCM defines its own role model using this feature. + +> **As of 2026-07-09:** OpenKCM's role model is an open product decision. The table below reflects the proposed roles — not yet confirmed. A role definition document is pending. The Platform Mesh authorization UI epic (ships this year) will allow the OpenKCM UI to show/hide actions based on role once the role model is finalized. -| Role | Scope | What they can do in OpenKCM | +| Role (proposed) | Scope | What they can do in OpenKCM | |---|---|---| -| Super Admin | Org level — air-gapped model | Full access — all accounts, all keys, cross-workspace kill switch | -| Platform Operator | Org level — enterprise model | Infrastructure health only — no key material, no key operations | -| Security Admin | Org level | Register L1 keys, bind L1→L2, trigger kill switch, view full key chain across all accounts | -| Workspace Admin | Workspace level | View key status for their workspace — no key management actions | -| Developer | Namespace level | Nothing — zero-touch encryption; no key visibility | +| L1 Key Administrator | Account level | Register L1 keys, bind L1→L2, trigger kill switch, view full key chain | +| Security Admin | Account level | Create L3 service keys, view key status | +| Developer / Member | Account level | Nothing — zero-touch encryption; no key visibility | -OpenFGA derives the permission boundary from the organizational relationship graph automatically. No per-user configuration needed in OpenKCM. +OpenKCM uses Platform Mesh provider permissions to enforce role boundaries. Custom role logic lives in OpenKCM, not in Platform Mesh. --- diff --git a/product-vision/cmk-tenancy-model.md b/product-vision/cmk-tenancy-model.md index 8e743b4..05f2153 100644 --- a/product-vision/cmk-tenancy-model.md +++ b/product-vision/cmk-tenancy-model.md @@ -1,11 +1,20 @@ --- status: Draft -last_updated: 2026-06-24 +last_updated: 2026-07-09 audience: Open Source Community, Contributors, Stakeholders --- # OpenKCM CMK Platform Mesh — Tenancy Model +## Platform dependency — Model 1 not yet deliverable + +> **As of 2026-07-09 (confirmed with Platform Mesh team):** +> kcp does not track the relationship between accounts and organizations as a structural platform primitive. The workspace tree is a visual representation only — there is no org-level API that a provider can build on for cross-account governance. +> +> **Model 1 (org-level OpenKCM) is blocked** until Platform Mesh builds an org-level provider API or dedicated virtual workspace. **Model 2 (account-level) is the only currently deliverable model.** The org-level scenarios in this document are target architecture, not current scope. + +--- + ## Overview This document defines the tenancy model for OpenKCM CMK Platform Mesh. It describes the entities, their relationships, and the key binding model that governs how customer-owned encryption keys are applied across a Platform Mesh deployment. @@ -240,7 +249,9 @@ Platform Mesh (shared installation) --- -### Scenario 2 — Air-gapped / sovereign deployment (Model 1: org-level enablement) +### Scenario 2 — Air-gapped / sovereign deployment (Model 1: org-level enablement) ⚠ Future state + +> **Platform dependency not yet met.** This scenario requires an org-level provider API from Platform Mesh that does not exist today. kcp's workspace tree is visual only — there is no structural org primitive OpenKCM can build on. Documented here as target architecture pending Platform Mesh building this capability. An organization runs their own Platform Mesh installation. They are both the platform operator and the org owner. They enable OpenKCM at org level — the CMK Controller governs all accounts across the entire organization from one place. From ffac5f64424f1347bdc1874965a4f56ac190bc78 Mon Sep 17 00:00:00 2001 From: isanmaz Date: Tue, 14 Jul 2026 09:22:44 +0200 Subject: [PATCH 5/6] docs: align product vision and tenancy model with 2026-07-09 Platform Mesh meeting decisions --- product-vision/cmk-platform-mesh-vision.md | 63 ++++++++++------------ product-vision/cmk-tenancy-model.md | 28 +++++----- 2 files changed, 41 insertions(+), 50 deletions(-) diff --git a/product-vision/cmk-platform-mesh-vision.md b/product-vision/cmk-platform-mesh-vision.md index 3d819a7..af523b3 100644 --- a/product-vision/cmk-platform-mesh-vision.md +++ b/product-vision/cmk-platform-mesh-vision.md @@ -1,6 +1,6 @@ --- status: Draft -last_updated: 2026-07-09 +last_updated: 2026-07-14 audience: Open Source Community, Contributors, Stakeholders --- @@ -42,12 +42,12 @@ Platform Mesh is built on **kcp**, a Kubernetes control plane without container ## Key capabilities -- L1 Root Key registration at org level — one registration covers all accounts and all their workspaces +- L1 Root Key registration at account level — the account holder registers their own L1 key and binds it to their L2 - BYOK and HYOK — customer key material never touches the platform; OpenBao is the priority backend -- Kill switch — one action revokes access across all accounts and all their workspaces in the organization +- Kill switch — one action revokes access to all namespaces and services within the account - Zero-touch encryption — workloads deployed from the marketplace are automatically encrypted without developer intervention - Audit trail — via Platform Mesh audit infrastructure -- Access control — via Platform Mesh OpenFGA (no custom role logic in OpenKCM) +- Access control — via Platform Mesh provider permissions (OpenKCM defines its own role model) - Lightweight embedded UI — microfrontend in the Platform Mesh portal via Luigi; no separate web interface --- @@ -56,9 +56,9 @@ Platform Mesh is built on **kcp**, a Kubernetes control plane without container | Level | Name | Provisioned by | Admin actions | |---|---|---|---| -| L1 | Root Key | Security admin (via OpenKCM UI at org level) | Register, rotate, revoke, kill switch | -| L2 | Domain Key | CMK Controller — automatic, one per account/workspace | View only — bind L1→L2 done by security admin at org level; cannot create or delete | -| L3 | Service Key | Security admin (via OpenKCM UI) | Create, view status — see open question below | +| L1 | Root Key | Key Admin (via OpenKCM UI at account level) | Register, bind to L2, trigger kill switch | +| L2 | Domain Key | CMK Controller — automatic, one per account/workspace | View only — cannot create or delete | +| L3 | Service Key | Account Encryption Admin (via OpenKCM UI, per namespace) | Create, view status | | L4 | Data Encryption Key | Consuming service (via Krypton Gateway KMIP) | Not visible to admin | ### How L2 is provisioned @@ -161,13 +161,15 @@ CMK Controller scoped to Account B Platform Mesh is **not opinionated about authorization** — it delegates role definition to the provider via the provider permissions feature. OpenKCM defines its own role model using this feature. -> **As of 2026-07-09:** OpenKCM's role model is an open product decision. The table below reflects the proposed roles — not yet confirmed. A role definition document is pending. The Platform Mesh authorization UI epic (ships this year) will allow the OpenKCM UI to show/hide actions based on role once the role model is finalized. +> **As of 2026-07-09 (confirmed with Platform Mesh team):** OpenKCM uses provider permissions to define custom roles. The Platform Mesh authorization UI epic (ships this year) will allow the OpenKCM UI to show/hide actions based on role once it ships. Until then: implement functionality fully, apply role enforcement to UI once the epic ships. -| Role (proposed) | Scope | What they can do in OpenKCM | +All roles are scoped to **account level**. There are no cross-account roles. + +| Role | Scope | What they can do | |---|---|---| -| L1 Key Administrator | Account level | Register L1 keys, bind L1→L2, trigger kill switch, view full key chain | -| Security Admin | Account level | Create L3 service keys, view key status | -| Developer / Member | Account level | Nothing — zero-touch encryption; no key visibility | +| Key Admin | Account | Registers L1 key, binds L1→L2, triggers kill switch, sees full key hierarchy (L1, L2, all namespaces, all L3 keys) | +| Account Encryption Admin | Namespace | Manages L3 service key for their namespace only — no visibility into other namespaces, L1, or L2 | +| Developer | Namespace (application only) | Deploys services — zero-touch encryption, no key visibility at any level | OpenKCM uses Platform Mesh provider permissions to enforce role boundaries. Custom role logic lives in OpenKCM, not in Platform Mesh. @@ -176,20 +178,18 @@ OpenKCM uses Platform Mesh provider permissions to enforce role boundaries. Cust ## Platform Mesh account model ``` -Organization (e.g. ACME Corp) ← OpenKCM lives here (org level) +Account (e.g. ACME Corp) ← OpenKCM scoped here (account level) │ - ├── CMK Controller ← org level, watches all account workspaces + ├── CMK Controller ← account level, watches this account's workspace │ - └── Account: acme-prod ← workspace, APIBinding to OpenKCM here + └── Workspace: acme-prod ← one L2 Domain Key auto-provisioned here │ ├── Namespace: default → Application workloads - ├── Namespace: db-a → Database A - └── Namespace: db-b → Database B + ├── Namespace: db-a → Database A (L3 key, managed by Encryption Admin for db-a) + └── Namespace: db-b → Database B (L3 key, managed by Encryption Admin for db-b) ``` -One organization has one or more accounts. Each account maps to a kcp workspace. The CMK Controller provisions one L2 domain key per account workspace automatically. The security admin registers one or more L1 keys at org level and binds each L1 key to the relevant account workspaces. - -One L1 key can be bound to multiple workspaces. Different workspaces can be bound to different L1 keys. Pressing the kill switch at org level locks everything — all workspaces, all namespaces, all workloads, regardless of which L1 key they are bound to. +One account has one workspace. The CMK Controller provisions one L2 domain key per account workspace automatically. The Key Admin registers an L1 key at account level and binds it to the account's L2 key. Account Encryption Admins create L3 service keys for each service within their namespace. Different namespaces are governed by different Account Encryption Admins — no cross-namespace visibility. --- @@ -301,8 +301,8 @@ Example: revoke MongoDB only → MongoDB data inaccessible, Postgres and Redis u | Action | Scope | Effect | |---|---|---| -| Revoke L1 Root Key | All workspaces bound to that L1 | All services in those workspaces become inaccessible | -| Kill switch (org level) | Entire organization | All workspaces, all namespaces, all services inaccessible — regardless of which L1 they are bound to | +| Revoke L1 Root Key | That account | All namespaces and services in the account become inaccessible | +| Kill switch (account level) | That account | All namespaces, all services inaccessible — cascades through L2 → L3 → L4 automatically | --- @@ -324,22 +324,17 @@ The CMK Controller connects to Platform Mesh via outbound HTTPS to kcp — no in Platform Mesh │ ├── kcp (control plane) -│ ├── Organization workspace: root:acme ← OpenKCM lives here -│ │ └── OpenKCM APIBinding → CMK API available to all accounts -│ └── Virtual workspace: aggregated view of all bound account objects +│ ├── Account workspace: acme-prod ← OpenKCM enabled here at account level +│ │ └── OpenKCM APIBinding → CMK API available in this workspace +│ └── Virtual workspace: aggregated view of this account's bound objects │ -├── OpenKCM provider cluster (org level) -│ ├── CMK Controller ← watches virtual workspace, provisions L2, manages lifecycle +├── OpenKCM provider cluster (account level) +│ ├── CMK Controller ← watches this account's workspace, provisions L2, manages lifecycle │ ├── CMK UI (microfrontend via Luigi, embedded in Platform Mesh portal) │ └── OpenBao binding ← provider-to-provider, key material stays in customer keystore │ -├── Account workspace: acme-prod -│ ├── L2 Domain Key CR ← auto-provisioned by CMK Controller -│ ├── L3 Service Key CRs ← created by security admin via OpenKCM UI -│ └── Workload namespaces → KMIP endpoint + key ID injected into pods at deploy time -│ -└── Account workspace: acme-dev +└── Account workspace: acme-prod ├── L2 Domain Key CR ← auto-provisioned by CMK Controller - ├── L3 Service Key CRs ← created by security admin via OpenKCM UI + ├── L3 Service Key CRs ← created by Account Encryption Admin via OpenKCM UI per namespace └── Workload namespaces → KMIP endpoint + key ID injected into pods at deploy time ``` diff --git a/product-vision/cmk-tenancy-model.md b/product-vision/cmk-tenancy-model.md index 05f2153..4ceb450 100644 --- a/product-vision/cmk-tenancy-model.md +++ b/product-vision/cmk-tenancy-model.md @@ -1,6 +1,6 @@ --- status: Draft -last_updated: 2026-07-09 +last_updated: 2026-07-14 audience: Open Source Community, Contributors, Stakeholders --- @@ -68,7 +68,7 @@ This document defines the tenancy model for OpenKCM CMK Platform Mesh. It descri | L1 Root Key | +----------------------+ | L1KeyID | -| OrgID / AccountID | ← org level (Model 1) or account level (Model 2) +| AccountID | ← account level (Model 2, current); org level future state only | Name | | Status | | KeystoreType | ← OpenBao, AWS KMS, Azure KV, HSM... @@ -120,7 +120,7 @@ This document defines the tenancy model for OpenKCM CMK Platform Mesh. It descri | Security Admin | +------------------+ | UserID | -| OrgID / AccountID| ← org level (Model 1) or account level (Model 2) +| AccountID | ← account level (Model 2, current) | Role | +------------------+ | @@ -138,10 +138,10 @@ This document defines the tenancy model for OpenKCM CMK Platform Mesh. It descri The top-level administrative boundary. Represents one customer organization. One account has exactly one workspace. The account is the tenant — pressing the kill switch at account level locks the entire account. ### Security Admin -A user responsible for registering L1 root keys, binding them to L2 domain keys, creating L3 service keys, and triggering the kill switch. In Model 1 (org-level enablement), the security admin operates at org level and has visibility across all accounts. In Model 2 (account-level enablement), the security admin operates within their own account only. +A user responsible for registering L1 root keys, binding them to L2 domain keys, creating L3 service keys, and triggering the kill switch. In Model 2 (account-level enablement — the current model), the security admin operates within their own account only. In Model 1 (org-level — future state, platform dependency not yet met), the security admin would operate at org level with visibility across all accounts. ### CMK Controller -A Kubernetes controller that watches OpenKCM CRDs and reconciles key state. In Model 1, it runs at org level and governs all accounts in the organization. In Model 2, it is scoped to a single account. One controller per OpenKCM deployment. +A Kubernetes controller that watches OpenKCM CRDs and reconciles key state. In Model 2 (current), it is scoped to a single account. In Model 1 (future state), it would run at org level and govern all accounts in the organization. One controller per OpenKCM deployment. ### Workspace The deployment environment within an account. One account has one workspace. Contains multiple namespaces where applications and services run. @@ -150,7 +150,7 @@ The deployment environment within an account. One account has one workspace. Con A Kubernetes namespace within the workspace. Applications and services run here. Namespace-level encryption separation is achieved through L3 Service Keys — one per service — all wrapped under the account's single L2 Domain Key. ### L1 Root Key -A customer-owned root encryption key. Registered by the security admin at org level (Model 1) or account level (Model 2). Key material never leaves the customer's external keystore — OpenKCM CMK holds only a reference. One L1 key can be bound to multiple accounts (Model 1). Each L1 key is backed by one external keystore. +A customer-owned root encryption key. Registered by the Key Admin at account level (Model 2 — current). Key material never leaves the customer's external keystore — OpenKCM CMK holds only a reference. Each L1 key is backed by one external keystore. ### External Keystore The customer's own key management system where L1 key material lives. Supported backends: OpenBao, AWS KMS, Azure Key Vault, GCP KMS, HSM via PKCS#11. OpenKCM CMK never stores key material — it holds a pointer and calls the keystore at runtime via Krypton. @@ -174,13 +174,12 @@ An application or workload running inside a namespace (e.g. MongoDB, Postgres, R | Rule | Description | |---|---| | One L2 per account | CMK Controller provisions exactly one L2 Domain Key per account/workspace via Krypton API | -| Admin registers L1 | The security admin registers one or more L1 keys at org level (Model 1) or account level (Model 2) | -| Admin binds L1 → L2 | The security admin decides which L1 key governs which account | +| Admin registers L1 | The Key Admin registers an L1 key at account level | +| Admin binds L1 → L2 | The Key Admin binds the L1 key to the account's L2 key | | One L1 per L2 | Each L2 Domain Key is bound to exactly one L1 Root Key at a time | -| One L1 → many L2s | One L1 Root Key can be bound to multiple accounts (Model 1) | | Different L1s per account | Different accounts can be governed by different L1 keys | -| Admin creates L3 | The security admin creates one L3 Service Key per service via the OpenKCM CMK UI | -| Unbound account | An account with no L1 binding is not customer-governed — it uses platform-managed encryption until the admin binds an L1 key | +| Admin creates L3 | The Account Encryption Admin creates one L3 Service Key per service via the OpenKCM CMK UI, scoped to their namespace | +| Unbound account | An account with no L1 binding is not customer-governed — it uses platform-managed encryption until the Key Admin binds an L1 key | --- @@ -188,11 +187,8 @@ An application or workload running inside a namespace (e.g. MongoDB, Postgres, R | Action | Scope | Effect | |---|---|---| -| Revoke L1 Root Key | All accounts bound to that L1 | All services in those accounts become inaccessible | -| Kill switch — Model 1 (org level) | Entire organization | All accounts, all namespaces, all services inaccessible — regardless of which L1 they are bound to | -| Kill switch — Model 2 (account level) | That account only | All namespaces and services in that account become inaccessible | - -In Model 1, if different accounts are bound to different L1 keys, revoking one L1 affects only the accounts bound to it. The org-level kill switch revokes everything across all accounts. +| Revoke L1 Root Key | That account | All namespaces and services in the account become inaccessible | +| Kill switch (account level) | That account | All namespaces, all services inaccessible — cascades through L2 → L3 → L4 automatically | --- From b067f42149f8518df6a84dd0694f68332343bd2f Mon Sep 17 00:00:00 2001 From: isanmaz Date: Tue, 14 Jul 2026 09:32:34 +0200 Subject: [PATCH 6/6] =?UTF-8?q?docs:=20scope=20product=20vision=20to=20Ope?= =?UTF-8?q?nKCM=20core=20=E2=80=94=20remove=20deployment-specific=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- product-vision/cmk-platform-mesh-vision.md | 340 --------------------- product-vision/cmk-tenancy-model.md | 287 ----------------- 2 files changed, 627 deletions(-) delete mode 100644 product-vision/cmk-platform-mesh-vision.md delete mode 100644 product-vision/cmk-tenancy-model.md diff --git a/product-vision/cmk-platform-mesh-vision.md b/product-vision/cmk-platform-mesh-vision.md deleted file mode 100644 index af523b3..0000000 --- a/product-vision/cmk-platform-mesh-vision.md +++ /dev/null @@ -1,340 +0,0 @@ ---- -status: Draft -last_updated: 2026-07-14 -audience: Open Source Community, Contributors, Stakeholders ---- - -# OpenKCM CMK — Platform Mesh - -## Platform dependency — Model 1 not yet deliverable - -> **As of 2026-07-09 (confirmed with Platform Mesh team):** -> kcp does not track the relationship between accounts and organizations as a structural platform primitive. The workspace tree is a visual representation only — there is no org-level API that OpenKCM can build on for cross-account governance. -> -> **Model 1 (org-level OpenKCM) is blocked** until Platform Mesh builds an org-level provider API or dedicated virtual workspace. This document describes both models as target architecture. **Model 2 (account-level) is the only currently deliverable model.** - ---- - -## Overview - -OpenKCM CMK Platform Mesh is a lightweight CMK integration embedded in the Platform Mesh portal. Designed for Platform Mesh operators and tenants who need customer-managed encryption without running a separate CMK product. - -OpenKCM is a **service provider** on Platform Mesh. It publishes its key management API through the Platform Mesh provider-consumer model. When an operator enables OpenKCM from the marketplace at account level — an APIBinding is created and key lifecycle operations become available in that workspace without any direct access to the OpenKCM provider infrastructure. - -**Target deployment:** Platform Mesh — running as a Kubernetes controller at account level (Model 2, current) or org level (Model 1, future — see platform dependency above). - ---- - -## Platform Mesh architecture — what OpenKCM builds on - -Platform Mesh is built on **kcp**, a Kubernetes control plane without container scheduling. Every account maps to an isolated kcp workspace. OpenKCM integrates with four platform primitives: - -| Primitive | What it does | How OpenKCM uses it | -|---|---|---| -| **APIExport** | Provider publishes its service API | OpenKCM publishes the CMK API (key registration, binding, kill switch) from its provider workspace | -| **APIBinding** | Consumer subscribes to a provider API | When an account enables OpenKCM from the marketplace, it creates an APIBinding — the CMK API appears in their workspace | -| **Virtual workspaces** | Aggregated view of all bound consumer objects | The CMK Controller watches all consumer workspaces from one virtual endpoint — no per-workspace polling | -| **OpenFGA (ReBAC)** | Relationship-based authorization within an account | OpenKCM defines its own role model via Platform Mesh provider permissions — Platform Mesh is not opinionated about authorization | - -**Placement and governance scope:** Where OpenKCM is placed determines what it can govern. At account level (Model 2 — current), it governs only that account's workspace — the account holder sees and controls only their own keys, and cross-account visibility is intentionally absent. At org level (Model 1 — future, platform dependency not yet met), it would have a single aggregated view across all accounts — required for cross-workspace kill switch and single pane of glass L1 management. Model 1 requires Platform Mesh to build an org-level provider API first. - ---- - -## Key capabilities - -- L1 Root Key registration at account level — the account holder registers their own L1 key and binds it to their L2 -- BYOK and HYOK — customer key material never touches the platform; OpenBao is the priority backend -- Kill switch — one action revokes access to all namespaces and services within the account -- Zero-touch encryption — workloads deployed from the marketplace are automatically encrypted without developer intervention -- Audit trail — via Platform Mesh audit infrastructure -- Access control — via Platform Mesh provider permissions (OpenKCM defines its own role model) -- Lightweight embedded UI — microfrontend in the Platform Mesh portal via Luigi; no separate web interface - ---- - -## Key hierarchy - -| Level | Name | Provisioned by | Admin actions | -|---|---|---|---| -| L1 | Root Key | Key Admin (via OpenKCM UI at account level) | Register, bind to L2, trigger kill switch | -| L2 | Domain Key | CMK Controller — automatic, one per account/workspace | View only — cannot create or delete | -| L3 | Service Key | Account Encryption Admin (via OpenKCM UI, per namespace) | Create, view status | -| L4 | Data Encryption Key | Consuming service (via Krypton Gateway KMIP) | Not visible to admin | - -### How L2 is provisioned - -L2 provisioning is triggered by an APIBinding being created in an account's workspace. The CMK Controller — watching all consumer workspaces via the virtual workspace endpoint — detects the new binding and calls the Krypton gRPC API to provision one L2 domain key for that account. One account = one L2. L2 is not provisioned per namespace — it is provisioned once at account level and covers all namespaces within that account. - -**Model 1 (org-level enablement):** OpenKCM enabled at org level → CMK Controller provisions one L2 for every existing account in the org. Every new account created afterwards gets an L2 automatically. - -**Model 2 (account-level enablement):** Each account enables OpenKCM independently → CMK Controller scoped to that account provisions one L2 for that account only. - -The security admin does not create L2 keys — they only bind an L1 key to the existing L2. An unbound account is not customer-governed — it uses platform-managed encryption until the admin binds an L1 key. - -### How L4 is handled - -L4 (Data Encryption Keys) are managed entirely by consuming services (e.g. MongoDB, PostgreSQL) via the Krypton Gateway KMIP interface. Platform Mesh injects the KMIP endpoint and the relevant key ID into workload pods as environment variables or Kubernetes Secrets at deploy time — this is what makes encryption zero-touch for developers. L4 is not visible in the admin UI. The kill switch at L1 cascades automatically through L2, L3, and L4 — the admin does not need to act at L4 level. - ---- - -## Deployment models - -The tenant boundary is always the account/workspace. L2 is always one per account. These two facts are constant across both deployment models. - -**The difference between the two models is how many L2s the CMK Controller governs** — and therefore how many accounts fall under a single security admin's key governance. - -| | Model 1 (org level) ⚠ future | Model 2 (account level) ✓ current | -|---|---|---| -| Controller scope | All accounts in the org | One account only | -| L2s governed | N — one per account | 1 | -| L1 → L2 bindings | N — one per account | 1 | -| Kill switch scope | All accounts in the org | That account only | -| Who operates OpenKCM | Customer (= platform provider = org owner) | Account holder independently | -| Platform dependency | Requires org-level provider API — not yet available in Platform Mesh | None — available today | - -OpenKCM on Platform Mesh covers two deployment scenarios. **Model 2 is the currently deliverable model.** Model 1 is documented as target architecture pending Platform Mesh building an org-level provider primitive. - -### How the self-selection works (target state) - -| Where OpenKCM is enabled | Deployment model | Status | -|---|---|---| -| **Account level** | Enterprise / managed platform | ✓ Deliverable today | -| **Org level** | Air-gapped / sovereign | ⚠ Blocked — requires Platform Mesh org-level provider API | - -> **Open question (confirmed with Platform Mesh team 2026-07-09):** kcp does not expose an org-level structural primitive today. The workspace tree is visual only. Platform Mesh would need to build a dedicated org-level provider API or virtual workspace for Model 1 to be possible. Timeline unknown. - ---- - -### Model 1 — Org level enablement (air-gapped / sovereign) ⚠ Future state - -> **Platform dependency not yet met.** This model requires an org-level provider API from Platform Mesh that does not exist today. Documented here as target architecture only. - -The customer enables OpenKCM from the marketplace at **org level**. OpenKCM operates across the entire organization. The org-level super admin has full cross-workspace visibility and control — single pane of glass, cross-workspace kill switch, full governance. The platform provider and the account holder are the same entity. - -``` -Customer enables OpenKCM at org level - │ - ▼ -CMK Controller at org level -└── Provisions L2 automatically for every account in the org -└── Provisions L2 for every new account created afterwards -└── Super admin sees all accounts, all keys, full kill switch -└── No external party in the loop -``` - -**L2 provisioning trigger:** OpenKCM enabled at org level → CMK Controller provisions one L2 for every existing account. New account created → L2 provisioned automatically. - ---- - -### Model 2 — Account level enablement (enterprise / managed platform) ✓ Current - -The customer enables OpenKCM from the marketplace at **account level**. OpenKCM operates within that account only. The account holder manages their own keys independently — the platform provider has zero visibility into that account's key governance. Different accounts can each enable their own OpenKCM instance independently. - -``` -Account Holder A enables OpenKCM at account level - │ - ▼ -CMK Controller scoped to Account A -└── Provisions L2 for Account A only -└── Account Holder A sees only their own keys -└── Platform provider has no visibility into Account A's key governance - -Account Holder B enables OpenKCM at account level (independently) - │ - ▼ -CMK Controller scoped to Account B -└── Provisions L2 for Account B only -└── Completely isolated from Account A -``` - -**L2 provisioning trigger:** Account enables OpenKCM → CMK Controller provisions one L2 for that account. - -**The sovereignty guarantee:** the platform provider operates the infrastructure but is completely outside the key governance boundary. Each account holder owns and operates their own OpenKCM instance. - ---- - -**The critical boundary in Model 2:** even though the platform provider operates Platform Mesh, they cannot see key material, key bindings, or trigger key operations for any account that has enabled OpenKCM at account level. OpenFGA enforces this — account-level enablement means the account holder owns the OpenKCM workspace, not the platform provider. - ---- - -## Role separation — how authorization works - -Platform Mesh is **not opinionated about authorization** — it delegates role definition to the provider via the provider permissions feature. OpenKCM defines its own role model using this feature. - -> **As of 2026-07-09 (confirmed with Platform Mesh team):** OpenKCM uses provider permissions to define custom roles. The Platform Mesh authorization UI epic (ships this year) will allow the OpenKCM UI to show/hide actions based on role once it ships. Until then: implement functionality fully, apply role enforcement to UI once the epic ships. - -All roles are scoped to **account level**. There are no cross-account roles. - -| Role | Scope | What they can do | -|---|---|---| -| Key Admin | Account | Registers L1 key, binds L1→L2, triggers kill switch, sees full key hierarchy (L1, L2, all namespaces, all L3 keys) | -| Account Encryption Admin | Namespace | Manages L3 service key for their namespace only — no visibility into other namespaces, L1, or L2 | -| Developer | Namespace (application only) | Deploys services — zero-touch encryption, no key visibility at any level | - -OpenKCM uses Platform Mesh provider permissions to enforce role boundaries. Custom role logic lives in OpenKCM, not in Platform Mesh. - ---- - -## Platform Mesh account model - -``` -Account (e.g. ACME Corp) ← OpenKCM scoped here (account level) - │ - ├── CMK Controller ← account level, watches this account's workspace - │ - └── Workspace: acme-prod ← one L2 Domain Key auto-provisioned here - │ - ├── Namespace: default → Application workloads - ├── Namespace: db-a → Database A (L3 key, managed by Encryption Admin for db-a) - └── Namespace: db-b → Database B (L3 key, managed by Encryption Admin for db-b) -``` - -One account has one workspace. The CMK Controller provisions one L2 domain key per account workspace automatically. The Key Admin registers an L1 key at account level and binds it to the account's L2 key. Account Encryption Admins create L3 service keys for each service within their namespace. Different namespaces are governed by different Account Encryption Admins — no cross-namespace visibility. - ---- - -## OpenBao — provider-to-provider integration - -OpenKCM does not connect to OpenBao directly as an external dependency. On Platform Mesh, OpenBao is itself a **service provider** — it publishes its API through the same APIExport/APIBinding model. OpenKCM is a **composing provider** — it binds to OpenBao's API to store key material, then exposes the CMK API to end consumers. - -The security admin never touches OpenBao directly. They register their L1 key in the OpenKCM UI — OpenKCM resolves the OpenBao binding underneath. This is the HYOK guarantee: key material stays in OpenBao (customer-controlled), OpenKCM holds only the reference. - ---- - -## What the security admin sees - -The security admin operates from the OpenKCM CMK UI — a microfrontend embedded in the Platform Mesh portal. In Model 1 (org-level enablement), they see the full key chain for the entire organization in one place. In Model 2 (account-level enablement), each account's security admin sees only their own account's key chain. - -On enabling OpenKCM from the Platform Mesh marketplace, the CMK Controller automatically provisions L2 domain keys for all relevant account workspaces. These L2 keys appear in the UI immediately. The admin then registers their L1 root key and binds it to each account's L2 key. They also create L3 service keys for each service that needs to be encrypted under that account's L2. - -Actions are only available where the admin has authority — CMK Controller-provisioned L2 keys are visible but cannot be created or deleted by the admin. - ---- - -## What developers see - -Nothing. Zero-touch encryption means workloads come up encrypted without any key configuration on the developer's part. The developer deploys to a namespace — Platform Mesh injects the KMIP endpoint and key ID into the pod at deploy time. Encryption is handled automatically once the security admin has bound an L1 key to that workspace. - ---- - -## L3 Service Key visibility — open question - -L3 keys are service-level keys, one per service (e.g. MongoDB, PostgreSQL), created by the security admin via the OpenKCM UI and wrapped under the L2 of that account. Three options are under consideration for how L3 is surfaced in the UI: - -- **Option A — L3 fully internal, never shown.** The security admin creates L3 keys via the UI but they are not displayed after creation. The kill switch at L1 cascades down through L2 and L3 automatically. Simplest model. - -- **Option B — L3 visible and manageable.** The org-level UI shows a breakdown: account → services → each with their L3 key status. The security admin creates and views L3 keys. Useful for verifying that each service is actually encrypted. - -- **Option C — L3 with selective revocation.** In addition to Option B, the kill switch can be triggered at L3 level — revoke only a specific service, not the entire account. Open architectural question: who owns selective service revocation — OpenKCM CMK Platform Mesh or Krypton? - -> **Current direction:** Option B for the initial release — L3 visible and manageable by the security admin. Option C is a future feature pending resolution of the selective revocation ownership question. - -### Option A — L3 fully internal - -``` -Organization: ACME Corp -└── OpenKCM CMK (org level) - │ - ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages - │ - ├── Account Workspace: acme-prod - │ └── L2 Domain Key: acme-prod-domain [Bound] ← admin binds L1→L2 - │ - └── Account Workspace: acme-dev - └── L2 Domain Key: acme-dev-domain [Bound] - -L3 and L4 keys exist but are never shown in the UI. -Kill switch: L1 revoked → L2 revoked → L3 revoked → all workloads inaccessible. -``` - -### Option B — L3 visible and manageable - -``` -Organization: ACME Corp -└── OpenKCM CMK (org level) - │ - ├── L1 Root Key: openbao/acme-l1-master [Active] ← admin registers + manages - │ - ├── Account Workspace: acme-prod - │ ├── L2 Domain Key: acme-prod-domain [Bound] ← admin binds L1→L2 - │ └── Services: - │ ├── mongodb → L3: acme-prod-mongodb-key [Active] ← admin creates - │ └── postgres → L3: acme-prod-postgres-key [Active] ← admin creates - │ - └── Account Workspace: acme-dev - ├── L2 Domain Key: acme-dev-domain [Bound] - └── Services: - └── redis → L3: acme-dev-redis-key [Active] ← admin creates - -Admin can see and create L3 keys. No delete or revoke actions at L3 level. -Kill switch at L1 still cascades automatically across all L2 and L3. -``` - -### Option C — L3 with selective revocation (future / open question) - -``` -Organization: ACME Corp -└── OpenKCM CMK (org level) - │ - ├── L1 Root Key: openbao/acme-l1-master [Active] - │ - ├── Account Workspace: acme-prod - │ ├── L2 Domain Key: acme-prod-domain [Bound] - │ └── Services: - │ ├── mongodb → L3: acme-prod-mongodb-key [Active] [Revoke] - │ └── postgres → L3: acme-prod-postgres-key [Active] [Revoke] - │ - └── Account Workspace: acme-dev - ├── L2 Domain Key: acme-dev-domain [Bound] - └── Services: - └── redis → L3: acme-dev-redis-key [Active] [Revoke] - -Admin can revoke individual service keys without triggering the full kill switch. -Example: revoke MongoDB only → MongoDB data inaccessible, Postgres and Redis unaffected. - -⚠ Open question: who owns selective revocation — OpenKCM CMK Platform Mesh or Krypton? -``` - ---- - -## Kill switch scope - -| Action | Scope | Effect | -|---|---|---| -| Revoke L1 Root Key | That account | All namespaces and services in the account become inaccessible | -| Kill switch (account level) | That account | All namespaces, all services inaccessible — cascades through L2 → L3 → L4 automatically | - ---- - -## Integration path — how OpenKCM connects to Platform Mesh - -OpenKCM uses the **multicluster-runtime** integration path. The CMK Controller is a custom controller with its own reconciliation logic — not a passive sync agent. This is required because: - -- Kill switch propagation is cross-workspace and must cascade through L2 → L3 → L4 in a controlled sequence -- L2 provisioning requires calling the Krypton gRPC API, not just syncing CRD state -- Authorization decisions (which admin can act on which workspace) require custom logic on top of OpenFGA - -The CMK Controller connects to Platform Mesh via outbound HTTPS to kcp — no inbound access to the OpenKCM provider cluster is required. - ---- - -## Deployment scenario - -``` -Platform Mesh -│ -├── kcp (control plane) -│ ├── Account workspace: acme-prod ← OpenKCM enabled here at account level -│ │ └── OpenKCM APIBinding → CMK API available in this workspace -│ └── Virtual workspace: aggregated view of this account's bound objects -│ -├── OpenKCM provider cluster (account level) -│ ├── CMK Controller ← watches this account's workspace, provisions L2, manages lifecycle -│ ├── CMK UI (microfrontend via Luigi, embedded in Platform Mesh portal) -│ └── OpenBao binding ← provider-to-provider, key material stays in customer keystore -│ -└── Account workspace: acme-prod - ├── L2 Domain Key CR ← auto-provisioned by CMK Controller - ├── L3 Service Key CRs ← created by Account Encryption Admin via OpenKCM UI per namespace - └── Workload namespaces → KMIP endpoint + key ID injected into pods at deploy time -``` diff --git a/product-vision/cmk-tenancy-model.md b/product-vision/cmk-tenancy-model.md deleted file mode 100644 index 4ceb450..0000000 --- a/product-vision/cmk-tenancy-model.md +++ /dev/null @@ -1,287 +0,0 @@ ---- -status: Draft -last_updated: 2026-07-14 -audience: Open Source Community, Contributors, Stakeholders ---- - -# OpenKCM CMK Platform Mesh — Tenancy Model - -## Platform dependency — Model 1 not yet deliverable - -> **As of 2026-07-09 (confirmed with Platform Mesh team):** -> kcp does not track the relationship between accounts and organizations as a structural platform primitive. The workspace tree is a visual representation only — there is no org-level API that a provider can build on for cross-account governance. -> -> **Model 1 (org-level OpenKCM) is blocked** until Platform Mesh builds an org-level provider API or dedicated virtual workspace. **Model 2 (account-level) is the only currently deliverable model.** The org-level scenarios in this document are target architecture, not current scope. - ---- - -## Overview - -This document defines the tenancy model for OpenKCM CMK Platform Mesh. It describes the entities, their relationships, and the key binding model that governs how customer-owned encryption keys are applied across a Platform Mesh deployment. - ---- - -## Entity Relationship Model - -``` -+------------------+ -| Account | -+------------------+ -| AccountID | -| Name | -| Status | -+------------------+ - | 1 - | - | 1 -+------------------+ -| Workspace | -+------------------+ -| WorkspaceID | -| AccountID | -| Status | -+------------------+ - | 1 - | - | N -+------------------+ -| Namespace | -+------------------+ -| NamespaceID | -| WorkspaceID | -| Name | -| Status | -+------------------+ - -+----------------------+ -| L2 Domain Key | -+----------------------+ -| L2KeyID | -| WorkspaceID | ← one per account/workspace, not per namespace -| Status | -| ProvisionedBy | ← CMK Controller (automatic, via Krypton API) -+----------------------+ - | 1 - | - | 1 (key binding — admin assigns) -+----------------------+ -| L1 Root Key | -+----------------------+ -| L1KeyID | -| AccountID | ← account level (Model 2, current); org level future state only -| Name | -| Status | -| KeystoreType | ← OpenBao, AWS KMS, Azure KV, HSM... -| KeystoreRef | ← reference only, no key material stored -| RegisteredBy | ← Security Admin -+----------------------+ - | 1 - | - | N -+----------------------+ -| External Keystore | -+----------------------+ -| KeystoreID | -| Type | -| URL | -| Status | -+----------------------+ - - -+------------------+ +------------------+ -| Namespace | | L2 Domain Key | -+------------------+ +------------------+ - | 1 | 1 - | | - | N | N -+------------------+ +------------------+ -| Service | | Key Binding | -+------------------+ +------------------+ -| ServiceID | | BindingID | -| NamespaceID | | L2KeyID | -| Name | | L1KeyID | -| Status | | BoundBy | ← Security Admin -+------------------+ | BoundAt | - | 1 +------------------+ - | - | 1 -+------------------+ -| L3 Service Key | -+------------------+ -| L3KeyID | -| ServiceID | -| L2KeyID | -| Status | -| CreatedBy | ← Security Admin (via OpenKCM CMK UI) -+------------------+ - - -+------------------+ -| Security Admin | -+------------------+ -| UserID | -| AccountID | ← account level (Model 2, current) -| Role | -+------------------+ - | - | registers L1 keys - | binds L1 → L2 - | creates L3 keys - | triggers kill switch -``` - ---- - -## Entities - -### Account -The top-level administrative boundary. Represents one customer organization. One account has exactly one workspace. The account is the tenant — pressing the kill switch at account level locks the entire account. - -### Security Admin -A user responsible for registering L1 root keys, binding them to L2 domain keys, creating L3 service keys, and triggering the kill switch. In Model 2 (account-level enablement — the current model), the security admin operates within their own account only. In Model 1 (org-level — future state, platform dependency not yet met), the security admin would operate at org level with visibility across all accounts. - -### CMK Controller -A Kubernetes controller that watches OpenKCM CRDs and reconciles key state. In Model 2 (current), it is scoped to a single account. In Model 1 (future state), it would run at org level and govern all accounts in the organization. One controller per OpenKCM deployment. - -### Workspace -The deployment environment within an account. One account has one workspace. Contains multiple namespaces where applications and services run. - -### Namespace -A Kubernetes namespace within the workspace. Applications and services run here. Namespace-level encryption separation is achieved through L3 Service Keys — one per service — all wrapped under the account's single L2 Domain Key. - -### L1 Root Key -A customer-owned root encryption key. Registered by the Key Admin at account level (Model 2 — current). Key material never leaves the customer's external keystore — OpenKCM CMK holds only a reference. Each L1 key is backed by one external keystore. - -### External Keystore -The customer's own key management system where L1 key material lives. Supported backends: OpenBao, AWS KMS, Azure Key Vault, GCP KMS, HSM via PKCS#11. OpenKCM CMK never stores key material — it holds a pointer and calls the keystore at runtime via Krypton. - -### Key Binding -The association between an L1 Root Key and an L2 Domain Key. Created by the security admin. One L2 Domain Key is bound to exactly one L1 Root Key. One L1 Root Key can be bound to multiple L2 Domain Keys (multiple accounts can share the same L1 key). Different accounts can be bound to different L1 keys — the admin decides. - -### L2 Domain Key -Provisioned automatically by the CMK Controller when OpenKCM is enabled on Platform Mesh — **one per account/workspace**. The CMK Controller calls Krypton explicitly via API to create it. The security admin cannot create or delete L2 keys. The admin binds an L1 key to the account's L2 key. All services across all namespaces in that account are encrypted under the single L2 key. - -### L3 Service Key -Created by the security admin via the OpenKCM CMK UI. Wrapped under the L2 Domain Key of that account. One L3 key per service instance. Not provisioned automatically — the security admin defines the service boundaries. - -### Service -An application or workload running inside a namespace (e.g. MongoDB, Postgres, Redis). Has one L3 Service Key. Encrypted automatically — no key configuration required from the developer. - ---- - -## Key Binding Rules - -| Rule | Description | -|---|---| -| One L2 per account | CMK Controller provisions exactly one L2 Domain Key per account/workspace via Krypton API | -| Admin registers L1 | The Key Admin registers an L1 key at account level | -| Admin binds L1 → L2 | The Key Admin binds the L1 key to the account's L2 key | -| One L1 per L2 | Each L2 Domain Key is bound to exactly one L1 Root Key at a time | -| Different L1s per account | Different accounts can be governed by different L1 keys | -| Admin creates L3 | The Account Encryption Admin creates one L3 Service Key per service via the OpenKCM CMK UI, scoped to their namespace | -| Unbound account | An account with no L1 binding is not customer-governed — it uses platform-managed encryption until the Key Admin binds an L1 key | - ---- - -## Kill Switch Scope - -| Action | Scope | Effect | -|---|---|---| -| Revoke L1 Root Key | That account | All namespaces and services in the account become inaccessible | -| Kill switch (account level) | That account | All namespaces, all services inaccessible — cascades through L2 → L3 → L4 automatically | - ---- - -## Lifecycle States - -### L1 Root Key lifecycle - -``` -Registered → Active → Suspended → Revoked - ↑ │ - └──────────┘ (re-activated by admin) -``` - -- **Registered** — key reference created in OpenKCM CMK, not yet validated -- **Active** — key reachable and validated by Krypton; workloads are encrypted -- **Suspended** — key temporarily unavailable; grace period begins; workloads inaccessible after grace period expires -- **Revoked** — kill switch executed; all bound workloads inaccessible; irreversible without new key registration and approval - -### L2 Domain Key lifecycle - -Managed by the CMK Controller. Follows the state of the bound L1 key — if L1 is revoked, L2 is revoked automatically. - -### L3 Service Key lifecycle - -Created by the security admin via the OpenKCM CMK UI. Revoked when the L2 above it is revoked. - ---- - -## Deployment Scenarios - -These scenarios map directly to the two deployment models defined in `cmk-platform-mesh-vision.md`. The self-selecting mechanism — where the customer enables OpenKCM from the marketplace at org level or account level — determines which scenario applies. - -### Scenario 1 — Enterprise / managed platform (Model 2: account-level enablement) - -A customer organization (e.g. ACME Corp) runs workloads on a shared Platform Mesh installation operated by a platform provider. They are one of many tenants on the platform. Each account holder enables OpenKCM independently at account level and manages their own keys in isolation. - -- OpenKCM CMK Platform Mesh is the right product -- CMK Controller scoped to that account — one L2 provisioned for that account -- Kill switch scope: that account only — does not affect other tenants -- Platform provider has no visibility into any account's key governance - -``` -Platform Mesh (shared installation) -│ -├── Account: ACME Corp ← enables OpenKCM at account level, manages own keys -│ └── Workspace → L2 → Namespaces → L3 per service -│ -├── Account: VW ← enables OpenKCM at account level, independently -│ └── Workspace → L2 → Namespaces → L3 per service -│ -└── Account: Siemens ← enables OpenKCM at account level, independently - └── Workspace → L2 → Namespaces → L3 per service -``` - ---- - -### Scenario 2 — Air-gapped / sovereign deployment (Model 1: org-level enablement) ⚠ Future state - -> **Platform dependency not yet met.** This scenario requires an org-level provider API from Platform Mesh that does not exist today. kcp's workspace tree is visual only — there is no structural org primitive OpenKCM can build on. Documented here as target architecture pending Platform Mesh building this capability. - -An organization runs their own Platform Mesh installation. They are both the platform operator and the org owner. They enable OpenKCM at org level — the CMK Controller governs all accounts across the entire organization from one place. - -- OpenKCM CMK Platform Mesh is the right product — org-level enablement -- CMK Controller at org level — provisions L2 for every account automatically -- Security admin has single pane of glass across all accounts -- Kill switch scope: entire organization — all accounts, all namespaces, all services -- No external platform provider in the loop - -``` -Air-gapped deployment (single organization owns and operates everything) -│ -├── Org level: OpenKCM enabled here → CMK Controller governs all accounts -│ -├── Account: prod → L2 auto-provisioned → security admin binds L1 → L3 per service -├── Account: dev → L2 auto-provisioned → security admin binds L1 → L3 per service -└── Account: staging → L2 auto-provisioned → security admin binds L1 → L3 per service -``` - ---- - -## Open Questions - -**1. Two APIExports — can one OpenKCM deployment serve both models?** -Can a single OpenKCM deployment publish two APIExports — one at org level and one at account level — so customers can choose their model at enablement time without deploying a separate instance? To be validated with the Platform Mesh team. - ---- - -**2. Multi-party approval — Platform Mesh integration** -Does Platform Mesh provide a native four-eyes approval mechanism that OpenKCM CMK Platform Mesh can integrate with, or does the lightweight variant rely on the tenant's own processes? - ---- - -**3. L3 visibility scope** -Which L3 option (A, B, or C) applies to each deployment scenario? - -> **Current direction:** Option B for initial release — L3 visible and manageable by the security admin in both scenarios. Option C (selective service-level revocation) is a future feature pending resolution of who owns selective revocation — OpenKCM CMK or Krypton. \ No newline at end of file