Overview - KMS

Architecture

Exoscale Key Management Service (KMS) is a centralized, fully managed security service that enables you to create, control, and manage the lifecycle of cryptographic keys. It provides data encryption capabilities across your Exoscale workloads, custom applications, and external integrations.

Fundamentally, data encryption shifts the security challenge from protecting the data to protecting the keys. Exoscale KMS addresses this by defining a secure key hierarchy that cryptographically wraps your generated Data Encryption keys. It safeguards your assets while offering granular operations for access and control. The keys you create never leave the KMS environment unencrypted. All management and usage operations are executed securely through the Exoscale KMS API.

Terminology

Key types

KMS Key

A customer-controlled cryptographic key managed within Exoscale KMS. It serves as a master key used to securely wrap and protect Data Encryption Keys (DEKs), rather than encrypting data directly.

Data Encryption Key (DEK)

A key used to encrypt and decrypt actual customer data at rest. DEKs are generated on-demand and are never stored in plaintext by the KMS.

Default Organization Key

A platform-managed KMS key automatically provisioned for every Exoscale organization upon onboarding. It guarantees that baseline encryption workflows are available out-of-the-box without additional setup. This key is fully managed by Exoscale, it may not be deleted or disabled, it is replicated in all Exoscale zones at all times and you may not modify or disable its rotation schedule.

Encryption Concepts

Envelope Encryption

A security practice where data is encrypted with a Data Encryption Key (DEK), and the DEK itself is then encrypted (wrapped) by a higher-level KMS key. This localizes the impact of a potential compromise and simplifies key rotation.

Key Material

The raw cryptographic bytes that constitute a key, used to perform encryption, decryption or wrapping operations.

Key Rotation

The process of generating fresh versioned cryptographic key material of a KMS key. After rotation, legacy versions remain authorized exclusively for decrypting existing data, while the latest version is automatically used for all new encryption operations.

Additional Authenticated Data (AAD)/Encryption Context

Non-confidential, customer-provided data bound cryptographically to the ciphertext. It is used in ciphertext integrity checks.

Key Deployment

Multi-Zone Key

A KMS key that may be replicated across multiple Exoscale zones.

Primary Key

A Multi-Zone Key in the creation zone. The primary key dictates shared key lifecycle properties across all zone replicas.

Replica Key

A copy of a primary key in another Exoscale zone. It operates as a fully functional key for zone-local cryptographic operations, while its baseline lifecycle states (e.g., rotation, deletion) remain synchronized with the primary key.

Features

Protection of Data at Rest

Exoscale KMS integrates seamlessly with the broader Exoscale ecosystem to secure your infrastructure assets automatically. By utilizing either custom KMS keys or the Default Organization Key, server-side encryption is enforced across your cloud resources to ensure that data at-rest is always encrypted.

• Exoscale Object Storage (SOS): Secure your buckets and objects. In KMS mode, each object is encrypted using a unique Data Encryption Key (DEK) wrapped by your specified KMS key.

• Compute: Root Volumes are encrypted at-rest. The Compute orchestrator will leverage your default KMS key, unless specified otherwise (i.e., a KMS key of your choice).

Encrypt and Decrypt Data

For custom software and automated workflows, Exoscale KMS provides direct access via the Exoscale API, client SDKs, and CLI to secure application-level data. This enables developers and operators to implement robust data protection patterns directly within their applications and deployment pipelines.

• Direct Payload Cryptography: Encrypt and decrypt small, sensitive payloads directly through the CLI, SDKs, or API endpoints, for example application configuration secrets, connection strings, certificates, or API tokens.

• High-Performance Envelope Encryption: For large files or databases, use Exoscale KMS to generate on-demand Data Encryption Keys (DEKs). Your application receives a plaintext DEK for immediate, high-speed local encryption and a wrapped (encrypted) DEK. You can store the wrapped DEK safely alongside your data, ensuring the master key material never leaves the KMS.

Cryptographic Primitives

Symmetric Encryption and Data Integrity

Exoscale KMS uses the Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) with 256-bit keys for symmetric key operations. AES-GCM is an authenticated encryption scheme, so besides the ciphertext it also produces an authentication tag. The tag is computed over the ciphertext and any Additional Authenticated Data (AAD), which is context that is not secret but is bound to the ciphertext. If either the ciphertext or the AAD is modified, the tag check fails and decryption is rejected.

To further secure cryptographic operations, Exoscale KMS employs Key Derivation Functions (KDF) to generate additional keys from an initial secret. Specifically, we use the HMAC-based Extract-and-Expand Key Derivation Function (HKDF), combining the initial secret with a unique, randomly generated salt. This derives a distinct, per-call key for encryption operations performed under a KMS key.

Data Protection via Envelope Encryption

To provide robust security guarantees for key lifecycle management, Exoscale KMS relies on Envelope Encryption. This is the practice of encrypting plaintext data with a data key, and then encrypting (or “enveloping”) that data key under another master key encryption key.

Exoscale KMS utilizes a tiered key hierarchy to achieve this. Your organization’s KMS keys are protected by a secure, long-term root key. In turn, your KMS keys are used to encrypt Data Encryption Keys (DEKs) on demand, which are then used to encrypt your actual data. When an authorized user or service needs to access encrypted data, the system first decrypts the enveloped DEK using your KMS key, and then uses that plaintext DEK to decrypt the underlying message.

Key Hierarchy

Symmetric Encryption

Encrypt Operation

When encrypting data (or Data Encryption Keys) using a KMS key, Exoscale KMS employs a key-committing scheme to provide strict security guarantees that go beyond standard AES-GCM. The encryption process follows these steps:

1. Key Lookup: The service validates the infrastructure Root Key and securely retrieves the KMS key material associated with your specified Key ID.
2. Salt Generation: A 32-byte random salt is securely generated for the operation.
3. Key Derivation: Using the HMAC-based Extract-and-Expand Key Derivation Function (HKDF), the service derives two ephemeral keys from your KMS key and the salt:
   • A temporary Data Encryption Key.
   • A signature key.
4. AAD Construction: Additional Authenticated Data (AAD) is assembled by combining server-side context with any optional AAD provided by you via the encryption-context field in the request payload.
5. Encryption: The plaintext is encrypted using AES-GCM with the derived ephemeral DEK and the constructed AAD.
6. Payload Formatting: The resulting ciphertext is serialized into a secure Exoscale format that includes the cipher format version, ciphertext length, the ciphertext itself, and a resource identifier.
7. Authentication Tagging: An HMAC-SHA256 signature is computed over the serialized payload and the salt using the derived signature key.
8. Final Assembly: The service returns the final, secure payload containing the formatted ciphertext blob, the salt, and the authentication tag.

Decrypt Operation

The KMS strictly verifies the payload’s integrity before attempting any decryption. The decryption process is as follows:

1. Ciphertext Parsing: The provided payload is parsed to extract the ciphertext blob, salt, HMAC tag, and KMS key version.
2. Key Lookup: The corresponding KMS key material is retrieved using the Key ID, version, and the infrastructure Root Key.
3. Key Derivation: The ephemeral DEK and signature keys are securely re-derived via HKDF using the retrieved KMS key and the extracted salt.
4. Integrity Check: The HMAC-SHA256 tag is recomputed over the blob and salt. If the recomputed tag does not perfectly match the provided tag, the operation aborts immediately, returning an invalid ciphertext error.
5. AAD Reconstruction: The exact AAD used during the encryption phase is rebuilt.
6. Decryption: The ciphertext is decrypted using AES-GCM with the derived DEK and rebuilt AAD, safely returning the plaintext to the authorized client.

Generation of Data Encryption Keys (DEK)

When you request a Data Encryption Key to encrypt your local data, Exoscale KMS generates it dynamically and securely:

1. A random key of your requested length or specification is generated using a secure cryptographic random number generator.
2. This plaintext key is immediately encrypted under your target KMS key using the standard Encrypt Operation detailed above.
3. The service returns both the plaintext DEK and the encrypted (ciphertext) DEK to your application.

Security Best Practice: Exoscale KMS never stores or persists your DEKs. It is the client application’s responsibility to use the plaintext DEK strictly in memory to encrypt data, store the ciphertext DEK alongside the encrypted data, and safely discard the plaintext DEK from memory once the operation is complete.

Re-encryption

The Re-encryption operation allows you to transition encrypted data (such as an enveloped DEK) from one KMS key to another without ever exposing the plaintext to your application layer or the network.

1. The service performs a Decrypt operation within its secure boundary using the source KMS Key and your source AAD to recover the plaintext.
2. It then immediately performs an Encrypt operation on that plaintext using the new target KMS Key and target AAD.
3. The newly generated ciphertext is returned to your application.

KMS Key Rotation

Key rotation enhances security by generating new cryptographic material for a KMS Key, incrementing its version while keeping the underlying Key ID identical. This ensures your applications do not need to be updated with new key identifiers.

• Rotation Constraints: Keys can be rotated automatically (based on a schedule you define) or manually. Manual rotation is limited to a maximum of 10 times per key. To be rotated, a key must belong to Exoscale KMS, have an EncryptDecrypt usage scope, and must not be disabled or pending deletion. For multi-zone keys, rotation can only be triggered from the key’s designated origin zone. Only symmetric keys can be rotated. Asymmetric keys, whether used for signing or for RSA encryption, cannot be rotated and keep a single version.
• Rotation Process: The KMS generates new encrypted key material tied to the infrastructure Root Key. The key’s version and revision numbers are incremented, and the new cryptographic material is appended securely to the database.
• Multi-Zone Replication: If the rotated key is multi-zone enabled, the KMS automatically synchronizes the new key material asynchronously across all of your configured replica zones.

Asymmetric Encryption

In addition to symmetric keys, Exoscale KMS supports RSA key pairs for encrypting payloads with RSA-OAEP. When you create a KMS key with the encrypt-decrypt usage and an RSA key-spec, the KMS generates a public/private key pair. The private key is wrapped under the infrastructure Root Key, in the same way as symmetric key material, and never leaves the KMS unencrypted.

Asymmetric encryption is useful when data must be encrypted by parties that have no access to the KMS: they encrypt locally with the exported public key, and only authorized callers of the KMS can decrypt the result.

Supported Key Specifications

The OAEP hash function is fixed by the key specification. External parties encrypting with the exported public key must use the same hash function, otherwise the KMS cannot decrypt the ciphertext.

The encrypt and decrypt endpoints are the same as for symmetric keys. When an encryption-context is provided, it is used as the OAEP label rather than as AAD.

Encrypt Operation

Encryption only requires the public key, so the private key is never unwrapped. The encryption process follows these steps:

1. Validation: The service retrieves the KMS key associated with your specified Key ID and checks that it is enabled and has the encrypt-decrypt usage. The plaintext must not exceed the maximum plaintext size of the key specification. For larger data, use a symmetric KMS key with envelope encryption instead. Any failed check aborts the operation.
2. Label Construction: The optional encryption-context provided in the request payload is used as the OAEP label.
3. Encryption: The plaintext is encrypted using RSA-OAEP with the public key, the OAEP hash function of the key specification and the label.
4. Final Assembly: The service returns the resulting ciphertext.

Decrypt Operation

The decryption process is as follows:

1. Validation: The service retrieves the KMS key associated with your specified Key ID and checks that it is enabled and has the encrypt-decrypt usage. The ciphertext length must match the key size (384 bytes for RSA_3072, 512 bytes for RSA_4096). Any failed check aborts the operation.
2. Private Key Unwrapping: The private key is unwrapped using the infrastructure Root Key, only for the duration of the operation.
3. Label Reconstruction: The OAEP label is rebuilt from the encryption-context provided in the request payload. It must match the one used during encryption.
4. Decryption: The ciphertext is decrypted using RSA-OAEP with the private key and the rebuilt label. If the padding or label check fails, the operation aborts, returning an invalid ciphertext error.
5. Final Assembly: The service returns the plaintext to the authorized client.

Export Public Key Operation

The public key is stored unencrypted alongside the wrapped private key, so it is returned without unwrapping the private key. It is DER-encoded as X.509 SubjectPublicKeyInfo (SPKI), so that data can be encrypted outside the KMS with standard tooling such as openssl.

RSA encryption keys cannot be rotated.

Digital Signatures

Exoscale KMS supports asymmetric KMS keys for creating and verifying digital signatures. When you create a KMS key with the sign-verify usage, the KMS generates a public/private key pair. The private key is wrapped under the infrastructure Root Key, in the same way as symmetric key material, and never leaves the KMS unencrypted. The public key is not secret and can be exported to anyone who needs to verify your signatures.

Supported Key Specifications

When creating a signing key, you must select a key-spec. It defines the algorithm family and key size, and is enforced for every subsequent operation on that key.

Choosing a key specification:

• ECC (NIST curves): The recommended default for most workloads. Elliptic curves reach the same security level as RSA with much smaller keys, resulting in faster signing and smaller signatures, and are supported by mostly every client and library.
• Ed25519: A modern elliptic curve with rigidly and verifiably derived parameters, for customers who prefer an alternative to the NIST curves. The same key signs with pure Ed25519 (EDDSA_ED25519) or its prehash variant Ed25519ph (ED25519_PH_SHA_512), see Ed25519 Signing Algorithms.
• RSA: Offers the broadest compatibility with legacy systems. RSA signatures use the RSASSA-PSS padding scheme, which is recommended over PKCS#1 v1.5 for new applications.
• ML-DSA: A post-quantum signature scheme standardized in FIPS 204. Use it to protect long-lived signatures.

Message Types

The message to sign or verify can be provided in one of two forms, using the message-type field:

• raw (default): The message itself, up to 4096 bytes. For RSA and ECDSA keys, the KMS hashes it with the hash function of the selected signing algorithm. EDDSA_ED25519 and ML-DSA sign the message directly, as these algorithms hash it internally.
• digest: A hash of the message, computed locally with the hash function of the selected signing algorithm. Its length must match the hash output size (32, 48 or 64 bytes for SHA-256, SHA-384 or SHA-512). This is useful for signing large files, since only the digest is sent to the KMS, which never sees the original message. This mode is available for RSA and ECDSA keys, and for Ed25519 keys with ED25519_PH_SHA_512.

Ed25519 Signing Algorithms

ECC_EDWARDS25519 keys support two signing algorithms from RFC 8032 on the same key pair. Each one accepts a single message type:

• EDDSA_ED25519 (pure Ed25519): Only accepts raw messages. The algorithm hashes the full message together with secret key material, so there is no digest a client could compute on its own.
• ED25519_PH_SHA_512 (Ed25519ph): Only accepts a digest, the 64 byte SHA-512 hash of the message. Requests using this algorithm must set message-type to digest explicitly.

The two algorithms produce different signatures for the same message, so a signature only verifies with the signing algorithm that produced it.

Sign Operation

The signing process follows these steps:

1. Validation: The service retrieves the KMS key associated with your specified Key ID and checks that it is enabled and has the sign-verify usage. The signing-algorithm must match the key’s key-spec (e.g., an ECC_NIST_P384 key requires ECDSA_SHA_384), and the message-type must be supported by the key, with a digest matching the hash output size. Any failed check aborts the operation.
2. Private Key Unwrapping: The private key is unwrapped using the infrastructure Root Key, only for the duration of the operation.
3. Signing: For RSA and ECDSA keys, a raw message is first hashed with the hash function of the signing algorithm. The signature is then computed with the private key, using RSASSA-PSS, ECDSA, Ed25519, Ed25519ph or ML-DSA depending on the key specification and signing algorithm.
4. Final Assembly: The service returns the signature, along with the key specification and signing algorithm used.

Verify Operation

Verification only requires the public key, so the private key is never unwrapped. This lets you check a signature without having to fetch and parse the public key yourself. The verification process is as follows:

1. Validation: The key, signing-algorithm and message-type are validated, as for signing.
2. Signature Check: For RSA and ECDSA keys, a raw message is first hashed, as for signing. The signature is then verified against the public key stored with the KMS key. If it does not match the message, the operation aborts, returning an invalid signature error.
3. Final Assembly: The service confirms the signature is valid and returns the key specification.

Export Public Key Operation

The public key is stored unencrypted alongside the wrapped private key, so it is returned without unwrapping the private key. Use it to verify signatures offline, without calling the KMS. The key must be enabled.

Encodings

To remain compatible with standard tooling (such as openssl and common X.509 libraries), Exoscale KMS uses the following formats:

• Public keys: DER-encoded X.509 SubjectPublicKeyInfo (SPKI), for all key specifications, including Ed25519 and ML-DSA.
• ECDSA signatures: ASN.1 DER-encoded (SEQUENCE { r, s }).
• RSA-PSS signatures: MGF1 using the same hash as the message digest, with a salt length equal to the hash output length. Verification requires the same salt length, so signatures produced outside the KMS with a different salt length are rejected.
• Ed25519 and ML-DSA signatures: Raw fixed-size bytes (64 bytes for Ed25519 and Ed25519ph, 3309 bytes for ML-DSA-65 and 4627 bytes for ML-DSA-87).

Key Lifecycle

Asymmetric KMS keys cannot be rotated and have a single version. Because a public key is typically distributed to many verifiers, rotating it would require replacing every copy. To move to a new key pair, create a new KMS key and distribute its public key.