> For the complete documentation index, see [llms.txt](https://docs.envector.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.envector.io/1.5.x/key-management/managed-kms.md).

# Managed KMS

The managed Key Management Service (KMS) isolates all plaintext key material behind a dedicated service. Plaintext secret keys are never written to disk or stored in object storage: they exist only briefly inside a trusted execution boundary (KMS-TEE) and are zeroized after use. This page details the KMS design; for an overview of enVector's two key models see [Key Management](/1.5.x/key-management/key-management.md). For operations see [KMS Operations](/1.5.x/key-management/managed-kms/kms.md), for rotation and incident response see [Key Rotation & Incident Response](/1.5.x/key-management/managed-kms/key-rotation.md), and for the client API see [KMSClient](/1.5.x/api-reference/kms.md).

## Core design principle: protect the SSS, and everything else follows

**If the Shamir's Secret Shares (SSS) are kept safe, every other key in the KMS is automatically protected.** The SSS is the single secret an operator must manage directly. All other keys — KEK, FHE SecKey, Metadata Key, EncKey, EvalKey — are protected automatically within a Vault-rooted hierarchy of trust.

```
SSS (Vault unseal shares)
 └─► Vault (unsealed → establishes the root of trust)
      └─► KEK (Vault Transit — plaintext never leaves Vault)
           ├─► FHE SecKey    (sealed envelope; decrypted only transiently inside the TEE)
           └─► Metadata Key  (sealed envelope; decrypted only transiently inside the TEE)
                ├─► EncKey  (public key)
                └─► EvalKey (public key)
```

As long as the SSS is not leaked, Vault stays sealed; while Vault is sealed the KEK is unreachable; and without the KEK the sealed FHE SecKey and Metadata Key cannot be decrypted. Operators never need to track or store the individual keys separately. For higher assurance, the SSS can be split N-of-K across multiple custodians.

### Security principles

| Principle                         | How it is applied                                                                                                        | Security effect                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| Single point of secret management | Keep the SSS in air-gapped storage or an HSM; never expose it to online systems during operation                         | Vault stays sealed; the whole key hierarchy is protected     |
| No plaintext key storage          | FHE SecKey and Metadata Key are stored in Vault KV only as KEK-sealed envelopes                                          | No plaintext key exposure even if storage is stolen          |
| No direct KEK custody             | The KEK plaintext never leaves the Vault Transit boundary                                                                | No KEK exposure even if the KMS process is compromised       |
| KEK rotation / rewrap             | Keep the FHE SecKey and Metadata Key; rotate only the KEK version                                                        | Refresh the wrapping layer without re-encrypting data        |
| Execution-boundary separation     | The external-facing KMS is split from the secret-handling KMS-TEE                                                        | No access to secret material if the API layer is compromised |
| Least privilege                   | Per-role AppRole and Vault tokens; only the required paths and operations are allowed                                    | Limited blast radius if a single token is stolen             |
| Token lifecycle                   | Bootstrap issuance, renew loop, `revoke-self` + cache cleanup on shutdown                                                | Reduced risk from long-lived credentials and stale tokens    |
| Transport protection              | TLS/mTLS across KMS ↔ TEE ↔ Vault; certificate keys and the CA private key are mounted with separated scope              | Reduced exposure on the wire and cross-key exposure          |
| Runtime protection                | Plaintext keys are held in memory only at the moment of use and zeroized afterward; secret values are excluded from logs | Reduced leakage via memory dump, swap, or logs               |
| Audit trail                       | Key generation, access, rotation, deletion, permission-denied, and bootstrap events are recorded                         | Basis for compromise detection and forensic analysis         |

## Security architecture

### Components and responsibilities

| Component               | Primary responsibility                                                                  | Security meaning                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **KMS** (control plane) | gRPC/HTTP API, JWT verification, RBAC, tenant/key-scope checks, public-key store access | Receives external requests; holds no Vault token or raw key material                                   |
| **KMS-TEE**             | KeyGen, Rotate, Metadata, ScoreDecryptor, MetadataCipher                                | Execution boundary that handles secret material; per-role Vault tokens live only inside this container |
| **Vault KV**            | Stores sealed FHE SecKey, sealed Metadata Key, and key metadata                         | No plaintext keys — envelopes only                                                                     |
| **Vault Transit**       | KEK generation, encrypt/decrypt, rewrap, rotate                                         | KEK provider; KEK plaintext never leaves the boundary                                                  |
| **Object Storage**      | Stores public-key material (EncKey, EvalKey)                                            | Public keys are not secrets, so they live in the Public Key Storage separately                         |

The control plane (`KMS`) and the TEE worker (`KMS-TEE`) run as **separate containers**. Only KMS-TEE holds Vault tokens and touches secret material; the control plane never does.

### Key request flows

All flows assume that secret-key plaintext never crosses the cryptographic boundary. The KeyManager service directs work and tracks state, while plaintext secret keys are generated and used only inside KMS-TEE. Vault Transit requests are protected with TLS, and Vault storage holds only sealed secret keys.

* **KeyGen** — the TEE generates the FHE SecKey / Metadata Key, seals them with the KEK via Vault Transit, and persists only the sealed envelopes to Vault KV; the derived public keys (EncKey, EvalKey) are written to Public Key Storage.
* **Key Rotate** — see [Key Rotation & Incident Response](/1.5.x/key-management/managed-kms/key-rotation.md): the KEK version is rotated and the sealed envelopes are rewrapped, keeping the underlying secret keys unchanged.

## Infrastructure dependencies

The KMS does not run standalone; it depends on several components for key sealing, certificates, and audit. The separation of the control plane (KMS) from the TEE worker (KMS-TEE) is central to the dependency model.

### Secret Manager (Vault/OpenBao)

The KMS's Secret Manager — backed by HashiCorp Vault (or OpenBao) — is its secret-key store. Secret keys and metadata keys are **never** written to object storage — they are sealed only into the Secret Manager. The **only** subject that accesses it is the KMS-TEE container; the control plane holds no Vault token.

* **Transit engine** — encrypts/decrypts (seals/unseals) the homomorphic-encryption secret keys
* **Secret engine** — stores secret-key metadata and the sealed secret keys
* **AppRole auth** — issues per-role tokens for the five roles (`TEE_KEYGEN`, `TEE_ROTATE`, `TEE_METADATA`, `TEE_SCORE_DECRYPTOR`, `TEE_METADATA_CIPHER`) for least-privilege separation
* **Storage backend** — Vault file storage (`/vault/file`, volume `kms-vault-data`); sealed keys and metadata are persisted here. **Deleting the volume loses everything.**
* **Bootstrap** — a one-time init/bootstrap unseals Vault (Shamir shares + root token) and derives the five AppRole tokens; the root token and shares exist only transiently in control-plane memory and are not left on disk.

> The secret store is backend-neutral. OpenBao can be used in place of Vault via an image swap (it is exposed under the `vault` alias); see the KMS deployment overlays.

### Step-CA

A local certificate authority for TLS/mTLS. At deploy time a `cert-init` container sends a CSR and receives certificates.

* **Issued certificates** — the CA bundle `/certs/ca/root_ca.crt` (shared read-only by Vault, KMS-TEE, KMS), plus the Vault server cert, the KMS API server cert, and the KMS-TEE client cert (for mTLS with Vault)
* **Vault mTLS** — with the TLS `.hcl` config, KMS-TEE authenticates using `KMS_VAULT_CACERT` / `CLIENT_CERT` / `CLIENT_KEY`
* Replaceable with an organization's internal CA

### Identity provider (Keycloak)

The KMS shares the enVector system's OIDC identity provider (Keycloak); it can be replaced with an existing organization Keycloak or OIDC-compatible IdP. It issues signed JWTs carrying the `envector_roles`, `tenant_id`, and `principal_id` claims. See [Keycloak / OIDC](/1.5.x/operations-and-management/authentication/keycloak.md).

| Role            | KMS capability                                                                |
| --------------- | ----------------------------------------------------------------------------- |
| `pubkey-reader` | `kms.pubkey.read`, `kms.pubkey.list`                                          |
| `keymanager`    | above + `kms.tee.generate`, `kms.tee.key.rotate`, `kms.tee.key.metadata.read` |
| `topk`          | `kms.tee.score.decrypt`, `kms.tee.metadata.cipher`                            |
| `security`      | all of the above (full access)                                                |

### Object Storage (MinIO)

The KMS uses object storage as its Public Key Storage. Secret keys and metadata keys are **never** stored here. The accessing subject is the KMS control plane.

### Audit-dedicated messaging

The audit service uses a dedicated messaging stack — Redpanda (a lightweight Kafka-compatible message queue) and Vector (log agent). The pipeline is `file/stdout → Vector → Redpanda (topic envector.kms.audit.events.v1) → audit service → S3 (kms-audit bucket, separate from the public-key storage)`. See [Audit](/1.5.x/operations-and-management/audit.md).

See the detailed APIs in [KMSClient](/1.5.x/api-reference/kms.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.envector.io/1.5.x/key-management/managed-kms.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.