~~NOTOC~~
{{wvds:title>Protocol}}
===== 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)
----
[[.:integration|< Code Examples]] | [[.:api|Next: API Reference >]]