~~NOTOC~~
{{wvds:title>Protokoll}}
===== Protokoll-Spezifikation =====
Das Request/Response-Protokoll ist binaer und laeuft ueber Shared Memory.
----
==== Request Format ====
Offset Groesse Feld Beschreibung
-----------------------------------------------------------------------
0 1 Magic 0xC7 (fester Wert)
1 1 Version 0x01 (Protokoll-Version)
2 1 RequestType Operation (siehe Tabelle)
3 1 Flags Reserviert (0x00)
4 4 PayloadLength Laenge der Payload in Bytes (Little-Endian)
8 N Payload Request-spezifische Daten
=== Magic Byte ===
Das Magic Byte ''0xC7'' dient zur Erkennung gueltiger Requests. Requests ohne korrektes Magic werden sofort abgelehnt.
=== Request Types ===
| Type | Name | Beschreibung |
| ''0x01'' | AES_ENCRYPT | AES-256-GCM verschluesseln |
| ''0x02'' | AES_DECRYPT | AES-256-GCM entschluesseln |
| ''0x10'' | MLDSA_SIGN | ML-DSA Signatur erstellen |
| ''0x11'' | MLDSA_VERIFY | ML-DSA Signatur pruefen |
| ''0x20'' | MLKEM_KEYGEN | ML-KEM Schluesselpaar generieren |
| ''0x21'' | MLKEM_ENCAPS | ML-KEM Encapsulation |
| ''0x22'' | MLKEM_DECAPS | ML-KEM Decapsulation |
----
==== Response Format ====
Offset Groesse Feld Beschreibung
-----------------------------------------------------------------------
0 1 Magic 0xC8 (Response Magic)
1 1 Version 0x01
2 1 Status 0x00 = Success, sonst Error Code
3 1 Flags Reserviert
4 4 PayloadLength Laenge der Response-Payload
8 N Payload Response-spezifische Daten
=== Status Codes ===
| Code | Name | Beschreibung |
| ''0x00'' | SUCCESS | Operation erfolgreich |
| ''0x01'' | INVALID_HEADER | Header-Format ungueltig |
| ''0x02'' | INVALID_TYPE | Unbekannter Request-Type |
| ''0x03'' | INVALID_PAYLOAD | Payload-Format ungueltig |
| ''0x04'' | KEY_NOT_FOUND | Key-ID existiert nicht |
| ''0x05'' | CRYPTO_ERROR | Kryptografischer Fehler |
| ''0x06'' | DECRYPTION_FAILED | Tag-Verifikation fehlgeschlagen |
| ''0x07'' | RATE_LIMITED | Zu viele Anfragen |
| ''0x08'' | NONCE_REUSE | Nonce wurde bereits verwendet |
| ''0x09'' | PAYLOAD_TOO_LARGE | Payload > 64 KB |
----
==== Payload-Formate ====
=== AES_ENCRYPT Request (0x01) ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 4 KeyID (Little-Endian)
4 2 AAD_Length (Little-Endian)
6 N AAD (Additional Authenticated Data)
6+N M Plaintext (zu verschluesselnde Daten)
=== AES_ENCRYPT Response ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 12 Nonce (vom Service generiert)
12 16 Tag (Authentication Tag)
28 N Ciphertext (verschluesselte Daten)
=== AES_DECRYPT Request (0x02) ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 4 KeyID
4 12 Nonce
16 16 Tag
32 2 AAD_Length
34 N AAD
34+N M Ciphertext
=== AES_DECRYPT Response ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 N Plaintext (entschluesselte Daten)
----
=== MLDSA_SIGN Request (0x10) ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 4 KeyID (Private Key)
4 N Message (zu signierende Nachricht)
=== MLDSA_SIGN Response ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 2 SignatureLength (Little-Endian)
2 N Signature (ML-DSA-65: 3293 Bytes)
=== MLDSA_VERIFY Request (0x11) ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 4 KeyID (Public Key)
4 2 SignatureLength
6 N Signature
6+N M Message
=== MLDSA_VERIFY Response ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 1 Valid (0x01 = gueltig, 0x00 = ungueltig)
----
=== MLKEM_KEYGEN Request (0x20) ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 4 KeyID (ID fuer neues Schluesselpaar)
=== MLKEM_KEYGEN Response ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 2 PublicKeyLength (Little-Endian)
2 N PublicKey (ML-KEM-768: 1184 Bytes)
**Hinweis:** Der Private Key verbleibt im Service und wird unter der KeyID gespeichert.
=== MLKEM_ENCAPS Request (0x21) ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 2 PublicKeyLength
2 N PublicKey
=== MLKEM_ENCAPS Response ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 2 CiphertextLength
2 N Ciphertext (ML-KEM-768: 1088 Bytes)
2+N 32 SharedSecret
=== MLKEM_DECAPS Request (0x22) ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 4 KeyID (Private Key)
4 2 CiphertextLength
6 N Ciphertext
=== MLKEM_DECAPS Response ===
Offset Groesse Feld
-----------------------------------------------------------------------
0 32 SharedSecret
----
==== Beispiel: Vollstaendiger Request/Response ====
**AES_ENCRYPT Request fuer "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 ist leer in diesem Beispiel)
----
[[.:integration|< Code-Beispiele]] | [[.:api|Weiter: API-Referenz >]]