Specifica del Protocollo

Il protocollo richiesta/risposta è binario e funziona via memoria condivisa.

Formato Richiesta

Offset  Dim.     Campo           Descrizione
-----------------------------------------------------------------------
0       1        Magic           0xC7 (valore fisso)
1       1        Version         0x01 (versione protocollo)
2       1        RequestType     Operazione (vedi tabella)
3       1        Flags           Riservato (0x00)
4       4        PayloadLength   Lunghezza payload in byte (Little-Endian)
8       N        Payload         Dati specifici della richiesta

Magic Byte

Il Magic Byte 0xC7 serve per identificare richieste valide. Richieste senza magic corretto vengono immediatamente rifiutate.

Request Types

Tipo Nome Descrizione
0x01 AES_ENCRYPT Cifratura AES-256-GCM
0x02 AES_DECRYPT Decifratura AES-256-GCM
0x10 MLDSA_SIGN Creazione firma ML-DSA
0x11 MLDSA_VERIFY Verifica firma ML-DSA
0x20 MLKEM_KEYGEN Generazione coppia chiavi ML-KEM
0x21 MLKEM_ENCAPS Incapsulamento ML-KEM
0x22 MLKEM_DECAPS Decapsulamento ML-KEM

Formato Risposta

Offset  Dim.     Campo           Descrizione
-----------------------------------------------------------------------
0       1        Magic           0xC8 (Response Magic)
1       1        Version         0x01
2       1        Status          0x00 = Successo, altrimenti codice errore
3       1        Flags           Riservato
4       4        PayloadLength   Lunghezza payload risposta
8       N        Payload         Dati specifici della risposta

Codici di Stato

Codice Nome Descrizione
0x00 SUCCESS Operazione riuscita
0x01 INVALID_HEADER Formato header non valido
0x02 INVALID_TYPE Request-Type sconosciuto
0x03 INVALID_PAYLOAD Formato payload non valido
0x04 KEY_NOT_FOUND Key-ID non esiste
0x05 CRYPTO_ERROR Errore crittografico
0x06 DECRYPTION_FAILED Verifica tag fallita
0x07 RATE_LIMITED Troppe richieste
0x08 NONCE_REUSE Nonce già usata
0x09 PAYLOAD_TOO_LARGE Payload > 64 KB

Formati Payload

Richiesta AES_ENCRYPT (0x01)

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       4        KeyID           (Little-Endian)
4       2        AAD_Length      (Little-Endian)
6       N        AAD             (Additional Authenticated Data)
6+N     M        Plaintext       (dati da cifrare)

Risposta AES_ENCRYPT

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       12       Nonce           (generata dal servizio)
12      16       Tag             (Authentication Tag)
28      N        Ciphertext      (dati cifrati)

Richiesta AES_DECRYPT (0x02)

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       4        KeyID
4       12       Nonce
16      16       Tag
32      2        AAD_Length
34      N        AAD
34+N    M        Ciphertext

Risposta AES_DECRYPT

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       N        Plaintext       (dati decifrati)

Richiesta MLDSA_SIGN (0x10)

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       4        KeyID           (Private Key)
4       N        Message         (messaggio da firmare)

Risposta MLDSA_SIGN

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       2        SignatureLength (Little-Endian)
2       N        Signature       (ML-DSA-65: 3293 byte)

Richiesta MLDSA_VERIFY (0x11)

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       4        KeyID           (Public Key)
4       2        SignatureLength
6       N        Signature
6+N     M        Message

Risposta MLDSA_VERIFY

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       1        Valid           (0x01 = valida, 0x00 = non valida)

Richiesta MLKEM_KEYGEN (0x20)

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       4        KeyID           (ID per nuova coppia chiavi)

Risposta MLKEM_KEYGEN

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       2        PublicKeyLength (Little-Endian)
2       N        PublicKey       (ML-KEM-768: 1184 byte)

Nota: La chiave privata rimane nel servizio e viene memorizzata sotto KeyID.

Richiesta MLKEM_ENCAPS (0x21)

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       2        PublicKeyLength
2       N        PublicKey

Risposta MLKEM_ENCAPS

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       2        CiphertextLength
2       N        Ciphertext      (ML-KEM-768: 1088 byte)
2+N     32       SharedSecret

Richiesta MLKEM_DECAPS (0x22)

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       4        KeyID           (Private Key)
4       2        CiphertextLength
6       N        Ciphertext

Risposta MLKEM_DECAPS

Offset  Dim.     Campo
-----------------------------------------------------------------------
0       32       SharedSecret

Esempio: Richiesta/Risposta Completa

Richiesta AES_ENCRYPT per „Hello“: 

Offset: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
Byte:   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" (testo in chiaro vuoto in questo esempio)

< Esempi di codice | Continua: Riferimento API >