~~NOTOC~~
{{wvds:title>Protokol}}

===== Specifikacija Protokola =====

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

----

==== Format Zahtjeva ====

<code>
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
</code>

=== 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 ====

<code>
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
</code>

=== 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) ===

<code>
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)
</code>

=== AES_ENCRYPT Odgovor ===

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

=== AES_DECRYPT Zahtjev (0x02) ===

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

=== AES_DECRYPT Odgovor ===

<code>
Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       N        Plaintext       (dešifrirani podaci)
</code>

----

=== MLDSA_SIGN Zahtjev (0x10) ===

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

=== MLDSA_SIGN Odgovor ===

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

=== MLDSA_VERIFY Zahtjev (0x11) ===

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

=== MLDSA_VERIFY Odgovor ===

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

----

=== MLKEM_KEYGEN Zahtjev (0x20) ===

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

=== MLKEM_KEYGEN Odgovor ===

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

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

=== MLKEM_ENCAPS Zahtjev (0x21) ===

<code>
Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       2        PublicKeyLength
2       N        PublicKey
</code>

=== MLKEM_ENCAPS Odgovor ===

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

=== MLKEM_DECAPS Zahtjev (0x22) ===

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

=== MLKEM_DECAPS Odgovor ===

<code>
Pomak   Veličina  Polje
-----------------------------------------------------------------------
0       32       SharedSecret
</code>

----

==== Primjer: Potpuni Zahtjev/Odgovor ====

**AES_ENCRYPT Zahtjev za "Hello":**

<code>
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)
</code>

----

[[.:integration|< Primjeri koda]] | [[.:api|Dalje: API Referenca >]]