Encryption/Decryption
These two endpoint implements the encryption and decryption of short data message using the AES scheme.
where <KID> is a Key ID as a 32-character hexadecimal string
Encrypt
Encrypt a message
https://my.ence.do/api/crypto/cipher/encryptEncrypt a short data message and return the ciphertext.
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer JWT_TOKEN |
| Content-Type* | 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* | 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
- 200: Operation successful
- 400: Incorrect arguments
- 401: Missing or invalid JWT_TOKEN
- 403: Incorrect access scope
- 406: Operation failed
- 409: Incorrect internal state
- 411: Protocol error - Content-Length required
- 412: Protocol error - CORS validation failed
- 413: Protocol error - request body too big
- 418: TLS connection required
- 500: Internal server error
{
"ciphertext": "T96b12W+suWq7mHeba5E",
"iv": "zz0R+wb+Czj1OqAQ35bG0A==",
"tag": "J2TnT2veAxaHWTH9a6hy0g=="
}
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
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.
Possible alg values
| Value | Description |
|---|---|
| AES128-ECB | Regarding NIST SP 800-38A |
| AES128-CBC | Regarding NIST SP 800-38A |
| AES128-GCM | Regarding NIST SP 800-38D |
| AES192-ECB | Regarding NIST SP 800-38A |
| AES192-CBC | Regarding NIST SP 800-38A |
| AES192-GCM | Regarding NIST SP 800-38D |
| AES256-ECB | Regarding NIST SP 800-38A |
| AES256-CBC | Regarding NIST SP 800-38A |
| AES256-GCM | Regarding NIST SP 800-38D |
Response data for successful operation
| Name | Type | Description |
|---|---|---|
ciphertext | String | Base64 encoded ciphertext |
iv | String | Base64 IV generated by the process |
tag | String | Optional TAG in base64 (for AES-GCM only) |
Log entries
| Event | Result | Source |
|---|---|---|
| LOG_TYPE_FAILED_SCOPE_CHECK | LOG_RESULT_FAILED | 403 |
| LOG_TYPE_CRYPTO_ENCRYPT | LOG_RESULT_ERROR | 400 |
| LOG_TYPE_CRYPTO_ENCRYPT | LOG_RESULT_FAILED | 406 |
| LOG_TYPE_CRYPTO_ENCRYPT | LOG_RESULT_OK | 200 |
Decrypt
Decrypt a message
https://my.ence.do/api/crypto/cipher/decryptDecrypt a short data message and return the plaintext.
Headers
| Name | Type | Description |
|---|---|---|
| Authorization* | String | Bearer JWT_TOKEN |
| Content-Type* | 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* | 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
- 200: Operation successful
- 400: Incorrect argument(s)
- 401: Missing or invalid JWT_TOKEN
- 403: Incorrect access scope
- 406: Operation failed
- 409: Incorrect internal state
- 411: Protocol error - Content-Length required
- 412: Protocol error - CORS validation failed
- 413: Protocol error - request body too big
- 418: TLS connection required
- 500: Internal server error
{
"plaintext": "SGVsbG9Xb3JsZDAxMjM0NQ=="
}
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
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.
Possible alg values
Check the list here.
Response data for successful operation
| Name | Type | Description |
|---|---|---|
plaintext | String | Base64 decrypted plaintext |
Log entries
| Event | Result | Source |
|---|---|---|
| LOG_TYPE_FAILED_SCOPE_CHECK | LOG_RESULT_FAILED | 403 |
| LOG_TYPE_CRYPTO_DECRYPT | LOG_RESULT_ERROR | 400 |
| LOG_TYPE_CRYPTO_DECRYPT | LOG_RESULT_FAILED | 406 |
| LOG_TYPE_CRYPTO_DECRYPT | LOG_RESULT_OK | 200 |