Bring your own key (BYOK)

Bring your own key (BYOK) lets you import key material generated outside Thalassa Cloud—such as from an on-premises HSM or another cloud provider—into a regional KMS key. Imported keys are flagged imported: true in key metadata.

HMAC key types cannot be imported.

Overview

BYOK uses a wrapping key provided by Thalassa Cloud for your region. You wrap your key material off-platform, then submit the wrapped material through the create key API.

┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
│  Your HSM /  │     │  Off-platform   │     │  Thalassa Cloud  │
│  key source  │────►│  wrap with      │────►│  POST /keys with   │
│              │     │  wrapping key   │     │  importKeyMaterial │
└──────────────┘     └─────────────────┘     └──────────────────┘

Never paste raw key bytes into a browser or send unwrapped key material over the API.

Step 1: Get the regional wrapping key

Retrieve the RSA public wrapping key for your target region:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  https://api.thalassa.cloud/v1/kms/nl-01/wrapping-key

The response contains the wrapping key as a PEM-encoded RSA public key. Use this key to wrap your key material off-platform.

Step 2: Wrap key material off-platform

Wrap your key material using your preferred tooling:

• Command-line utilities compatible with your HSM or key source
• HSM export and wrap procedures defined by your security team
• Industry-standard transit wrapping workflows

Perform all wrapping operations off-platform. Only submit the wrapped result to Thalassa Cloud.

The exact wrap procedure depends on your key source and key type. Consult your HSM vendor documentation and internal security policies.

Step 3: Import the wrapped key

Create a key with importKeyMaterial set to the base64-encoded wrapped key material:

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organisation-Identity: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "imported-master-key",
    "description": "BYOK from on-premises HSM",
    "keyType": "aes256-gcm96",
    "importKeyMaterial": "'"$WRAPPED_KEY_MATERIAL"'"
  }' \
  https://api.thalassa.cloud/v1/kms/nl-01/keys

Optional: allow rotation on imported keys

Rotation on imported keys is disabled by default. To enable rotation later, set allowRotation: true at import time:

{
  "name": "imported-signing-key",
  "keyType": "ecdsa-p256",
  "importKeyMaterial": "...",
  "allowRotation": true
}

Without allowRotation: true at import, manual and automatic rotation are not available for the key.

Supported import types

All key types that support BYOK in Key types can be imported except HMAC types.

The keyType in your import request must match the type of the source key material.

Security considerations

• Wrap off-platform — Raw key material must never transit unencrypted to the API
• Least privilege — Restrict create permission on KMS keys to key administrators
• Audit — Monitor import and subsequent crypto operations in your audit log
• Rotation planning — Decide whether imported keys need rotation before import; allowRotation cannot be changed after create

What’s next

• Rotation — Configure rotation for imported keys with allowRotation
• Export and public keys — Export is separate from BYOK import
• Best practices — Operational security guidance