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

Fix HID transfers, harden the tunnel, add E2E crypto and direct peers

Browse Source 
The HID failure came down to the endpoint type map being indexed by
endpoint number without the direction bit. A composite device can have
endpoint 1 as both interrupt IN (0x81) and bulk OUT (0x01); the last one
read won, so interrupt URBs were submitted as bulk and the kernel rejected
them. The device attached and stayed silent.

Endpoint data now comes from the raw descriptors read from /dev/bus/usb
rather than sysfs, which only ever exposes the active alternate setting —
a webcam's isochronous endpoints are invisible there because they only
exist after SET_INTERFACE. Two sysfs parsing bugs fell out of that too:
the numeric endpoint attributes are hex without a prefix (wMaxPacketSize
"0040" was read as 40, not 64), and bInterval was never read at all.

Reliability: three places could freeze the whole process. The share path
fed io.Pipe from the WebSocket read loop, so one slow USB transfer stalled
every tunnel and the keepalives with them. The relay wrote to client
sockets while holding the hub lock, so one peer that stopped reading
blocked routing and registration for everyone. Control transfers ran
inline in the protocol loop behind a 5s timeout. Also fixed: a use-after-
free where a discarded URB's memory could be collected while the kernel
still owned it, a reap loop that spun at 100% CPU on ioctl errors, a
missing attach timeout, a double close(done) panic, and Hash[:8] in the
relay's log line, which let a client with a short hash take the server
down.

Adds mode "both", so one client can offer and consume devices at once.
The tunnel and client-left callbacks became multicast for it: as plain
fields the second manager to register silently unhooked the first.

Tunnel traffic is now AES-256-GCM end to end, on the relay path as well
as directly. The key is derived from the three tokens, not from the group
hash — the relay is told the hash, so a key derived from it would protect
nothing from the one party in the middle. Group IDs are unchanged, so
existing setups keep working; only clients configured without the tokens
drop to unencrypted, relay-only operation.

Peers now try to connect directly, with the relay supplying the public
address neither side can determine for itself. Candidates are raced
because an unreachable address hangs until timeout rather than refusing.
Falling back to the relay is not an error.

Platform reach: cross-compiled targets for ARM, MIPS and RISC-V (the
Linux client needed no code changes — usbdevfs is not architecture
specific), multi-arch Docker images, an Android bridge that accepts
devices over SCM_RIGHTS because apps cannot open /dev/bus/usb, and macOS
builds via system_profiler enumeration.

Adds a Windows KMDF filter driver under driver/windows with its Go side.
UNTESTED: it has never been compiled or run, needs the WDK to build and
an EV certificate to distribute. Treat it as a starting point.

Adds "usb-client diag": says per machine whether sharing and using are
possible, what stands in the way, and what fixes it. Reports can be
uploaded to a relay to get them off machines that are awkward to copy
from.

96 tests, all green under -race. Builds for linux, windows and darwin on
amd64 and arm64.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
duffyduck
2026-08-11 22:02:04 +02:00
co-authored by Claude Opus 5
parent 54178dce75
commit 9ed473a965
95 changed files with 12181 additions and 892 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/client/share.go
+264 -31
View File
@@ -8,6 +8,7 @@ import (
"time"
"github.com/duffy/usb-server/internal/config"
"github.com/duffy/usb-server/internal/crypto"
"github.com/duffy/usb-server/internal/protocol"
"github.com/duffy/usb-server/internal/usb"
"github.com/duffy/usb-server/internal/usbip"
@@ -22,21 +23,81 @@ type ShareManager struct {
devices []usb.Device
active map[string]*activeShare // busID -> active share
tunnels map[string]*shareTunnel // tunnelID -> tunnel
// secret derives per-tunnel keys. Nil when the client is configured with
// only a group hash, in which case tunnels stay unencrypted.
secret *crypto.TunnelSecret
// listener accepts direct connections from peers. Nil when direct
// connections are disabled or could not be set up, which just means every
// tunnel goes through the relay.
listener *directListener
}
type activeShare struct {
device *usb.Device
server *usbip.Server
usedBy string // client ID using this device
tunnelID string
device *usb.Device
server *usbip.Server
usedBy string // client ID using this device
tunnelID string
}
type shareTunnel struct {
id string
busID string
inPipe *io.PipeWriter
outPipe *io.PipeReader
done chan struct{}
id string
busID string
// in carries peer -> USB/IP server bytes. It buffers instead of blocking
// so that feeding it from the WebSocket read loop cannot stall the client.
in *streamBuffer
// out carries USB/IP server -> peer bytes. This direction stays a pipe:
// blocking there is real backpressure onto the USB reap loop, which is
// what we want when the network cannot keep up.
outPipe *io.PipeReader
done chan struct{}
// codec seals outgoing and opens incoming payloads, whichever transport
// carries them.
codec *tunnelCodec
// sendMu guards swapping the transport when a direct connection takes
// over from the relay mid-tunnel.
sendMu sync.Mutex
send tunnelSender
direct *directConn
}
// setTransport switches this tunnel to a new sender, closing the old direct
// connection if there was one.
func (t *shareTunnel) setTransport(sender tunnelSender, conn *directConn) {
t.sendMu.Lock()
defer t.sendMu.Unlock()
if t.direct != nil && t.direct != conn {
t.direct.Close()
}
t.send = sender
t.direct = conn
}
// deliver encodes and transmits one payload over the current transport.
func (t *shareTunnel) deliver(payload []byte) error {
t.sendMu.Lock()
sender := t.send
t.sendMu.Unlock()
if sender == nil {
return fmt.Errorf("tunnel %s has no transport", t.id)
}
return send(t.codec, sender, payload)
}
// closeDirect tears down any direct connection this tunnel holds.
func (t *shareTunnel) closeDirect() {
t.sendMu.Lock()
defer t.sendMu.Unlock()
if t.direct != nil {
t.direct.Close()
t.direct = nil
}
}
// NewShareManager creates a share manager
@@ -46,18 +107,118 @@ func NewShareManager(client *Client, cfg *config.Config) *ShareManager {
cfg: cfg,
active: make(map[string]*activeShare),
tunnels: make(map[string]*shareTunnel),
secret: client.TunnelSecret(),
}
// Set up callbacks
sm.startDirectListener()
// Share-side messages only this manager handles.
client.OnRequestDevice = sm.handleRequestDevice
client.OnReleaseDevice = sm.handleReleaseDevice
client.OnTunnelData = sm.handleTunnelData
client.OnClientLeft = sm.handleClientLeft
client.OnForceRelease = sm.handleForceRelease
// Shared with the use manager in "both" mode, hence multicast.
client.AddTunnelHandler(sm.handleTunnelData)
client.AddClientLeftHandler(sm.handleClientLeft)
client.AddDisconnectHandler(sm.handleRelayDisconnect)
return sm
}
// startDirectListener opens the port peers connect to for direct tunnels.
//
// Failure is never fatal: without a listener every tunnel simply goes through
// the relay, which is exactly how the system worked before.
func (sm *ShareManager) startDirectListener() {
if sm.cfg.DisableDirect {
log.Printf("[share] direct connections disabled by configuration")
return
}
if sm.secret == nil {
log.Printf("[share] direct connections unavailable: no tokens configured, only a group hash")
return
}
listener, err := newDirectListener(sm.cfg.DirectPort, sm.secret)
if err != nil {
log.Printf("[share] direct connections unavailable: %v (falling back to relay)", err)
return
}
sm.listener = listener
sm.client.SetDirectPort(listener.Port())
}
// DirectPort reports the port peers can reach for direct tunnels, 0 if none.
func (sm *ShareManager) DirectPort() int {
if sm.listener == nil {
return 0
}
return sm.listener.Port()
}
// awaitDirect waits for the peer to connect directly and, when it does, moves
// the tunnel off the relay.
//
// The switch is safe at any moment because USB/IP is a stream of complete
// messages and each tunnel frame carries one chunk of it: frames sent before
// the switch travel via the relay, frames after it travel directly, and both
// arrive in order at the same reader. Nothing is in flight in pieces.
func (sm *ShareManager) awaitDirect(tunnel *shareTunnel, accepted <-chan *directConn) {
select {
case conn := <-accepted:
if conn == nil {
return
}
select {
case <-tunnel.done:
conn.Close()
return
default:
}
log.Printf("[share] tunnel %s now direct with %s, bypassing the relay",
tunnel.id, conn.RemoteAddr())
tunnel.setTransport(directSender(conn), conn)
// Incoming frames now arrive on this connection instead of the relay.
receiveLoop(conn, tunnel.codec, func(payload []byte) error {
_, err := tunnel.in.Write(payload)
return err
}, tunnel.done, "share/"+tunnel.busID)
// The direct connection ended. The USB/IP stream cannot resume on the
// relay mid-conversation — the peer's VHCI has torn down its side —
// so release the device and let it be requested again.
select {
case <-tunnel.done:
default:
log.Printf("[share] direct connection for %s ended, releasing device", tunnel.busID)
go sm.handleReleaseDevice(tunnel.busID, "")
}
case <-tunnel.done:
}
}
// handleRelayDisconnect releases every active share after the relay link
// drops. The relay discarded those tunnels, so the remote side is gone and
// the local device would otherwise stay claimed and unusable.
func (sm *ShareManager) handleRelayDisconnect() {
sm.mu.RLock()
busIDs := make([]string, 0, len(sm.active))
for busID := range sm.active {
busIDs = append(busIDs, busID)
}
sm.mu.RUnlock()
for _, busID := range busIDs {
log.Printf("[share] releasing %s (relay connection lost)", busID)
sm.handleReleaseDevice(busID, "")
}
}
// Run starts the share manager: periodic device enumeration + event handling
func (sm *ShareManager) Run() error {
// Initial enumeration
@@ -89,6 +250,14 @@ func (sm *ShareManager) GetDevices() []usb.Device {
return result
}
// RefreshNow re-enumerates and announces immediately, rather than waiting for
// the next poll. Used when devices appear through the bridge, where the
// change is known the instant it happens.
func (sm *ShareManager) RefreshNow() {
sm.refreshDevices()
sm.broadcastDeviceList()
}
func (sm *ShareManager) refreshDevices() {
devices, err := usb.Enumerate()
if err != nil {
@@ -202,15 +371,44 @@ func (sm *ShareManager) handleRequestDevice(targetClient, fromClient, busID, req
tunnelID += "0"
}
inReader, inWriter := io.Pipe()
codec, err := newTunnelCodec(sm.secret, tunnelID, crypto.DirShareToUse)
if err != nil {
sm.mu.Unlock()
server.Detach()
log.Printf("[share] failed to set up tunnel encryption for %s: %v", busID, err)
sm.client.SendJSON(map[string]interface{}{
"type": protocol.MsgDeviceDenied,
"bus_id": busID,
"request_id": requestID,
"reason": fmt.Sprintf("tunnel setup failed: %v", err),
"target_client": fromClient,
})
return
}
in := newStreamBuffer()
outReader, outWriter := io.Pipe()
tunnel := &shareTunnel{
id: tunnelID,
busID: busID,
inPipe: inWriter,
in: in,
outPipe: outReader,
done: make(chan struct{}),
codec: codec,
}
// Start on the relay. If the peer reaches us directly, the transport is
// swapped underneath without the USB/IP layer noticing.
tunnel.setTransport(relaySender(sm.client, tunnelID), nil)
// Register the tunnel before announcing it, so a peer that connects
// immediately after receiving the grant is not rejected as unknown.
var accepted <-chan *directConn
if sm.listener != nil {
var err error
if accepted, err = sm.listener.Expect(tunnelID); err != nil {
log.Printf("[share] cannot expect a direct connection for %s: %v", busID, err)
}
}
share := &activeShare{
@@ -224,23 +422,26 @@ func (sm *ShareManager) handleRequestDevice(targetClient, fromClient, busID, req
sm.tunnels[tunnelID] = tunnel
sm.mu.Unlock()
// Start USB/IP protocol handler in background
// Start USB/IP protocol handler in background.
// The tunnel carries the USB/IP transfer phase directly: on Linux the
// use side hands the socket straight to VHCI, and on Windows usbip.exe's
// management phase is answered locally, so there is no import request here.
go func() {
defer func() {
close(tunnel.done)
inWriter.Close()
in.Close()
outWriter.Close()
outReader.Close()
}()
// First handle the management phase (import request from client)
// The USB/IP client will send OP_REQ_IMPORT, we respond, then enter transfer phase
err := server.HandleConnection(inReader, outWriter)
err := server.HandleConnection(in, outWriter)
if err != nil {
log.Printf("[share] USB/IP connection error for %s: %v", busID, err)
}
}()
// Forward outgoing data from USB/IP server to tunnel
// Forward outgoing data from the USB/IP server over whichever transport
// the tunnel currently uses.
go func() {
buf := make([]byte, 65536)
for {
@@ -248,13 +449,20 @@ func (sm *ShareManager) handleRequestDevice(targetClient, fromClient, busID, req
if err != nil {
return
}
if err := sm.client.SendTunnelData(tunnelID, buf[:n]); err != nil {
if err := tunnel.deliver(buf[:n]); err != nil {
log.Printf("[share] tunnel %s send failed: %v", tunnelID, err)
return
}
}
}()
// Send grant message
// Wait in the background for the peer to connect directly.
if accepted != nil {
go sm.awaitDirect(tunnel, accepted)
}
// Send grant message, including where we can be reached directly. The
// relay adds the public address it sees before passing this on.
sm.client.SendJSON(map[string]interface{}{
"type": protocol.MsgDeviceGranted,
"bus_id": busID,
@@ -263,9 +471,12 @@ func (sm *ShareManager) handleRequestDevice(targetClient, fromClient, busID, req
"dev_id": dev.DevID(),
"speed": dev.Speed,
"target_client": fromClient,
"endpoints": localEndpoints(sm.DirectPort()),
"encrypted": codec.encrypted(),
})
log.Printf("[share] device %s granted to %s (tunnel=%s)", busID, fromClient, tunnelID)
log.Printf("[share] device %s granted to %s (tunnel=%s, encrypted=%v)",
busID, fromClient, tunnelID, codec.encrypted())
// Broadcast updated device list
sm.refreshDevices()
@@ -282,13 +493,17 @@ func (sm *ShareManager) handleReleaseDevice(busID, fromClient string) {
return
}
// Close the tunnel pipe to signal HandleConnection to stop reading
// Close the tunnel input to signal HandleConnection to stop reading
var tunnelDone <-chan struct{}
if tunnel, ok := sm.tunnels[share.tunnelID]; ok {
tunnel.inPipe.Close()
tunnel.in.Close()
tunnel.closeDirect()
tunnelDone = tunnel.done
delete(sm.tunnels, share.tunnelID)
}
if sm.listener != nil {
sm.listener.Forget(share.tunnelID)
}
server := share.server
delete(sm.active, busID)
@@ -332,7 +547,7 @@ func (sm *ShareManager) handleForceRelease(targetClient, fromClient, busID strin
return
}
log.Printf("[share] force-releasing %s (requested by %s, was used by %s)", busID, fromClient[:8], share.usedBy[:8])
log.Printf("[share] force-releasing %s (requested by %s, was used by %s)", busID, protocol.ShortID(fromClient), protocol.ShortID(share.usedBy))
sm.handleReleaseDevice(busID, share.usedBy)
}
@@ -347,7 +562,7 @@ func (sm *ShareManager) handleClientLeft(msg *protocol.ClientLeft) {
sm.mu.RUnlock()
for _, busID := range toRelease {
log.Printf("[share] auto-releasing %s (client %s left)", busID, msg.ClientID[:8])
log.Printf("[share] auto-releasing %s (client %s left)", busID, protocol.ShortID(msg.ClientID))
sm.handleReleaseDevice(busID, msg.ClientID)
}
}
@@ -358,11 +573,24 @@ func (sm *ShareManager) handleTunnelData(tunnelID string, data []byte) {
sm.mu.RUnlock()
if !exists {
// In "both" mode the use manager owns the other tunnels and sees the
// same frames, so an unknown ID here is normal.
return
}
// Write incoming data to the USB/IP server's input pipe
tunnel.inPipe.Write(data)
payload, err := tunnel.codec.decode(data)
if err != nil {
log.Printf("[share] tunnel %s: rejecting relayed frame: %v", tunnelID, err)
go sm.handleReleaseDevice(tunnel.busID, "")
return
}
// Buffered, non-blocking: this runs on the WebSocket read loop, which
// must never stall on the USB side.
if _, err := tunnel.in.Write(payload); err != nil {
log.Printf("[share] tunnel %s input failed: %v — releasing %s", tunnelID, err, tunnel.busID)
go sm.handleReleaseDevice(tunnel.busID, "")
}
}
func (sm *ShareManager) cleanup() {
@@ -371,7 +599,8 @@ func (sm *ShareManager) cleanup() {
for busID, share := range sm.active {
if tunnel, ok := sm.tunnels[share.tunnelID]; ok {
tunnel.inPipe.Close()
tunnel.in.Close()
tunnel.closeDirect()
}
share.server.Detach()
log.Printf("[share] cleaned up device %s", busID)
@@ -379,6 +608,11 @@ func (sm *ShareManager) cleanup() {
sm.active = make(map[string]*activeShare)
sm.tunnels = make(map[string]*shareTunnel)
if sm.listener != nil {
sm.listener.Close()
sm.listener = nil
}
}
// DeviceListForAPI returns device info formatted for the web API
@@ -407,4 +641,3 @@ func (sm *ShareManager) DeviceListForAPI() []map[string]interface{} {
}
return result
}