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)
Zuletzt geändert: den 29.01.2026 um 15:12
