ML-KEM

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

Allowed users

User

Allowed

Alternative

ExtAuth

Required access scope

Main

keymgmt:use:<KID>

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

Encapsulation

Generate a shared secret

POST https://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

Name	Type	Description
Authorization*	String	Bearer JWT_TOKEN
Content-Type*	String	application/json

Request Body

Name	Type	Description
kid*	String	Key ID, 32-character hex string encapsulation key

Response status code

200: Operation successful

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

400: Bad Request Incorrect argument(s)

401: Unauthorized Missing or invalid JWT_TOKEN

403: Forbidden Incorrect access scope

406: Not Acceptable Operation failed

409: Conflict Incorrect internal state

418: I'm a Teapot TLS (https) connection required

Possible alg values

Algorithm	Description
MLKEM512	Regarding FIPS 203, ML-KEM-512 key
MLKEM768	Regarding FIPS 203, ML-KEM-768 key
MLKEM1024	Regarding FIPS 203, ML-KEM-1024 key

Response data for successful operation

Name	Type	Description
alg	String	ML-KEM algorithm type represented by the kid
ct	String	Base64 encoded ciphertext
ss	String	Base64 encoded shared secret

Log entries

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

Decapsulation

Extract the shared secret

POST https://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

Name	Type	Description
Authorization*	String	Bearer JWT_TOKEN
Content-Type*	String	application/json

Request Body

Name	Type	Description
ct	String	Base64 encoded ciphertext returned by encaps
kid*	String	Key ID, 32-character hex string decapsulation key

Response status code

200: Operation successful

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

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

Log entries

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