API Reference¶
This page contains the API reference for all the REST APIs exposed by the server.
All parameters and (successful) outputs are JSON objects. The Parameters and Output fields in the tables below describe top-level fields in the JSON object.
GET /init_server¶
Path |
GET /init_server |
Description |
Kyber ML-KEM key generation output containing the ML-KEM-768 encap_key for transport key setup |
Parameters |
None |
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- mlkem_encap_key
|
mlkem_encap_key |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The ML-KEM-768 encapsulation key (decodes to 1184 bytes) |
POST /load_tk¶
Path |
POST /load_tk |
Description |
Loads the Encrypted Transport Key from the Server to the TEE API Server using ML-KEM-768 algorithm |
Parameters
|
- encrypted_tk
- ciphertext
|
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- tk_valid
|
encrypted_tk |
|
Type |
String |
Encoding |
Standard base64 |
Description |
Decodes to the AES-256-CTR encrypted transport key (32 bytes) prepended with nonce (16 bytes) |
ciphertext |
|
Type |
String |
Encoding |
Standard base64 |
Description |
The ML-KEM-768 -derived ciphertext (decodes to 1088 bytes) |
tk_valid |
|
Type |
Boolean |
Description |
Result of load_tk |
GET /mlkem_keygen¶
Path |
GET /mlkem_keygen |
Description |
ML-KEM key generation output containing ML-KEM-768 encap_key and encrypted decap_key |
Parameters |
None |
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- mlkem_encap_key
- encrypted_mlkem_decap_key
|
mlkem_encap_key |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The ML-KEM-768 encapsulation key (decodes to 1184 bytes) |
encrypted_mlkem_decap_key |
|
Type |
String |
Encoding |
Standard base64 |
Description |
Decodes to the AES-256-CTR encrypted ML-KEM-768 decapsulation key (2400 bytes) prepended with nonce (16 bytes) and postpended with salt (32 bytes for key derivation) |
POST /mlkem_decrypt¶
Path |
POST /mlkem_decrypt |
Description |
Decrypts the encrypted data using the encrypted decap_key and ciphertext to obtain the data |
Parameters
|
- encrypted_data
- encrypted_mlkem_decap_key
- ciphertext
|
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- data
|
encrypted_data |
|
Type |
String |
Encoding |
Standard base64 |
Description |
The encrypted data |
encrypted_mlkem_decap_key |
|
Type |
String |
Encoding |
Standard base64 |
Description |
Decodes to the AES-256-CTR encrypted ML-KEM-768 decapsulation key (2400 bytes) prepended with nonce (16 bytes) and postpended with salt (32 bytes for key derivation) |
ciphertext |
|
Type |
String |
Encoding |
Standard base64 |
Description |
The ML-KEM-768 -derived ciphertext (decodes to 1088 bytes) |
data |
|
Type |
String |
Encoding |
Standard base64 |
Description |
The decrypted data. |
POST /tofrontdecrypt¶
Path |
POST /tofrontdecrypt |
Description |
Encrypts the data using the shared_secret obtained from decapsulating the decap_key and ciphertext. |
Parameters
|
- data
- ciphertext
- encrypted_mlkem_decap_key
|
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- encrypted_data
|
data |
|
Type |
String |
Encoding |
Standard base64 |
Description |
The data to encrypt and sent to frontend. |
ciphertext |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The ML-KEM-768 -derived ciphertext (decodes to 1088 bytes) |
encrypted_mlkem_decap_key |
|
Type |
String |
Encoding |
Standard base64 |
Description |
Decodes to the AES-256-CTR encrypted ML-KEM-768 decapsulation key (2400 bytes) prepended with nonce (16 bytes) and postpended with salt (32 bytes for key derivation) |
encrypted_data |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The encrypted data. |
GET /keygen¶
Path |
GET /keygen |
Description |
SPP key generation output containing encrypted secret key and NIST P-256 public key |
Parameters |
None |
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- encrypted_secret_key
- public_key
|
encrypted_secret_key |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
Decodes to the AES-256-CTR encrypted SPP secret key (32 bytes) prepended with nonce (16 bytes) and postpended with salt (32 bytes for key derivation) |
public_key |
|
Type |
String |
Encoding |
Hexadecimal (DER) |
Description |
The SPP public key |
POST /sign¶
Path |
POST /sign |
Description |
Generates the signature and proof by signing the digest using the SPP keys |
Parameters
|
- digest
- encrypted_secret_key
- public_key
|
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- signature
- proof
|
digest |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The SHA-256 digest to sign (decodes to 32 bytes) |
encrypted_secret_key |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
Decodes to the AES-256-CTR encrypted SPP secret key (32 bytes) prepended with nonce (16 bytes) and postpended with salt (32 bytes for key derivation) |
public_key |
|
Type |
String |
Encoding |
Hexadecimal (DER) |
Description |
The SPP public key |
signature |
|
Type |
String |
Encoding |
Hexadecimal (DER) |
Description |
The ECDSA secp256r1 signature |
proof |
|
Type |
String |
Encoding |
Standard base64 |
Description |
The generated zero-knowledge proof |
POST /verify¶
Path |
POST /verify |
Description |
Verify that the signature and proof for the digest is valid |
Parameters
|
- digest
- signature
- public_key
- proof
|
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- is_valid
|
digest |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The SHA-256 digest to sign (decodes to 32 bytes) |
signature |
|
Type |
String |
Encoding |
Hexadecimal (DER) |
Description |
The ECDSA secp256r1 signature |
public_key |
|
Type |
String |
Encoding |
Hexadecimal (DER) |
Description |
The SPP public key |
proof |
|
Type |
String |
Encoding |
Standard base64 |
Description |
The generated zero-knowledge proof |
is_valid |
|
Type |
Boolean |
Description |
Result of verify |
GET /mldsa_keygen¶
Path |
GET /mldsa_keygen |
Description |
MLDSA key generation output containing ML-DSA-65 public_key and encrypted private_key |
Parameters |
None |
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- mldsa_public_key
- encrypted_mldsa_private_key
|
mldsa_public_key |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The ML-DSA-65 public key (decodes to 1952 bytes) |
encrypted_mldsa_private_key |
|
Type |
String |
Encoding |
Standard base64 |
Description |
Decodes to the AES-256-CTR encrypted ML-DSA-65 secret key (4032 bytes) prepended with nonce (16 bytes) and postpended with salt (32 bytes for key derivation) |
POST /mldsa_sign¶
Path |
POST /mldsa_sign |
Description |
Generates the signature by signing the message using the ML-DSA-65 keys |
Parameters
|
- message
- encrypted_mldsa_private_key
- context
|
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- mlsignature
|
message |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The message to sign |
encrypted_mldsa_private_key |
|
Type |
String |
Encoding |
Standard base64 |
Description |
Decodes to the AES-256-CTR encrypted ML-DSA-65 secret key (4032 bytes) prepended with nonce (16 bytes) and postpended with salt (32 bytes for key derivation) |
context |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The ML-DSA context |
mlsignature |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The ML-DSA-65 detached signature |
POST /mldsa_verify¶
Path |
POST /mldsa_verify |
Description |
Verify that the ML-DSA-65 signature for the message is valid |
Parameters
|
- message
- mlsignature
- mldsa_public_key
- context
|
Return status Codes
|
200: The request completed successfully and a JSON output is returned.
400: The request failed and a string containing the error is returned.
500: The request failed and a string containing the error is returned.
|
Output
|
- is_valid
|
message |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The message to verify |
mlsignature |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The ML-DSA-65 detached signature |
mldsa_public_key |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The ML-DSA-65 public key (decodes to 1952 bytes) |
context |
|
Type |
String |
Encoding |
Hexadecimal |
Description |
The ML-DSA context that you provided |
is_valid |
|
Type |
Boolean |
Description |
Result of mldsa_verify |