~~NOTOC~~
{{wvds:title>Protocollo}}
===== 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)
----
[[.:integration|< Esempi di codice]] | [[.:api|Continua: Riferimento API >]]