Hacker-Software
/
usb-server
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
usb-server/README.md

9.1 KiB
Raw Blame History

USB Server

USB-Sharing ueber Netzwerk mit Relay-Server fuer NAT-Traversal.

Architektur

┌──────────────────┐         ┌──────────────┐         ┌──────────────────┐
│  Client (share)  │──ws/wss─│ Relay Server │─ws/wss──│  Client (use)    │
│  gibt USB-Geraete│         │ (Docker)     │         │  empfaengt USB-  │
│  frei            │         │ gruppiert    │         │  Geraete         │
│  Web-UI :8080    │         │ nach Hash    │         │  Web-UI :8080    │
└────────┬─────────┘         └──────────────┘         └────────┬─────────┘
         │                                                     │
    Physische USB                                     Virtuelle USB
    Geraete                                           (vhci-hcd)

Relay-Server: Einfacher WebSocket-Vermittler. Braucht keine Konfiguration - verbindet alle Clients die den gleichen Hash haben. Als Docker-Container deploybar.

Client: Kann in zwei Modi betrieben werden:

  • Share-Modus: Gibt alle lokalen USB-Geraete frei. Geraete werden erst dann vom System getrennt wenn ein Use-Client sie anfordert.
  • Use-Modus: Zeigt verfuegbare Geraete von allen Share-Clients an. Geraete koennen einzeln verbunden/getrennt werden.

Gruppierung: 3 zufaellige Tokens werden zu einem SHA256-Hash kombiniert. Alle Clients mit dem gleichen Hash gehoeren zusammen.

Quick Start

1. Relay-Server starten

# Mit Docker
docker compose up -d

# Oder direkt
make relay
./bin/usb-relay --port 8443

2. Tokens generieren

Auf dem ersten Client:

./bin/usb-client generate-token

Ausgabe:

Token 1: aB3dE...
Token 2: xY7zW...
Token 3: mN4pQ...
Hash:    a1b2c3d4e5...

Die 3 Tokens auf alle weiteren Clients kopieren.

3. USB-Geraete freigeben (Share-Modus)

./bin/usb-client share --relay ws://relay-server:8443

4. USB-Geraete empfangen (Use-Modus)

./bin/usb-client use --relay ws://relay-server:8443

Web-UI oeffnen: http://localhost:8080

Installation

Go installieren

Linux (Debian/Ubuntu)

# Aktuelle Version herunterladen (go1.25.0 oder neuer)
wget https://go.dev/dl/go1.25.0.linux-amd64.tar.gz

# Altes Go entfernen und neues installieren
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.25.0.linux-amd64.tar.gz

# PATH einrichten - ans Ende von ~/.bashrc oder ~/.profile anfuegen:
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Pruefen
go version

Windows

  1. Installer herunterladen: https://go.dev/dl/ (Datei go1.25.0.windows-amd64.msi)
  2. MSI-Installer ausfuehren - installiert Go nach C:\Program Files\Go
  3. Der Installer richtet den PATH automatisch ein
  4. Neue Eingabeaufforderung oeffnen und pruefen: 
    go version

Falls der PATH nicht automatisch gesetzt wurde:

  1. Windows-Taste > "Umgebungsvariablen" suchen > "Umgebungsvariablen fuer dieses Konto bearbeiten"
  2. Variable Path bearbeiten > Neu > C:\Program Files\Go\bin hinzufuegen
  3. Eingabeaufforderung neu oeffnen

Make installieren

Linux (Debian/Ubuntu)

sudo apt update
sudo apt install make

Linux (Fedora/RHEL)

sudo dnf install make

Windows

Option A: Chocolatey (empfohlen)

# Chocolatey installieren (Admin-PowerShell):
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Make installieren:
choco install make

Option B: MSYS2

  1. MSYS2 von https://www.msys2.org herunterladen und installieren
  2. In der MSYS2-Shell: 
    pacman -S make
  3. C:\msys64\usr\bin zum Windows PATH hinzufuegen

Option C: Ohne Make - Go-Befehle direkt ausfuehren (siehe unten)

Voraussetzungen (Laufzeit)

Linux (Share-Modus):

  • Root-Rechte (fuer USB-Geraetezugriff)

Linux (Use-Modus):

  • Kernel-Modul vhci-hcd: 
    sudo modprobe vhci-hcd
  • Fuer automatisches Laden bei Boot: 
    echo "vhci-hcd" | sudo tee /etc/modules-load.d/vhci-hcd.conf

Bauen

Mit Make

# Alles bauen (Relay + Client, Linux)
make all

# Nur Relay-Server
make relay

# Nur Client (Linux)
make client

# Client fuer Windows (Cross-Compilation von Linux)
make client-windows

Ohne Make (Go direkt)

# Linux Relay-Server
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/usb-relay ./cmd/usb-relay/

# Linux Client
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/usb-client ./cmd/usb-client/

# Windows Client (Cross-Compilation von Linux)
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o bin/usb-client.exe ./cmd/usb-client/

Unter Windows (cmd.exe):

set CGO_ENABLED=0
go build -ldflags="-s -w" -o bin\usb-client.exe ./cmd/usb-client/

Unter Windows (PowerShell):

$env:CGO_ENABLED=0
go build -ldflags="-s -w" -o bin\usb-client.exe ./cmd/usb-client/

Docker (Relay-Server)

docker compose up -d

Der Relay lauscht auf Port 8443.

CLI Befehle

usb-client generate-token          # 3 Tokens + Hash generieren
usb-client share [optionen]        # Share-Modus starten
usb-client use [optionen]          # Use-Modus starten
usb-client list                    # Lokale USB-Geraete auflisten
usb-client gui                     # Nur Web-UI starten
usb-client config                  # Konfiguration anzeigen
usb-client config set [optionen]   # Konfiguration aendern
usb-client install-service         # Als systemd-Service installieren
usb-client uninstall-service       # Service deinstallieren

Optionen

--config <pfad>    Config-Datei (Standard: ~/.usb-server/config.json)
--relay <adresse>  Relay-Server (z.B. ws://localhost:8443)
--hash <hash>      Gruppen-Hash
--name <name>      Client-Name
--web-port <port>  Web-UI Port (Standard: 8080)
--no-gui           Web-UI deaktivieren

Web-UI

Die Web-UI ist unter http://localhost:8080 erreichbar und bietet:

  • Geraete-Tab: Liste aller verfuegbaren/verbundenen USB-Geraete
  • Einstellungen: Relay-Adresse, Modus, Name konfigurieren
  • Token: Tokens generieren oder eintragen
  • Service: Als Systemdienst installieren/deinstallieren

Konfiguration

Die Konfiguration wird in ~/.usb-server/config.json gespeichert:

{
  "relay_addr": "ws://localhost:8443",
  "hash": "a1b2c3d4...",
  "mode": "use",
  "name": "Mein-PC",
  "web_port": 8080,
  "token1": "...",
  "token2": "...",
  "token3": "...",
  "auto_connect": [
    {"vendor_id": "1234", "product_id": "5678"},
    {"bus_id": "1-1.4"}
  ]
}

Als Service installieren

# Service installieren (braucht root)
sudo ./bin/usb-client install-service

# Service Status pruefen
systemctl status usb-client

# Service deinstallieren
sudo ./bin/usb-client uninstall-service

Sicherheit

  • Transport-Verschluesselung: Verwende wss:// (WebSocket over TLS) fuer den Relay-Server bei Einsatz ueber das Internet.
  • Gruppierung: Die 3 Tokens dienen als gemeinsames Geheimnis. Nur wer alle 3 Tokens kennt kann den Hash berechnen.
  • Relay: Der Relay-Server sieht nur den Hash, nicht die Tokens.

Fuer TLS am Relay-Server empfiehlt sich ein Reverse-Proxy (nginx/traefik) mit Let's Encrypt:

server {
    listen 443 ssl;
    server_name relay.example.com;

    ssl_certificate /etc/letsencrypt/live/relay.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;

    location /ws {
        proxy_pass http://localhost:8443;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Technische Details

  • Sprache: Go (single binary, keine Runtime-Abhaengigkeiten)
  • USB/IP: Natives USB/IP-Protokoll (kein externes usbip-Paket noetig)
  • USB-Zugriff: Direkte usbdevfs-ioctls (kein CGO/libusb)
  • VHCI: Direkte sysfs-Schnittstelle zum vhci-hcd Kernel-Modul
  • Relay: WebSocket mit JSON-Kontrollnachrichten und Binary-Tunneldaten
  • Tunnel: USB/IP-Protokolldaten werden durch WebSocket-Binary-Frames getunnelt

Verzeichnisstruktur

cmd/usb-relay/       - Relay-Server Binary
cmd/usb-client/      - Client Binary (share + use Modi)
internal/relay/      - WebSocket Relay & Hub
internal/protocol/   - Nachrichtentypen
internal/client/     - Client Core, Share & Use Manager
internal/usbip/      - USB/IP Protokoll, Server, VHCI
internal/usb/        - USB Enumeration & usbdevfs
internal/token/      - Token-Generierung
internal/config/     - Konfiguration
internal/web/        - Web-UI (embedded)
internal/service/    - Systemd Service

Lizenz

Proprietaere Software. Alle Rechte vorbehalten. Siehe LICENSE fuer Details.

Third-Party Lizenzen

Diese Software verwendet Open-Source-Bibliotheken. Siehe NOTICE fuer Details.