KMS Configuration

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

Sign in to the AWS Console → navigate to KMS → Customer managed keys
Click Create key
Configure:
Setting Value
Key type Symmetric
Key usage Encrypt and decrypt
Key material origin KMS (AWS-generated)
Add an alias (e.g. enclave-platform-cmk) and an optional description
On the Key administrators step, add your IAM user or role as a key administrator (so you can manage it later)
On the Key usage permissions step, leave this blank for now — you will grant access via an IAM policy in a later step
Click Finish — note the Key ARN from the key detail page; you will enter this in Enclave

Setting	Value
Key type	Symmetric
Key usage	Encrypt and decrypt
Key material origin	KMS (AWS-generated)

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:

Assume Role (recommended)
Static Credentials

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

In the AWS Console, go to IAM → Users → Create user
User name: enclave-appliance (or any name you prefer)
On the Set permissions step, do not attach any permissions — click Next
Click Create user
Open the new user → Security credentials tab → Create access key
Choose “Application running outside AWS” → click Next → Create access key
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

Go to IAM → Roles → Create role
Trusted entity type: AWS account → This account (same account as the user)
Click Next — do not attach any permissions yet
Role name: enclave-kms-role (or any name you prefer)
Click Create role

Step 4 — Set the trust policy to allow the appliance user to assume this role

Open the enclave-kms-role role → Trust relationships tab → Edit trust policy
Replace the entire content with:

{
  "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.

Click Update policy

Step 4b — Allow the appliance user to call AssumeRoleThe user also needs an IAM permission to call sts:AssumeRole on the role.

Go to the enclave-appliance user → Permissions tab → Add permissions → Create inline policy
JSON editor — paste:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "sts:AssumeRole",
    "Resource": "arn:aws:iam::YOUR_ACCOUNT_ID:role/enclave-kms-role"
  }]
}

Name the policy enclave-assume-kms-role → Create policy

Step 4c — Attach KMS permissions to the role

Go back to the enclave-kms-role role → Permissions tab → Add permissions → Create inline policy
JSON editor — paste:

{
  "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.

Name the policy enclave-kms-permissions → Create policy
Copy the Role ARN from the role Summary page — you will need it in Step 5

Step 5 — Configure in Enclave AdminLog 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

In the AWS Console, go to IAM → Users → Create user
User name: enclave-kms (or any name you prefer)
On the Set permissions step, choose Attach policies directly → click Create policy
In the policy editor, switch to JSON and paste:

{
  "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.

Name the policy enclave-kms-policy → Create policy
Back in the user creation wizard, attach the new policy → click Next → Create user

Step 3 — Create access keys for the user

Open the enclave-kms user → Security credentials tab → Create access key
Choose “Application running outside AWS” → Next → Create access key
Save the Access Key ID and Secret Access Key

Step 4 — Configure in Enclave AdminLog 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

Log in to CipherTrust Manager as an administrator
Navigate to Keys → Create Key
Configure:
Setting Value
Algorithm AES
Key size 256 bits
Usage mask Encrypt, Decrypt, Wrap Key, Unwrap Key
Name enclave-platform-cmk (or any name)
Click Create — note the Key ID shown on the key detail page

Setting	Value
Algorithm	AES
Key size	256 bits
Usage mask	Encrypt, Decrypt, Wrap Key, Unwrap Key
Name	`enclave-platform-cmk` (or any name)

Step 2 — Create a KMIP client identity for Enclave

In CipherTrust Manager, navigate to KMIP → Client Profiles → Create Client Profile
- Protocol: KMIP 1.x or 2.x
- Authentication: Certificate
Under Client Certificates, click Add Client → generate or import a certificate for Enclave
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:

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

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.

Get Started

Deployment

Platform Guide

Key Management

Storage

Organization

Security & Trust

Why configure a platform KMS

What the KMS admin panel shows

KMS roles

AWS KMS — end to end

Step 1 — Create a Customer Managed Key in AWS KMS

Choose your authentication method

Thales CipherTrust (KMIP / HYOK) — end to end

Step 1 — Create an AES-256 key in CipherTrust Manager

Step 2 — Create a KMIP client identity for Enclave

Step 3 — Verify network connectivity

Step 4 — Configure in Enclave Admin

After activating

Provision per-organisation workload keys

​Why configure a platform KMS

​What the KMS admin panel shows

​KMS roles

​AWS KMS — end to end

​Step 1 — Create a Customer Managed Key in AWS KMS

​Choose your authentication method

​Thales CipherTrust (KMIP / HYOK) — end to end

​Step 1 — Create an AES-256 key in CipherTrust Manager

​Step 2 — Create a KMIP client identity for Enclave

​Step 3 — Verify network connectivity

​Step 4 — Configure in Enclave Admin

​After activating

​Provision per-organisation workload keys

Why configure a platform KMS

What the KMS admin panel shows

KMS roles

AWS KMS — end to end

Step 1 — Create a Customer Managed Key in AWS KMS

Choose your authentication method

Thales CipherTrust (KMIP / HYOK) — end to end

Step 1 — Create an AES-256 key in CipherTrust Manager

Step 2 — Create a KMIP client identity for Enclave

Step 3 — Verify network connectivity

Step 4 — Configure in Enclave Admin

After activating

Provision per-organisation workload keys