Quick Start

Prerequisites

Update to the latest Exoscale CLI (minimum version: 1.74.5). For installation, visit Exoscale CLI Installation.

First Steps via CLI

KMS Keys

Create

Create a key and assign it a name that reflects its intended purpose:

exo kms key create my-key-name

The command returns the key’s UUID, which you’ll reference in all subsequent operations.

List

List all keys in your organization:

exo kms key list

To inspect a specific key’s status, zone, and metadata:

exo kms key show <key-uuid>

Replication

For enabling replication of a kms key, you need to create a key with the --multizone flag:

exo kms key create replication-key-name --multizone

Then replicate it to a target zone:

exo kms key replicate <key-uuid> de-fra-1

Once replicated, you can direct operations to the replica either via a zone-specific CLI profile or the --zone flag:

exo kms crypto encrypt <key-uuid> "ZGVhdGggc3RhciBwbGFucwo=" --encryption-context "bXktZW5jcnlwdGlvbi1jb250ZXh0Cg==" --zone de-fra-1

Enable and Disable

Disabling a key blocks all cryptographic operations without destroying the key material. For replicated keys, this operation is zone-scoped. That means disabling a key in one zone leaves replicas in other zones fully operational.

exo kms key disable <key-uuid>

exo kms key enable <key-uuid>

Deletion

Key deletion is a two-step process with a mandatory delay (7–30 days) to protect against accidental or premature deletion. During the pending-deletion period, all cryptographic operations on the key are disabled. Once the delay expires, the key and its material are permanently destroyed with no recovery.

Schedule a deletion:

exo kms key schedule-deletion <key-uuid> --delay-days 7

Cancel before the delay expires:

exo kms key cancel-deletion <key-uuid>

Cryptographic Operations

Encrypt

Plaintext must be base64-encoded. The encryption context is an authenticated, non-secret string bound to the ciphertext. If provided, it must be presented identically at decryption time.

exo kms crypto encrypt <key-uuid> "ZGVhdGggc3RhciBwbGFucwo=" --encryption-context "bXktZW5jcnlwdGlvbi1jb250ZXh0Cg=="

The command returns base64-encoded ciphertext.

Decrypt

exo kms crypto decrypt <key-uuid> <ciphertext> --encryption-context "bXktZW5jcnlwdGlvbi1jb250ZXh0Cg=="

The decryption context must match exactly what was used at encryption time. A mismatch results in a decryption failure.

Generate Data Key

For bulk data, use envelope encryption: generate a DEK, encrypt your data locally with it, then discard the plaintext DEK. Store only the encrypted DEK alongside your ciphertext.

exo kms crypto generate-data-key <key-uuid> --key-spec AES-256 --encryption-context "Z2VuZXJhdGUtZGVrLWNvbnRleHQK"

The response includes both the plaintext and encrypted DEK. Use the plaintext DEK with your local cryptographic library, discard it immediately after use, and persist the encrypted form.

To decrypt again, call decrypt with the stored encrypted DEK to recover the plaintext DEK, then use it locally to decrypt your data.

First Steps via Portal

Use the Portal to create a KMS key and confirm that it is ready for use.

Create a KMS Key

In the Exoscale Portal, select Security and then KMS Keys under KMS. Select Add and configure the key:

Zone: The zone in which to create the key.
Name: A unique, human-readable name for the key.
Description: Optional information about the key’s intended use.
Multizone: Enable this setting if the key must be replicated to other zones.

The key usage is set to encrypt-decrypt. Select Add to create the key.

Important

You cannot change the Multizone setting after the key is created. Enable it during creation if you intend to replicate the key.

The new key appears in the KMS Keys list. Confirm that its status is Enabled.

View the Key Details

Select the key name to open its details page. The page shows the key ID, status, origin zone, multizone setting, creation date, and rotation information. Copy the key ID to reference the key in CLI and API operations.

You can also use the details page to:

rotate the key manually or enable automatic rotation;
review key versions under Rotations;
review replicas under Replications; and
schedule the key for deletion when it is no longer required.

To encrypt or decrypt data, generate a data key, or re-encrypt ciphertext, use the Exoscale CLI or the KMS API.

Next Steps

Last updated on August 11, 2026