CMK service
The CMK service is the core service of the CMK product: the governance control plane for customer keys. Tenants use it to register their root keys, link those keys to the systems that should use them, and control the key lifecycle. CMK holds key metadata and policy, not key material: key operations run in a keystore through plugins, either the keystore the platform provides for the tenant or, for HYOK keys, the customer's own keystore.
Repository: openkcm/cmk
Responsibilities
- Manage customer keys and their key configurations.
- Link systems (the services that consume a key in a region) to a key, switch them to another key, or unlink them.
- Propagate key and system changes to the regional systems.
- Serve the tenants of its CMK region: one CMK runs in each regional deployment and receives its tenants from the central Registry.
- Run approval workflows for sensitive operations.
- Verify the signed client data that ExtAuthZ adds to every API request, with ExtAuthZ's public keys from
clientData.signingKeysPath. - Map the tenant's identity provider groups to CMK roles. See CMK authorization.
Key types
Each tenant gets a dedicated keystore, which CMK takes from a pool of prepared keystores. The pool is kept filled through the keystore provider plugin and the keystore:fill task. BYOK keys are created in this keystore; HYOK keys stay in the customer's own keystore. System-managed keys, generated by the keystore on request, are not available in the current version.
| Key type | Who creates the key material | How CMK uses it |
|---|---|---|
| BYOK (bring your own key) | The customer, outside the provider | The customer imports wrapped key material into the provider through CMK |
| HYOK (hold your own key) | The customer, in their own keystore | CMK links an existing key by its ID in the customer's keystore |
Bring your own key
- CMK asks the keystore provider for import parameters (a wrapping public key and the wrapping algorithm) and returns them to the customer.
- The customer wraps the key material with that public key.
- The customer sends the wrapped material to CMK, which passes it to the provider's import operation.
CMK does not store the key material.
Hold your own key
CMK links an existing key in the customer's keystore. The key must be enabled and of type AES-256. Every five minutes, CMK checks the state of linked HYOK keys and propagates changes, for example a key that the customer disabled.
Key rotation
CMK does not rotate key material itself. Rotation happens in the keystore. CMK can detect new key versions in the provider and then sends a SYSTEM_KEY_ROTATE task to the affected systems. This detection is controlled by a feature flag.
Propagation to regions
CMK sends changes to the systems in each region as tasks, using Orbital over AMQP. In a deployment with Krypton, the CMK-2-Krypton Bridge receives the tasks of its region and carries them out in Krypton.
| Task | Purpose |
|---|---|
KEY_ENABLE, KEY_DISABLE | Enable or disable a key for its systems |
KEY_DELETE, KEY_DETACH | Remove a key, or detach it from its systems |
SYSTEM_LINK, SYSTEM_UNLINK | Start or stop using a key for a system |
SYSTEM_SWITCH | Move a system to another key |
SYSTEM_KEY_ROTATE | Tell a system that its key has a new version |
Tenant onboarding and offboarding jobs arrive from the Registry in the same way.
Processes
CMK is one binary, cmkd, with a subcommand per process. The Helm chart runs each process as its own Deployment, and db-migrator as Jobs before and after every install and upgrade. The API server serves the REST API on port 8081; every process serves its probes and metrics on port 8888.
| Process | Purpose |
|---|---|
api-server | REST API for the CMK UI and API clients |
tenant-manager | Tenant onboarding and offboarding |
event-reconciler | Sends tasks to regional systems and tracks their results |
task-scheduler | Schedules periodic tasks, such as the HYOK state check |
task-worker | Runs scheduled and asynchronous tasks |
db-migrator | Applies database migrations |
REST API
The API is described in an OpenAPI specification in the repository (apis/cmk/cmk-ui.yaml). Its main resources are keys, key configurations, systems, system groups, workflows, tenants and groups.
Storage
- PostgreSQL: one schema per tenant.
- Redis: queue for asynchronous tasks. It holds no key material.
Plugins
CMK uses plugins for keystore operations, keystore management, identity management, notifications, system information and certificate issuing.
User interface
The CMK UI is an OpenUI5 web application that calls the CMK REST API. Users sign in through Session Manager.
Deployment
CMK ships as the Helm chart oci://ghcr.io/openkcm/charts/cmk, whose source is in the charts/cmk directory of the cmk repository. Its values.yaml documents every value, including each configuration key with the processes that read it. The release image ghcr.io/openkcm/images/cmk/cmk-full-plugins includes the AWS KMS keystore plugin and the SCIM identity management plugins; see Plugins.