Skip to main content

Encryption/Decryption

These two endpoint implements the encryption and decryption of short data message using the AES scheme.

Allowed usersUser✓Master✗ExtAuth✓
Required access scopekeymgmt:use:<KID>

where <KID> is a Key ID as a 32-character hexadecimal string

Encrypt​

Encrypt a message​

POSThttps://my.ence.do/api/crypto/cipher/encrypt

Encrypt a short data message and return the ciphertext.

Headers​

NameTypeDescription
Authorization*StringBearer JWT_TOKEN
Content-Type*Stringapplication/json

Request Body​

NameTypeDescription
alg*StringAlgorithm to use (e.g. AES256-GCM)
ext_kidStringExternal Key ID, 32 chars hex string
kid*StringKey ID, 32 chars hex string
msg*StringPlaintex to encrypt (max. 2048 bytes)
pubkeyStringBase64 encoded external public key
ctxStringAdditional context data (HKDF argument) (max. 64 bytes)
aadStringOptional AAD data for AES-GSM only

Response status code​

{
"ciphertext": "T96b12W+suWq7mHeba5E",
"iv": "zz0R+wb+Czj1OqAQ35bG0A==",
"tag": "J2TnT2veAxaHWTH9a6hy0g=="
}
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.

Possible alg values​

ValueDescription
AES128-ECBRegarding NIST SP 800-38A
AES128-CBCRegarding NIST SP 800-38A
AES128-GCMRegarding NIST SP 800-38D
AES192-ECBRegarding NIST SP 800-38A
AES192-CBCRegarding NIST SP 800-38A
AES192-GCMRegarding NIST SP 800-38D
AES256-ECBRegarding NIST SP 800-38A
AES256-CBCRegarding NIST SP 800-38A
AES256-GCMRegarding NIST SP 800-38D

Response data for successful operation​

NameTypeDescription
ciphertextStringBase64 encoded ciphertext
ivStringBase64 IV generated by the process
tagStringOptional TAG in base64 (for AES-GCM only)

Log entries​

EventResultSource
LOG_TYPE_FAILED_SCOPE_CHECKLOG_RESULT_FAILED403
LOG_TYPE_CRYPTO_ENCRYPTLOG_RESULT_ERROR400
LOG_TYPE_CRYPTO_ENCRYPTLOG_RESULT_FAILED406
LOG_TYPE_CRYPTO_ENCRYPTLOG_RESULT_OK200

Decrypt​

Decrypt a message​

POSThttps://my.ence.do/api/crypto/cipher/decrypt

Decrypt a short data message and return the plaintext.

Headers​

NameTypeDescription
Authorization*StringBearer JWT_TOKEN
Content-Type*Stringapplication/json

Request Body​

NameTypeDescription
alg*StringAlgorithm to use (e.g. AES256-GCM)
ext_kidStringExternal Key ID, 32 chars hex string
kid*StringKey ID, 32 chars hex string
msg*StringCiphertext to decrypt (max. 2048 bytes)
pubkeyStringBase64 encoded external public key
ctxStringAdditional context data (HKDF argument) (max. 64 bytes)
ivStringCiphertext IV
tagStringTAG value if AES-GCM used
aadStringOptional AAD data for AES-GSM only

Response status code​

{
"plaintext": "SGVsbG9Xb3JsZDAxMjM0NQ=="
}
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.

Possible alg values​

Check the list here.

Response data for successful operation​

NameTypeDescription
plaintextStringBase64 decrypted plaintext

Log entries​

EventResultSource
LOG_TYPE_FAILED_SCOPE_CHECKLOG_RESULT_FAILED403
LOG_TYPE_CRYPTO_DECRYPTLOG_RESULT_ERROR400
LOG_TYPE_CRYPTO_DECRYPTLOG_RESULT_FAILED406
LOG_TYPE_CRYPTO_DECRYPTLOG_RESULT_OK200