# usbshare — USB-Filtertreiber für Windows

Ein KMDF-Upper-Filtertreiber, der Userspace-Zugriff auf ein USB-Gerät
ermöglicht, **ohne** den vorhandenen Gerätetreiber zu ersetzen. Das ist der
Ansatz, den VirtualHere verwendet, und der Grund, warum es dort kein Zadig
braucht und das Gerät lokal funktionsfähig bleibt.

> ## Lies das zuerst
>
> **Dieser Code ist nie gelaufen.** Ich habe ihn geschrieben, aber weder
> kompiliert noch getestet — dafür braucht es Windows mit dem WDK, und das
> stand mir nicht zur Verfügung. Er ist als Ausgangspunkt gedacht, nicht als
> fertiges Produkt.
>
> Kernel-Code verzeiht nichts: ein Fehler ist ein Bluescreen, kein
> Stacktrace. Ein Treiber, der beim Booten geladen wird und dabei abstürzt,
> kann ein System unbootbar machen. **Teste ausschließlich in einer VM mit
> Snapshot**, bis er stabil läuft.
>
> Rechne mit mehreren Runden Debugging. Die Struktur sollte stimmen, die
> Details fast sicher nicht.

## Warum ein Filtertreiber

Windows hat kein Äquivalent zu Linux' usbdevfs. Um URBs an ein Gerät zu
senden, braucht es Kernel-Code. Die Alternativen:

| Ansatz | Gerät lokal nutzbar | Installation | HID/Massenspeicher |
|--------|---------------------|--------------|--------------------|
| WinUSB | Nein — ersetzt den Treiber | Zadig, pro Gerät | Meist blockiert |
| **Filtertreiber** | **Ja** | INF, pro Gerät oder klassenweit | Ja |

Der Filter setzt sich *über* den vorhandenen Treiber in den Stack. Im
Normalbetrieb reicht er alles unverändert durch. Erst wenn Userspace ein Gerät
beansprucht, fängt er die IRPs des Klassentreibers ab und leitet stattdessen
die URBs aus dem Userspace an den USB-Hub weiter.

```
      Ohne Beanspruchung            Während des Teilens
   ┌────────────────────┐        ┌────────────────────┐
   │  Klassentreiber    │        │  Klassentreiber    │
   │  (usbhid, usbstor) │        │  (bekommt nichts)  │
   └─────────┬──────────┘        └─────────┬──────────┘
             │                             ╳  abgefangen
   ┌─────────▼──────────┐        ┌─────────▼──────────┐
   │  usbshare (Filter) │        │  usbshare (Filter) │◄── usb-client
   └─────────┬──────────┘        └─────────┬──────────┘     via IOCTL
             │ durchgereicht               │ URBs
   ┌─────────▼──────────┐        ┌─────────▼──────────┐
   │  USB-Hub-Treiber   │        │  USB-Hub-Treiber   │
   └────────────────────┘        └────────────────────┘
```

## Dateien

| Datei | Inhalt |
|-------|--------|
| `driver.c` | Treiber-Einstieg, Geräte-Hinzufügen, PnP |
| `queue.c` | IOCTL-Verarbeitung, URB-Weiterleitung |
| `filter.c` | Abfangen der Klassentreiber-Anfragen im beanspruchten Zustand |
| `usbshare.h` | Interne Strukturen |
| `public.h` | IOCTL-Schnittstelle — auch von der Go-Seite verwendet |
| `usbshare.inf` | Installationsdatei |
| `usbshare.vcxproj` | Visual-Studio-Projekt |

## Bauen

Voraussetzungen: Visual Studio 2022 mit „Desktop development with C++",
Windows SDK und [WDK](https://learn.microsoft.com/windows-hardware/drivers/download-the-wdk).

```cmd
msbuild usbshare.vcxproj /p:Configuration=Release /p:Platform=x64
```

## Testen (nur in einer VM)

```cmd
:: Testsignierung erlauben — danach neu starten
bcdedit /set testsigning on
bcdedit /set nointegritychecks on

:: Selbst signieren
makecert -r -pe -ss PrivateCertStore -n "CN=usbshare-test" test.cer
signtool sign /v /s PrivateCertStore /n usbshare-test /t http://timestamp.digicert.com usbshare.sys

:: Installieren: Rechtsklick auf usbshare.inf → Installieren, dann Gerät neu einstecken
```

Für Kernel-Debugging: zweite Maschine oder Host mit WinDbg, verbunden über
`bcdedit /debug on` und `/dbgsettings net`.

## Verteilen

Für den Einsatz außerhalb einer Testmaschine muss der Treiber von Microsoft
gegengezeichnet sein. Dafür brauchst du:

1. **EV-Code-Signing-Zertifikat** — auf eine geprüfte reale Identität
   (Firma oder Einzelperson), etwa 300–500 €/Jahr, Ausstellung dauert Tage bis
   Wochen wegen der Identitätsprüfung.
2. **Microsoft-Partner-Center-Konto**, verifiziert mit demselben Zertifikat.
3. **Attestation Signing**: Treiber hochladen, Microsoft zeichnet gegen.
   Ausreichend für die meisten Fälle; volle WHQL-Zertifizierung braucht
   zusätzlich HLK-Testläufe.

Diesen Teil kann nur jemand mit einer realen Identität erledigen — er läuft
auf deinen Namen, nicht auf meinen. Das ist die eigentliche Hürde, nicht der
Code.

## Was fehlt

Der Treiber deckt Control-, Bulk- und Interrupt-Transfers ab. Nicht
implementiert:

- **Isochrone Transfers** (Webcams, Audio). Sie brauchen eine andere
  URB-Struktur mit Paketdeskriptoren und Bandbreitenreservierung.
- **Auswahl der Konfiguration/Alt-Settings** über den Filter — derzeit wird
  die vom Klassentreiber gesetzte übernommen.
- **Reset und Halt-Clear** sind angelegt, aber ungetestet.