diff --git a/docs/use-cases/001-OpenKCM-Platform-Mesh-Integration.md b/docs/use-cases/001-OpenKCM-Platform-Mesh-Integration.md index dcdb56e..5b75b10 100644 --- a/docs/use-cases/001-OpenKCM-Platform-Mesh-Integration.md +++ b/docs/use-cases/001-OpenKCM-Platform-Mesh-Integration.md @@ -1,57 +1,57 @@ --- authors: - Aysan +last_updated: 2026-07-15 --- ## Persona -**Platform Users** - Anyone with access to an account in Platform who enables OpenKCM via Platform Mesh and accesses the OpenKCM CMK UI for management of their keychain (e.g., configuring CMK with HYOK or BYOK). These users interact exclusively with the CMK Layer of OpenKCM through the web interface, while the Crypto Service operates as an integrated backend service. +**Platform Users** - Anyone with access to an account in a platform who enables OpenKCM and uses it to manage their customer encryption keys (e.g., configuring HYOK or BYOK). These users interact with OpenKCM to configure their key hierarchy, while Krypton operates as the integrated backend that executes all crypto operations. ## Overview -As a Platform User, I need to enable OpenKCM encryption services for my account/tenant through Platform Mesh. This integration provisions the CMK Service with its web UI and automatically configures the backend Crypto Service. Platform Users work exclusively with Customer Managed Keys (CMK) through the CMK UI interface. +As a Platform User, I need to enable OpenKCM for my account through a platform. This integration provisions OpenKCM and automatically configures Krypton as the backend. Platform Users configure and manage their Customer Managed Keys (CMK) through OpenKCM. ## User Stories ### Story 1: Enable OpenKCM for My Account **As a** Platform User -**I want to** enable OpenKCM encryption services for my account -**So that** I can manage my customer encryption keys through the CMK UI +**I want to** enable OpenKCM for my account +**So that** I can manage my customer encryption keys **User Journey:** -1. I create a new account or tenant in KCP -2. Platform Mesh automatically detects the new tenant resource -3. The system triggers OpenKCM CMK Service provisioning -4. The backend Crypto Service is automatically configured and integrated -5. I receive notification that OpenKCM CMK UI is ready -6. I can now access the CMK web interface to configure my encryption keys +1. I create a new account in my platform +2. The platform automatically detects the new account and provisions OpenKCM +3. Krypton is automatically configured and integrated as the crypto backend +4. I receive notification that OpenKCM is ready +5. I can now configure my encryption keys through OpenKCM ### Story 2: Configure My Customer-Managed Encryption **As a** Platform User -**I want to** set up my Customer Managed Keys through the CMK UI +**I want to** set up my Customer Managed Keys in OpenKCM **So that** I have full sovereignty over my encryption keys **User Journey:** -1. I log into the OpenKCM CMK UI through my KCP account +1. I log into OpenKCM through my account 2. I see the key configuration dashboard 3. I choose my preferred key management approach (BYOK or HYOK) 4. I configure my external key store (AWS KMS, Azure Key Vault, etc.) -5. The CMK Service coordinates with the backend Crypto Service +5. OpenKCM validates the configuration with Krypton 6. I receive confirmation that my customer-managed encryption is active -7. I can monitor and manage my keys through the CMK UI +7. I can monitor and manage my keys through OpenKCM ### Story 3: Configure BYOK (Bring Your Own Key) **As a** Platform User -**I want to** use my existing encryption keys from my cloud provider +**I want to** use my existing keys from my cloud provider **So that** I can maintain consistency with my existing security infrastructure **User Journey:** -1. I access the OpenKCM CMK UI configuration wizard +1. I open the key configuration in OpenKCM 2. I select "Bring Your Own Key (BYOK)" 3. I provide my existing key ARN/URI from AWS KMS, Azure Key Vault, or GCP KMS -4. I configure the necessary permissions and trust relationships through the UI -5. The CMK Service validates my key configuration with the backend Crypto Service -6. My applications begin using my own keys for encryption (handled by Crypto Service) -7. I can monitor my key status and usage in the CMK UI dashboard +4. I configure the necessary permissions and trust relationships +5. OpenKCM validates my key configuration through Krypton +6. My applications begin using my own keys for encryption (handled by Krypton) +7. I can monitor my key status and usage in OpenKCM ### Story 4: Set up HYOK (Hold Your Own Key) **As a** Platform User with strict compliance requirements @@ -59,32 +59,32 @@ As a Platform User, I need to enable OpenKCM encryption services for my account/ **So that** I maintain complete control and meet regulatory requirements **User Journey:** -1. I choose "Hold Your Own Key (HYOK)" in the CMK UI during setup +1. I choose "Hold Your Own Key (HYOK)" in OpenKCM during setup 2. I configure connection to my HSM or on-premises key management system -3. I provide necessary certificates and connection details through the CMK interface -4. The CMK Service establishes secure communication with my key store via the Crypto Service -5. I verify through the CMK UI that keys never leave my controlled environment +3. I provide necessary certificates and connection details +4. Krypton establishes secure communication with my key store +5. I verify in OpenKCM that keys never leave my controlled environment 6. My data is encrypted using keys that remain under my physical control -7. I can monitor the connection status and key health in the CMK dashboard +7. I can monitor the connection status and key health in OpenKCM ## Requirements ### Functional Requirements #### For OpenKCM Service Enablement: -- **REQ-001**: System must automatically detect new tenant/account creation in KCP -- **REQ-002**: Platform Mesh must trigger OpenKCM CMK Service provisioning without user intervention -- **REQ-003**: Backend Crypto Service must be automatically configured and integrated -- **REQ-004**: User must receive clear notification of CMK UI availability -- **REQ-005**: OpenKCM CMK UI must become accessible once provisioning completes -- **REQ-006**: User must be able to access CMK configuration wizard through the web interface +- **REQ-001**: System must automatically detect new account creation in KCP +- **REQ-002**: The platform must trigger OpenKCM provisioning without user intervention +- **REQ-003**: Krypton must be automatically configured and integrated +- **REQ-004**: User must receive clear notification when OpenKCM is ready +- **REQ-005**: OpenKCM must become accessible once provisioning completes +- **REQ-006**: User must be able to access key configuration through OpenKCM #### For Customer-Managed Key Configuration: -- **REQ-007**: User must be able to configure CMK through the CMK UI without technical expertise -- **REQ-008**: CMK Service must coordinate seamlessly with backend Crypto Service +- **REQ-007**: User must be able to configure CMK through OpenKCM without technical expertise +- **REQ-008**: OpenKCM must coordinate seamlessly with Krypton - **REQ-009**: System must validate external key store connectivity before activation - **REQ-010**: Rollback capability must be available if configuration fails -- **REQ-011**: Key configuration changes must propagate to Crypto Service automatically +- **REQ-011**: Key configuration changes must propagate to Krypton automatically - **REQ-012**: Configuration status must be visible to the user throughout the process #### For External Key Store Integration: @@ -99,39 +99,31 @@ As a Platform User, I need to enable OpenKCM encryption services for my account/ #### Performance: - **REQ-019**: Provisioning must complete within 5 minutes for standard setup -- **REQ-020**: CSEK to CMK migration must not cause application downtime +- **REQ-020**: Key configuration changes must not cause application downtime - **REQ-021**: External key store validation must complete within 30 seconds - **REQ-022**: Configuration changes must propagate to all regions within 2 minutes #### Security: - **REQ-023**: All external key store credentials must be encrypted at rest -- **REQ-024**: Integration must use least-privilege access principles +- **REQ-024**: Integration must use least-privilege access principles - **REQ-025**: All configuration actions must be logged for audit - **REQ-026**: Multi-factor authentication required for HYOK setup - **REQ-027**: Network connections to external systems must be encrypted #### Reliability: - **REQ-028**: Provisioning failures must be automatically retried -- **REQ-029**: Partial failures must not leave tenant in inconsistent state +- **REQ-029**: Partial failures must not leave account in inconsistent state - **REQ-030**: External key store outages must not prevent data access - **REQ-031**: Configuration must be backed up and recoverable ## Acceptance Criteria ### Successful Provisioning: -- ✅ New tenant automatically triggers OpenKCM setup -- ✅ User receives email notification when setup is complete -- ✅ OpenKCM UI is accessible within 5 minutes of account creation -- ✅ Default CSEK encryption is active immediately +- ✅ New account automatically triggers OpenKCM setup +- ✅ User receives notification when setup is complete +- ✅ OpenKCM is accessible within 5 minutes of account creation - ✅ Configuration wizard guides user through setup options -### Successful CSEK to CMK Migration: -- ✅ User can initiate migration through UI without technical knowledge -- ✅ All existing data is re-encrypted with new key hierarchy -- ✅ Applications continue working without modification during migration -- ✅ User receives confirmation when migration is complete -- ✅ Key management dashboard shows new CMK status - ### Successful External Key Store Integration: - ✅ User can connect to AWS KMS, Azure Key Vault, or GCP KMS - ✅ System validates permissions and connectivity before activation @@ -142,14 +134,13 @@ As a Platform User, I need to enable OpenKCM encryption services for my account/ ### Error Scenarios: - ❌ If provisioning fails → Automatic retry with user notification - ❌ If external key store is unreachable → Clear error with resolution steps -- ❌ If migration fails → Automatic rollback to previous state +- ❌ If configuration fails → Automatic rollback to previous state - ❌ If permissions are insufficient → Detailed permission requirements shown ## Business Value ### For Platform Users: - **Zero-Touch Setup**: Automatic provisioning when creating new accounts -- **Gradual Adoption**: Start with default encryption, upgrade when ready - **Compliance Ready**: Easy path to meet regulatory requirements - **Vendor Flexibility**: Use any supported key management system - **Data Sovereignty**: Full control over encryption keys and data access @@ -163,8 +154,8 @@ As a Platform User, I need to enable OpenKCM encryption services for my account/ ## Integration Dependencies -### Platform Mesh Requirements: -- **Tenant Lifecycle Events**: Detection of account/tenant creation and deletion +### Platform Requirements: +- **Account Lifecycle Events**: Detection of account creation and deletion - **Service Discovery**: Registration of OpenKCM services in mesh - **Network Policies**: Secure communication between services - **Resource Management**: CPU, memory, and storage provisioning @@ -173,4 +164,4 @@ As a Platform User, I need to enable OpenKCM encryption services for my account/ - **Cloud KMS APIs**: Integration with AWS, Azure, GCP key management - **HSM Connectivity**: PKCS#11 and proprietary HSM interfaces - **Identity Integration**: SSO and authentication with existing systems -- **Monitoring Integration**: Health checks and alerting for key services \ No newline at end of file +- **Monitoring Integration**: Health checks and alerting for key services diff --git a/docs/use-cases/002-L1-Key-Actions.md b/docs/use-cases/002-L1-Key-Actions.md index a1f7d60..2536cd8 100644 --- a/docs/use-cases/002-L1-Key-Actions.md +++ b/docs/use-cases/002-L1-Key-Actions.md @@ -1,14 +1,15 @@ --- authors: - - Aysan Mazloumi + - Aysan +last_updated: 2026-07-15 --- ## Persona -**Platform Users** - Anyone with access to an account in KCP who enables OpenKCM via Platform Mesh and accesses the OpenKCM UI for management of the keychain (e.g., switching from CSEK to CMK with HYOK or BYOK). These users interact with the CMK Layer of OpenKCM to configure and manage their customer-managed encryption keys. +**Platform Users** - Anyone with access to an account in a platform who enables OpenKCM and uses it to manage the keychain (e.g., switching from CSEK to CMK with HYOK or BYOK). These users interact with OpenKCM to configure and manage their customer-managed encryption keys. ## Overview -As a Platform User, I need to control my encryption keys to maintain data security and compliance. L1 key actions allow me to manage the lifecycle of my Customer Master Keys through the OpenKCM UI. +As a Platform User, I need to control my encryption keys to maintain data security and compliance. L1 key actions allow me to manage the lifecycle of my Customer Master Keys through OpenKCM. ## User Stories @@ -18,7 +19,7 @@ As a Platform User, I need to control my encryption keys to maintain data securi **So that** my applications can both encrypt new data and decrypt existing data **User Journey:** -1. I log into the OpenKCM UI through my KCP account +1. I log into OpenKCM through my KCP account 2. I navigate to my key management dashboard 3. I select my L1 key and click "Enable" 4. I receive confirmation that encryption and decryption operations are now active @@ -30,7 +31,7 @@ As a Platform User, I need to control my encryption keys to maintain data securi **So that** I can prevent new data encryption while still accessing existing data **User Journey:** -1. I access the OpenKCM UI and go to key management +1. I access OpenKCM and go to key management 2. I select my active L1 key and click "Disable" 3. I confirm the action understanding it will stop new encryption 4. I receive confirmation that the key is now in read-only mode diff --git a/docs/use-cases/003-MongoDB-Get-a-Key-With-CMK-Integration.md b/docs/use-cases/003-MongoDB-Get-a-Key-With-CMK-Integration.md index 0d1b9fd..a78e8fb 100644 --- a/docs/use-cases/003-MongoDB-Get-a-Key-With-CMK-Integration.md +++ b/docs/use-cases/003-MongoDB-Get-a-Key-With-CMK-Integration.md @@ -1,14 +1,15 @@ --- authors: - - Aysan + - Aysan +last_updated: 2026-07-15 --- ## Persona -**Tenant Administrator** - A user who manages MongoDB in Platform Mesh and needs to set up end-to-end encryption using their own L1 Customer Master Key through OpenKCM. +**Tenant Administrator** - A user who manages MongoDB in a platform and needs to set up end-to-end encryption using their own L1 Customer Master Key through OpenKCM. ## Overview -As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my L1 Customer Master Key through the CMK UI, and ensure my MongoDB service can request encryption keys to protect database records with my customer-controlled encryption. +As a Tenant Administrator, I need to enable OpenKCM for my account, configure my L1 Customer Master Key through the OpenKCM UI, and ensure my MongoDB service can request encryption keys to protect database records with my customer-controlled encryption. ## User Stories @@ -18,25 +19,25 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my **So that** I can manage customer-controlled encryption for my MongoDB data **User Journey:** -1. I create or access my tenant account in KCP (Platform Mesh) -2. Platform Mesh detects my tenant and automatically provisions OpenKCM services -3. I receive notification that OpenKCM CMK UI is available -4. I can now access the CMK web interface to configure my encryption keys -5. Backend Crypto Service is automatically configured and ready for MongoDB integration +1. I create or access my account in the platform +2. The platform automatically provisions OpenKCM services for my account +3. I receive notification that OpenKCM is available +4. I can now configure my encryption keys through OpenKCM +5. Krypton is automatically configured and ready for MongoDB integration **Requirements:** -- Platform Mesh automatically provisions OpenKCM when tenant is created -- CMK UI becomes accessible within 5 minutes of tenant creation -- Crypto Service is configured and running for my tenant +- Platform automatically provisions OpenKCM when account is created +- OpenKCM becomes accessible within 5 minutes of account creation +- Krypton is configured and running for my account - I receive clear notification when services are ready ### Story 2: Upload My L1 Customer Master Key **As a** Tenant Administrator -**I want to** configure my L1 Customer Master Key in the CMK UI +**I want to** configure my L1 Customer Master Key in the OpenKCM UI **So that** all my data encryption uses my own customer-controlled key **User Journey:** -1. I log into the OpenKCM CMK UI with my tenant credentials +1. I log into OpenKCM with my tenant credentials 2. I navigate to "Master Key Configuration" section 3. I choose my key management option: - **Option A (BYOK)**: I provide my AWS KMS key ARN and configure access permissions @@ -46,7 +47,7 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my 6. System confirms my L1 key is ready for encryption operations **Requirements:** -- CMK UI supports both BYOK (AWS KMS, Azure Key Vault) and HYOK (HSM) configurations +- OpenKCM UI supports both BYOK (AWS KMS, Azure Key Vault) and HYOK (HSM) configurations - Connection test validates L1 key accessibility before saving - Configuration changes take effect within 2 minutes - Clear status indicators show L1 key state (Inactive/Active/Error) @@ -54,7 +55,7 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my ### Story 3: MongoDB Requests Encryption Key from OpenKCM **As a** MongoDB service in my tenant -**I want to** request encryption keys from OpenKCM Crypto Service +**I want to** request encryption keys from Krypton **So that** I can encrypt database records using the tenant's L1 Customer Master Key **Technical Journey:** @@ -71,8 +72,8 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my } ``` -2. **MongoDB Authentication**: I authenticate with OpenKCM Crypto Service - - Use mTLS certificate provided by Platform Mesh +2. **MongoDB Authentication**: I authenticate with Krypton + - Use mTLS certificate provided by the platform - Certificate includes my tenant scope and MongoDB service identity 3. **Key Request**: I request encryption key via KMIP protocol @@ -83,8 +84,8 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my - Service: mongodb-prod ``` -4. **Key Derivation**: Crypto Service processes my request - - Validates I'm authorized for "my-tenant" +4. **Key Derivation**: Krypton processes my request + - Validates I'm authorized for "my-tenant" - Derives ephemeral encryption key from the configured L1 Customer Master Key - Returns fresh encryption key for this operation @@ -109,11 +110,11 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my 6. **Audit Logging**: All operations are logged - MongoDB logs: Successful data encryption for tenant - - Crypto Service logs: Encryption key provided to MongoDB for my-tenant - - CMK Service logs: L1 key used for encryption key derivation + - Krypton logs: Encryption key provided to MongoDB for my-tenant + - OpenKCM logs: L1 key used for encryption key derivation **Requirements:** -- MongoDB authenticates successfully with Crypto Service using tenant-scoped certificates +- MongoDB authenticates successfully with Krypton using tenant-scoped certificates - Encryption key requests complete within 100ms - Each encryption operation uses a fresh ephemeral key - Keys are derived from the tenant's configured L1 Customer Master Key @@ -123,15 +124,15 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my ## End-to-End Flow ``` -1. Tenant Administrator → Enable OpenKCM (Platform Mesh provisions services) +1. Tenant Administrator → Enable OpenKCM (platform provisions services) ↓ -2. Tenant Administrator → Configure L1 Key in CMK UI (BYOK/HYOK) +2. Tenant Administrator → Configure L1 Key in OpenKCM UI (BYOK/HYOK) ↓ 3. L1 Customer Master Key → Active and available for encryption operations ↓ -4. MongoDB → Request encryption key from Crypto Service +4. MongoDB → Request encryption key from Krypton ↓ -5. Crypto Service → Derive ephemeral key from L1 Customer Master Key +5. Krypton → Derive ephemeral key from L1 Customer Master Key ↓ 6. MongoDB → Encrypt data using derived key, store encrypted data ↓ @@ -141,11 +142,11 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my ## Requirements ### Functional Requirements: -- **REQ-001**: Platform Mesh must automatically provision OpenKCM services for new tenants -- **REQ-002**: CMK UI must support L1 key configuration (BYOK and HYOK) +- **REQ-001**: Platform must automatically provision OpenKCM services for new accounts +- **REQ-002**: OpenKCM UI must support L1 key configuration (BYOK and HYOK) - **REQ-003**: System must validate L1 key connectivity before activation -- **REQ-004**: MongoDB must authenticate with Crypto Service using mTLS -- **REQ-005**: Crypto Service must derive encryption keys from configured L1 key +- **REQ-004**: MongoDB must authenticate with Krypton using mTLS +- **REQ-005**: Krypton must derive encryption keys from configured L1 key - **REQ-006**: MongoDB must encrypt sensitive data using OpenKCM-provided keys - **REQ-007**: All operations must maintain tenant isolation @@ -164,13 +165,13 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my ## Success Criteria ### Setup Phase Success: -- ✅ OpenKCM services provisioned automatically when tenant created -- ✅ Tenant can access CMK UI and configure L1 Customer Master Key +- ✅ OpenKCM services provisioned automatically when account created +- ✅ Tenant can access OpenKCM and configure L1 Customer Master Key - ✅ L1 key connection tested and confirmed active -- ✅ MongoDB service registered and authenticated with Crypto Service +- ✅ MongoDB service registered and authenticated with Krypton ### Operational Phase Success: -- ✅ MongoDB successfully requests encryption keys from Crypto Service +- ✅ MongoDB successfully requests encryption keys from Krypton - ✅ Data encrypted using keys derived from tenant's L1 Customer Master Key - ✅ Tenant isolation maintained (MongoDB only accesses own tenant's keys) - ✅ Performance requirements met for all key operations @@ -187,5 +188,5 @@ As a Tenant Administrator, I need to enable OpenKCM for my tenant, configure my - **Seamless Integration**: MongoDB encryption works transparently with minimal setup - **Regulatory Compliance**: Customer-controlled encryption meets compliance requirements - **Data Security**: All database records protected with customer's own keys -- **Operational Simplicity**: Automated provisioning with simple UI configuration -- **Audit Ready**: Full traceability from key configuration to data encryption \ No newline at end of file +- **Operational Simplicity**: Automated provisioning with simple configuration through OpenKCM +- **Audit Ready**: Full traceability from key configuration to data encryption diff --git a/docs/use-cases/004-Crypto-Layer-Platform-Mesh-integration.md b/docs/use-cases/004-Crypto-Layer-Platform-Mesh-integration.md index dc8b251..b12b01c 100644 --- a/docs/use-cases/004-Crypto-Layer-Platform-Mesh-integration.md +++ b/docs/use-cases/004-Crypto-Layer-Platform-Mesh-integration.md @@ -1,29 +1,30 @@ --- authors: - Aysan +last_updated: 2026-07-15 --- ## Persona -**Platform Mesh Administrator** - An infrastructure administrator responsible for deploying and managing OpenKCM's Crypto Layer services within the Platform Mesh infrastructure. They ensure the Crypto Service is properly deployed, configured, and integrated with the mesh for tenant services like MongoDB. +**Platform Mesh Administrator** - An infrastructure administrator responsible for deploying and managing Krypton within the Platform Mesh infrastructure. They ensure Krypton is properly deployed, configured, and integrated with the mesh for tenant services like MongoDB. ## Overview -As a Platform Mesh Administrator, I need to deploy OpenKCM's Crypto Layer service within the Platform Mesh infrastructure so that tenant services (like MongoDB, PostgreSQL, microservices) can request encryption keys for data protection. The Crypto Layer must be highly available, scalable, and integrated with Platform Mesh's service discovery and networking. +As a Platform Mesh Administrator, I need to deploy Krypton within the Platform Mesh infrastructure so that tenant services (like MongoDB, PostgreSQL, microservices) can request encryption keys for data protection. Krypton must be highly available, scalable, and integrated with Platform Mesh's service discovery and networking. ## User Stories -### Story 1: Deploy Crypto Service in Platform Mesh +### Story 1: Deploy Krypton in Platform Mesh **As a** Platform Mesh Administrator -**I want to** deploy the OpenKCM Crypto Service within Platform Mesh +**I want to** deploy Krypton within Platform Mesh **So that** tenant services can access encryption key management capabilities **Deployment Journey:** 1. **Infrastructure Preparation**: I prepare the Platform Mesh environment - Kubernetes cluster with sufficient resources allocated - - Network policies configured for Crypto Service communication + - Network policies configured for Krypton communication - Storage provisioned for key metadata and configuration -2. **Crypto Service Deployment**: I deploy the Crypto Service components +2. **Krypton Deployment**: I deploy the Krypton components ```yaml # crypto-service-deployment.yaml apiVersion: apps/v1 @@ -45,13 +46,11 @@ As a Platform Mesh Administrator, I need to deploy OpenKCM's Crypto Layer servic - containerPort: 5696 # KMIP port - containerPort: 8443 # HTTPS management env: - - name: POSTGRES_CONNECTION - value: "postgresql://crypto-db:5432/openkcm" - name: TENANT_ISOLATION_ENABLED value: "true" ``` -3. **Service Registration**: I register Crypto Service with Platform Mesh +3. **Service Registration**: I register Krypton with Platform Mesh ```yaml # crypto-service.yaml apiVersion: v1 @@ -59,9 +58,6 @@ As a Platform Mesh Administrator, I need to deploy OpenKCM's Crypto Layer servic metadata: name: openkcm-crypto-service namespace: openkcm-system - annotations: - platform-mesh.io/service-type: "encryption-service" - platform-mesh.io/discovery-enabled: "true" spec: selector: app: openkcm-crypto-service @@ -80,15 +76,15 @@ As a Platform Mesh Administrator, I need to deploy OpenKCM's Crypto Layer servic - Platform Mesh health check integration **Requirements:** -- Crypto Service deployed with high availability (3+ replicas) +- Krypton deployed with high availability (3+ replicas) - Service registered in Platform Mesh service discovery - Health checks configured and reporting healthy status - Network policies allow tenant service communication -### Story 2: Configure Crypto Service Integration with Platform Mesh +### Story 2: Configure Krypton Integration with Platform Mesh **As a** Platform Mesh Administrator -**I want to** configure the Crypto Service for seamless Platform Mesh integration -**So that** tenant services can discover and authenticate with the Crypto Service +**I want to** configure Krypton for seamless Platform Mesh integration +**So that** tenant services can discover and authenticate with Krypton **Configuration Journey:** 1. **Service Discovery Setup**: I configure Platform Mesh service discovery @@ -158,33 +154,24 @@ As a Platform Mesh Administrator, I need to deploy OpenKCM's Crypto Layer servic - Service discoverable through Platform Mesh DNS - mTLS certificates properly provisioned and valid - Network policies allow authorized tenant service access - - Crypto Service registers successfully with service mesh + - Krypton registers successfully with service mesh **Requirements:** -- Service discoverable via Platform Mesh service registry +- Krypton discoverable via Platform Mesh service registry - mTLS certificates automatically provisioned and rotated - Network policies enforce secure tenant service access - Integration validated through connectivity tests -### Story 3: Configure Multi-Tenant Isolation for Crypto Service +### Story 3: Configure Multi-Tenant Isolation for Krypton **As a** Platform Mesh Administrator -**I want to** configure tenant isolation within the Crypto Service +**I want to** configure tenant isolation within Krypton **So that** each tenant's encryption keys are completely isolated from other tenants **Isolation Configuration Journey:** -1. **Tenant Database Setup**: I configure PostgreSQL with Row-Level Security - ```sql - -- Enable Row-Level Security for tenant isolation - ALTER TABLE key_metadata ENABLE ROW LEVEL SECURITY; - - -- Create tenant isolation policy - CREATE POLICY tenant_isolation ON key_metadata - USING (tenant_id = current_setting('app.current_tenant')); - - -- Create tenant-specific database roles - CREATE ROLE tenant_a_crypto; - GRANT SELECT, INSERT, UPDATE ON key_metadata TO tenant_a_crypto; - ``` +1. **Tenant Isolation Setup**: I configure API-level tenant isolation + - Tenant context is enforced on every request via mTLS certificate identity + - Cross-tenant access is rejected at the service layer + - Each tenant's key data is scoped to their authenticated identity 2. **Tenant Certificate Provisioning**: I set up tenant-specific mTLS certificates ```yaml @@ -222,24 +209,21 @@ As a Platform Mesh Administrator, I need to deploy OpenKCM's Crypto Layer servic organizationalUnit: "tenant-a" route: tenant: "tenant-a" - database: "tenant_a_keys" ``` 4. **Isolation Validation**: I test tenant boundaries - Verify tenant-a services can only access tenant-a keys - Confirm cross-tenant requests are blocked - Validate certificate-based tenant identification - - Test database-level isolation with RLS policies **Requirements:** -- PostgreSQL RLS enforces database-level tenant isolation -- mTLS certificates identify tenant context for each request -- Crypto Service routes requests to correct tenant data +- Tenant isolation enforced at the API level via mTLS certificate identity +- mTLS certificates scoped to tenant and service identity - Cross-tenant access attempts are blocked and logged -### Story 4: Monitor and Scale Crypto Service Deployment +### Story 4: Monitor and Scale Krypton **As a** Platform Mesh Administrator -**I want to** monitor Crypto Service performance and scale based on demand +**I want to** monitor Krypton performance and scale based on demand **So that** encryption key operations maintain performance SLAs across all tenants **Monitoring and Scaling Journey:** @@ -306,12 +290,12 @@ As a Platform Mesh Administrator, I need to deploy OpenKCM's Crypto Layer servic ## Technical Architecture -### Crypto Service Deployment Architecture: +### Krypton Deployment Architecture: ``` Platform Mesh Cluster ├── openkcm-system namespace -│ ├── Crypto Service Pods (3+ replicas) -│ ├── PostgreSQL Database (RLS enabled) +│ ├── Krypton Pods (3+ replicas) +│ ├── Key Metadata Store │ ├── Certificate Manager │ └── Monitoring Stack ├── Tenant Namespaces @@ -329,7 +313,7 @@ Platform Mesh Cluster ``` Tenant Service (MongoDB) → Platform Mesh Service Discovery ↓ - Crypto Service Endpoint Resolution + Krypton Endpoint Resolution ↓ mTLS Connection Establishment ↓ @@ -343,9 +327,9 @@ Tenant Service (MongoDB) → Platform Mesh Service Discovery ## Requirements ### Deployment Requirements: -- **REQ-001**: Crypto Service must deploy with high availability (3+ replicas) +- **REQ-001**: Krypton must deploy with high availability (3+ replicas) - **REQ-002**: Service must register with Platform Mesh service discovery -- **REQ-003**: PostgreSQL database must be configured with Row-Level Security +- **REQ-003**: Tenant isolation must be enforced at the API level - **REQ-004**: mTLS certificates must be automatically provisioned and rotated ### Performance Requirements: @@ -355,7 +339,7 @@ Tenant Service (MongoDB) → Platform Mesh Service Discovery - **REQ-008**: Service startup time must be under 60 seconds ### Security Requirements: -- **REQ-009**: Tenant isolation must be enforced at network and database levels +- **REQ-009**: Tenant isolation must be enforced at the API level - **REQ-010**: All service communications must use mTLS encryption - **REQ-011**: Certificate-based tenant identification must be validated - **REQ-012**: Security policies must prevent cross-tenant access @@ -369,16 +353,16 @@ Tenant Service (MongoDB) → Platform Mesh Service Discovery ## Success Criteria ### Deployment Success: -- ✅ Crypto Service deployed and running with high availability +- ✅ Krypton deployed and running with high availability - ✅ Service registered and discoverable through Platform Mesh - ✅ Multi-tenant isolation configured and validated - ✅ Network policies and certificates properly configured ### Integration Success: -- ✅ Tenant services (MongoDB, etc.) can discover and connect to Crypto Service +- ✅ Tenant services (MongoDB, etc.) can discover and connect to Krypton - ✅ KMIP protocol communication working correctly - ✅ mTLS authentication and tenant identification working -- ✅ Database-level tenant isolation enforced +- ✅ API-level tenant isolation enforced ### Operational Success: - ✅ Monitoring dashboards show service health and performance @@ -393,4 +377,4 @@ Tenant Service (MongoDB) → Platform Mesh Service Discovery - **Security Compliance**: Proper tenant isolation and audit trails for regulatory requirements - **Developer Experience**: Transparent integration allows services to add encryption easily - **Cost Optimization**: Shared infrastructure with auto-scaling optimizes resource usage -- **Platform Integration**: Native Platform Mesh integration provides seamless service discovery \ No newline at end of file +- **Platform Integration**: Native Platform Mesh integration provides seamless service discovery diff --git a/docs/use-cases/005.MongoDB-Get-a-Key-from_Crypto-Layer.md b/docs/use-cases/005.MongoDB-Get-a-Key-from_Crypto-Layer.md index f5ef074..9bba599 100644 --- a/docs/use-cases/005.MongoDB-Get-a-Key-from_Crypto-Layer.md +++ b/docs/use-cases/005.MongoDB-Get-a-Key-from_Crypto-Layer.md @@ -1,35 +1,36 @@ --- authors: - Aysan +last_updated: 2026-07-15 --- ## Persona -**MongoDB Service** - A database service running within the Apeiro Platform Mesh that needs to encrypt/decrypt data using OpenKCM's Crypto Layer. MongoDB operates without customer involvement in key management and uses OpenKCM's internal key hierarchy for transparent encryption. +**MongoDB Service** - A database service running within a Platform Mesh account that needs to encrypt/decrypt data using Krypton. MongoDB operates without customer involvement in key management and uses OpenKCM's internal key hierarchy for transparent encryption. ## Overview -As a MongoDB service running in Platform Mesh, I need to request encryption keys from OpenKCM's Crypto Layer to encrypt database records. I don't require customer-managed keys (CMK) - instead, I use OpenKCM's internal key management system for automatic, transparent encryption without customer key configuration. +As a MongoDB service running in Platform Mesh, I need to request encryption keys from Krypton to encrypt database records. I don't require customer-managed keys (CMK) — instead, I use OpenKCM's internal key management system for automatic, transparent encryption without customer key configuration. ## User Stories -### Story 1: MongoDB Registers with OpenKCM Crypto Service +### Story 1: MongoDB Registers with Krypton **As a** MongoDB service instance -**I want to** register with OpenKCM Crypto Layer +**I want to** register with Krypton **So that** I can request encryption keys for data protection operations **Technical Journey:** 1. **Service Deployment**: I get deployed in Platform Mesh for a tenant -2. **Automatic Registration**: Platform Mesh automatically registers me with OpenKCM Crypto Service +2. **Automatic Registration**: Platform Mesh automatically registers me with Krypton - Service identity: `mongodb-cluster-tenant-a` - Service type: `database` - Tenant context: `tenant-a` 3. **Certificate Provisioning**: I receive mTLS certificates from Platform Mesh - - Client certificate for Crypto Service authentication + - Client certificate for Krypton authentication - Certificate scoped to my tenant and service permissions -4. **Connection Establishment**: I establish persistent connection to Crypto Service +4. **Connection Establishment**: I establish persistent connection to Krypton - TLS 1.3 with mutual authentication - Connection pooling for performance -5. **Service Validation**: Crypto Service confirms my registration +5. **Service Validation**: Krypton confirms my registration - Validates certificate and service identity - Authorizes me for tenant-a encryption operations @@ -41,7 +42,7 @@ As a MongoDB service running in Platform Mesh, I need to request encryption keys ### Story 2: MongoDB Requests Encryption Key for Data Storage **As a** MongoDB service -**I want to** request encryption keys from Crypto Layer +**I want to** request encryption keys from Krypton **So that** I can encrypt database records transparently **Technical Journey:** @@ -58,7 +59,7 @@ As a MongoDB service running in Platform Mesh, I need to request encryption keys } ``` -2. **Key Request via KMIP**: I request encryption key from Crypto Service +2. **Key Request via KMIP**: I request encryption key from Krypton ``` KMIP Request: - Operation: Create Symmetric Key @@ -67,14 +68,14 @@ As a MongoDB service running in Platform Mesh, I need to request encryption keys - Usage: encrypt ``` -3. **Internal Key Derivation**: Crypto Service processes request +3. **Internal Key Derivation**: Krypton processes request - Uses internal L2 tenant key (automatically managed by OpenKCM) - Derives L4 ephemeral key for this encryption operation - No customer L1 key required - fully internal key management 4. **Data Encryption**: I encrypt sensitive fields ```python - # Get encryption key from Crypto Service + # Get encryption key from Krypton encryption_key = kmip_client.get_key(tenant_id="tenant-a") # Encrypt sensitive data @@ -105,7 +106,7 @@ As a MongoDB service running in Platform Mesh, I need to request encryption keys ### Story 3: MongoDB Decrypts Data for Read Operations **As a** MongoDB service -**I want to** decrypt stored data using keys from Crypto Layer +**I want to** decrypt stored data using keys from Krypton **So that** applications can access readable customer data **Technical Journey:** @@ -127,7 +128,7 @@ As a MongoDB service running in Platform Mesh, I need to request encryption keys } ``` -3. **Decryption Key Request**: I request decryption key via KMIP +3. **Decryption Key Request**: I request decryption key via KMIP from Krypton ``` KMIP Request: - Operation: Get Symmetric Key @@ -138,7 +139,7 @@ As a MongoDB service running in Platform Mesh, I need to request encryption keys 4. **Data Decryption**: I decrypt the sensitive fields ```python - # Get decryption key from Crypto Service + # Get decryption key from Krypton decryption_key = kmip_client.get_key(tenant_id="tenant-a", usage="decrypt") # Decrypt sensitive fields @@ -156,7 +157,7 @@ As a MongoDB service running in Platform Mesh, I need to request encryption keys ``` 5. **Performance Optimization**: I cache keys briefly for performance - - Keys cached for maximum 5 minutes + - Keys cached for a short period to reduce round-trips - Batch operations reuse same key when possible - Connection pooling reduces latency @@ -201,11 +202,11 @@ As a MongoDB service running in Platform Mesh, I need to request encryption keys ## Technical Flow ``` -MongoDB Service → Crypto Service Authentication (mTLS) +MongoDB Service → Krypton Authentication (mTLS) ↓ MongoDB → Request encryption key (KMIP) ↓ -Crypto Service → Derive ephemeral key from internal L2 key +Krypton → Derive ephemeral key from internal L2 key ↓ MongoDB → Encrypt data with ephemeral key ↓ @@ -217,8 +218,8 @@ For reads: MongoDB requests decryption key and decrypts data ## Requirements ### Functional Requirements: -- **REQ-001**: MongoDB must authenticate with Crypto Service using mTLS certificates -- **REQ-002**: Crypto Service must provide encryption keys using internal key hierarchy +- **REQ-001**: MongoDB must authenticate with Krypton using mTLS certificates +- **REQ-002**: Krypton must provide encryption keys using internal key hierarchy - **REQ-003**: MongoDB must encrypt sensitive database fields automatically - **REQ-004**: System must maintain tenant isolation without customer key management - **REQ-005**: Key operations must work without customer CMK configuration @@ -251,7 +252,7 @@ For reads: MongoDB requests decryption key and decrypts data ### Integration Success: - ✅ Zero application code changes required for encryption -- ✅ MongoDB service integrates transparently with Crypto Layer +- ✅ MongoDB service integrates transparently with Krypton - ✅ Performance impact within acceptable limits - ✅ System operates reliably without customer key management @@ -262,4 +263,4 @@ For reads: MongoDB requests decryption key and decrypts data - **Tenant Isolation**: Each tenant's data encrypted with isolated keys - **Performance**: Minimal impact on database operations - **Compliance**: Encrypted data storage meets regulatory requirements -- **Operational Simplicity**: No customer key management overhead \ No newline at end of file +- **Operational Simplicity**: No customer key management overhead diff --git a/docs/use-cases/006-OpenKCM-CMK-Tanent-Management.md b/docs/use-cases/006-OpenKCM-Tenant-Management.md similarity index 92% rename from docs/use-cases/006-OpenKCM-CMK-Tanent-Management.md rename to docs/use-cases/006-OpenKCM-Tenant-Management.md index d2971f9..cea5c0c 100644 --- a/docs/use-cases/006-OpenKCM-CMK-Tanent-Management.md +++ b/docs/use-cases/006-OpenKCM-Tenant-Management.md @@ -1,6 +1,7 @@ --- authors: - Aysan +last_updated: 2026-07-15 --- ## Persona @@ -56,14 +57,14 @@ As a Platform User, I need to enable OpenKCM encryption services from the Platfo ✓ Tenant environment created ✓ Encryption keys configured ✓ Services can now request encryption keys - ✓ CMK UI available at: https://cmk.openkcm.io/tenant/acme-corp-12345" + ✓ OpenKCM UI is accessible through your platform account" ``` **Requirements:** - Simple one-click enablement from marketplace - Automatic tenant provisioning within 3 minutes - Clear confirmation when service is ready -- CMK UI immediately accessible after provisioning +- OpenKCM UI immediately accessible after provisioning ### Story 2: Automatic Tenant Creation (Behind the Scenes) **As a** Platform User @@ -89,7 +90,7 @@ As a Platform User, I need to enable OpenKCM encryption services from the Platfo 4. **Service Integration Setup**: My services can immediately use encryption: - MongoDB, PostgreSQL, microservices can request keys - mTLS certificates automatically issued for my services - - Crypto Service routes my requests to isolated boundaries + - Krypton routes my requests to isolated boundaries **My Experience:** - I don't need to understand L2 keys or MTCI standards @@ -103,15 +104,14 @@ As a Platform User, I need to enable OpenKCM encryption services from the Platfo - All my services can immediately access encryption capabilities - Complete audit trail maintained for compliance -### Story 3: Access My Tenant Management Interface +### Story 3: Access My OpenKCM Tenant Dashboard **As a** Platform User -**I want to** access the CMK UI to manage my organization's encryption settings +**I want to** access the OpenKCM UI to manage my organization's encryption settings **So that** I can configure customer-managed keys and monitor my encryption usage **User Journey:** -1. **Access CMK UI**: I click the provided link to access my tenant - - URL: `https://cmk.openkcm.io/tenant/acme-corp-12345` - - Single sign-on through my Platform account +1. **Access OpenKCM UI**: I access my tenant through my platform account + - Single sign-on through my platform account 2. **View My Tenant Dashboard**: I see my organization's encryption environment ``` @@ -149,7 +149,7 @@ As a Platform User, I need to enable OpenKCM encryption services from the Platfo - Compliance status and audit logs **Requirements:** -- CMK UI accessible immediately after tenant creation +- OpenKCM UI accessible immediately after tenant creation - Clear visibility into tenant status and capabilities - Option to configure customer-managed keys - Usage analytics and monitoring available @@ -177,7 +177,7 @@ As a Platform User, I need to enable OpenKCM encryption services from the Platfo # Data encrypted with ephemeral keys derived from my tenant boundary ``` -3. **Monitor Encryption Usage**: I see encryption activity in CMK UI +3. **Monitor Encryption Usage**: I see encryption activity in OpenKCM ``` Service Integration Update: @@ -214,11 +214,11 @@ PostgreSQL RLS configured for tenant isolation ↓ mTLS certificate templates created for tenant services ↓ -Crypto Service routing configured for tenant requests +Krypton routing configured for tenant requests ↓ Platform User receives "Ready" notification ↓ -Platform User accesses CMK UI +Platform User accesses OpenKCM UI ↓ Platform User's services automatically discover OpenKCM ↓ @@ -247,14 +247,14 @@ Customer: Beta Corp (beta-corp-67890) ### User Experience Requirements: - **REQ-001**: One-click enablement from Platform marketplace - **REQ-002**: Automatic tenant provisioning within 3 minutes -- **REQ-003**: CMK UI accessible immediately after provisioning +- **REQ-003**: OpenKCM UI accessible immediately after provisioning - **REQ-004**: Services integrate with encryption automatically ### Technical Requirements (Automated by Controller): - **REQ-005**: Each tenant gets unique L2 Tenant Encryption Key - **REQ-006**: PostgreSQL RLS enforces tenant isolation - **REQ-007**: mTLS certificates scoped to tenant boundaries -- **REQ-008**: Crypto Service routes requests to correct tenant +- **REQ-008**: Krypton routes requests to correct tenant ### Security Requirements: - **REQ-009**: Multi-Tenant Cryptographic Isolation (MTCI) standard implemented @@ -267,7 +267,7 @@ Customer: Beta Corp (beta-corp-67890) ### User Experience Success: - ✅ Platform Users can enable OpenKCM with one click - ✅ Tenant environment ready within 3 minutes -- ✅ CMK UI accessible and easy to navigate +- ✅ OpenKCM UI accessible and easy to navigate - ✅ Services integrate with encryption automatically ### Security Success: diff --git a/docs/use-cases/007-OpenKCM-CMK-KeyStore-Plugins.md b/docs/use-cases/007-OpenKCM-CMK-KeyStore-Plugins.md index 2c0b022..c5c2c4f 100644 --- a/docs/use-cases/007-OpenKCM-CMK-KeyStore-Plugins.md +++ b/docs/use-cases/007-OpenKCM-CMK-KeyStore-Plugins.md @@ -8,7 +8,7 @@ authors: ## Overview -As an Enterprise Security Administrator, I need to integrate my organization's existing external keystores with OpenKCM's CMK service. This allows me to maintain our Customer Master Keys (L1) in our trusted keystore infrastructure while enabling OpenKCM to derive tenant and service keys for our Platform Mesh applications. The CMK Plugins provide secure connectors to various keystore providers without exposing our master keys. +As an Enterprise Security Administrator, I need to integrate my organization's existing external keystores with OpenKCM's CMK service. This allows me to maintain our Customer Master Keys (L1) in our trusted keystore infrastructure while enabling OpenKCM to derive tenant and service keys for our platform applications. The CMK Plugins provide secure connectors to various keystore providers without exposing our master keys. ## Business Context diff --git a/docs/use-cases/008-OpenKCM-CMK-Certificate-Plugins.md b/docs/use-cases/008-OpenKCM-CMK-Certificate-Plugins.md index 16950db..3a3d703 100644 --- a/docs/use-cases/008-OpenKCM-CMK-Certificate-Plugins.md +++ b/docs/use-cases/008-OpenKCM-CMK-Certificate-Plugins.md @@ -4,11 +4,11 @@ authors: --- ## Persona -**CMK API Server** - The OpenKCM Customer Managed Key API service that needs to automatically generate x509 client certificates for tenant authentication to external keystores. The CMK API Server integrates with OpenBao PKI service (running on Platform Mesh) to request, generate, and manage client certificates on-demand for secure keystore connections. +**CMK API Server** - The OpenKCM Customer Managed Key API service that needs to automatically generate x509 client certificates for tenant authentication to external keystores. The CMK API Server integrates with OpenBao PKI service to request, generate, and manage client certificates on-demand for secure keystore connections. ## Overview -As the CMK API Server, I need to integrate with the OpenBao PKI service running on Platform Mesh to automatically generate x509 client certificates for tenant authentication to external keystores. When tenants configure keystore connections that require client certificate authentication, I must request properly signed certificates from OpenBao PKI and configure them for secure mTLS connections to external keystores. +As the CMK API Server, I need to integrate with the OpenBao PKI service to automatically generate x509 client certificates for tenant authentication to external keystores. When tenants configure keystore connections that require client certificate authentication, I must request properly signed certificates from OpenBao PKI and configure them for secure mTLS connections to external keystores. ## Business Context @@ -18,17 +18,17 @@ The CMK API Server needs automated certificate generation because: - **Automation**: Certificate generation must be seamless during tenant onboarding - **Certificate Lifecycle**: Automatic renewal and rotation without service disruption - **Compliance**: All certificates must follow organizational PKI policies -- **Integration**: Leverage existing OpenBao PKI infrastructure on Platform Mesh +- **Integration**: Leverage existing OpenBao PKI infrastructure ## User Stories ### Story 1: Initialize OpenBao PKI Plugin for Certificate Operations **As the** CMK API Server -**I want to** establish connection with OpenBao PKI service on Platform Mesh +**I want to** establish connection with OpenBao PKI service **So that** I can request x509 client certificates for tenant keystore authentication **Technical Journey:** -1. **Discover OpenBao PKI Service**: I discover OpenBao PKI through Platform Mesh service registry +1. **Discover OpenBao PKI Service**: I discover OpenBao PKI through the platform service registry ```yaml # Service discovery for OpenBao PKI apiVersion: v1 @@ -435,7 +435,7 @@ CMK API Server ├── Certificate Renewal Scheduler └── Keystore Connection Manager -Platform Mesh Integration +Platform Integration ├── OpenBao PKI Service (platform-services namespace) ├── Kubernetes Service Account Authentication ├── Service Discovery for OpenBao endpoint diff --git a/docs/use-cases/009-OpenKCM-CMK-Identity-Management-Plugin.md b/docs/use-cases/009-OpenKCM-CMK-Identity-Management-Plugin.md index 7fe200f..2d19028 100644 --- a/docs/use-cases/009-OpenKCM-CMK-Identity-Management-Plugin.md +++ b/docs/use-cases/009-OpenKCM-CMK-Identity-Management-Plugin.md @@ -28,7 +28,7 @@ The CMK API Server needs identity management integration because: **So that** I can enforce group-based access controls for CMK operations **Plugin Initialization Journey:** -1. **Discover Identity Management Service**: I identify available identity providers on Platform Mesh +1. **Discover Identity Management Service**: I identify available identity providers on the platform ```yaml # Service discovery for identity management apiVersion: v1 @@ -387,7 +387,7 @@ CMK API Server ├── Access Policy Engine └── Audit Logger with Group Context -Identity Provider Integration (Platform Mesh) +Identity Provider Integration (Platform) ├── Keycloak Service (Primary - Pending Integration) ├── Active Directory Connector (Optional) ├── External LDAP Services (Optional) diff --git a/docs/use-cases/010-OpenKCM-CMK-UI-Adoption.md b/docs/use-cases/010-OpenKCM-CMK-UI-Adoption.md deleted file mode 100644 index 999966a..0000000 --- a/docs/use-cases/010-OpenKCM-CMK-UI-Adoption.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -authors: - - Aysan ---- - -## Persona -**Platform UI Development Team** - The team responsible for integrating OpenKCM's Customer Managed Key (CMK) functionality into the platform's unified user interface. They need to adopt and embed CMK components while maintaining consistent user experience across the platform. - -## Overview - -As the Platform UI Development Team, we need to adopt OpenKCM's CMK UI components and integrate them seamlessly into the platform's existing interface framework. This adoption ensures users can access key management functionality through the familiar platform experience without separate authentication flows or interface inconsistencies. - -## Business Context - -UI adoption is required because: -- **Unified Platform Experience**: All services must integrate with platform's interface standards -- **Consistent User Journey**: Users expect seamless navigation across platform capabilities -- **Single Authentication**: Eliminate separate login flows for key management -- **Brand Consistency**: Maintain platform's visual identity and design system -- **Operational Integration**: Key management embedded in existing workflows - -## Adoption Requirements - -### Core Integration Needs -- **Component Adoption**: Integrate CMK UI components into platform's component library -- **Authentication Integration**: Adopt platform's SSO and user session management -- **Design System Alignment**: Apply platform's styling, themes, and visual guidelines -- **Navigation Integration**: Embed CMK functionality within platform's navigation structure -- **State Management**: Integrate CMK operations with platform's state management system - -### Technical Adoption Areas -- **Frontend Framework**: Adopt platform's frontend technology stack and patterns -- **API Integration**: Connect CMK backend through platform's API gateway -- **Routing**: Integrate CMK routes within platform's routing system -- **Error Handling**: Adopt platform's error handling and user feedback patterns -- **Performance Standards**: Meet platform's performance and accessibility requirements - -### User Experience Adoption -- **Interface Consistency**: Adopt platform's UI patterns, layouts, and interactions -- **Notification System**: Integrate with platform's notification and messaging system -- **Help and Documentation**: Adopt platform's help system and user guidance -- **Accessibility**: Comply with platform's accessibility standards and requirements -- **Mobile Responsiveness**: Adopt platform's responsive design patterns - -### Operational Adoption -- **Monitoring Integration**: Adopt platform's monitoring and analytics systems -- **Audit Integration**: Connect CMK audit trails with platform's audit system -- **Compliance Reporting**: Integrate with platform's compliance and reporting tools -- **Configuration Management**: Adopt platform's configuration and settings management - -## Adoption Success Criteria - -### Technical Success -- ✅ CMK components fully integrated with platform's UI framework -- ✅ Single sign-on working seamlessly across platform and CMK -- ✅ Consistent visual appearance with platform design system -- ✅ Navigation flows integrated with platform's routing system - -### User Experience Success -- ✅ Users can access key management without leaving platform interface -- ✅ Consistent interaction patterns across all platform services -- ✅ Unified help and support experience -- ✅ Performance meets platform's user experience standards - -### Operational Success -- ✅ CMK operations visible in platform's monitoring dashboards -- ✅ Audit trails integrated with platform's compliance systems -- ✅ Configuration managed through platform's standard tools -- ✅ Error handling consistent with platform's patterns - -## Business Value - -- **Seamless User Experience**: Unified interface reduces user friction and training needs -- **Operational Efficiency**: Integrated workflows improve productivity -- **Consistent Brand Experience**: Maintains platform's professional appearance -- **Reduced Development Overhead**: Shared components and patterns reduce maintenance -- **Improved Feature Adoption**: Familiar interface encourages key management usage -- **Future-Ready Architecture**: Established integration patterns support future services \ No newline at end of file diff --git a/docs/use-cases/011-OpenKCM-Business-Use_Case.md b/docs/use-cases/011-OpenKCM-Business-Use_Case.md index 9eaa8da..b9d96c3 100644 --- a/docs/use-cases/011-OpenKCM-Business-Use_Case.md +++ b/docs/use-cases/011-OpenKCM-Business-Use_Case.md @@ -246,7 +246,7 @@ This directly addresses the requirement for **Red Button testing capability** **The answer — through a concrete example:** -A security engineer at a multi-tenant platform (like Platform Mesh) needs to encrypt MongoDB data at rest. Today, they configure MongoDB to connect to Krypton Gateway via KMIP over mTLS: +A security engineer at a multi-tenant platform needs to encrypt MongoDB data at rest. Today, they configure MongoDB to connect to Krypton Gateway via KMIP over mTLS: ```yaml security: @@ -406,11 +406,11 @@ Of course, end-to-end testing is essential to ensure the full chain works correc --- -## Demo Scenario: Platform Mesh + MongoDB +## Demo Scenario: Platform + MongoDB ### Phase 1: Setup — "Show It Works" -**Story:** A security engineer on the Platform Mesh platform decides to enable encryption at rest for MongoDB using Krypton. +**Story:** A security engineer on a platform account decides to enable encryption at rest for MongoDB using Krypton. 1. **Before encryption:** Show that MongoDB data is stored in plaintext on disk. 2. **Enable Krypton:** Configure MongoDB to connect to Krypton Gateway via KMIP. diff --git a/docs/use-cases/011-OpenKCM-Target_Audiences.md b/docs/use-cases/011-OpenKCM-Target_Audiences.md index 6febcb9..3ea3fa0 100644 --- a/docs/use-cases/011-OpenKCM-Target_Audiences.md +++ b/docs/use-cases/011-OpenKCM-Target_Audiences.md @@ -6,7 +6,7 @@ **The answer — through a concrete example:** -A security engineer at a multi-tenant platform (like Platform Mesh) needs to encrypt MongoDB data at rest. Today, they configure MongoDB to connect to Krypton Gateway via KMIP over mTLS: +A security engineer at a multi-tenant platform needs to encrypt MongoDB data at rest. Today, they configure MongoDB to connect to Krypton Gateway via KMIP over mTLS: ```yaml security: diff --git a/docs/use-cases/012-OpenKCM-Platform-Mesh-Deployment-Models.md b/docs/use-cases/012-OpenKCM-Platform-Mesh-Deployment-Models.md new file mode 100644 index 0000000..138418e --- /dev/null +++ b/docs/use-cases/012-OpenKCM-Platform-Mesh-Deployment-Models.md @@ -0,0 +1,38 @@ +--- +authors: + - Aysan +date: 2026-07-15 +last_updated: 2026-07-15 +status: Draft +--- + +# OpenKCM — Platform Mesh Deployment Model + +## Overview + +OpenKCM is deployed at **account level** on Platform Mesh. Each account enables OpenKCM independently, manages its own L1 key, and runs its own CMK Controller scoped to that account. The platform provider has zero visibility into any account's key governance. + +--- + +## Use Case — Shared Platform Provider: Multiple Independent Organizations as Tenants + +**Who:** A company offering a managed Platform Mesh installation to multiple independent organizations (e.g. a managed service provider or systems integrator offering Platform Mesh as a service). + +**The situation:** The platform provider operates the infrastructure. Each tenant is a fully independent organization with its own account on Platform Mesh. Each organization has strict requirements that the platform provider cannot access their data or their key governance. The platform provider and the tenant are different legal entities. + +**Why the keychain matters:** Each organization enables OpenKCM at account level independently. Each organization's CMK Controller is scoped entirely to their own account. The platform provider has zero visibility into any tenant's key governance — this is enforced by the Platform Mesh account model and OpenFGA, not just policy. + +**The critical distinction from a single-operator model:** The platform provider does not touch OpenKCM at all — they provide the infrastructure; each tenant brings or enables their own OpenKCM. "Cannot read tenant data" is a structural guarantee of the deployment topology, not a product feature the platform provider configures. + +**What OpenKCM provides (per tenant):** +- Each tenant enables OpenKCM at their account level — CMK Controller scoped to their account only +- Tenant registers their own L1 (BYOK or HYOK) — platform provider has no reference to it +- L2 provisioned for that account, L3 per service — fully isolated from all other tenants +- Kill switch scope: that account only — does not affect other tenants or the platform provider +- Audit logs belong to the tenant — platform provider cannot access them + +**Deployment model:** Each tenant runs their own CMK Controller scoped to their account, L1 in each tenant's own keystore. + +**L4 path:** Tenant's choice — each organization manages their own L4 independently. KMIP self-registration for standard workloads. UI-managed L4 for tenants with per-customer data isolation requirements within their own services. + +**The one-liner:** *A platform provider whose tenants are independent organizations — each owns their own keys, and the provider is structurally excluded from key governance.* diff --git a/docs/use-cases/Delieveries.md b/docs/use-cases/Delieveries.md deleted file mode 100644 index 6cedae1..0000000 --- a/docs/use-cases/Delieveries.md +++ /dev/null @@ -1,121 +0,0 @@ - -# OpenKCM MVP Deliverables - June 2026 - -## Architecture Overview - -The system is designed with a specific fallback mechanism when the CMK (L1) layer is not linked. In this scenario, the internal versioned key serves as the anchor within the Crypto layer. This enables parallel development within two logical systems: **Crypto Layer** and **CMK Layer**. - ---- - -## CMK Service MVP - -**Timeline:** January - June 2026 - -### MVP CMK Goals by End of June 2026: -- ✅ **CMK UI integrated in Platform** - Seamless user interface within platform dashboard -- ✅ **Platform users can enable OpenKCM** - One-click automated deployment -- ✅ **AWS KMS plugin** - Users can connect their AWS KMS keys -- ✅ **Upload L1 keys from AWS KMS** via CMK UI - Import customer master keys -- ✅ **View and enable L1 keys on specific tenants** - Tenant-key assignment interface -- ✅ **Tenant management** - Create, manage, assign keys to tenants - -### CMK Dashboard - Key Management - - -### CMK Core Features: -- **Platform Integration** - Embedded UI with SSO -- **AWS KMS Plugin** - Connect to customer's AWS accounts -- **Key Import Workflow** - Retrieve and display AWS KMS keys -- **Tenant-Key Assignment** - Assign specific keys to specific tenants -- **Key Management Dashboard** - View all imported and platform keys -- **One-Click Enablement** - Automated service deployment from platform - -### CMK Independence: -- **No Crypto Layer dependency** - CMK operates independently -- **Standalone key management** - Manages L1 keys without crypto integration -- **Platform-focused** - UI and tenant management primary goals -- **Future integration ready** - Architecture supports eventual Crypto connection - ---- - -## Crypto Service MVP - - **Timeline:** January - June 2026 - -### MVP Crypto Goals by End of June 2026: -- ✅ **KMIP server implementation** - Basic encrypt/decrypt protocol for MongoDB -- ✅ **Simple tenant key management** - Generate/store keys per tenant -- ✅ **MongoDB integration** - Transparent database encryption via KMIP -- ✅ **Basic tenant isolation** - Separate key storage per tenant -- ✅ **Key generation service** - Create encryption keys for MongoDB collections -- ✅ **Health monitoring** - Service status and basic metrics - -### Crypto Service - MongoDB Encryption Independent - -``` -MongoDB Database - ↓ (KMIP Protocol) -Crypto KMIP Server -├── Tenant Key Generation -├── Simple Key Storage -├── Basic Tenant Isolation -└── MongoDB Integration -``` - -### MongoDB Use Case (Independent Operation): -1. **MongoDB needs encryption** for a collection -2. **MongoDB calls Crypto** via KMIP protocol -3. **Crypto generates tenant-specific key** (no CMK involvement) -4. **Crypto returns key** to MongoDB via KMIP response -5. **MongoDB encrypts collection** transparently -6. **No external dependencies** - fully self-contained - -### Crypto (Krypton) Features: -- **KMIP Protocol Server** - Handle MongoDB key requests -- **Autonomous Key Generation** - Create AES-256 keys for database encryption -- **Tenant Database** - Simple tenant → keys mapping storage -- **MongoDB Direct Integration** - KMIP-based transparent encryption -- **Basic Audit Logging** - Key operation tracking for compliance -- **Service Health Monitoring** - Status checks and basic metrics - -### Crypto Independence: -- **No CMK dependency** - Generates and manages own keys -- **MongoDB-focused** - Direct integration with database encryption -- **Self-contained** - All encryption capabilities built-in -- **Scalable foundation** - Architecture ready for future CMK integration - ---- - -## Parallel Development Strategy - -### Independent Delivery Goals: -- **CMK Team** delivers customer key management and platform integration -- **Crypto Team** delivers working MongoDB encryption capabilities -- **No cross-team dependencies** during MVP phase -- **Both teams deliver complete, usable functionality** - -### Future Integration (Post-MVP): -- **Q3 2026:** Crypto Layer integrates with CMK L1 keys -- **Q4 2026:** Advanced key hierarchy (L1 → L2 → L3 → L4) -- **Q1 2027:** Full OpenKCM integration with external keystores - -### Success Criteria: - -#### CMK Success: -- ✅ Platform users can enable OpenKCM seamlessly -- ✅ Users can import and manage AWS KMS keys -- ✅ Tenant-key assignments work correctly -- ✅ UI integrated smoothly within platform experience - -#### Crypto Success: -- ✅ MongoDB databases encrypt transparently using Crypto keys -- ✅ KMIP protocol handles all standard operations -- ✅ Tenant isolation prevents cross-tenant key access -- ✅ Service operates reliably with proper monitoring - -### Business Value: -- **Immediate Customer Value** - Working encryption and key management -- **Parallel Team Productivity** - No blocking dependencies -- **Risk Mitigation** - Each team delivers independently -- **Future-Ready Architecture** - Integration path clearly defined -- **Compliance Foundation** - Audit logging and security controls in place \ No newline at end of file