ML-KEM
This section describes two endpoints functional for key-encapsulation PQC operations - ML-KEM, FIPS 203 compliant.
where <KID> is a Key ID as a 32-character hexadecimal string
Encapsulation
Generate a shared secret
https://my.ence.do/api/crypto/pqc/mlkem/encapsThe 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
- 400: Incorrect argument(s)
- 401: Missing or invalid JWT_TOKEN
- 403: Incorrect access scope
- 406: Operation failed
- 409: Incorrect internal state
- 411: Protocol error - Content-Length required
- 412: Protocol error - CORS validation failed
- 413: Protocol error - request body too big
- 418: TLS (https) connection required
- 500: Internal server error
{
"ct": "4IzdVAZlsNHaUXGNaPMUg139TwnW5QB7WvVKAMEFnHF3JT122JTTnCHuZ1Z6sc2Hvz3WETWJ0ePKUVRJ5HzxDQ==",
"ss": "YBby9t5R6aiQ13CE0RJ7Z0jIMOIXGLN+U9Tebo3/CU=",
"alg": "MLKEM512"
}
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
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
https://my.ence.do/api/crypto/pqc/mlkem/decapsThe 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
- 400: Incorrect argument(s)
- 401: Missing or invalid JWT_TOKEN
- 403: Incorrect access scope
- 406: Operation failed
- 409: Incorrect internal state
- 411: Protocol error - Content-Length required
- 412: Protocol error - CORS validation failed
- 413: Protocol error - request body too big
- 418: TLS connection required
- 500: Internal server error
{
"ss": "YBby9t5R6aiQ13CE0RJ7Z0jIMOIXGLN+U9Tebo3/CU="
}
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
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 |