# Exoscale Documentation — Key Management Service (KMS) > Create, control, and manage cryptographic keys with Exoscale Key Management Service. --- url: https://community.exoscale.com/product/security/kms/ --- # Key Management Service (KMS) - [Quick Start - KMS](https://community.exoscale.com/product/security/kms/quick-start/index.md) - Get started quickly with a guided setup to achieve your first successful use of the service, including the required steps and configuration. - [Overview - KMS](https://community.exoscale.com/product/security/kms/overview/index.md) - Terminology and key features at a glance, learn the core concepts, capabilities, and options of this service before you dive deeper. - [How-To - KMS](https://community.exoscale.com/product/security/kms/how-to/index.md) - Step-by-step guides to configure the service and use specific features, with clear instructions for common tasks and problem solving. - [Service Boundaries - KMS](https://community.exoscale.com/product/security/kms/service-boundaries/index.md) - Service boundaries: quotas, limits, and the guaranteed service levels (SLA) for this product, including key constraints to plan and operate reliably. - [Reference - KMS](https://community.exoscale.com/product/security/kms/reference/index.md) - Reference documentation for API, CLI, and tools, browse comprehensive details, parameters, commands, and integration notes. --- url: https://community.exoscale.com/product/security/kms/quick-start/ --- # Quick Start - KMS ## Prerequisites Update to the latest Exoscale CLI (minimum version: 1.74.5). For installation, visit [Exoscale CLI Installation](https://github.com/exoscale/cli#installation). ## First Steps via CLI ### KMS Keys #### Create Create a key and assign it a name that reflects its intended purpose: ```bash 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: ```bash exo kms key list ``` To inspect a specific key's status, zone, and metadata: ```bash exo kms key show ``` #### Replication For enabling replication of a kms key, you need to create a key with the `--multizone` flag: ```bash exo kms key create replication-key-name --multizone ``` Then replicate it to a target zone: ```bash exo kms key replicate de-fra-1 ``` Once replicated, you can direct operations to the replica either via a zone-specific CLI profile or the `--zone` flag: ```bash exo kms crypto encrypt "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. ```bash exo kms key disable ``` ```bash exo kms key enable ``` #### 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: ```bash exo kms key schedule-deletion --delay-days 7 ``` Cancel before the delay expires: ```bash exo kms key cancel-deletion ``` ### 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. ```bash exo kms crypto encrypt "ZGVhdGggc3RhciBwbGFucwo=" --encryption-context "bXktZW5jcnlwdGlvbi1jb250ZXh0Cg==" ``` The command returns base64-encoded ciphertext. #### Decrypt ```bash exo kms crypto decrypt --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. ```bash exo kms crypto generate-data-key --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](https://portal.exoscale.com/), 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](https://community.exoscale.com/reference/cli/exo/kms/index.md) or the [KMS API](https://community.exoscale.com/reference/api/kms/index.md). ## Next Steps * [Rotate your KMS Keys](https://community.exoscale.com/product/security/kms/how-to/rotate-key/index.md) * [Replicate a KMS Key Across Zones](https://community.exoscale.com/product/security/kms/how-to/replicate-key/index.md) * [Review KMS Limits and Quotas](https://community.exoscale.com/product/security/kms/service-boundaries/limits-and-quotas/index.md) --- url: https://community.exoscale.com/product/security/kms/overview/ --- # 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. ![Alt text](kms-overview.png) ## 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 > [!NOTE] > Encryption at rest is already fully available and supported across Exoscale. Native integration with Exoscale KMS to back these capabilities will be introduced shortly after the initial product launch. 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 | Key | Description | Lifecycle | | ---------- | --------------------------------------------------------------------------------------------- | -------------------------------------------- | | Root Key | Stored securely within our backend infrastructure. | Rotated periodically by Exoscale. | | KMS Key | Assigned at the organization level. Each organization initially receives one default KMS key. KMS Keys act as your master key within the Exoscale environment. | Automatically rotated by Exoscale based on a schedule you configure. | | Derived Encryption Key | A 256-bit AES-GCM one-time encryption key used to encrypt customer data and keys. It is derived from the KMS key via HKDF for each specific encryption request. | Generated once per encryption operation; regenerated dynamically for decryption. | Data Encryption Keys (DEK) | Organizations can generate as many DEKs as needed to encrypt actual data resources. | Usage and lifecyle fully controlled by you. | ### 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 | Key Spec | Algorithm | OAEP Hash Function | Maximum Plaintext Size | | ---------- | --------- | ------------------ | ---------------------- | | `RSA_3072` | RSA-OAEP | SHA-384 | 286 bytes | | `RSA_4096` | RSA-OAEP | SHA-512 | 382 bytes | 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. | Key Spec | Family | Signing Algorithms | Hash Function | Standard | | ------------------ | ------ | --------------------------------------------------------------- | --------------------------------- | ---------- | | `RSA_3072` | RSA | `RSASSA_PSS_SHA_256`, `RSASSA_PSS_SHA_384`, `RSASSA_PSS_SHA_512` | SHA-256, SHA-384 or SHA-512 | FIPS 186-5 | | `RSA_4096` | RSA | `RSASSA_PSS_SHA_256`, `RSASSA_PSS_SHA_384`, `RSASSA_PSS_SHA_512` | SHA-256, SHA-384 or SHA-512 | FIPS 186-5 | | `ECC_NIST_P256` | ECC | `ECDSA_SHA_256` | SHA-256 | FIPS 186-5 | | `ECC_NIST_P384` | ECC | `ECDSA_SHA_384` | SHA-384 | FIPS 186-5 | | `ECC_NIST_P521` | ECC | `ECDSA_SHA_512` | SHA-512 | FIPS 186-5 | | `ECC_EDWARDS25519` | ECC | `EDDSA_ED25519`, `ED25519_PH_SHA_512` | SHA-512 | FIPS 186-5 | | `ML_DSA_65` | Post-quantum | `ML_DSA_SHAKE_256` | SHAKE-256 (built into the algorithm) | FIPS 204 | | `ML_DSA_87` | Post-quantum | `ML_DSA_SHAKE_256` | SHAKE-256 (built into the algorithm) | FIPS 204 | 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](#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. --- url: https://community.exoscale.com/product/security/kms/how-to/ --- # How-To - KMS Step-by-step guides to configure the service and use specific features, with clear instructions for common tasks and problem solving. - [Re-Encrypt](https://community.exoscale.com/product/security/kms/how-to/re-encrypt/index.md) - Re-encrypt ciphertext between KMS keys through the CLI or API without exposing plaintext. - [Rotate a KMS Key](https://community.exoscale.com/product/security/kms/how-to/rotate-key/index.md) - Rotate customer-managed KMS keys, configure automatic rotation, and understand key versions. - [Replicate a KMS Key Across Zones](https://community.exoscale.com/product/security/kms/how-to/replicate-key/index.md) - Create and replicate multi-zone KMS keys through the CLI or API for regional workloads. - [Schedule the Deletion of a KMS Key](https://community.exoscale.com/product/security/kms/how-to/schedule-deletion/index.md) - Schedule or cancel KMS key deletion and understand the mandatory waiting period. - [Sign and Verify with Asymmetric KMS Keys](https://community.exoscale.com/product/security/kms/how-to/sign-verify/index.md) - Create asymmetric KMS keys, sign messages and verify signatures through the CLI or API. --- url: https://community.exoscale.com/product/security/kms/how-to/re-encrypt/ --- # Re-Encrypt This guide explains how to use the Re-Encrypt operation to transition your encrypted data to a new key seamlessly. ## How Re-Encryption Works The Re-Encryption operation decrypts and re-encrypts ciphertext entirely within Exoscale KMS, ensuring the underlying plaintext is never exposed to your application layer or transmitted over the network. You can use this operation to transition encrypted data (such as an enveloped Data Encryption Key, or DEK) to a completely different KMS key. Alternatively, you can re-encrypt the data under its current KMS key. Whenever you do this, KMS automatically encrypts the data using the latest available version of the key material, making this the standard method for updating your ciphertext after a key rotation. The operation also allows you to optionally set a new encryption context. Because of this, you can choose to re-encrypt data under the same KMS key solely to update its encryption context. The process happens entirely within the Exoscale KMS secure boundary: 1. **Decrypt:** The service uses the **source KMS key** and your source encryption context (AAD) to recover the plaintext internally. 2. **Encrypt:** It immediately encrypts that plaintext using the **destination KMS key** and your target encryption context (AAD). 3. **Return:** The newly generated ciphertext is returned safely to your application. > [!NOTE] > The destination KMS key you reference must be compatible with the operation. Specifically, the key must be **enabled**, be of the same key type, and have the `encrypt-decrypt` usage permission. ## Using the Exoscale CLI You can perform this operation using the dedicated `exo kms crypto reencrypt` command. Ensure your CLI is configured for the zone where your source key is located, or use the `--zone` flag. **Re-encrypt a ciphertext:** ```bash exo kms crypto reencrypt --zone ``` ## Using the Exoscale API You can perform this operation using the Exoscale API. When running this command, ensure you are targetting the zone where your source key is located. You must provide the payload as a JSON string containing the source and destination details. **Re-encrypt a ciphertext:** ```bash exo api re-encrypt --zone <<< '{ "source": { "key": "", "ciphertext": "" }, "destination": { "key": "" } }' ``` ## Encryption Context If your original ciphertext was encrypted using an Additional Authenticated Data (AAD) context, you must provide it in the source. You can also specify a new, optional encryption context for the destination. All contexts and ciphertexts must be Base64-encoded. With the API: ```bash exo api re-encrypt --zone <<< '{ "source": { "key": "", "ciphertext": "", "encryption-context": "" }, "destination": { "key": "", "encryption-context": "" } }' ``` With the CLI: You must provide it using the --source-encryption-context (or -s) flag. You can also specify a new encryption context for the destination using the --dest-encryption-context (or -d) flag. All contexts and ciphertexts must be Base64-encoded. ```bash exo kms crypto reencrypt \ --source-encryption-context "" \ --dest-encryption-context "" \ --zone ``` --- url: https://community.exoscale.com/product/security/kms/how-to/rotate-key/ --- # Rotate a KMS Key Rotating your KMS keys regularly is a cryptographic best practice. It limits the volume of data protected by a single piece of key material, reducing the potential blast radius of a compromised key without disrupting your active workflows. When you rotate a key, Exoscale KMS generates a fresh, versioned layer of key material while preserving the key's historical key material. ## How Key Rotation Works Exoscale KMS handles key rotation through a versioning system, ensuring continuous availability for both new and legacy data. * **Encryption & Wrapping:** The newly generated version resulting from a rotation instantly becomes the active key material version. All subsequent requests to encrypt data or wrap Data Encryption Keys (DEKs) will automatically use this new version. * **Decryption & Unwrapping:** Legacy key versions are never discarded during a rotation. They are preserved in the key material history and remain authorized *exclusively* for decrypting existing ciphertext. > [!NOTE] > Thanks to **Envelope Encryption**, rotating a KMS key does *not* require you to download and re-encrypt your actual storage objects or compute volumes. Your data remains safely encrypted locally by its unique DEK; only the lightweight DEK itself remains cryptographically tied to the older KMS key version. ## Managing Rotation Across Key Types ### Customer-Managed Keys For your additional KMS keys you create and control, you have full governance over how and when rotation occurs: * **Automatic Rotation**: This is enabled by default with a period of `[365 days]`, but it can be disabled at any time. * **Changing the Rotation Period**: The rotation frequency cannot be modified directly while active. To update the period, you must first disable automatic rotation, and then re-enable it while specifying your new desired timeframe. * **Multi-Zone Propagation**: For keys configured as multi-zone, you must trigger or configure rotation exclusively on the **Primary Key**. The newly generated key material and history will automatically propagate to all regional **Replica Keys**. > [!NOTE] > **Manual Rotations:** If you suspect a key compromise or need to force an immediate key update outside of your automated schedule, you can perform up to **10 manual rotations** per customer-managed KMS key. ### The Default Organization Key The Default Organization Key features a fully platform-managed rotation schedule to guarantee out-of-the-box baseline security. * You **cannot** manually trigger a rotation for this key. * You **cannot** modify or disable its automated rotation schedule. --- url: https://community.exoscale.com/product/security/kms/how-to/replicate-key/ --- # Replicate a KMS Key Across Zones Multi-zone keys allow you to replicate your KMS key material across the Exoscale zones of your choice. This ensures that cryptographic operations remain available locally within those zones, providing low-latency access and high availability for geographically distributed workloads. A key is designated as multi-zone exclusively at **creation-time** by setting the `multi-zone` attribute to `true`. Once enabled, you can safely replicate the key to other zones via the `replicate-kms-key` API endpoint, the CLI `replicate` command . The replication operation is eventually consistent. A successful call guarantees that a replica of the key eventually exists in the given target zone. ## Lifecycle Management of Replicated Keys The lifecycle of a replicated set of keys is hierarchical, governed entirely by the **Primary Key**, except for the key status; you can enable or disable a replica independently from its primary key. ### The Primary Key * **Origin**: This is the original multi-zone key created in your initial choice of zone. * **Authority**: It acts as the single source of truth for the entire replicated set. You manage the rotation schedules, trigger manual rotations, or schedule deletions exclusively from this key. ### The Replica Keys * **Synchronization**: Any change to the Primary Key’s shared properties including key material history, and state updates is automatically propagated to all **Replica Keys** across your designated zones. * **Local Autonomy**: While they inherit their baseline lifecycle states from the primary key, replicas function as fully local assets for day-to-day cryptographic operations (such as wrapping and unwrapping Data Encryption Keys, Enabling and Disabling keys). > [!IMPORTANT] > Because replica keys rely on the primary key for their lifecycle state, administrative actions like key rotation must always be targeted at the Primary Key. You cannot independently rotate or alter the key material of a single replica. ## The Default Organization Key The **Default Organization Key** is fully platform-managed and automatically replicated across all Exoscale zones out-of-the-box. If you decide to migrate a workload away from this default key by re-wrapping your data or Data Encryption Keys (DEKs) with a KMS key you created, you must manually ensure regional parity: > [!IMPORTANT] > Custom KMS keys are not automatically global. If you transition from the Default Organization Key to a custom key, you must explicitly configure your new key as a **Multi-Zone Key** and replicate it to all zones where your distributed workloads will rely on it for encryption or decryption operations. --- url: https://community.exoscale.com/product/security/kms/how-to/schedule-deletion/ --- # Schedule the Deletion of a KMS Key This guide explains how to schedule and cancel the deletion of Exoscale Key Management Service (KMS) keys using the Exoscale CLI and API. > [!WARNING] > Deleting a KMS key is a destructive and irreversible action. Proceed only if you are absolutely certain that the key is no longer needed to decrypt any existing data, now or in the future. If you are unsure, you should **disable** the KMS key instead of deleting it. Key deletion is a two-step process that enforces a mandatory waiting period (between 7 and 30 days) to protect against accidental or premature deletion. During this `pending-deletion` period, all cryptographic operations using the key are disabled. Once the delay expires, the key and its cryptographic material are permanently destroyed and cannot be recovered. --- ## Using the Exoscale CLI When running these commands, ensure your CLI is configured for the zone where your key is located. **Schedule a key deletion:** ```bash exo kms key schedule-deletion --delay-days 7 ``` Cancel a deletion (before the delay expires): ```bash exo kms key cancel-deletion ``` ## Using the Exoscale API You can also interact directly with the API using the exo api command. Be sure to specify the correct zone flag. Schedule a deletion: ```bash exo api schedule-kms-key-deletion --zone <<< '{"delay-days": 7}' ``` Cancel a deletion (before the delay expires): ```bash exo api cancel-kms-key-deletion --zone ``` > [!NOTE] > Post-Cancellation State: When you cancel a scheduled key deletion, the key is reverted to a disabled state. To resume using it for cryptographic operations, you must manually re-enable the KMS key. > [!TIP] > You can also schedule and cancel the deletion of your KMS keys directly from the Exoscale Console. --- url: https://community.exoscale.com/product/security/kms/how-to/sign-verify/ --- # Sign and Verify with Asymmetric KMS Keys This guide explains how to create an asymmetric KMS key, sign messages with it, and verify the resulting signatures, either through Exoscale KMS or offline with the exported public key. ## How Signing Works When you create a KMS key with the `sign-verify` usage, Exoscale KMS generates a public/private key pair. The private key never leaves the KMS unencrypted: all signing operations are performed within the KMS secure boundary. The public key is not secret and can be exported to anyone who needs to verify your signatures. Every signing key has a `key-spec` that defines its algorithm, and every sign or verify request must provide a `signing-algorithm` that matches it: | Key Spec | Signing Algorithms | | ------------------ | ---------------------------------------------------------------- | | `RSA_3072` | `RSASSA_PSS_SHA_256`, `RSASSA_PSS_SHA_384`, `RSASSA_PSS_SHA_512` | | `RSA_4096` | `RSASSA_PSS_SHA_256`, `RSASSA_PSS_SHA_384`, `RSASSA_PSS_SHA_512` | | `ECC_NIST_P256` | `ECDSA_SHA_256` | | `ECC_NIST_P384` | `ECDSA_SHA_384` | | `ECC_NIST_P521` | `ECDSA_SHA_512` | | `ECC_EDWARDS25519` | `EDDSA_ED25519`, `ED25519_PH_SHA_512` | | `ML_DSA_65` | `ML_DSA_SHAKE_256` | | `ML_DSA_87` | `ML_DSA_SHAKE_256` | For guidance on choosing a key specification, see the [Overview](https://community.exoscale.com/product/security/kms/overview/index.md#digital-signatures). > [!NOTE] > Asymmetric KMS keys cannot be rotated. To move to a new key pair, create a new KMS key and distribute its public key to your verifiers. ## Create a Signing Key The `usage` and `key-spec` are set at creation time and cannot be changed afterwards. With the CLI: ```bash exo kms key create my-signing-key --usage sign-verify --key-spec ECC_NIST_P256 --zone ``` With the API: ```bash exo api create-kms-key --zone <<< '{ "name": "my-signing-key", "usage": "sign-verify", "key-spec": "ECC_NIST_P256" }' ``` The command returns the key's UUID, which you reference in all subsequent operations. ## Sign a Message Messages must be Base64-encoded. With the CLI: ```bash exo kms crypto sign "" \ --signing-algorithm ECDSA_SHA_256 \ --zone ``` With the API: ```bash exo api sign --zone <<< '{ "message": "", "signing-algorithm": "ECDSA_SHA_256" }' ``` The response contains the Base64-encoded signature, along with the key specification and signing algorithm used: ```json { "signature": "", "key-spec": "ECC_NIST_P256", "signing-algorithm": "ECDSA_SHA_256" } ``` ### Sign a Digest To sign larger data, or to avoid sending the original data to the KMS, hash it locally and send only the digest with the `message-type` set to `digest`. The hash function must match the signing algorithm (e.g., SHA-256 for `ECDSA_SHA_256`). > [!NOTE] > Digests are supported for RSA and ECDSA keys, and for Ed25519 keys with `ED25519_PH_SHA_512`. `EDDSA_ED25519` and ML-DSA hash the message internally and only accept raw messages. Compute the Base64-encoded SHA-256 digest of a file: ```bash openssl dgst -sha256 -binary my-file.tar.gz | base64 ``` With the CLI: ```bash exo kms crypto sign "" \ --signing-algorithm ECDSA_SHA_256 \ --message-type digest \ --zone ``` With the API: ```bash exo api sign --zone <<< '{ "message": "", "message-type": "digest", "signing-algorithm": "ECDSA_SHA_256" }' ``` ## Verify a Signature with the KMS Verifying through the KMS saves you from fetching and parsing the public key yourself. The request takes the same `message`, `message-type` and `signing-algorithm` as the sign request, along with the signature to verify. With the CLI: ```bash exo kms crypto verify "" "" \ --signing-algorithm ECDSA_SHA_256 \ --zone ``` With the API: ```bash exo api verify --zone <<< '{ "message": "", "signature": "", "signing-algorithm": "ECDSA_SHA_256" }' ``` If the signature is valid, the response confirms it: ```json { "signature-valid": true, "key-id": "", "key-spec": "ECC_NIST_P256" } ``` If the signature does not match the message, the request fails with an invalid signature error. ## Verify a Signature Offline Third parties without access to your Exoscale organization can verify signatures with the exported public key, using standard tooling such as `openssl`. ### Export the Public Key With the CLI: ```bash exo kms key get-public-key --zone ``` With the API: ```bash exo api get-public-key --zone ``` The response contains the Base64-encoded public key, DER-encoded as X.509 `SubjectPublicKeyInfo` (SPKI): ```json { "key-id": "", "key-spec": "ECC_NIST_P256", "public-key": "" } ``` Convert it to the PEM format expected by most tools: ```bash echo "" | base64 -d > public-key.der openssl pkey -pubin -inform DER -in public-key.der -out public-key.pem ``` ### Verify with OpenSSL Decode the signature returned by the sign operation: ```bash echo "" | base64 -d > signature.bin ``` Then verify it against the original message, using the command matching your key specification. ECDSA (`ECDSA_SHA_256`, `ECDSA_SHA_384` or `ECDSA_SHA_512`, with the matching `-sha256`, `-sha384` or `-sha512` flag): ```bash openssl dgst -sha256 -verify public-key.pem -signature signature.bin message.txt ``` RSA-PSS (`RSASSA_PSS_SHA_256`, `RSASSA_PSS_SHA_384` or `RSASSA_PSS_SHA_512`, with the matching hash flag). The salt length is equal to the hash output length: ```bash openssl dgst -sha384 \ -sigopt rsa_padding_mode:pss \ -sigopt rsa_pss_saltlen:digest \ -verify public-key.pem -signature signature.bin message.txt ``` Ed25519 (`EDDSA_ED25519`): ```bash openssl pkeyutl -verify -pubin -inkey public-key.pem -rawin -in message.txt -sigfile signature.bin ``` Each command prints `Verified OK` or `Signature Verified Successfully` when the signature is valid. --- url: https://community.exoscale.com/product/security/kms/service-boundaries/ --- # Service Boundaries - KMS - [Limits and Quotas - KMS](https://community.exoscale.com/product/security/kms/service-boundaries/limits-and-quotas/index.md) - KMS Limitations and Quotas - [SLA - KMS](https://community.exoscale.com/product/security/kms/service-boundaries/sla/index.md) - KMS Service Level Agreement - [Pricing ↗︎](https://www.exoscale.com/pricing/#security) --- url: https://community.exoscale.com/product/security/kms/service-boundaries/limits-and-quotas/ --- # Limits and Quotas - KMS ## Limits Exoscale automatically provisions a default Key Management Service (KMS) key for all organizations. This key is fully managed by Exoscale and automatically replicated across all zones. The following hard limitations apply to default keys: - They cannot be deleted. - Custom keys cannot use the reserved name of a default key. - Automatic key rotation for default keys cannot be disabled. > [!CAUTION] The number of manual key rotations permitted for any single KMS key is strictly limited to 10. This is a system limit and cannot be modified. ## Quotas | Usage | Quota | | --- | --- | | Maximum number of keys per organization per zone | 1,000 | > [!NOTE] > Key replicas within a replicated key set do not count toward your quota; only the primary key is counted. --- url: https://community.exoscale.com/product/security/kms/service-boundaries/sla/ --- # SLA - KMS These product-specific SLAs define the Service Availability Target for Exoscale Key Management Service (KMS). It applies to each Client using the Service. Capitalized terms used herein but not defined herein shall have the meanings set forth in the Exoscale Terms and Conditions or EUSA, whichever applies. ## SLA Definitions | Metric | Target | Definition | | -------- | -------- | ------------ | | Availability | >= 99.95% | The percentage of time in a calendar month that the service is available for external connectivity. | ## Product Specifications For detailed product features, technical specifications, and tutorials, please refer to the [Exoscale documentation](https://community.exoscale.com/product/security/kms/overview/index.md). ## Client Responsibilities Exoscale operates, secures, and maintains the underlying infrastructure of the Key Management Service (KMS). When utilizing customer-managed KMS keys, clients retain responsibility for the operational lifecycle and access configurations of those keys, specifically: * **Key Lifecycle Management**: Establishing and managing key automatic rotations schedules to maintain a secure posture. > [!NOTE] > Key rotation is entirely non-disruptive and does not affect the availability of historical key versions required for ongoing cryptographic or decryption operations. * **Key Deletions & Verification**: Deciding when to schedule key deletions. Clients are responsible for verifying that a key is no longer referenced by any Exoscale services or workloads before the mandatory waiting period ends, and for actively canceling the pending deletion if dependencies need to be resolved. * ** Key Availability**: Ensuring that custom keys remain active and enabled as long as they are required by other Exoscale services (such as Compute or Object Storage) protecting your workloads. * **Access Control & Policies**: Defining and maintaining IAM policies and configurations governing access to KMS service and KMS keys. The KMS SLA applies strictly to the availability and performance of the Exoscale KMS platform itself. For a complete explanation of the shared responsibility framework between Exoscale and Clients, please see the [Exoscale Shared Responsibility Model documentation](https://community.exoscale.com/platform/compliance/shared-responsability-model/index.md). ## Exclusions No compensation or credit shall be granted if a service disruption, data unavailability, or data loss is caused by client-managed configuration or lifecycle decisions, including: * **Finalized Key Deletions**: Disruption or permanent data loss resulting from a scheduled key deletion finalizing while the key is still actively required by Exoscale workloads (e.g., failing to verify dependencies or cancel the deletion before the waiting period ends). * **Inadvertent Disabling**: Disabling an active key during normal, non-emergency operational workflows without transitioning workloads, resulting in self-inflicted disruption. * **Improper Key Material Handling**: Failure to properly replicate key material, leading to unavailability during multi-zone cryptographic requests. * **Access Control Misconfigurations**: IAM policies or revoked permissions that block authorized access to KMS operations. For the complete list of SLA exclusions, please refer to the [General Exoscale Terms and Conditions](https://www.exoscale.com/terms/). This exclusion does not cover security incidents or data breaches resulting from a compromise of the underlying Exoscale infrastructure or failures within the Exoscale-managed KMS platform itself. ## Retribution Service credits apply only to the availability of the Key Management Service as defined above. The standard retribution and SLA credit schemes apply for Exoscale Key Management Service as described under the [General Exoscale Terms and Conditions](https://www.exoscale.com/terms/) or the [EUSA](https://www.exoscale.com/eusa/), whichever applies. Service Credits shall be the Client's sole remedy in the event of a failure to meet the Service Level Objective. | Monthly Uptime Percentage | Service Credit Percentage of Monthly Service Fees for Affected Resources | | --------------------------- | ------------------------------------------------------------------------- | | from 99.95% to 98.3% | 50% | | below 98.3% | 100% | ### Claim Service Credit To request a service credit, refer to the Service Unavailability Credit section of the [Exoscale Terms and Conditions](https://www.exoscale.com/terms/) or the [EUSA](https://www.exoscale.com/eusa/), whichever applies. --- url: https://community.exoscale.com/product/security/kms/reference/ --- # Reference - KMS - [API KMS](https://community.exoscale.com/reference/api/kms/index.md) - All operations on KMS. (external) - [CLI KMS](https://community.exoscale.com/reference/cli/exo/kms/index.md) - All commands on KMS. (external)