> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kvelden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Key Management

> Connect your own KMS, provision CMKs, run key health checks, and manage encryption policies — all without Kvelden ever holding your master keys.

## Key management modes

| Mode                          | Who holds the master key     | Best for                                                |
| ----------------------------- | ---------------------------- | ------------------------------------------------------- |
| **Platform-managed**          | Kvelden's HSM infrastructure | Getting started quickly; always active alongside BYOK   |
| **BYOK** (Bring Your Own Key) | Your cloud KMS (AWS KMS)     | AWS customers who want full key custody                 |
| **HYOK** (Hold Your Own Key)  | Your on-premise HSM via KMIP | Air-gapped, regulated environments (Thales CipherTrust) |

<Info>
  These modes control **who holds the master (wrapping) key** for envelope
  encryption. In BYOK/HYOK the key lives in your own KMS/HSM; in Platform-managed
  it lives in Kvelden's HSM. In all modes files are encrypted with a per-file key —
  but because Enclave can reach the wrapping key, it can decrypt server-side to
  serve your downloads and any workflows you enable (DLP, signing). For content
  that Enclave itself can **never** read, use a
  [Zero-Knowledge or ZK-Strict room](/security/zero-knowledge), where keys are held
  only on your devices.
</Info>

Key Management is available under **Security → Key Management**. Only users with the **Owner** or **Security Officer** role can access this section.

***

## Prerequisites

Before connecting a KMS:

* **Owner** or **Security Officer** role in Enclave
* Network connectivity between your Enclave deployment and the KMS endpoint (relevant for private-cloud and on-premise deployments)

For provider-specific prerequisites see the individual provider pages linked below.

***

## Key ownership & least-privilege permissions

Enclave is **use-only**: it wraps and unwraps file DEKs with your keys, but it
**never creates, disables, rotates, or deletes** a key in your KMS. You create keys
in your own KMS console (setting their key policy, rotation schedule, and grants)
and **adopt** them into Enclave. Your KMS custodian owns the full key lifecycle —
this is the separation of duties auditors expect (SOC 2, ISO 27001, PCI DSS).

Because Enclave never manages key state, the credentials you grant it can be scoped
to the minimum needed to encrypt and decrypt:

<Tabs>
  <Tab title="AWS KMS">
    | Allow                                                                 | Do **not** grant                                                                                                          |
    | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
    | `kms:Encrypt` · `kms:Decrypt` · `kms:DescribeKey` · `kms:ListAliases` | `kms:CreateKey` · `kms:CreateAlias` · `kms:ScheduleKeyDeletion` · `kms:DisableKey` · `kms:EnableKey` · `kms:PutKeyPolicy` |

    Scope the statement to the specific key ARN(s) you adopt.
  </Tab>

  <Tab title="Thales CipherTrust (KMIP)">
    | Allow                                               | Do **not** grant                                       |
    | --------------------------------------------------- | ------------------------------------------------------ |
    | `Encrypt` · `Decrypt` · `Locate` · `Get Attributes` | `Create` · `Destroy` · `Revoke` · `Register` · `ReKey` |
  </Tab>
</Tabs>

<Note>
  A key you adopt must already exist and be usable by the credentials/identity you
  configured. Archiving a key in Enclave only stops Enclave from *using* it — it does
  not touch your KMS. To truly retire a key, do so in your KMS after migrating any
  files still encrypted under it.
</Note>

***

## BYOK Connections

The **BYOK Connections** tab lists all KMS connections configured for your organisation. Click a connection name to view its provisioned keys and connection details.

### Adding a connection

1. Navigate to **Security → Key Management → BYOK Connections**
2. Click **Add KMS Connection**
3. Select a provider and fill in the required fields
4. Click **Save** — Enclave stores the configuration and runs an automatic connection test

<Note>
  The wizard does not ask you to configure a key scope. Scopes are assigned separately through **Encryption Policies** — see [Encryption Policies](#encryption-policies).
</Note>

### Connection statuses

| Status       | Meaning                                                        |
| ------------ | -------------------------------------------------------------- |
| **Active**   | Connection verified; encryption and decryption are operational |
| **Pending**  | Connection test in progress                                    |
| **Failed**   | Last test failed; check credentials and key permissions        |
| **Disabled** | Manually disabled; no encryption operations are accepted       |

Use the **Test Connection** button on any row to re-verify at any time.

### KMS providers

<CardGroup cols={2}>
  <Card title="AWS KMS" icon="aws" href="/enclave/kms/aws-kms">
    BYOK via IAM Role (recommended) or static credentials. Supports symmetric CMKs in any AWS region.
  </Card>

  <Card title="Thales CipherTrust" icon="shield-halved" href="/enclave/kms/thales-ciphertrust">
    HYOK via KMIP over mutual TLS. For on-premise HSMs and air-gapped environments.
  </Card>
</CardGroup>

<Note>
  **Azure Key Vault** and **GCP Cloud KMS** integrations are on the roadmap. Contact [support@kvelden.com](mailto:support@kvelden.com) if either is a requirement for your deployment.
</Note>

### Disabling and deleting connections

* **Disable** — stops Enclave from using the connection for new operations. Existing encrypted data is unaffected.
* **Delete** — permanently removes the connection. Enclave will block deletion if any files are still encrypted under this KMS. Migrate or delete those files first.

<Note>
  Disable a connection before deleting it. You cannot delete an active connection.
</Note>

***

## Platform KMS

The **Platform KMS** tab shows KMS connections managed by the Kvelden platform team on behalf of your organisation, backed by Kvelden's HSM infrastructure. A platform KMS appears here — and becomes selectable in your **Encryption Policies** — **only once the platform team has provisioned a dedicated key for your organisation**. Until then, no platform KMS option is shown.

### How it works

* Once provisioned for your organisation, the platform KMS remains available even after you add your own BYOK connection, and stays visible under this tab.
* You **cannot disable or delete** a platform KMS connection — these are managed exclusively by the Kvelden platform team.
* Adding a BYOK connection does not deactivate the platform KMS. Files uploaded before BYOK was configured remain wrapped under the platform key until you run a **DEK Key Migration** to move them.

### What it protects

Platform KMS keys wrap the DEKs of all files that do not yet have a BYOK encryption policy applied. This ensures every file in your vault has a valid key wrapping layer from day one, even before any BYOK configuration is in place.

### Coexistence with BYOK

Platform KMS and BYOK connections operate side by side. Once you configure a BYOK connection and set an encryption policy, new file uploads use your BYOK key. Existing files continue to use the platform key until migrated. You control the migration timeline — see [DEK Key Migration](#dek-key-migration).

<Info>
  Platform KMS connections are managed by the Kvelden platform team. Disable, delete, and test actions are not available to tenant users.
</Info>

***

## Provisioned Keys

Each BYOK KMS connection can have one or more **CMKs (Customer Managed Keys)** registered against it. A provisioned key is a reference to a specific key ID in your external KMS — Enclave uses it to wrap and unwrap file DEKs.

Click any **connection name** in the BYOK Connections table to open the **Connection Detail** page, which shows:

* Connection metadata (protocol, org unit, creation date, connection ID)
* All provisioned keys for that connection, along with their current health status

### Provisioning a key

Provisioning **adopts a key you already created in your KMS** — Enclave does not
create keys. Create the CMK in your AWS KMS / CipherTrust console first, grant it
the [use-only permissions](#key-ownership-least-privilege-permissions) above, then:

1. Click **Provision a Key**
2. Provide **either** identifier (Enclave resolves and validates the other against your KMS):

| Field         | Description                                                                               |
| ------------- | ----------------------------------------------------------------------------------------- |
| Key Name      | The stable key name — CipherTrust `Name` (rotation-safe, preferred) or the AWS KMS alias. |
| Key ID        | The opaque identifier — Thales KMIP UUID, or the AWS key ID / ARN.                        |
| Display label | A friendly name shown in Enclave lists (optional, cosmetic).                              |

At least one of **Key Name** / **Key ID** is required. For Thales the **Name** is
authoritative and rotation-safe: the current version's name is always stored so a
later rotation is followed automatically.

3. Click **Adopt Key** — Enclave validates the key with a test wrap/unwrap and registers it

<Note>
  Scope and encryption policy assignment are managed separately in **Encryption Policies** — see [Encryption Policies](#encryption-policies).
</Note>

<Note>
  **Rotating a Thales key?** When a CipherTrust key is provisioned with its Key Name, Enclave follows rotations automatically: new data uses the new version and older data stays readable. Use the [Key Rotation](#key-rotation) panel to move existing files onto the current version on your schedule. Full lifecycle and safety runbook: [Thales CipherTrust → Key rotation](/enclave/kms/thales-ciphertrust#key-rotation-ciphertrust-key-versioning).
</Note>

### Key Health Check

The **Run Health Check** button on the connection detail page performs a live wrap-and-unwrap test against every provisioned key in that connection, in sequence. Use this to verify your KMS is reachable and that all keys are operational before a file operation or a scheduled audit.

**Running a check**

1. Open the connection detail page (**Security → Key Management → BYOK Connections** → click a connection name)
2. Click **Run Health Check**
3. Enclave tests each key in turn — a progress indicator is shown per row as the check runs
4. When all keys have been tested, a **Health Summary** banner appears at the top of the key table

**Health states**

| State           | Colour | Meaning                                                                                    |
| --------------- | ------ | ------------------------------------------------------------------------------------------ |
| **Healthy**     | Green  | Wrap and unwrap succeeded; response times are shown (e.g. `Wrap 60ms / Unwrap 38ms`)       |
| **Disabled**    | Amber  | The key exists in the KMS but is disabled; decrypt operations will fail for affected files |
| **Deleted**     | Amber  | The key has been deleted from the KMS; all files encrypted under it are unreadable         |
| **Unreachable** | Red    | Enclave could not reach the KMS endpoint, or the key operation returned an error           |
| **Inactive**    | Grey   | The key is registered but not active — no encryption policy is currently assigned to it    |

<Warning>
  A **Deleted** or **Unreachable** key means files encrypted under that key cannot be decrypted. Resolve the issue in your KMS and re-run the health check to confirm recovery.
</Warning>

**Health Summary banner**

| Overall status                           | Condition                                   |
| ---------------------------------------- | ------------------------------------------- |
| **All Keys Healthy**                     | Every tested key returned Healthy           |
| **Warning**                              | One or more keys are Disabled or Inactive   |
| **Critical — Immediate Action Required** | One or more keys are Deleted or Unreachable |

### Health Report

Once a health check has been run, a **Download Report** button appears alongside **Run Health Check**. Clicking it generates and downloads a branded PDF health report named `kms-health-report-{connection}-{date}.pdf`.

| Section                           | Contents                                                                                                                  |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Cover page**                    | Connection name, provider, protocol, tenant, tested-by, and tested-at timestamp; 5-KPI summary strip; overall status pill |
| **Key details**                   | One row per provisioned key — external key ID, alias, status, org unit, policy status, and health result                  |
| **Issue detail cards**            | For every non-healthy key, the specific error, stage, or reason returned by the KMS                                       |
| **Notes and recommended actions** | Per-state guidance on how to resolve each issue                                                                           |
| **Attestation block**             | Space for a KMS administrator signature, suitable for compliance audit evidence                                           |

### Removing a key registration

1. Click the **Actions** menu on the key row
2. Select **Remove Key Registration**

<Warning>
  Removing a key registration while files are still encrypted under it will make those files unreadable. Migrate all files to a different key first using **DEK Key Migration** before removing the old key.
</Warning>

***

## Encryption Policies

**Encryption Policies** is a dedicated tab within **Security → Key Management** that controls which CMK is used for new file encryptions at each scope level. Policies decouple key provisioning from key selection — you can provision many keys across multiple connections and choose precisely which one is active for each scope.

### Policy table

| Column             | Description                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------- |
| **Scope**          | The part of the organisation this policy covers (Tenant-wide, Domain, or Department)          |
| **KMS Connection** | The BYOK connection that provides the CMK                                                     |
| **Pinned CMK**     | The specific provisioned key selected for this scope; blank indicates "First active" fallback |
| **Provider**       | The KMS provider (AWS KMS, Thales CipherTrust, etc.)                                          |
| **Status**         | Whether the underlying connection is Active, Failed, or Disabled                              |

### Tenant default key

The top of the Encryption Policies page shows a **Tenant Default Key** status card:

* **Active** — a tenant-wide policy is set; all unscoped files use this CMK for new encryptions
* **No policy set** — new uploads fall back to the Platform KMS until a BYOK policy is assigned

### Assigning a policy

1. Click **Assign Policy**
2. **Step 1** — Select scope level (Tenant-wide, Domain, or Department) and the KMS connection
3. **Step 2** — Pick a specific provisioned key, or leave as **First active**
4. Click **Assign** to save

<Note>
  Only one policy per scope can be active at a time. Assigning a new policy to an existing scope replaces the current one immediately. Existing encrypted files are not affected.
</Note>

### Pinned CMK vs First active

| Mode             | Behaviour                                                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| **Pinned CMK**   | New file encryptions use exactly this key — deterministic and auditable. Recommended for regulated scopes. |
| **First active** | Enclave resolves to the first healthy, active key at encryption time. More resilient to key rotation.      |

### Key scopes

| Scope           | Applies to                                                    |
| --------------- | ------------------------------------------------------------- |
| **Tenant-wide** | All files across the entire organisation (broadest)           |
| **Domain**      | Files belonging to a specific domain org unit                 |
| **Department**  | Files belonging to a specific department org unit (narrowest) |

A department-scoped policy overrides a domain-scoped policy, which overrides the tenant-wide policy.

### Removing a policy

Click the **Delete** icon on a policy row to remove it. New encryptions in that scope fall back to the next broader scope policy (or to the Platform KMS if none exists).

<Warning>
  Removing a policy does not affect files already encrypted under that policy's key. It only affects which key is used for new encryptions going forward.
</Warning>

***

## DEK Key Migration

DEK Key Migration lets you re-wrap all file encryption keys from one key or KMS vendor to **another** key — for example moving from the Platform KMS to your BYOK key, or from AWS KMS to Thales CipherTrust. File content is never re-encrypted or moved.

**What changes:** The wrapped DEK stored for each file (the key wrapping layer only).\
**What does not change:** File ciphertext, storage location, permissions, or metadata.

Files remain fully accessible during migration.

<Note>
  **Migration vs. Rotation.** Use **DEK Key Migration** to move DEKs to a *different* key or vendor. Use [Key Rotation](#key-rotation) to move DEKs onto a *newer version of the same key* after you rotate it in your KMS.
</Note>

### Running a migration

<Steps>
  <Step title="Open DEK Key Migration">
    Navigate to **Security → Key Management → BYOK Connections**. The **DEK Key Migration** panel appears below the connections table.
  </Step>

  <Step title="Select source and target KMS">
    Use the **From** and **To** selectors to choose the source KMS and the target KMS.
  </Step>

  <Step title="Preview the migration">
    Click **Preview Migration**. Enclave counts:

    | Counter        | Meaning                                                    |
    | -------------- | ---------------------------------------------------------- |
    | Will Migrate   | Files eligible for re-wrapping                             |
    | In Use         | Files currently open by users; retried automatically       |
    | ZK Files       | Zero-knowledge encrypted files; skipped (client-held keys) |
    | Pending Upload | Files mid-upload; skipped until upload completes           |
  </Step>

  <Step title="Start the migration">
    Review the plan and click **Start Migration**. Enclave re-wraps DEKs in the background — you can navigate away and return to check progress.
  </Step>
</Steps>

### Monitoring progress

| Indicator    | Meaning                                      |
| ------------ | -------------------------------------------- |
| **Migrated** | Files successfully re-wrapped so far         |
| **Skipped**  | ZK or pending-upload files (permanent skips) |
| **Failed**   | Files that could not be re-wrapped           |
| **ETA**      | Estimated time remaining                     |

### Pausing, resuming, and cancelling

| Action           | Effect                                                                     |
| ---------------- | -------------------------------------------------------------------------- |
| **Pause**        | Stops processing new files; already-migrated files keep their new wrapping |
| **Resume**       | Continues from where it left off                                           |
| **Retry failed** | Re-attempts files that failed in a previous run                            |
| **Cancel**       | Permanently stops the migration; already-migrated files are unaffected     |

### Migration History

Click **View History** to see all past migrations — route, status, initiated-by, file counts, and duration.

***

## Key Rotation

Key Rotation re-wraps the data keys of files that are still bound to an **older version** of a key onto its **current version**, after you rotate that key in your KMS. Like migration, it re-wraps the DEK only — file content is never touched and files stay readable throughout.

<Note>
  **Rotation vs. Migration.** Rotation stays on the *same* key and just moves files onto its newest version. [DEK Key Migration](#dek-key-migration) moves DEKs to a *different* key or KMS vendor.
</Note>

Key Rotation currently supports **Thales CipherTrust** keys provisioned with their **Key Name** (wrap-by-name). AWS KMS rotates its backing keys automatically and transparently, so no action is required there — AWS keys do not appear in this panel. For the full rotation lifecycle and safety runbook, see [Thales CipherTrust → Key rotation](/enclave/kms/thales-ciphertrust#key-rotation-ciphertrust-key-versioning).

### When to use it

After you rotate a key in CipherTrust Manager, Enclave automatically wraps *new* data with the new version and notifies your Owners and Security Officers. Existing files stay readable on their original versions. Run a rekey when you want to move that existing data onto the current version — for example, before retiring an old key version in CipherTrust Manager.

### Running a rekey

<Steps>
  <Step title="Open Key Rotation">
    Navigate to **Security → Key Management → BYOK Connections**. The **Key Rotation** panel appears below the DEK Key Migration panel.
  </Step>

  <Step title="Select the key">
    Choose the CipherTrust key from the **Key** selector. Only Thales keys configured with a Key Name appear here.
  </Step>

  <Step title="Review the status">
    Enclave shows how the key's files are distributed across versions:

    | Counter          | Meaning                                                          |
    | ---------------- | ---------------------------------------------------------------- |
    | On older version | Files still wrapped by a superseded version — the rekey worklist |
    | Already current  | Files already on the current version                             |
    | In Use           | Files currently open by users; retried automatically             |
    | Skipped          | Zero-knowledge or pending-upload files (not re-wrappable here)   |
  </Step>

  <Step title="Start the rekey">
    If any files are on an older version, click **Rekey to current version** and confirm. Enclave re-wraps them in the background — you can navigate away and return to check progress.
  </Step>
</Steps>

<Warning>
  Keep the older key versions **enabled for unwrap** in CipherTrust Manager until the rekey reports **0 files on older versions**. Deactivating or destroying a version that still wraps live data makes those files permanently unreadable.
</Warning>

### Monitoring, pausing, and history

The Key Rotation panel exposes the same live progress and controls as DEK Key Migration — **Rekeyed / In Use / Skipped / Failed** counters, an ETA, and **Pause**, **Resume**, **Retry failed**, and **Cancel** actions. Click **View History** for past rekeys.

***

## Required roles

| Action                              | Required role           |
| ----------------------------------- | ----------------------- |
| View KMS connections                | Owner, Security Officer |
| Add / edit / delete connections     | Owner, Security Officer |
| Test connections                    | Owner, Security Officer |
| Provision / remove keys             | Owner, Security Officer |
| Run key health check                | Owner, Security Officer |
| Download health report              | Owner, Security Officer |
| Assign / remove encryption policies | Owner, Security Officer |
| Start / manage DEK migration        | Owner, Security Officer |
| View migration history              | Owner, Security Officer |
| Start / manage key rotation (rekey) | Owner, Security Officer |
| View rotation history               | Owner, Security Officer |