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)
Zuletzt geändert: il 29/01/2026 alle 22:02
