> ## 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.
# KMS Configuration
> Configure the Key Management System that the Enclave appliance uses to wrap and unwrap file encryption keys — required before users can upload files.
This guide is for the person who deployed the Enclave appliance and completed first-boot setup. That account has access to **Admin → Platform Infra** to configure infrastructure. If you are an organisation owner setting up your own BYOK keys, see [Key Management](/enclave/key-management) instead.
## Why configure a platform KMS
The appliance requires a KMS to wrap the DEKs (Data Encryption Keys) that protect every uploaded file. Without an active KMS connection, the appliance cannot process file uploads.
| Provider | Best for |
| ---------------------- | ------------------------------------------------------------------------- |
| **AWS KMS** | Appliances with outbound HTTPS access to AWS; strongest cloud key custody |
| **Thales CipherTrust** | Air-gapped or on-premise environments with an existing HSM |
***
## What the KMS admin panel shows
**Admin → Platform Infra → KMS** is organised into three areas:
* **Connections** — each KMS backend you have added (AWS KMS, Thales CipherTrust), with its status and role badges.
* **Roles** — which connection performs each platform key job (see below).
* **Tenant keys** — the per-organisation encryption keys provisioned on each connection.
## KMS roles
A KMS connection can hold up to three distinct roles. They are independent: one connection can hold several, or you can split them across connections — for example **AWS KMS for platform secrets and Thales CipherTrust for tenant workload keys** at the same time.
| Role | What it protects | Allowed providers |
| ------------------------ | ----------------------------------------------------- | ----------------------------------------------------- |
| **Platform secrets** | Encrypts stored platform credentials and keys at rest | AWS KMS, or the appliance master key — **not** Thales |
| **License signing** | The key that signs deployment licences | AWS KMS |
| **Tenant workload keys** | Per-organisation keys that wrap file DEKs | Any connection (AWS or Thales) |
You can keep **multiple KMS connections active at the same time**. Activating one connection no longer disables the others — disable a connection explicitly when you no longer need it.
***
## AWS KMS — end to end
### Step 1 — Create a Customer Managed Key in AWS KMS
1. Sign in to the **AWS Console** → navigate to **KMS → Customer managed keys**
2. Click **Create key**
3. Configure:
| Setting | Value |
| ------------------- | ------------------- |
| Key type | Symmetric |
| Key usage | Encrypt and decrypt |
| Key material origin | KMS (AWS-generated) |
4. Add an alias (e.g. `enclave-platform-cmk`) and an optional description
5. On the **Key administrators** step, add your IAM user or role as a key administrator (so you can manage it later)
6. On the **Key usage permissions** step, leave this blank for now — you will grant access via an IAM policy in a later step
7. Click **Finish** — note the **Key ARN** from the key detail page; you will enter this in Enclave
The CMK must be in the same AWS region where you plan to configure the connection. You can use the same CMK for both the platform KMS and the secrets encryption key.
***
### Choose your authentication method
The appliance runs on VMware and has no EC2 instance profile. Two options are available:
The appliance authenticates using a dedicated IAM user and then assumes a role that holds the KMS permissions. The role can be rotated or restricted independently of the user credentials.
***
**Step 2 — Create a dedicated IAM user for the appliance**
1. In the AWS Console, go to **IAM → Users → Create user**
2. User name: `enclave-appliance` (or any name you prefer)
3. On the **Set permissions** step, do not attach any permissions — click **Next**
4. Click **Create user**
5. Open the new user → **Security credentials** tab → **Create access key**
6. Choose **"Application running outside AWS"** → click **Next** → **Create access key**
7. **Save the Access Key ID and Secret Access Key** — you will need these in Step 5
***
**Step 3 — Create an IAM role for KMS access**
1. Go to **IAM → Roles → Create role**
2. Trusted entity type: **AWS account** → **This account** (same account as the user)
3. Click **Next** — do not attach any permissions yet
4. **Role name**: `enclave-kms-role` (or any name you prefer)
5. Click **Create role**
***
**Step 4 — Set the trust policy to allow the appliance user to assume this role**
1. Open the `enclave-kms-role` role → **Trust relationships** tab → **Edit trust policy**
2. Replace the entire content with:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "AllowEnclaveApplianceToAssume",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::YOUR_ACCOUNT_ID:user/enclave-appliance"
},
"Action": "sts:AssumeRole"
}]
}
```
Replace `YOUR_ACCOUNT_ID` with your 12-digit AWS account ID. The principal is the **IAM user** (not a role), so AWS validates it immediately — no "Invalid principal" error.
3. Click **Update policy**
***
**Step 4b — Allow the appliance user to call AssumeRole**
The user also needs an IAM permission to call `sts:AssumeRole` on the role.
1. Go to the `enclave-appliance` user → **Permissions** tab → **Add permissions** → **Create inline policy**
2. JSON editor — paste:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::YOUR_ACCOUNT_ID:role/enclave-kms-role"
}]
}
```
3. Name the policy `enclave-assume-kms-role` → **Create policy**
***
**Step 4c — Attach KMS permissions to the role**
1. Go back to the `enclave-kms-role` role → **Permissions** tab → **Add permissions** → **Create inline policy**
2. JSON editor — paste:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "EnclaveKMSAccess",
"Effect": "Allow",
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:REGION:YOUR_ACCOUNT_ID:key/YOUR_CMK_ID"
}]
}
```
Replace `REGION`, `YOUR_ACCOUNT_ID`, and `YOUR_CMK_ID` with your values. The CMK ID is the last section of the Key ARN you noted in Step 1.
3. Name the policy `enclave-kms-permissions` → **Create policy**
4. Copy the **Role ARN** from the role Summary page — you will need it in Step 5
***
**Step 5 — Configure in Enclave Admin**
Log in to the Enclave Admin Panel → go to **Admin → Platform Infra → KMS** → **Add KMS Connection**:
| Field | Value |
| ----------------- | ---------------------------------------------------- |
| Provider | AWS KMS |
| Auth method | Assume Role |
| Access Key ID | `enclave-appliance` user access key (from Step 2) |
| Secret Access Key | `enclave-appliance` user secret key (from Step 2) |
| Role ARN | `arn:aws:iam::YOUR_ACCOUNT_ID:role/enclave-kms-role` |
| CMK ARN / Key ID | Full Key ARN from Step 1 |
| Region | AWS region of the CMK |
Click **Test Connection** — a successful test confirms the role assumption and a live KMS encrypt/decrypt round-trip.
Click **Save** → then **Activate** on the connection row.
Use an IAM user's access key and secret directly. Simpler to set up; suitable when you do not need role-level isolation.
Static credentials are stored encrypted in the appliance database. Rotate them at least every 90 days and restrict the IAM user to the minimum required permissions.
***
**Step 2 — Create an IAM user with KMS permissions**
1. In the AWS Console, go to **IAM → Users → Create user**
2. User name: `enclave-kms` (or any name you prefer)
3. On the **Set permissions** step, choose **Attach policies directly** → click **Create policy**
4. In the policy editor, switch to **JSON** and paste:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [{
"Sid": "EnclaveKMSAccess",
"Effect": "Allow",
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:DescribeKey"
],
"Resource": "arn:aws:kms:REGION:YOUR_ACCOUNT_ID:key/YOUR_CMK_ID"
}]
}
```
Replace `REGION`, `YOUR_ACCOUNT_ID`, and `YOUR_CMK_ID` with your values.
5. Name the policy `enclave-kms-policy` → **Create policy**
6. Back in the user creation wizard, attach the new policy → click **Next** → **Create user**
***
**Step 3 — Create access keys for the user**
1. Open the `enclave-kms` user → **Security credentials** tab → **Create access key**
2. Choose **"Application running outside AWS"** → **Next** → **Create access key**
3. **Save the Access Key ID and Secret Access Key**
***
**Step 4 — Configure in Enclave Admin**
Log in to the Enclave Admin Panel → go to **Admin → Platform Infra → KMS** → **Add KMS Connection**:
| Field | Value |
| ----------------- | ------------------------ |
| Provider | AWS KMS |
| Auth method | Static Credentials |
| Access Key ID | IAM user access key |
| Secret Access Key | IAM user secret key |
| CMK ARN / Key ID | Full Key ARN from Step 1 |
| Region | AWS region of the CMK |
Click **Test Connection** — a successful test confirms a live KMS encrypt/decrypt round-trip.
Click **Save** → then **Activate** on the connection row.
***
## Thales CipherTrust (KMIP / HYOK) — end to end
Use this option for fully on-premise or air-gapped environments with a Thales HSM.
### Step 1 — Create an AES-256 key in CipherTrust Manager
1. Log in to **CipherTrust Manager** as an administrator
2. Navigate to **Keys → Create Key**
3. Configure:
| Setting | Value |
| ---------- | -------------------------------------- |
| Algorithm | AES |
| Key size | 256 bits |
| Usage mask | Encrypt, Decrypt, Wrap Key, Unwrap Key |
| Name | `enclave-platform-cmk` (or any name) |
4. Click **Create** — note the **Key ID** shown on the key detail page
### Step 2 — Create a KMIP client identity for Enclave
1. In CipherTrust Manager, navigate to **KMIP → Client Profiles** → **Create Client Profile**
* Protocol: KMIP 1.x or 2.x
* Authentication: Certificate
2. Under **Client Certificates**, click **Add Client** → generate or import a certificate for Enclave
3. Export the following as **PEM files**:
* Client certificate
* Client private key
* CA certificate (CipherTrust Manager root or intermediate chain)
### Step 3 — Verify network connectivity
The appliance must reach CipherTrust Manager on TCP port `5696`. From the appliance VM, verify:
```bash theme={null}
nc -zv your-hsm-host 5696
```
A successful connection returns `Connection to your-hsm-host 5696 port [tcp/*] succeeded`.
### Step 4 — Configure in Enclave Admin
Log in to the Enclave Admin Panel → go to **Admin → Platform Infra → KMS** → **Add KMS Connection**:
| Field | Value |
| ------------------ | ------------------------------------ |
| Provider | Thales CipherTrust |
| KMIP Endpoint | `your-hsm-host:5696` |
| Client Certificate | Paste PEM-encoded client certificate |
| Client Key | Paste PEM-encoded client private key |
| CA Certificate | Paste PEM-encoded CA certificate |
| CMK ID | Key ID from Step 1 |
Click **Test Connection** — a successful test confirms mutual TLS and that Enclave can reach the key. Click **Save** → then **Activate** on the connection row.
***
## After activating
Once a KMS connection is activated:
* The connection row shows **Active** status in **Admin → Platform Infra → KMS**
* The appliance begins using this KMS immediately for all new file DEK wrap/unwrap operations
* Users can now upload files
You can run **more than one KMS connection active at once** — activating a connection no longer disables the others. Disabling is an explicit action, and a connection **cannot be disabled** while it is the platform secrets provider or while any organisation still has an active key provisioned on it. Files encrypted under a key remain readable as long as that key's connection stays configured.
***
## Provision per-organisation workload keys
Each organisation that uses the platform KMS receives its **own dedicated key** rather than sharing a single platform key. This gives per-organisation isolation, revocation, and audit trails. An organisation only sees the platform KMS as an option in its **Encryption Policies** once you have provisioned a key for it.
Go to **Admin → Platform Infra → KMS → Tenant keys → Provision key**, choose the **connection** and **organisation**, then either:
* **Create a new key** — Enclave creates a fresh key for the organisation on the selected KMS, or
* **Use an existing key** — adopt a key you already manage.
**Thales CipherTrust: adopt by key name, not the KMIP UUID.** On CipherTrust the key's UUID changes on every rotation, so Enclave tracks per-organisation keys by their stable **name**. When adopting an existing CipherTrust key, enter the **key name** (for example `enclave-tenant-acme`) — not the UUID. The current UUID is resolved and shown automatically for reference. AWS KMS keys are identified by their stable key ID/ARN as usual.