Skip to main content

ML-KEM

This section describes two endpoints functional for key-encapsulation PQC operations - ML-KEM, FIPS 203 compliant.

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

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

Encapsulation​

Generate a shared secret​

POSThttps://my.ence.do/api/crypto/pqc/mlkem/encaps

The encapsulation algorithm ML-KEM accepts an encapsulation key as input, generates randomness internally, and outputs a ciphertext CT and a shared key SS.

Headers​

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

Request Body​

NameTypeDescription
kid*StringKey ID, 32-character hex string encapsulation key

Response status code​

{
"ct": "4IzdVAZlsNHaUXGNaPMUg139TwnW5QB7WvVKAMEFnHF3JT122JTTnCHuZ1Z6sc2Hvz3WETWJ0ePKUVRJ5HzxDQ==",
"ss": "YBby9t5R6aiQ13CE0RJ7Z0jIMOIXGLN+U9Tebo3/CU=",
"alg": "MLKEM512"
}

Possible alg values​

AlgorithmDescription
MLKEM512Regarding FIPS 203, ML-KEM-512 key
MLKEM768Regarding FIPS 203, ML-KEM-768 key
MLKEM1024Regarding FIPS 203, ML-KEM-1024 key

Response data for successful operation​

NameTypeDescription
algStringML-KEM algorithm type represented by the kid
ctStringBase64 encoded ciphertext
ssStringBase64 encoded shared secret

Log entries​

EventResultSource
LOG_TYPE_FAILED_SCOPE_CHECKLOG_RESULT_FAILED403
LOG_TYPE_CRYPTO_PQC_MLKEM_ENCAPSLOG_RESULT_ERROR400
LOG_TYPE_CRYPTO_PQC_MLKEM_ENCAPSLOG_RESULT_FAILED406
LOG_TYPE_CRYPTO_PQC_MLKEM_ENCAPSLOG_RESULT_OK200

Decapsulation​

Extract the shared secret​

POSThttps://my.ence.do/api/crypto/pqc/mlkem/decaps

The decapsulation algorithm accepts a decapsulation key and an ML-KEM ciphertext as input, does not use any randomness, and outputs a shared.

Headers​

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

Request Body​

NameTypeDescription
ct*StringBase64 encoded ciphertext returned by encaps
kid*StringKey ID, 32-character hex string decapsulation key

Response status code​

{
"ss": "YBby9t5R6aiQ13CE0RJ7Z0jIMOIXGLN+U9Tebo3/CU="
}

Log entries​

EventResultSource
LOG_TYPE_FAILED_SCOPE_CHECKLOG_RESULT_FAILED403
LOG_TYPE_CRYPTO_PQC_MLKEM_DECAPSLOG_RESULT_ERROR400
LOG_TYPE_CRYPTO_PQC_MLKEM_DECAPSLOG_RESULT_FAILED406
LOG_TYPE_CRYPTO_PQC_MLKEM_DECAPSLOG_RESULT_OK200