JSON-Protokoll der Windows-Bauform
Diese Seite beschreibt jede Anfrage und Antwort der Windows-Bauform. Maßgeblich sind die Typen in
win/src/protocol.rs.
Transport
- Der Dienst lauscht auf einer oder mehreren Named Pipes; ohne Konfiguration auf
\\.\pipe\wvds_crypto. Welche Pipes eine Konfigurationsdatei öffnet, steht unter Bauoptionen und Konfiguration. - Eine Anfrage ist genau eine Zeile UTF-8-JSON, abgeschlossen mit
\n. Die Antwort ist ebenso eine Zeile. Über eine Verbindung lassen sich beliebig viele Anfragen nacheinander senden. - Binärdaten sind Base64 nach RFC 4648 mit Auffüllung (
=). - Mehrere Clients dürfen gleichzeitig verbunden sein.
Gemeinsame Felder
Jede Anfrage trägt operation und request_id. Die request_id wählt der Client; der Dienst gibt sie
unverändert zurück.
Jede Antwort auf eine lesbare Anfrage enthält:
| Feld | Typ | Inhalt |
|---|---|---|
id | Zeichenkette | vom Dienst vergebene UUID der Antwort |
request_id | Zeichenkette | aus der Anfrage |
timestamp | Zahl | Zeitpunkt der Antwort, Millisekunden seit 1970-01-01 UTC |
success | Wahrheitswert | true bei Erfolg |
error | Objekt | nur bei Misserfolg: code, message, optional details |
duration_us | Zahl | Bearbeitungszeit in Mikrosekunden |
Ist die Zeile kein gültiges JSON oder fehlt ein Pflichtfeld, antwortet der Dienst nur mit
{"success":false,"error":{"code":"INVALID_REQUEST","message":"…"}}, ohne request_id.
Operationen
operation | Felder der Anfrage | Zusätzliche Felder der Antwort |
|---|---|---|
info | – | version, algorithms, status, uptime_seconds, requests_processed, keys_stored |
keygen | algorithm, optional level | key_id, algorithm, bei Schlüsselpaaren public_key |
aes_encrypt | key_id, plaintext, optional aad | ciphertext, nonce, tag, key_id |
aes_decrypt | key_id, ciphertext, nonce, tag, optional aad | plaintext |
ml_dsa_sign | key_id, message | signature, signature_size |
ml_dsa_verify | public_key, message, signature, level | valid |
ml_kem_encapsulate | public_key, level | ciphertext, shared_secret |
ml_kem_decapsulate | key_id, ciphertext | shared_secret |
export_public_key | key_id | public_key, algorithm |
hkdf | ikm, length, optional salt, info | derived_key |
Felder mit Binärinhalt sind Base64: plaintext, aad, ciphertext, nonce, tag, message,
signature, public_key, shared_secret, ikm, salt, info, derived_key. key_id und length
sind Zahlen.
algorithm und level
| Zweck | Zulässige Werte |
|---|---|
keygen.algorithm | AES-256-GCM, AES256, AES; ML-DSA, ML-DSA-44, ML-DSA-65, ML-DSA-87; ML-KEM, ML-KEM-512, ML-KEM-768, ML-KEM-1024 (Groß- und Kleinschreibung beliebig) |
level für ML-DSA | ML-DSA-44, ML-DSA-65, ML-DSA-87, ml-dsa-44 …, oder kurz 44, 65, 87 |
level für ML-KEM | ML-KEM-512, ML-KEM-768, ML-KEM-1024, ml-kem-512 …, oder kurz 512, 768, 1024 |
Ein keygen mit ML-DSA oder ML-KEM ohne level erzeugt ML-DSA-65 bzw. ML-KEM-768. Ein unbekannter
level führt zu UNSUPPORTED_ALGORITHM.
Hinweise zu einzelnen Operationen
aes_encrypterzeugt die Nonce selbst und gibt sie in der Antwort zurück. Bewahren Sienonceundtagmit dem Chiffrat auf;aes_decryptbraucht beide.ml_dsa_verifymeldet eine ungültige Signatur als Erfolg mit"valid": false. Werten Sie immervalidaus, nicht nursuccess.hkdf: Einsaltoderinfo, das kein gültiges Base64 ist, behandelt der Dienst als leer. Prüfen Sie die Kodierung vor dem Senden. Die größte mögliche Ausgabe liegt bei 8160 Byte (255 × 32).
Beispiel
Anfrage:
{"operation":"keygen","request_id":"k1","algorithm":"ML-KEM","level":"ML-KEM-768"}
Antwort (gekürzt):
{"id":"5d1c…","request_id":"k1","timestamp":1760788800000,"success":true,"duration_us":412,"key_id":2741182583,"algorithm":"ML-KEM-768","public_key":"…"}