Binarni protokol izvedbe L4Re

Ta stran bajt za bajtom opisuje vsako sporočilo, ki ga izvedba L4Re razume in pošilja. Velja za različico protokola 1. Merodajna je zaglavna datoteka l4re/pub/include/wvds_crypto.h; ta stran jo povzema in dopolnjuje z vedenjem storitve, ki ga iz zaglavja samega ni mogoče razbrati.

Prenos

Zahteve in odgovori potujejo prek DataspaceEndpoint. Storitev se prijavi pod imenom IPC CRYPTO_SVC in klicatelja pričakuje pod imenom CRYPTO_CLI; skupno območje vsake strani meri 64 KiB.

Korak	Kdo	Klic
Pošiljanje zahteve	odjemalec	`add_new_req(id, vrsta, naslov, dolžina)`; kot `vrsta` običajno vrsta zahteve iz glave
Branje in sprostitev zahteve	storitev	prebere sporočilo in za vsako sprejeto ali zavrnjeno zahtevo pokliče `free_peer_req`
Pošiljanje odgovora	storitev	`add_new_req` z istim `id` in vrsto IPC `0x80`
Branje in sprostitev odgovora	odjemalec	ovrednoti glavo in pokliče `free_peer_req`

id odgovor priredi zahtevi; izberete ga sami in naj bo enoličen med odprtimi zahtevami. Vrsta IPC odgovora je vedno 0x80, tudi pri napakah. Ali je odgovor napaka, pove izključno polje req_type v glavi sporočila.

Glava sporočila

Vsako sporočilo se začne s 16 bajti. Vsa števila so zapisana v vrstnem redu little-endian.

Odmik	Dolžina	Polje	Vsebina
0	4	`magic`	`0x43525950`, na povezavi `50 59 52 43`
4	1	`version`	`1`
5	1	`req_type`	vrsta zahteve ali odgovora, glejte spodaj
6	2	`flags`	`0`; storitev polja ne upošteva
8	4	`key_id`	identifikator ključa, `0`, če zahteva ključa ne potrebuje
12	4	`payload_len`	dolžina koristnih podatkov za glavo

Pred vsako obdelavo storitev preveri:

Sporočilo je dolgo vsaj 16 bajtov in največ 16 bajtov plus 64 KiB.
magic in version se ujemata.
payload_len je največ 65.536 in je natanko enak dolžini sporočila, zmanjšani za 16.

Prazno ali predolgo sporočilo storitev zavrže brez odgovora. Če je sporočilo krajše od glave, glava ni pravilna ali payload_len ne ustreza, odgovori z WVDS_ERR_INVALID_HEADER.

Vrste zahtev

Vrednost	Ime	`key_id`	Podprto
`0x01`	`WVDS_REQ_AES_GCM_ENCRYPT`	ključ AES	da
`0x02`	`WVDS_REQ_AES_GCM_DECRYPT`	ključ AES	da
`0x03`	`WVDS_REQ_CHACHA20_ENCRYPT`	ključ ChaCha20	le z možnostjo gradnje `chacha20`
`0x04`	`WVDS_REQ_CHACHA20_DECRYPT`	ključ ChaCha20	le z možnostjo gradnje `chacha20`
`0x10`	`WVDS_REQ_ML_DSA_SIGN`	ključ ML-DSA	da
`0x11`	`WVDS_REQ_ML_DSA_VERIFY`	`0`	da
`0x12`	`WVDS_REQ_ML_DSA_KEYGEN`	`0`	da
`0x20`	`WVDS_REQ_ML_KEM_ENCAP`	`0`	da
`0x21`	`WVDS_REQ_ML_KEM_DECAP`	ključ ML-KEM	da
`0x22`	`WVDS_REQ_ML_KEM_KEYGEN`	`0`	da
`0x30`, `0x31`	`WVDS_REQ_SLH_DSA_SIGN`, `…_VERIFY`	–	rezervirano
`0x40`, `0x41`	`WVDS_REQ_LMS_SIGN`, `…_VERIFY`	–	rezervirano
`0x50`	`WVDS_REQ_DERIVE_KEY`	`0`	da
`0x51`	`WVDS_REQ_IMPORT_KEY`	–	rezervirano
`0x52`	`WVDS_REQ_EXPORT_KEY`	par ključev	da
`0x80`	`WVDS_REQ_RESPONSE`	kot v zahtevi	odgovor
`0xFF`	`WVDS_REQ_ERROR`	`0`	odgovor z napako

Na rezervirane in nevgrajene vrste storitev odgovori z WVDS_ERR_INVALID_REQ_TYPE.

Zahteve, ki potrebuje ključ ChaCha20, danes ni mogoče izpolniti: nobena vrsta zahteve takšnega ključa ne ustvari. Enako velja za AES; glejte Ključi in njihova hramba.

Koristni podatki po zahtevah

Polja dolžin v koristnih podatkih merijo 4 bajte, little-endian. »Ostanek« pomeni vse bajte do konca koristnih podatkov.

AES-GCM

Vrsta	Zahteva	Odgovor
`0x01`	enkratna vrednost (12) · dolžina AAD (4) · AAD · čistopis (ostanek)	enkratna vrednost (12) · oznaka (16) · šifrirano besedilo (ostanek)
`0x02`	enkratna vrednost (12) · oznaka (16) · dolžina AAD (4) · AAD · šifrirano besedilo (ostanek)	čistopis (ostanek)

Enkratno vrednost zagotovi klicatelj. Vrednost, ki jo je storitev za ta ključ že videla med zadnjimi 1024, vodi do WVDS_ERR_ENCRYPTION_FAILED. ChaCha20 (0x03, 0x04) uporablja enako zgradbo.

ML-DSA

Vrsta	Zahteva	Odgovor
`0x12`	stopnja (1)	identifikator (4) · javni ključ (ostanek)
`0x10`	stopnja (1) · sporočilo (ostanek)	podpis (ostanek)
`0x11`	stopnja (1) · dolžina ključa (4) · javni ključ · dolžina podpisa (4) · podpis · sporočilo (ostanek)	rezultat (1): `1` veljaven, `0` neveljaven

Stopnje: 2 = ML-DSA-44, 3 = ML-DSA-65, 5 = ML-DSA-87. Pri 0x10 storitev podpiše le sporočilo; bajt stopnje vanj ne sodi, stopnjo pa storitev vzame iz ključa. Pri 0x12 je novi identifikator zapisan tudi v polju key_id glave odgovora.

Neveljaven podpis ni odgovor z napako, temveč odgovor z rezultatom 0. Če javnega ključa ni mogoče uporabiti, storitev odgovori z WVDS_ERR_VERIFICATION_FAILED.

ML-KEM

Vrsta	Zahteva	Odgovor
`0x22`	stopnja (1)	identifikator (4) · javni ključ (ostanek)
`0x20`	stopnja (1) · javni ključ (ostanek)	skupna skrivnost (32) · šifrirano besedilo (ostanek)
`0x21`	šifrirano besedilo (ostanek)	skupna skrivnost (32)

Stopnje: 1 = ML-KEM-512, 3 = ML-KEM-768, 5 = ML-KEM-1024.

Izpeljava ključev in javni ključi

Vrsta	Zahteva	Odgovor
`0x50`	dolžina soli (4) · sol · dolžina info (4) · info · izhodna dolžina (4) · IKM (ostanek)	izpeljani ključ (izhodna dolžina)
`0x52`	brez koristnih podatkov	javni ključ (ostanek)

Pri 0x50 mora biti key_id enak 0, IKM ne sme biti prazen, izhodna dolžina pa sme znašati največ 1024 bajtov. 0x52 vrne javni ključ ključa ML-DSA ali ML-KEM; za druge ključe storitev odgovori z WVDS_ERR_KEY_NOT_FOUND.

Velikosti

Nabor parametrov	Javni ključ	Podpis oz. šifrirano besedilo
ML-DSA-44	1312	2420
ML-DSA-65	1952	3309
ML-DSA-87	2592	4627
ML-KEM-512	800	768
ML-KEM-768	1184	1088
ML-KEM-1024	1568	1568

Vse vrednosti so v bajtih; zaglavje jih navaja kot konstante, npr. WVDS_ML_DSA_65_SIG_SIZE.

Odgovor z napako

Glava z req_type = 0xFF in key_id = 0, nato:

Odmik	Dolžina	Vsebina
0	4	koda napake
4	4	dolžina sporočila
8	ostanek	sporočilo, UTF-8, le za diagnostiko

Kode napak navaja Kode napak. Vrednotite kodo, ne sporočila; njegovo besedilo se lahko spremeni.

Zahteve brez odgovora

Če klicatelj preseže 60.000 zahtev v 60 sekundah, storitev nadaljnje zahteve zavrže brez odgovora, da poplava ne sproži druge poplave. Skupni pomnilnik zahteve kljub temu sprosti. Na strani klicatelja za vsako zahtevo predvidite časovno omejitev.