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.

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`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "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.

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`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "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": 0,
  "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”.

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`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "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": "string",
  "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`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "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.

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": "string"
  },
  "source": {
    "ciphertext": "string",
    "encryption-algorithm": "AES_256",
    "encryption-context": "string",
    "key": "string"
  }
}

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.

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`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "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`, `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`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "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`, `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": "string",
  "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`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "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 7, 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