Wrap/Unwrap

These two endpoint implements the NIST Key Wrapping scheme.

toAllowed users

User

Allowed

Master

Not allowed

ExtAuth

Allowed

Required access scope

Main

keymgmt:use:<KID>

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

Wrap

Wrap a message

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

Wrap plain message using the NIST Key Wrapping scheme.

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)
ext_kid	String	External Key ID, 32 chars hex string
kid*	String	Key ID, 32 chars hex string
msg*	String	Data message to wrap (max. 2048 bytes)
pubkey	String	Base64 encoded external public key
ctx	String	Additional context data (HKDF argument) (max. 64 bytes)
iv	String	Optional IV data

Response status code

200: Operation successful

{
  "wrapped": "ot5cd+SCF6w9dxdjtLnnr96yIMJQWVzb"
}

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	Regarding NIST SP 800-38F
AES192	Regarding NIST SP 800-38F
AES256	Regarding NIST SP 800-38F

Response data for successful operation

Name	Type	Description
wrapped	String	Base64 encoded wrapped data

Log entries

Event	Result	Source
LOG_TYPE_FAILED_SCOPE_CHECK	LOG_RESULT_FAILED	403
LOG_TYPE_CRYPTO_WRAP	LOG_RESULT_ERROR	400
LOG_TYPE_CRYPTO_WRAP	LOG_RESULT_FAILED	406
LOG_TYPE_CRYPTO_WRAP	LOG_RESULT_OK	200

Unwrap

Unwarp a message

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

Unwrap the encrypted message using the NIST Key Wrapping scheme.

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)
ext_kid	String	External Key ID, 32 chars hex string
iv	String	Ciphertext IV
kid*	String	Key ID, 32 chars hex string
msg*	String	Data message to unwrap (max. 2048 bytes)
pubkey	String	Base64 encoded external public key
ctx	String	Additional context data (HKDF argument) (max. 64 bytes)

Response status code

200: Operation successful

{
  "unwrapped": "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
unwrapped	String	Base64 encoded unwraped data

Log entries

Event	Result	Source
LOG_TYPE_FAILED_SCOPE_CHECK	LOG_RESULT_FAILED	403
LOG_TYPE_CRYPTO_UNWRAP	LOG_RESULT_ERROR	400
LOG_TYPE_CRYPTO_UNWRAP	LOG_RESULT_FAILED	406
LOG_TYPE_CRYPTO_UNWRAP	LOG_RESULT_OK	200