Specifikacija Protokola

Protokol zahtjeva/odgovora je binarni i teče preko dijeljene memorije.

Format Zahtjeva

Pomak   Veličina  Polje           Opis
-----------------------------------------------------------------------
0       1        Magic           0xC7 (fiksna vrijednost)
1       1        Version         0x01 (verzija protokola)
2       1        RequestType     Operacija (vidi tablicu)
3       1        Flags           Rezervirano (0x00)
4       4        PayloadLength   Duljina sadržaja u bajtima (Little-Endian)
8       N        Payload         Podaci specifični za zahtjev

Magic Byte

Magic byte 0xC7 služi za prepoznavanje važećih zahtjeva. Zahtjevi bez ispravnog magica se odmah odbijaju.

Request Types

Tip Naziv Opis
0x01 AES_ENCRYPT AES-256-GCM šifriranje
0x02 AES_DECRYPT AES-256-GCM dešifriranje
0x10 MLDSA_SIGN ML-DSA kreiranje potpisa
0x11 MLDSA_VERIFY ML-DSA provjera potpisa
0x20 MLKEM_KEYGEN ML-KEM generiranje ključnog para
0x21 MLKEM_ENCAPS ML-KEM enkapsulacija
0x22 MLKEM_DECAPS ML-KEM dekapsulacija

Format Odgovora

Pomak   Veličina  Polje           Opis
-----------------------------------------------------------------------
0       1        Magic           0xC8 (Response Magic)
1       1        Version         0x01
2       1        Status          0x00 = Uspjeh, inače kod greške
3       1        Flags           Rezervirano
4       4        PayloadLength   Duljina sadržaja odgovora
8       N        Payload         Podaci specifični za odgovor

Statusni Kodovi

Kod Naziv Opis
0x00 SUCCESS Operacija uspješna
0x01 INVALID_HEADER Format zaglavlja nevažeći
0x02 INVALID_TYPE Nepoznat Request-Type
0x03 INVALID_PAYLOAD Format sadržaja nevažeći
0x04 KEY_NOT_FOUND Key-ID ne postoji
0x05 CRYPTO_ERROR Kriptografska greška
0x06 DECRYPTION_FAILED Provjera oznake nije uspjela
0x07 RATE_LIMITED Previše zahtjeva
0x08 NONCE_REUSE Nonce već korištena
0x09 PAYLOAD_TOO_LARGE Sadržaj > 64 KB

Formati Sadržaja

AES_ENCRYPT Zahtjev (0x01)

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       4        KeyID           (Little-Endian)
4       2        AAD_Length      (Little-Endian)
6       N        AAD             (Additional Authenticated Data)
6+N     M        Plaintext       (podaci za šifriranje)

AES_ENCRYPT Odgovor

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       12       Nonce           (generirana od servisa)
12      16       Tag             (Authentication Tag)
28      N        Ciphertext      (šifrirani podaci)

AES_DECRYPT Zahtjev (0x02)

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       4        KeyID
4       12       Nonce
16      16       Tag
32      2        AAD_Length
34      N        AAD
34+N    M        Ciphertext

AES_DECRYPT Odgovor

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       N        Plaintext       (dešifrirani podaci)

MLDSA_SIGN Zahtjev (0x10)

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       4        KeyID           (Private Key)
4       N        Message         (poruka za potpis)

MLDSA_SIGN Odgovor

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       2        SignatureLength (Little-Endian)
2       N        Signature       (ML-DSA-65: 3293 bajta)

MLDSA_VERIFY Zahtjev (0x11)

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       4        KeyID           (Public Key)
4       2        SignatureLength
6       N        Signature
6+N     M        Message

MLDSA_VERIFY Odgovor

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       1        Valid           (0x01 = važeći, 0x00 = nevažeći)

MLKEM_KEYGEN Zahtjev (0x20)

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       4        KeyID           (ID za novi ključni par)

MLKEM_KEYGEN Odgovor

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       2        PublicKeyLength (Little-Endian)
2       N        PublicKey       (ML-KEM-768: 1184 bajta)

Napomena: Privatni ključ ostaje u servisu i sprema se pod KeyID.

MLKEM_ENCAPS Zahtjev (0x21)

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       2        PublicKeyLength
2       N        PublicKey

MLKEM_ENCAPS Odgovor

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       2        CiphertextLength
2       N        Ciphertext      (ML-KEM-768: 1088 bajta)
2+N     32       SharedSecret

MLKEM_DECAPS Zahtjev (0x22)

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       4        KeyID           (Private Key)
4       2        CiphertextLength
6       N        Ciphertext

MLKEM_DECAPS Odgovor

Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       32       SharedSecret

Primjer: Potpuni Zahtjev/Odgovor

AES_ENCRYPT Zahtjev za „Hello“: 

Pomak: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
Bajti:  C7 01 01 00 0B 00 00 00 01 00 00 00 05 00 48 65
        6C 6C 6F

Zaglavlje:
  C7           - Magic
  01           - Version
  01           - RequestType (AES_ENCRYPT)
  00           - Flags
  0B 00 00 00  - PayloadLength = 11

Sadržaj:
  01 00 00 00  - KeyID = 1
  05 00        - AAD_Length = 5
  48 65 6C 6C 6F - AAD = "Hello" (čisti tekst je prazan u ovom primjeru)

< Primjeri koda | Dalje: API Referenca >