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

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

Protokol zahteva/odgovor je binaren in teče preko skupnega pomnilnika.

----

==== Format Zahteve ====

<code>
Odmik   Velikost  Polje           Opis
-----------------------------------------------------------------------
0       1        Magic           0xC7 (fiksna vrednost)
1       1        Version         0x01 (verzija protokola)
2       1        RequestType     Operacija (glejte tabelo)
3       1        Flags           Rezervirano (0x00)
4       4        PayloadLength   Dolžina vsebine v bajtih (Little-Endian)
8       N        Payload         Podatki specifični za zahtevo
</code>

=== Magic Byte ===

Magic byte ''0xC7'' služi za prepoznavanje veljavnih zahtev. Zahteve brez pravilnega magic se takoj zavrnejo.

=== Request Types ===

| Tip | Ime | Opis |
| ''0x01'' | AES_ENCRYPT | AES-256-GCM šifriranje |
| ''0x02'' | AES_DECRYPT | AES-256-GCM dešifriranje |
| ''0x10'' | MLDSA_SIGN | ML-DSA ustvarjanje podpisa |
| ''0x11'' | MLDSA_VERIFY | ML-DSA preverjanje podpisa |
| ''0x20'' | MLKEM_KEYGEN | ML-KEM generiranje ključnega para |
| ''0x21'' | MLKEM_ENCAPS | ML-KEM enkapsulacija |
| ''0x22'' | MLKEM_DECAPS | ML-KEM dekapsulacija |

----

==== Format Odgovora ====

<code>
Odmik   Velikost  Polje           Opis
-----------------------------------------------------------------------
0       1        Magic           0xC8 (Response Magic)
1       1        Version         0x01
2       1        Status          0x00 = Uspeh, sicer koda napake
3       1        Flags           Rezervirano
4       4        PayloadLength   Dolžina vsebine odgovora
8       N        Payload         Podatki specifični za odgovor
</code>

=== Statusne Kode ===

| Koda | Ime | Opis |
| ''0x00'' | SUCCESS | Operacija uspešna |
| ''0x01'' | INVALID_HEADER | Format glave neveljaven |
| ''0x02'' | INVALID_TYPE | Neznan Request-Type |
| ''0x03'' | INVALID_PAYLOAD | Format vsebine neveljaven |
| ''0x04'' | KEY_NOT_FOUND | Key-ID ne obstaja |
| ''0x05'' | CRYPTO_ERROR | Kriptografska napaka |
| ''0x06'' | DECRYPTION_FAILED | Preverjanje oznake ni uspelo |
| ''0x07'' | RATE_LIMITED | Preveč zahtev |
| ''0x08'' | NONCE_REUSE | Nonce že uporabljena |
| ''0x09'' | PAYLOAD_TOO_LARGE | Vsebina > 64 KB |

----

==== Formati Vsebine ====

=== AES_ENCRYPT Zahteva (0x01) ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       4        KeyID           (Little-Endian)
4       2        AAD_Length      (Little-Endian)
6       N        AAD             (Additional Authenticated Data)
6+N     M        Plaintext       (podatki za šifriranje)
</code>

=== AES_ENCRYPT Odgovor ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       12       Nonce           (generirana s storitvijo)
12      16       Tag             (Authentication Tag)
28      N        Ciphertext      (šifrirani podatki)
</code>

=== AES_DECRYPT Zahteva (0x02) ===

<code>
Odmik   Velikost  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>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       N        Plaintext       (dešifrirani podatki)
</code>

----

=== MLDSA_SIGN Zahteva (0x10) ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       4        KeyID           (Private Key)
4       N        Message         (sporočilo za podpis)
</code>

=== MLDSA_SIGN Odgovor ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       2        SignatureLength (Little-Endian)
2       N        Signature       (ML-DSA-65: 3293 bajtov)
</code>

=== MLDSA_VERIFY Zahteva (0x11) ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       4        KeyID           (Public Key)
4       2        SignatureLength
6       N        Signature
6+N     M        Message
</code>

=== MLDSA_VERIFY Odgovor ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       1        Valid           (0x01 = veljaven, 0x00 = neveljaven)
</code>

----

=== MLKEM_KEYGEN Zahteva (0x20) ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       4        KeyID           (ID za nov ključni par)
</code>

=== MLKEM_KEYGEN Odgovor ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       2        PublicKeyLength (Little-Endian)
2       N        PublicKey       (ML-KEM-768: 1184 bajtov)
</code>

**Opomba:** Zasebni ključ ostane v storitvi in se shrani pod KeyID.

=== MLKEM_ENCAPS Zahteva (0x21) ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       2        PublicKeyLength
2       N        PublicKey
</code>

=== MLKEM_ENCAPS Odgovor ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       2        CiphertextLength
2       N        Ciphertext      (ML-KEM-768: 1088 bajtov)
2+N     32       SharedSecret
</code>

=== MLKEM_DECAPS Zahteva (0x22) ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       4        KeyID           (Private Key)
4       2        CiphertextLength
6       N        Ciphertext
</code>

=== MLKEM_DECAPS Odgovor ===

<code>
Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       32       SharedSecret
</code>

----

==== Primer: Popolna Zahteva/Odgovor ====

**AES_ENCRYPT Zahteva za "Hello":**

<code>
Odmik: 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

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

Vsebina:
  01 00 00 00  - KeyID = 1
  05 00        - AAD_Length = 5
  48 65 6C 6C 6F - AAD = "Hello" (čistopis je prazen v tem primeru)
</code>

----

[[.:integration|< Primeri kode]] | [[.:api|Naprej: API Referenca >]]