Quick Start

Prerequisites

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

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.