Cryptographic Operations

A suite of cryptographic primitives offered by the Exoscale KMS.

decrypt

Decrypt

POST /kms-key/{id}/decrypt

Decrypts a ciphertext.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Request body

Content-Type: application/json

Property	Type	Required	Description
`ciphertext`	string	yes	The Base64-encoded ciphertext payload to be decrypted. Base64-encoded string.
`encryption-algorithm`	string	no	The encryption algorithm this key must use. Validated against the key’s actual cryptographic profile. Required for asymmetric keys. Symmetric keys use AES_256 when it is omitted. Allowed values: `AES_256`, `RSAES_OAEP_SHA_256`.
`encryption-context`	string	no	The exact Base64-encoded Additional Authenticated Data (AAD) used during encryption to verify data integrity. Base64-encoded string.

Example

{
  "ciphertext": "string",
  "encryption-algorithm": "AES_256",
  "encryption-context": "string"
}

Responses

200: Base64 encoded plaintext.

Content-Type: application/json

Property	Type	Description
`encryption-algorithm`	string	The encryption algorithm that was used to decrypt this ciphertext. Allowed values: `AES_256`, `RSAES_OAEP_SHA_256`.
`plaintext`	string	The recovered Base64-encoded original plaintext payload. Base64-encoded string.

Example output

{
  "encryption-algorithm": "AES_256",
  "plaintext": "string"
}

400: Errors

Key Not Found: The request was rejected because the specified KMS Key could not be found.

Key is Disabled: The request was rejected because the specified KMS key is disabled.

Invalid Usage: The request was rejected because the operation is not allowed for this key’s usage.

Invalid Algorithm: The request was rejected because the specified encryption algorithm does not match the key’s cryptographic profile.

Invalid Ciphertext: The request was rejected because the ciphertext is malformed, was not produced by the specified KMS Key, or could not be authenticated (for example, because of a mismatched encryption context).

[BETA] Key Store Not Found: The request was rejected because the external key store of the specified KMS Key could not be found.

[BETA] Key Store Disconnected: The request was rejected because the external key store of the specified KMS Key is disconnected.

[BETA] Key Store Proxy Request Failed: The request was rejected because the request to the external key store proxy failed.

Content-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	[BETA] Error reported by the customer-managed XKS proxy of an external key store.

Example output

{
  "detail": "string",
  "status": 100,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for decrypt: golang | Python | Java

CLI: exo api decrypt

encrypt

Encrypt

POST /kms-key/{id}/encrypt

Encrypts a plaintext.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Request body

Content-Type: application/json

Property	Type	Required	Description
`plaintext`	string	yes	The Base64-encoded plaintext data you wish to encrypt. Base64-encoded string.
`encryption-algorithm`	string	no	The encryption algorithm this key must use. Validated against the key’s actual cryptographic profile. Required for asymmetric keys. Symmetric keys use AES_256 when it is omitted. Allowed values: `AES_256`, `RSAES_OAEP_SHA_256`.
`encryption-context`	string	no	Base64-encoded bytes to be used as the Additional Authenticated Data (AAD) for encryption integrity. Base64-encoded string.

Example

{
  "encryption-algorithm": "AES_256",
  "encryption-context": "string",
  "plaintext": "string"
}

Responses

200: Base64 encoded ciphertext

Content-Type: application/json

Property	Type	Description
`ciphertext`	string	The resulting Base64-encoded ciphertext after encryption. Base64-encoded string.
`encryption-algorithm`	string	The encryption algorithm that was used to encrypt this plaintext. Allowed values: `AES_256`, `RSAES_OAEP_SHA_256`.

Example output

{
  "ciphertext": "string",
  "encryption-algorithm": "AES_256"
}

400: Errors

Key Not Found: The request was rejected because the specified KMS Key could not be found.

Key is Disabled: The request was rejected because the specified KMS key is disabled.

Invalid Usage: The request was rejected because the operation is not allowed for this key’s usage.

Invalid Algorithm: The request was rejected because the specified encryption algorithm does not match the key’s cryptographic profile.

[BETA] Key Store Not Found: The request was rejected because the external key store of the specified KMS Key could not be found.

[BETA] Key Store Disconnected: The request was rejected because the external key store of the specified KMS Key is disconnected.

[BETA] Key Store Proxy Request Failed: The request was rejected because the request to the external key store proxy failed.

Content-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	[BETA] Error reported by the customer-managed XKS proxy of an external key store.

Example output

{
  "detail": "string",
  "status": 100,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for encrypt: golang | Python | Java

CLI: exo api encrypt

generate-data-key

Generate Data Encryption Key

POST /kms-key/{id}/generate-data-key

Generate a Data Encryption Key from a given KMS Key.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Request body

Content-Type: application/json

Property	Type	Required	Description
`bytes-count`	integer	no	Min: `1`. Max: `1024`.
`encryption-context`	string	no	Base64-encoded Additional Authenticated Data binding key generation parameters securely to operational scope. Base64-encoded string.
`key-spec`	string	no	Allowed values: `AES-256`.

Example

{
  "bytes-count": 1,
  "encryption-context": "string",
  "key-spec": "AES-256"
}

Responses

200: Data Encryption Key in the clear and in its base64 encoded encrypted format.

Content-Type: application/json

Property	Type	Description
`ciphertext`	string	The identical symmetric data key, returned safely wrapped/encrypted using the designated root parent KMS key. Base64-encoded string.
`plaintext`	string	The Base64-encoded raw symmetric data key payload. Expose only securely during active application setups. Base64-encoded string.

Example output

{
  "ciphertext": "string",
  "plaintext": "string"
}

400: Errors

Key Not Found: The request was rejected because the specified KMS Key could not be found.

Key is Disabled: The request was rejected because the specified KMS key is disabled.

Invalid Usage: The request was rejected because the operation is only allowed on symmetric keys with usage “encrypt-decrypt”.

[BETA] Key Store Not Found: The request was rejected because the external key store of the specified KMS Key could not be found.

[BETA] Key Store Disconnected: The request was rejected because the external key store of the specified KMS Key is disconnected.

[BETA] Key Store Proxy Request Failed: The request was rejected because the request to the external key store proxy failed.

Content-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	[BETA] Error reported by the customer-managed XKS proxy of an external key store.

Example output

{
  "detail": "string",
  "status": 100,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for generate-data-key: golang | Python | Java

CLI: exo api generate-data-key

get-public-key

Get Public Key

GET /kms-key/{id}/get-public-key

Retrieve the public key material of an asymmetric KMS key.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Responses

200: Public Key Details

Content-Type: application/json

Property	Type	Description
`key-id`	string	The UUID of the KMS key the public key material belongs to. Must be a valid UUID.
`key-spec`	string	The cryptographic key specification of the key pair, defining its algorithm and curve.
`public-key`	string	The Base64-encoded X.509 SubjectPublicKeyInfo (SPKI) DER encoding of the key’s public key. Base64-encoded string.
`usage`	string	The usage of the key pair, either `encrypt-decrypt` or `sign-verify`.

Example output

{
  "key-id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
  "key-spec": "string",
  "public-key": "string",
  "usage": "string"
}

400: Errors

Key Not Found: The request was rejected because the specified KMS Key could not be found.

Key is Disabled: The request was rejected because the specified KMS Key is disabled (or pending deletion).

Invalid Usage: The request was rejected because the specified KMS Key does not have public key material (its key-spec is symmetric).

Content-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	[BETA] Error reported by the customer-managed XKS proxy of an external key store.

Example output

{
  "detail": "string",
  "status": 100,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for get-public-key: golang | Python | Java

CLI: exo api get-public-key

re-encrypt

Re-encrypt

POST /kms-key/{id}/re-encrypt

Decrypts an existing ciphertext using its original key material and re-encrypts the underlying plaintext using a specified KMS key or the latest key material of the same KMS Key. Source and destination keys must belong to the same key family. IAM policies are evaluated for both the source and the destination key.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Request body

Content-Type: application/json

Property	Type	Required	Description
`destination`	Destination	yes
`source`	Source	yes

Example

{
  "destination": {
    "encryption-algorithm": "AES_256",
    "encryption-context": "string",
    "key": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab"
  },
  "source": {
    "ciphertext": "string",
    "encryption-algorithm": "AES_256",
    "encryption-context": "string",
    "key": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab"
  }
}

Responses

200: Base64 encoded ciphertext

Content-Type: application/json

Property	Type	Description
`ciphertext`	string	The new Base64-encoded ciphertext block safely wrapped by the chosen destination key parameters. Base64-encoded string.
`destination-encryption-algorithm`	string	The encryption algorithm that was used to encrypt the destination ciphertext. Allowed values: `AES_256`, `RSAES_OAEP_SHA_256`.
`source-encryption-algorithm`	string	The encryption algorithm that was used to decrypt the source ciphertext. Allowed values: `AES_256`, `RSAES_OAEP_SHA_256`.

Example output

{
  "ciphertext": "string",
  "destination-encryption-algorithm": "AES_256",
  "source-encryption-algorithm": "AES_256"
}

400: Errors

Key Not Found: The request was rejected because the specified KMS Key could not be found.

Key is Disabled: The request was rejected because the specified KMS key is disabled.

Not on Default: The request was rejected because the operation is not allowed on the default key.

Invalid Usage: The request was rejected because the operation is not allowed for this key’s usage.

Invalid Algorithm: The request was rejected because the specified encryption algorithm does not match the key’s cryptographic profile.

Key Family Mismatch: The request was rejected because the source and destination keys do not belong to the same key family.

Invalid Ciphertext: The request was rejected because the source ciphertext is malformed, was not produced by the source KMS Key, or could not be authenticated (for example, because of a mismatched encryption context).

[BETA] Key Store Not Found: The request was rejected because the external key store of the source or destination KMS Key could not be found.

[BETA] Key Store Disconnected: The request was rejected because the external key store of the source or destination KMS Key is disconnected.

[BETA] Key Store Proxy Request Failed: The request was rejected because the request to the external key store proxy failed.

Bad Request: The request was rejected because of an invalid request body or path parameter.

Content-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	[BETA] Error reported by the customer-managed XKS proxy of an external key store.

Example output

{
  "detail": "string",
  "status": 100,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for re-encrypt: golang | Python | Java

CLI: exo api re-encrypt

sign

Sign

POST /kms-key/{id}/sign

Signs a message or digest using a KMS key with usage sign-verify.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Request body

Content-Type: application/json

Property	Type	Required	Description
`message`	string	yes	The Base64-encoded message to sign (1-4096 decoded bytes). Its meaning depends on `message-type`, either the raw plaintext message or an already-hashed digest. Base64-encoded string. Min length: `1`. Max length: `5464`.
`signing-algorithm`	string	yes	The signing algorithm to use. Must match the family implied by the key’s `key-spec`. Allowed values: `RSASSA_PSS_SHA_256`, `RSASSA_PSS_SHA_384`, `RSASSA_PSS_SHA_512`, `RSASSA_PKCS1_V1_5_SHA_256`, `RSASSA_PKCS1_V1_5_SHA_384`, `RSASSA_PKCS1_V1_5_SHA_512`, `ECDSA_SHA_256`, `ECDSA_SHA_384`, `ECDSA_SHA_512`, `EDDSA_ED25519`, `ED25519_PH_SHA_512`, `ML_DSA_SHAKE_256`.
`message-type`	string	no	How `message` should be interpreted. Allowed values: `raw`, `digest`. Default: `raw`.

Example

{
  "message": "string",
  "message-type": "raw",
  "signing-algorithm": "RSASSA_PSS_SHA_256"
}

Responses

200: The message was successfully signed

Content-Type: application/json

Property	Type	Description
`key-spec`	string	The cryptographic key specification used to produce the signature.
`signature`	string	The resulting Base64-encoded signature. Base64-encoded string.
`signing-algorithm`	string	The signing algorithm used to produce the signature, echoing the request’s `signing-algorithm`.

Example output

{
  "key-spec": "string",
  "signature": "string",
  "signing-algorithm": "string"
}

400: Errors

Key Not Found: The request was rejected because the specified KMS Key could not be found.

Key is Disabled: The request was rejected because the specified KMS Key is disabled (or pending deletion).

Invalid Usage: The request was rejected because the operation is only allowed on keys with usage “sign-verify”.

Invalid Argument: The request was rejected because message-type, message, or signing-algorithm is invalid.

Content-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	[BETA] Error reported by the customer-managed XKS proxy of an external key store.

Example output

{
  "detail": "string",
  "status": 100,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for sign: golang | Python | Java

CLI: exo api sign

verify

Verify

POST /kms-key/{id}/verify

Verifies a signature against the public key of a KMS key with usage sign-verify.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Request body

Content-Type: application/json

Property	Type	Required	Description
`message`	string	yes	The Base64-encoded message to verify (1-4096 decoded bytes), with the same semantics as `sign`’s `message` field. Base64-encoded string. Min length: `1`. Max length: `5464`.
`signature`	string	yes	The Base64-encoded signature to verify against `message` (1-6144 decoded bytes). Base64-encoded string. Min length: `1`. Max length: `8192`.
`signing-algorithm`	string	yes	The signing algorithm `signature` was produced with. Must match the family implied by the key’s `key-spec`, with the same semantics as `sign`’s `signing-algorithm` field. Allowed values: `RSASSA_PSS_SHA_256`, `RSASSA_PSS_SHA_384`, `RSASSA_PSS_SHA_512`, `RSASSA_PKCS1_V1_5_SHA_256`, `RSASSA_PKCS1_V1_5_SHA_384`, `RSASSA_PKCS1_V1_5_SHA_512`, `ECDSA_SHA_256`, `ECDSA_SHA_384`, `ECDSA_SHA_512`, `EDDSA_ED25519`, `ED25519_PH_SHA_512`, `ML_DSA_SHAKE_256`.
`message-type`	string	no	How `message` should be interpreted, with the same semantics as `sign`’s `message-type` field. Allowed values: `raw`, `digest`. Default: `raw`.

Example

{
  "message": "string",
  "message-type": "raw",
  "signature": "string",
  "signing-algorithm": "RSASSA_PSS_SHA_256"
}

Responses

200: The signature is valid.

Content-Type: application/json

Property	Type	Description
`key-id`	string	The UUID of the KMS key used to verify the signature. Must be a valid UUID.
`key-spec`	string	The cryptographic key specification used to verify the signature.
`signature-valid`	boolean	Whether `signature` is a valid signature over `message` produced by this KMS key.

Example output

{
  "key-id": "a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab",
  "key-spec": "string",
  "signature-valid": true
}

400: Errors

Key Not Found: The request was rejected because the specified KMS Key could not be found.

Key is Disabled: The request was rejected because the specified KMS Key is disabled (or pending deletion).

Invalid Usage: The request was rejected because the operation is only allowed on keys with usage “sign-verify”.

Invalid Argument: The request was rejected because message-type, message, or signing-algorithm is invalid.

Invalid Signature: The request was rejected because signature is not a valid signature for message under this key.

Content-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	[BETA] Error reported by the customer-managed XKS proxy of an external key store.

Example output

{
  "detail": "string",
  "status": 100,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for verify: golang | Python | Java

CLI: exo api verify

Last updated on October 29, 2026

Cryptographic Operations

Other Operations

decrypt

Path parameters

Request body

Responses

encrypt

Path parameters

Request body

Responses

generate-data-key

Path parameters

Request body

Responses

get-public-key

Path parameters

Responses

re-encrypt

Path parameters

Request body

Responses

sign

Path parameters

Request body

Responses

verify

Path parameters

Request body

Responses