Set Up an External Key Store

An External Key Store (XKS) lets you keep the key material of a KMS key in a key manager that you operate outside of Exoscale, such as a Hardware Security Module (HSM) in your own data center. Exoscale KMS reaches that key manager through an XKS proxy that you host. This guide explains how to register the proxy as a key store, create KMS keys backed by it, and operate the key store over time.

How an External Key Store Works

Three components are involved:

• External key manager: The system that holds your key material. That material is never shared with Exoscale.
• XKS proxy: A service that you run and expose over HTTPS. It translates requests from Exoscale KMS into calls to your external key manager. It must implement the AWS KMS External Key Store Proxy API.
• Key store: The Exoscale KMS resource that holds the endpoint of your proxy and the credentials used to sign requests to it.

A KMS key created in a key store references exactly one key in your external key manager through its external-key-id.

Double Encryption

Data encrypted with a KMS key in an external key store is protected by two layers:

1. Inner layer: Exoscale KMS encrypts the plaintext with key material that it generates and holds for the KMS key.
2. Outer layer: Exoscale KMS sends the result to your XKS proxy, and your external key manager encrypts it again with the external key using AES-GCM.

Decryption runs in the opposite order: your external key manager first decrypts with the external key, then Exoscale KMS decrypts the result with the key material of the KMS key. Neither Exoscale nor your key manager can decrypt the data alone.

Prerequisites

Before you create a key store, make sure that:

• Your XKS proxy is reachable from Exoscale over HTTPS with a TLS certificate issued by a certificate authority trusted by Exoscale KMS, whose list is based on the Mozilla Root Store. Plain HTTP endpoints are rejected.
• The proxy authenticates requests with AWS SigV4, using the service name kms-xks-proxy and a region equal to the Exoscale zone of the key store. The accepted regions are at-vie-1, at-vie-2, bg-sof-1, ch-dk-2, ch-gva-2, de-fra-1, de-muc-1 and hr-zag-1.
• You know the access key and the secret key that the proxy expects for request signing.
• The external key you plan to use is enabled, is an AES 256 key, and allows both encryption and decryption.

The endpoint you register is the base URL of the XKS API on your proxy, including any path prefix, for example https://xks.example.com/kms/xks/v1. Exoscale KMS appends the operation paths to it:

You can manage key stores through the Exoscale CLI, the API and the SDKs.

Create a Key Store

A key store belongs to a single zone. Create it in the zone where you want to use its keys.

exo api create-key-store --zone <zone-name> <<< '{
  "name": "my-key-store",
  "description": "Keys held in our own HSM",
  "proxy": {
    "endpoint": "https://xks.example.com/kms/xks/v1",
    "auth": {
      "key": "<proxy-access-key>",
      "secret": "<proxy-secret-key>"
    }
  }
}'

Exoscale KMS calls the health endpoint of your proxy with these credentials before it saves the key store. If the call fails, the key store is not created.

The response contains the id of the key store, which you need for the next steps. The secret key is stored encrypted and is never returned by the API. The name must be unique within your organization and cannot be changed later.

Connect and Disconnect a Key Store

A new key store starts in the disconnected state. Connect it before you create or use keys:

exo api connect-key-store <key-store-uuid> --zone <zone-name>

Connecting runs a health check against the proxy. Once the key store is connected, Exoscale KMS checks the proxy periodically and the keys of the store can be used for cryptographic operations.

To suspend every key of a store at once without deleting anything:

exo api disconnect-key-store <key-store-uuid> --zone <zone-name>

While a key store is disconnected, its keys remain intact, but cryptographic operations on them are rejected and periodic health checks are paused. Connect the key store again to resume.

Create a KMS Key in the Key Store

Create the key in your external key manager first, then reference it from a new KMS key:

exo api create-kms-key --zone <zone-name> <<< '{
  "name": "my-external-key",
  "source": "external-key-store",
  "xks": {
    "xks-id": "<key-store-uuid>",
    "external-key-id": "<external-key-id>"
  }
}'

• xks-id is the id of a connected key store.
• external-key-id is the identifier of the key as your XKS proxy knows it. It accepts up to 128 letters, digits, underscores, dots and hyphens.

Exoscale KMS asks the proxy for the metadata of the external key. The request is rejected unless that key is enabled, has the AES_256 key spec, and supports both ENCRYPT and DECRYPT.

The following restrictions apply to KMS keys in an external key store:

Use the Key

A KMS key in an external key store is used like any other symmetric KMS key. The encrypt, decrypt, generate-data-key and re-encrypt operations are available through the CLI and the API:

exo kms crypto encrypt <key-uuid> "ZGVhdGggc3RhciBwbGFucwo=" --zone <zone-name>

exo kms crypto decrypt <key-uuid> <ciphertext> --zone <zone-name>

Every one of these operations calls your proxy. The request metadata sent to the proxy includes the operation name and a request ID, so you can log and authorize each call on your side.

You can also enable, disable and schedule the deletion of the KMS key as usual. Deleting the KMS key does not delete the external key in your key manager.