# Cryptographic Operations


<style>
  span[class^="pill-"] {
    color: white;
    padding: 2px 12px;
    border-radius: 12px;
    font-size: 0.6em;
    vertical-align: middle;
    margin-right: 12px;
    font-family: sans-serif;
    font-weight: bold;
    display: inline-block;
    line-height: 1;
  }
  span.pill-GET { background-color: #61affe; }
  span.pill-POST { background-color: #49cc90; }
  span.pill-PUT { background-color: #fca130; }
  span.pill-DELETE { background-color: #f93e3e; }
  span.pill-PATCH { background-color: #50e3c2; }
  span[class^="pill-"]:after {
    content: attr(data-label);
    font-size: 0.9rem;
  }
</style>

A suite of cryptographic primitives offered by the Exoscale KMS.

[Read more](https://community.exoscale.com/documentation/security/kms/overview)


---

## Other Operations

## <span data-label="POST" class="pill-POST"></span>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.<br/><br/>Base64-encoded string. |
| `encryption-context` | string | no | The exact Base64-encoded Additional Authenticated Data (AAD) used during encryption to verify data integrity.<br/><br/>Base64-encoded string. |

<details>
<summary>Example</summary>

```json
{
  "ciphertext": "string",
  "encryption-context": "string"
}
```
</details>


### Responses

**`200`**: Base64 encoded plaintext.

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `plaintext` | string | The recovered Base64-encoded original plaintext payload.<br/><br/>Base64-encoded string. |

<details>
<summary>Example output</summary>

```json
{
  "plaintext": "string"
}
```
</details>

**`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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `decrypt`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.Decrypt) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.decrypt) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#decrypt(java.util.UUID,com.exoscale.sdk.model.DecryptRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/): `exo api decrypt`

## <span data-label="POST" class="pill-POST"></span>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.<br/><br/>Base64-encoded string. |
| `encryption-context` | string | no | Base64-encoded bytes to be used as the Additional Authenticated Data (AAD) for encryption integrity.<br/><br/>Base64-encoded string. |

<details>
<summary>Example</summary>

```json
{
  "encryption-context": "string",
  "plaintext": "string"
}
```
</details>


### Responses

**`200`**: Base64 encoded ciphertext

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `ciphertext` | string | The resulting Base64-encoded ciphertext after encryption.<br/><br/>Base64-encoded string. |

<details>
<summary>Example output</summary>

```json
{
  "ciphertext": "string"
}
```
</details>

**`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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `encrypt`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.Encrypt) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.encrypt) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#encrypt(java.util.UUID,com.exoscale.sdk.model.EncryptRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/): `exo api encrypt`

## <span data-label="POST" class="pill-POST"></span>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.<br/><br/>Base64-encoded string. |
| `key-spec` | string | no | Allowed values: `AES-256`. |

<details>
<summary>Example</summary>

```json
{
  "bytes-count": 0,
  "encryption-context": "string",
  "key-spec": "AES-256"
}
```
</details>


### 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.<br/><br/>Base64-encoded string. |
| `plaintext` | string | The Base64-encoded raw symmetric data key payload. Expose only securely during active application setups.<br/><br/>Base64-encoded string. |

<details>
<summary>Example output</summary>

```json
{
  "ciphertext": "string",
  "plaintext": "string"
}
```
</details>

**`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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `generate-data-key`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.GenerateDataKey) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.generate_data_key) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#generateDataKey(java.util.UUID,com.exoscale.sdk.model.GenerateDataKeyRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/): `exo api generate-data-key`

## <span data-label="POST" class="pill-POST"></span>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.

### Path parameters

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

### Request body

Content-Type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `destination` | [Destination](/reference/api/_schemas/re-encrypt-request/#destination) | **yes** |  |
| `source` | [Source](/reference/api/_schemas/re-encrypt-request/#source) | **yes** |  |

<details>
<summary>Example</summary>

```json
{
  "destination": {
    "encryption-context": "string",
    "key": "string"
  },
  "source": {
    "ciphertext": "string",
    "encryption-context": "string",
    "key": "string"
  }
}
```
</details>


### 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.<br/><br/>Base64-encoded string. |

<details>
<summary>Example output</summary>

```json
{
  "ciphertext": "string"
}
```
</details>

**`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.

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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `re-encrypt`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.ReEncrypt) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.re_encrypt) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#reEncrypt(java.util.UUID,com.exoscale.sdk.model.ReEncryptRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/): `exo api re-encrypt`