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)

< Code-Beispiele | Weiter: API-Referenz >