Protocol Specification
The Request/Response protocol is binary and runs over Shared Memory.
Request Format
Offset Size Field Description ----------------------------------------------------------------------- 0 1 Magic 0xC7 (fixed value) 1 1 Version 0x01 (protocol version) 2 1 RequestType Operation (see table) 3 1 Flags Reserved (0x00) 4 4 PayloadLength Payload length in bytes (Little-Endian) 8 N Payload Request-specific data
Magic Byte
The Magic Byte 0xC7 serves to identify valid requests. Requests without correct magic are immediately rejected.
Request Types
| Type | Name | Description |
0x01 | AES_ENCRYPT | AES-256-GCM encryption |
0x02 | AES_DECRYPT | AES-256-GCM decryption |
0x10 | MLDSA_SIGN | ML-DSA signature creation |
0x11 | MLDSA_VERIFY | ML-DSA signature verification |
0x20 | MLKEM_KEYGEN | ML-KEM key pair generation |
0x21 | MLKEM_ENCAPS | ML-KEM encapsulation |
0x22 | MLKEM_DECAPS | ML-KEM decapsulation |
Response Format
Offset Size Field Description ----------------------------------------------------------------------- 0 1 Magic 0xC8 (Response Magic) 1 1 Version 0x01 2 1 Status 0x00 = Success, otherwise Error Code 3 1 Flags Reserved 4 4 PayloadLength Response payload length 8 N Payload Response-specific data
Status Codes
| Code | Name | Description |
0x00 | SUCCESS | Operation successful |
0x01 | INVALID_HEADER | Header format invalid |
0x02 | INVALID_TYPE | Unknown Request-Type |
0x03 | INVALID_PAYLOAD | Payload format invalid |
0x04 | KEY_NOT_FOUND | Key-ID doesn't exist |
0x05 | CRYPTO_ERROR | Cryptographic error |
0x06 | DECRYPTION_FAILED | Tag verification failed |
0x07 | RATE_LIMITED | Too many requests |
0x08 | NONCE_REUSE | Nonce was already used |
0x09 | PAYLOAD_TOO_LARGE | Payload > 64 KB |
Payload Formats
AES_ENCRYPT Request (0x01)
Offset Size Field ----------------------------------------------------------------------- 0 4 KeyID (Little-Endian) 4 2 AAD_Length (Little-Endian) 6 N AAD (Additional Authenticated Data) 6+N M Plaintext (data to encrypt)
AES_ENCRYPT Response
Offset Size Field ----------------------------------------------------------------------- 0 12 Nonce (generated by service) 12 16 Tag (Authentication Tag) 28 N Ciphertext (encrypted data)
AES_DECRYPT Request (0x02)
Offset Size Field ----------------------------------------------------------------------- 0 4 KeyID 4 12 Nonce 16 16 Tag 32 2 AAD_Length 34 N AAD 34+N M Ciphertext
AES_DECRYPT Response
Offset Size Field ----------------------------------------------------------------------- 0 N Plaintext (decrypted data)
MLDSA_SIGN Request (0x10)
Offset Size Field ----------------------------------------------------------------------- 0 4 KeyID (Private Key) 4 N Message (message to sign)
MLDSA_SIGN Response
Offset Size Field ----------------------------------------------------------------------- 0 2 SignatureLength (Little-Endian) 2 N Signature (ML-DSA-65: 3293 bytes)
MLDSA_VERIFY Request (0x11)
Offset Size Field ----------------------------------------------------------------------- 0 4 KeyID (Public Key) 4 2 SignatureLength 6 N Signature 6+N M Message
MLDSA_VERIFY Response
Offset Size Field ----------------------------------------------------------------------- 0 1 Valid (0x01 = valid, 0x00 = invalid)
MLKEM_KEYGEN Request (0x20)
Offset Size Field ----------------------------------------------------------------------- 0 4 KeyID (ID for new key pair)
MLKEM_KEYGEN Response
Offset Size Field ----------------------------------------------------------------------- 0 2 PublicKeyLength (Little-Endian) 2 N PublicKey (ML-KEM-768: 1184 bytes)
Note: The Private Key remains in the service and is stored under the KeyID.
MLKEM_ENCAPS Request (0x21)
Offset Size Field ----------------------------------------------------------------------- 0 2 PublicKeyLength 2 N PublicKey
MLKEM_ENCAPS Response
Offset Size Field ----------------------------------------------------------------------- 0 2 CiphertextLength 2 N Ciphertext (ML-KEM-768: 1088 bytes) 2+N 32 SharedSecret
MLKEM_DECAPS Request (0x22)
Offset Size Field ----------------------------------------------------------------------- 0 4 KeyID (Private Key) 4 2 CiphertextLength 6 N Ciphertext
MLKEM_DECAPS Response
Offset Size Field ----------------------------------------------------------------------- 0 32 SharedSecret
Example: Complete Request/Response
AES_ENCRYPT Request for „Hello“:
Offset: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
Bytes: C7 01 01 00 0B 00 00 00 01 00 00 00 05 00 48 65
6C 6C 6F
Header:
C7 - Magic
01 - Version
01 - RequestType (AES_ENCRYPT)
00 - Flags
0B 00 00 00 - PayloadLength = 11
Payload:
01 00 00 00 - KeyID = 1
05 00 - AAD_Length = 5
48 65 6C 6C 6F - AAD = "Hello" (Plaintext is empty in this example)
Zuletzt geändert: on 2026/01/29 at 09:54 PM
