Specifikacija Protokola

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

Format Zahteve

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

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

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

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)

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)

AES_ENCRYPT Odgovor

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

AES_DECRYPT Zahteva (0x02)

Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       4        KeyID
4       12       Nonce
16      16       Tag
32      2        AAD_Length
34      N        AAD
34+N    M        Ciphertext

AES_DECRYPT Odgovor

Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       N        Plaintext       (dešifrirani podatki)

MLDSA_SIGN Zahteva (0x10)

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

MLDSA_SIGN Odgovor

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

MLDSA_VERIFY Zahteva (0x11)

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

MLDSA_VERIFY Odgovor

Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       1        Valid           (0x01 = veljaven, 0x00 = neveljaven)

MLKEM_KEYGEN Zahteva (0x20)

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

MLKEM_KEYGEN Odgovor

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

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

MLKEM_ENCAPS Zahteva (0x21)

Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       2        PublicKeyLength
2       N        PublicKey

MLKEM_ENCAPS Odgovor

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

MLKEM_DECAPS Zahteva (0x22)

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

MLKEM_DECAPS Odgovor

Odmik   Velikost  Polje
-----------------------------------------------------------------------
0       32       SharedSecret

Primer: Popolna Zahteva/Odgovor

AES_ENCRYPT Zahteva za „Hello“: 

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)

< Primeri kode | Naprej: API Referenca >