# Encryption/Decryption

#### Allowed users

{% tabs %}
{% tab title="User" %}
Allowed
{% endtab %}

{% tab title="Master" %}
Not allowed
{% endtab %}

{% tab title="ExtAuth" %}
Allowed
{% endtab %}
{% endtabs %}

#### Required access scope

{% tabs %}
{% tab title="Main" %}
`keymgmt:use:<KID>`

&#x20;

where `<KID>` is a Key ID as a 32-character hexadecimal string
{% endtab %}
{% endtabs %}

## Encrypt

## Encrypt a message

<mark style="color:green;">`POST`</mark> `https://my.ence.do/api/crypto/cipher/encrypt`

Encrypt a short data message and return the ciphertext.

#### Headers

| Name                                            | Type   | Description       |
| ----------------------------------------------- | ------ | ----------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer JWT\_TOKEN |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json  |

#### Request Body

| Name                                    | Type   | Description                                             |
| --------------------------------------- | ------ | ------------------------------------------------------- |
| `alg`<mark style="color:red;">\*</mark> | String | Algorithm to use (e.g. AES256-GCM)                      |
| `ext_kid`                               | String | External Key ID, 32 chars hex string                    |
| `kid`<mark style="color:red;">\*</mark> | String | Key ID, 32 chars hex string                             |
| `msg`                                   | String | Plaintex to encrypt (max. 2048 bytes)                   |
| `pubkey`                                | String | Base64 encoded external public key                      |
| `ctx`                                   | String | Additional context data (HKDF argument) (max. 64 bytes) |
| `aad`                                   | String | Optional AAD data for AES-GSM only                      |

#### Response status code

{% tabs %}
{% tab title="200: Operation successful" %}

```javascript
{
  "ciphertext": "T96b12W+suWq7mHeba5E",
  "iv": "zz0R+wb+Czj1OqAQ35bG0A==",
  "tag": "J2TnT2veAxaHWTH9a6hy0g=="
}
```

{% endtab %}

{% tab title="400: Incorrect arguments" %}

{% endtab %}

{% tab title="401: Missing or invalid JWT\_TOKEN" %}

{% endtab %}

{% tab title="403: Incorrect access scope" %}

{% endtab %}

{% tab title="406: Operation failed" %}

{% endtab %}

{% tab title="409: Incorrect internal state" %}

{% endtab %}

{% tab title="418: TLS connection required" %}

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The key type pointed to `ext_kid` or represented by `pubkey` MUST be the same as the `kid` key type. Otherwise, indirect ECDH will fail.
{% endhint %}

#### Possible `alg` values

<table><thead><tr><th width="271">Value</th><th>Description</th></tr></thead><tbody><tr><td>AES128-ECB</td><td>Regarding NIST SP 800-38A</td></tr><tr><td>AES128-CBC</td><td>Regarding NIST SP 800-38A</td></tr><tr><td>AES128-GCM</td><td>Regarding NIST SP 800-38D</td></tr><tr><td>AES192-ECB</td><td>Regarding NIST SP 800-38A</td></tr><tr><td>AES192-CBC</td><td>Regarding NIST SP 800-38A</td></tr><tr><td>AES192-GCM</td><td>Regarding NIST SP 800-38D</td></tr><tr><td>AES256-ECB</td><td>Regarding NIST SP 800-38A</td></tr><tr><td>AES256-CBC</td><td>Regarding NIST SP 800-38A</td></tr><tr><td>AES256-GCM</td><td>Regarding NIST SP 800-38D</td></tr></tbody></table>

#### Response data for successful operation

<table><thead><tr><th width="232.609756097561">Name</th><th width="150">Type</th><th width="297.77565202829993">Description</th></tr></thead><tbody><tr><td><code>ciphertext</code></td><td>String</td><td>Base64 encoded ciphertext</td></tr><tr><td><code>iv</code></td><td>String</td><td>Base64 IV generated by the process</td></tr><tr><td><code>tag</code></td><td>String</td><td>Optional TAG in base64 (for AES-GCM only)</td></tr></tbody></table>

#### Log entries

<table><thead><tr><th width="330.3333333333333">Event</th><th>Result</th><th>Source</th></tr></thead><tbody><tr><td>LOG_TYPE_FAILED_SCOPE_CHECK</td><td>LOG_RESULT_FAILED</td><td>403</td></tr><tr><td>LOG_TYPE_CRYPTO_ENCRYPT</td><td>LOG_RESULT_ERROR</td><td>400</td></tr><tr><td>LOG_TYPE_CRYPTO_ENCRYPT</td><td>LOG_RESULT_FAILED</td><td>406</td></tr><tr><td>LOG_TYPE_CRYPTO_ENCRYPT</td><td>LOG_RESULT_OK</td><td>200</td></tr></tbody></table>

## Decrypt

## Decrypt a message

<mark style="color:green;">`POST`</mark> `https://my.ence.do/api/crypto/cipher/decrypt`

Decrypt a short data message and return the plaintext.

#### Headers

| Name                                            | Type   | Description       |
| ----------------------------------------------- | ------ | ----------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer JWT\_TOKEN |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json  |

#### Request Body

| Name                                    | Type   | Description                                             |
| --------------------------------------- | ------ | ------------------------------------------------------- |
| `alg`                                   | String | Algorithm to use (e.g. AES256-GCM)                      |
| `ext_kid`                               | String | External Key ID, 32 chars hex string                    |
| `kid`<mark style="color:red;">\*</mark> | String | Key ID, 32 chars hex string                             |
| `msg`                                   | String | Ciphertext to decrypt (max. 2048 bytes)                 |
| `pubkey`                                | String | Base64 encoded external public key                      |
| `ctx`                                   | String | Additional context data (HKDF argument) (max. 64 bytes) |
| `iv`                                    | String | Ciphertext IV                                           |
| `tag`                                   | String | TAG value if AES-GCM used                               |
| `aad`                                   | String | Optional AAD data for AES-GSM only                      |

#### Response status code

{% tabs %}
{% tab title="200: Operation successful" %}

```javascript
{
  "plaintext": "SGVsbG9Xb3JsZDAxMjM0NQ=="
}
```

{% endtab %}

{% tab title="400: Incorrect argument(s)" %}

{% endtab %}

{% tab title="401: Missing or invalid JWT\_TOKEN" %}

{% endtab %}

{% tab title="403: Incorrect access scope" %}

{% endtab %}

{% tab title="406: Operation failed" %}

{% endtab %}

{% tab title="409: Incorrect internal state" %}

{% endtab %}

{% tab title="418: TLS connection required" %}

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The key type pointed to `ext_kid` or represented by `pubkey` MUST be the same as the `kid` key type. Otherwise, indirect ECDH will fail.
{% endhint %}

#### Possible `alg` values

Check the list [here](#possible-alg-values).

#### Response data for successful operation

<table><thead><tr><th width="219.40244631903352">Name</th><th width="150">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>plaintext</code></td><td>String</td><td>Base64 decrypted plaintext</td></tr></tbody></table>

#### Log entries

<table><thead><tr><th width="320.32405294386126">Event</th><th>Result</th><th>Source</th></tr></thead><tbody><tr><td>LOG_TYPE_FAILED_SCOPE_CHECK</td><td>LOG_RESULT_FAILED</td><td>403</td></tr><tr><td>LOG_TYPE_CRYPTO_DECRYPT</td><td>LOG_RESULT_ERROR</td><td>400</td></tr><tr><td>LOG_TYPE_CRYPTO_DECRYPT</td><td>LOG_RESULT_FAILED</td><td>406</td></tr><tr><td>LOG_TYPE_CRYPTO_DECRYPT</td><td>LOG_RESULT_OK</td><td>200</td></tr></tbody></table>