Skip to main content

Wrap/Unwrap

These two endpoint implements the NIST Key Wrapping scheme.

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

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

Wrap​

Wrap a message​

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

Wrap plain message using the NIST Key Wrapping scheme.

Headers​

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

Request Body​

NameTypeDescription
algStringAlgorithm to use (e.g. AES256)
ext_kidStringExternal Key ID, 32 chars hex string
kid*StringKey ID, 32 chars hex string
msg*StringData message to wrap (max. 2048 bytes)
pubkeyStringBase64 encoded external public key
ctxStringAdditional context data (HKDF argument) (max. 64 bytes)
ivStringOptional IV data

Response status code​

{
"wrapped": "ot5cd+SCF6w9dxdjtLnnr96yIMJQWVzb"
}
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
AES128Regarding NIST SP 800-38F
AES192Regarding NIST SP 800-38F
AES256Regarding NIST SP 800-38F

Response data for successful operation​

NameTypeDescription
wrappedStringBase64 encoded wrapped data

Log entries​

EventResultSource
LOG_TYPE_FAILED_SCOPE_CHECKLOG_RESULT_FAILED403
LOG_TYPE_CRYPTO_WRAPLOG_RESULT_ERROR400
LOG_TYPE_CRYPTO_WRAPLOG_RESULT_FAILED406
LOG_TYPE_CRYPTO_WRAPLOG_RESULT_OK200

Unwrap​

Unwarp a message​

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

Unwrap the encrypted message using the NIST Key Wrapping scheme.

Headers​

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

Request Body​

NameTypeDescription
algStringAlgorithm to use (e.g. AES256)
ext_kidStringExternal Key ID, 32 chars hex string
ivStringCiphertext IV
kid*StringKey ID, 32 chars hex string
msg*StringData message to unwrap (max. 2048 bytes)
pubkeyStringBase64 encoded external public key
ctxStringAdditional context data (HKDF argument) (max. 64 bytes)

Response status code​

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

Log entries​

EventResultSource
LOG_TYPE_FAILED_SCOPE_CHECKLOG_RESULT_FAILED403
LOG_TYPE_CRYPTO_UNWRAPLOG_RESULT_ERROR400
LOG_TYPE_CRYPTO_UNWRAPLOG_RESULT_FAILED406
LOG_TYPE_CRYPTO_UNWRAPLOG_RESULT_OK200