> ## 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.

# Thales CipherTrust

> Connect Thales CipherTrust Manager as a HYOK provider via KMIP over mutual TLS — Enclave never holds your HSM admin credentials or master key material.

## Overview

Thales CipherTrust Manager integration uses the **KMIP (Key Management Interoperability Protocol)** over mutual TLS. Enclave presents a client certificate issued by your CipherTrust Manager, and all key operations (wrap / unwrap) happen inside the HSM. Master key material never leaves your infrastructure.

This integration is classified as **HYOK (Hold Your Own Key)** — the master key is retained entirely on your hardware.

***

## Prerequisites

* **CipherTrust Manager 2.x or later**, network-reachable from your Enclave deployment on the KMIP port (default `5696`)
* A **KMIP client identity** (certificate + private key) issued for Enclave by your CipherTrust Manager — see [Step 1](#step-1--create-a-kmip-client-identity-in-ciphertrust-manager) below
* A **symmetric AES-256 key** created in CipherTrust Manager — this becomes the CMK
* The **CipherTrust Manager CA certificate** (or intermediate chain) for TLS peer verification
* **Owner** or **Security Officer** role in Enclave

***

## Setup

### Step 1 — Create a KMIP client identity in CipherTrust Manager

1. Log in to **CipherTrust Manager** as an administrator
2. Navigate to **KMIP → Client Profiles** → **Create Client Profile**
   * Protocol: KMIP 1.x or 2.x (Enclave supports both)
   * Authentication method: Certificate
3. Under **Client Certificates**, click **Add Client** and generate or import a certificate for Enclave
4. Export the client certificate and private key as **PEM files** — you will upload these to Enclave in Step 3

<Note>
  CipherTrust Manager calls these "KMIP clients" or "KMIP identities". The certificate identifies Enclave to the HSM — treat the private key with the same care as any service credential.
</Note>

### Step 2 — Create a symmetric AES-256 key

1. In CipherTrust Manager, navigate to **Keys → Create Key**
2. Configure:

| Setting    | Value                                        |
| ---------- | -------------------------------------------- |
| Algorithm  | AES                                          |
| Key size   | 256 bits                                     |
| Usage mask | Encrypt, Decrypt, Wrap Key, Unwrap Key       |
| Name       | A descriptive name (e.g. `enclave-cmk-prod`) |

3. Note the **Key ID** shown after creation — you will enter this in Enclave as the CMK ID

### Step 3 — Configure in Enclave

1. Navigate to **Security → Key Management → BYOK Connections**
2. Click **Add KMS Connection** → select **Thales CipherTrust**
3. Fill in the connection fields:

| Field              | Value                                                  |
| ------------------ | ------------------------------------------------------ |
| KMIP Endpoint      | `your-hsm-host:5696` (hostname or IP, with port)       |
| Client Certificate | PEM-encoded client certificate from Step 1             |
| Client Key         | PEM-encoded client private key from Step 1             |
| CA Certificate     | PEM-encoded CipherTrust CA certificate (or full chain) |
| CMK ID             | Key ID (UUID) of the current key version from Step 2   |

4. Click **Save** — Enclave establishes the mutual TLS connection and runs a test wrap/unwrap against the CMK

5. When you **provision the CMK** against this connection (Step in [Key Management](/enclave/key-management#provisioned-keys)), also supply the key's **CipherTrust Key Name** (the stable `Name` attribute from Step 2). This enables [automatic key-rotation tracking](#key-rotation-ciphertrust-key-versioning) — strongly recommended for any key you intend to rotate.

<Note>
  Enclave never stores or exposes HSM admin credentials. The client certificate authorises key operations only — it does not grant administrative access to CipherTrust Manager.
</Note>

<Note>
  **CMK ID vs. Key Name.** CipherTrust identifies each *version* of a key by a distinct UUID (the CMK ID) but keeps the human-readable **Name** constant across rotations. Enclave records the CMK ID as the immutable base version (so data wrapped by it stays decryptable forever) and uses the Name to follow rotations forward. Supply both.
</Note>

***

## Network requirements

Enclave must be able to reach your CipherTrust Manager over TCP on the KMIP port:

| Protocol  | Port           | Direction                     |
| --------- | -------------- | ----------------------------- |
| TCP / TLS | 5696 (default) | Enclave → CipherTrust Manager |

For private-cloud and on-premise deployments, ensure the firewall or security group allows outbound connections from the Enclave server to the CipherTrust Manager host on this port.

<Warning>
  If the Enclave server is air-gapped or behind a strict egress policy, the connection test will fail with a TCP timeout. Verify connectivity with a manual TCP probe (`nc -zv your-hsm-host 5696`) before adding the connection in Enclave.
</Warning>

***

## Rotating the client certificate

When your KMIP client certificate approaches expiry:

1. In CipherTrust Manager, generate a new client certificate for the Enclave KMIP client identity
2. In Enclave, edit the existing Thales CipherTrust connection and replace the **Client Certificate** and **Client Key** fields with the new PEM files
3. Click **Save** — Enclave re-tests the connection with the new certificate
4. Revoke the old certificate in CipherTrust Manager once the connection is confirmed active

***

## Key rotation (CipherTrust key versioning)

CipherTrust Manager rotates a key by creating a **new version**: the key keeps its `Name` but the new version gets a fresh UUID, and only the newest version is `Active`. Enclave tracks this end to end so that **new data uses the new version automatically** while **older data stays readable against the exact version that wrapped it** — no bulk re-encryption is forced, and nothing is ever left undecryptable.

### How it works

<Steps>
  <Step title="Wrap by name">
    When a key is provisioned with its **CipherTrust Key Name**, every wrap resolves the currently-active version by name (via KMIP `Locate`) instead of targeting a fixed version UUID. New file keys are therefore always wrapped by the newest version, the moment CipherTrust makes it active.
  </Step>

  <Step title="Per-DEK version binding">
    Each wrapped data-encryption key records the exact key-version UUID that wrapped it. At read time Enclave unwraps against *that* version — so a file wrapped last year decrypts against last year's version even after several rotations.
  </Step>

  <Step title="Automatic detection">
    The first wrap after a rotation observes the new version. Enclave records the new version in the key's history, raises a **security notification** to Owners and Security Officers, and writes a tamper-evident **audit event** (`kms.key.rotation_detected`).
  </Step>

  <Step title="Rewrap on your schedule">
    Existing files keep working on their original versions. When you want to consolidate them onto the current version, run a **rewrap-to-current** job (below). It is never required for correctness — only for retiring old versions.
  </Step>
</Steps>

### Rotating a key — runbook

<Steps>
  <Step title="Rotate in CipherTrust Manager">
    Create a new version of the key (**Keys → your key → Rotate**, or via your scheduled rotation policy). The `Name` stays the same; a new active version UUID is created.
  </Step>

  <Step title="Confirm detection in Enclave">
    Upload or wait for one new file under the key's scope, then check **Security → Key Management**. The key shows the new current version, and Owners/Security Officers receive a "key rotation detected" notification. The event also appears in **Security → Audit Logs**.
  </Step>

  <Step title="Rewrap existing data onto the new version">
    On the provisioned key, open the actions menu and choose **Rewrap to current version**. Enclave shows how many files are still on an older version, then migrates them in the background — unwrapping each DEK against its recorded version and re-wrapping it against the current one. Plaintext DEKs never leave the HSM boundary, and files remain readable throughout.
  </Step>

  <Step title="Only then, deactivate old versions">
    Wait until the rewrap job reports **0 files on older versions** before you deactivate — and never before you **destroy** — any superseded version in CipherTrust Manager. Destroying a version that still wraps live DEKs is a **crypto-shred**: those files become permanently undecryptable.
  </Step>
</Steps>

<Warning>
  **Destroying a key version is irreversible.** A superseded version must remain *enabled for unwrap* in CipherTrust Manager until a rewrap job has moved every file off it (the console reports **0 files on older versions**). Deactivating or destroying it earlier will make the affected files unreadable — this is by design and cannot be recovered by Enclave or Kvelden.
</Warning>

<Note>
  **Crypto-shredding on purpose.** The same mechanism lets you *intentionally* render data unrecoverable: destroy the key version that wraps it and the ciphertext can never be unwrapped again. Use this only when you mean it (e.g. right-to-erasure workflows), and only for versions no live data depends on.
</Note>

### Requirements & scope

* Rotation tracking and rewrap-to-current require the key to be provisioned **with a CipherTrust Key Name** (wrap-by-name). Keys registered by version UUID only still work, but new versions are not followed automatically.
* Rewrap covers standard server-side encrypted files. **Zero-Knowledge (HYOK-ZK) files are skipped** — their DEKs are wrapped client-side and are re-keyed through the room's key-rotation flow instead.
* Rewrap is available to **Owner** and **Security Officer** roles and requires the **BYOK** infrastructure entitlement.

***

## After connecting

Once saved and showing **Active** status, provision the CMK against this connection and assign an Encryption Policy to activate key usage. See [Key Management](/enclave/key-management#provisioned-keys) for details.