Encryption/Decryption

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

Allowed users

User

Allowed

Master

ExtAuth

Required access scope

Main

keymgmt:use:<KID>

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

Encrypt

Encrypt a message

POST https://my.ence.do/api/crypto/cipher/encrypt

Encrypt 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

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

400: Incorrect arguments

401: Missing or invalid JWT_TOKEN

403: Incorrect access scope

406: Operation failed

409: Incorrect internal state

418: TLS connection required

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

POST https://my.ence.do/api/crypto/cipher/decrypt

Decrypt 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

{
  "plaintext": "SGVsbG9Xb3JsZDAxMjM0NQ=="
}

400: Incorrect argument(s)

401: Missing or invalid JWT_TOKEN

403: Incorrect access scope

406: Operation failed

409: Incorrect internal state

418: TLS connection required

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