Implement a first-class Windows UMDF virtual serial transport

[rtreit]

Summary

Implement a first-class Windows virtual serial transport for CatHub using User-Mode Driver Framework 2 (UMDF 2), with a pure Rust driver as the preferred production architecture. Use Microsoft's windows-drivers-rs project and the Rust WDK toolchain wherever the required UMDF APIs are available. This should remove the com0com dependency for CatHub-managed endpoints while keeping CatHub-authored driver logic outside the Windows kernel.

The initial platform target is supported x64 editions of Windows 11. TCP-only CatHub installations must remain driver-free, and existing physical or externally provisioned serial transports must remain supported.

This issue covers the complete production transport. The first implementation milestone is a deliberately narrow proof of concept that validates the architecture before the full compatibility surface is built.

Motivation

The current Windows example requires com0com pairs for five legacy serial clients:

Client	CatHub port	Application port
HDSDR through OmniRig	COM10	COM11
N1MM radio CAT	COM20	COM21
ARCP-590	COM30	COM31
N1MM WinKeyer	COM40	COM41
WKTools maintenance	COM42	COM43

This creates ten virtual COM ports, requires a separate legacy kernel driver, requires separate administrative provisioning, and can create driver-signing and Secure Boot problems on current Windows systems. The current development station required Secure Boot to be disabled for its legacy com0com 3.0.0.0 driver.

CatHub owns both the virtual endpoint and the station-facing protocol implementation. It therefore does not need a general-purpose two-ended null-modem cable. A CatHub-specific transport can expose one COM port to each legacy application and use a private device interface for the CatHub daemon.

Architectural direction

Use the Microsoft UMDF 2 virtual serial architecture as the starting point, but implement the CatHub driver in Rust. Treat the Microsoft VirtualSerial2 C++ sample as an API and behavior reference rather than a production code base.

Legacy Windows application
          |
        COM21
          |
Microsoft UMDF reflector
          |
WUDFHost.exe
          |
CatHub pure Rust virtual-serial UMDF driver DLL
          |
Private CatHub device interface
          |
cathub.exe
          |
Radio or WinKeyer broker

Only the application-facing COM port is public. CatHub communicates through a private, versioned device interface. CatHub-authored code must not include a kernel-mode driver binary.

The expected configured endpoints become:

Client	Visible COM port	CatHub backend
HDSDR through OmniRig	COM11	Private CatHub device channel
N1MM radio CAT	COM21	Private CatHub device channel
ARCP-590	COM31	Private CatHub device channel
N1MM WinKeyer	COM41	Private CatHub device channel
WKTools maintenance	COM43	Private CatHub device channel

Components

Pure Rust UMDF transport driver

Create a pure Rust UMDF 2 driver DLL using Microsoft's windows-drivers-rs project, Cargo, and the current supported WDK toolchain. Keep it isolated from the Rust daemon and limit it to Windows serial-device behavior and transport framing.

Rust is the preferred production implementation, including the exported driver entry point, WDF callbacks, request queues, device context, and private CatHub transport. A thin C or C++ shim is permitted only if the PoC identifies a specific blocking UMDF ABI, binding, or toolchain gap that cannot reasonably be fixed or contributed upstream. Any such exception must be documented with the missing API, the attempted Rust solution, the safety boundary, and a plan to remove the shim.

The Rust implementation must:

• build as the UMDF driver DLL through Cargo with a reproducible, pinned windows-drivers-rs and WDK configuration
• expose the required Windows driver entry points and callbacks through stable C ABI boundaries
• isolate all unsafe code in small, auditable Windows interop modules
• provide safe internal wrappers for WDF handles, request and buffer lifetimes, callback contexts, and ownership transfer
• prevent Rust panics from unwinding across Windows or WDF FFI boundaries
• keep the serial state machine, buffering, framing, and protocol logic in safe Rust
• document the pinned windows-drivers-rs revision and every local binding or build-system workaround
• treat Rust compiler warnings and Clippy warnings as errors and keep formatting, dependency, and supply-chain checks green
• test safe protocol and state-machine code independently from the installed driver wherever practical

The driver must:

• register application-facing Ports-class device instances and GUID_DEVINTERFACE_COMPORT
• expose a separate private CatHub device interface
• associate each application COM port with a stable CatHub endpoint identifier
• move bytes asynchronously between the COM handle and CatHub's private handle
• support independent endpoint instances without cross-endpoint data leakage
• run in a suitably isolated WUDFHost.exe configuration
• fail outstanding I/O predictably if the driver host or CatHub connection fails
• support clean device restart without rebooting Windows

Private CatHub protocol

Define a small versioned control and data contract between the UMDF driver and cathub.exe. It must support:

• protocol version negotiation
• endpoint discovery and identity
• CatHub attach and detach
• bidirectional byte transfer
• cancellation and purge notifications
• serial configuration and modem-control notifications
• application open and close notifications
• transport health and driver version reporting
• bounded buffers and explicit backpressure behavior

The private interface must be ACL-restricted so an unrelated process cannot impersonate CatHub or inject radio and keyer traffic.

CatHub Windows adapter

Add a Windows-only Rust adapter that discovers the private device interface and presents it to the existing serial endpoint and WinKeyer endpoint tasks as asynchronous byte streams plus control events.

The adapter must not move radio protocol policy into the driver. Dialect translation, permissions, PTT arbitration, WinKeyer leases, and fail-safe unkey behavior remain in cathub.exe.

Provisioning UX

Add first-class commands such as:

cathub virtual-serial status
cathub virtual-serial plan
cathub virtual-serial apply
cathub virtual-serial remove

The exact command names may change, but the UX must provide:

• read-only discovery and diagnostics
• a dry-run provisioning plan
• idempotent creation and reconciliation
• stable COM-number selection
• COM Name Arbiter collision detection
• explicit reporting of which devices CatHub owns
• removal of only CatHub-owned devices
• JSON output for installers and automation
• actionable driver, signature, Device Manager, and service-health errors

Provisioning that changes devices must require elevation. Normal CatHub operation must not require administrator privileges.

Installer and signing

Provide an optional Windows installer feature for virtual COM support. Operators using only Hamlib NET or gRPC must not receive a driver package.

The production package must include:

• the UMDF driver DLL
• INF and catalog files
• a production Authenticode signature on the driver package catalog
• installation, repair, upgrade, rollback, and removal behavior
• a compatible cathub.exe
• license and provenance documentation for any reused sample material

The supported configuration must run with Secure Boot and Memory Integrity enabled. Disabling either security feature is not an acceptable installation step.

Do not assume that a pure UMDF package requires Microsoft Hardware Dev Center submission. The initial production-distribution target is a directly distributed PnP package whose catalog is signed by a publicly trusted Authenticode publisher. Microsoft WHCP/HLK certification is a separate distribution option and is required if CatHub later targets Windows Update or if direct catalog signing fails the clean-system acceptance tests below.

Investigate SignPath Foundation first as a zero-cash-cost signing candidate. SignPath supports Authenticode signing of Windows .cat files, but CatHub must obtain explicit confirmation that the Foundation program will approve a UMDF driver-package catalog and that its certificate is suitable for this PnP installation scenario. Do not treat technical file-format support as policy approval.

Signing and distribution decision gate

The first signing task, before purchasing an EV certificate or beginning WHCP work, is to determine whether a directly distributed, third-party catalog-signed pure UMDF virtual COM package installs and runs on a clean supported Windows 11 system without Hardware Dev Center submission.

Test at least the following environment:

• Secure Boot enabled
• Memory Integrity enabled
• no CatHub or signing-provider certificate manually preinstalled
• test-signing mode disabled
• no developer or preproduction signing configuration
• installation initiated by a local administrator through the proposed installer flow

Capture and preserve:

• whether Windows stages and loads the package
• the exact elevation, publisher-trust, and security prompts
• the certificate chain and catalog verification results
• Device Manager, PnPUtil, Code Integrity, and UMDF host diagnostics
• behavior after reboot, upgrade, repair, and uninstall
• whether a standard user can subsequently use the installed COM port without elevation

Evaluate signing paths in this order:

1. SignPath Foundation, if it approves CatHub and this driver-package use case.
2. Another foundation, corporate sponsor, or ordinary publicly trusted Authenticode publisher suitable for direct catalog signing.
3. A CatHub-owned certificate only if the preceding options are unavailable and direct distribution is otherwise proven.
4. EV certificate, Hardware Developer Program registration, and WHCP/HLK submission only if clean Windows rejects direct distribution, Microsoft certification is required by target users, or Windows Update distribution becomes a goal.

Serial compatibility requirements

The Microsoft sample implements only a minimal subset and is not sufficient as shipped. The CatHub driver must implement the serial behavior exercised by supported clients, including at minimum:

• synchronous and overlapped ReadFile and WriteFile
• cancellation of pending reads and writes
• read and write timeouts
• baud rate, data bits, parity, and stop bits
• hardware and software flow-control configuration
• DTR and RTS control
• CTS, DSR, DCD, and RI state reporting
• WaitCommEvent and IOCTL_SERIAL_WAIT_ON_MASK
• setting and querying event masks
• purge, abort, and queue reset behavior
• serial properties, status, queue counts, and error reporting
• break-state behavior
• exclusive-open and multiple-handle policy
• clean application close, crash, and reconnect behavior
• power transition, sleep, resume, and device restart behavior

Unsupported serial operations must return consistent Windows errors and must not hang the caller.

Safety requirements

• A virtual endpoint failure must never leave PTT or WinKeyer transmission active.
• CatHub must revoke endpoint-owned PTT and keying state when the application closes, the private driver channel disconnects, or the UMDF host terminates.
• Driver buffers must be bounded.
• All lengths, IOCTL inputs, state transitions, and cancellation races must be validated and fuzzed.
• Raw CAT and keying payloads must not be logged by default.
• Driver installation and updates must be recoverable and must not make Windows unbootable.
• CatHub must clearly distinguish driver absence, incompatible driver version, endpoint provisioning failure, and application connection failure.

Configuration and compatibility

• Preserve existing [[serial_endpoint]] and [[winkeyer_endpoint]] behavior for physical ports and externally provisioned virtual pairs.
• Add an explicit CatHub-managed virtual transport selection rather than inferring it from a COM name.
• Record the application-facing COM name and stable endpoint identifier.
• Validate duplicate names, conflicting COM assignments, unsupported platforms, and driver-version mismatches.
• Provide a documented migration path from existing transport plus application_transport com0com pairs.
• Do not silently delete or repurpose existing com0com devices.
• Continue to support Hamlib NET and typed gRPC as the preferred driver-free interfaces.

Proof-of-concept milestone

Before committing to the full driver, complete a pure Rust PoC with this narrow scope:

1. Build Microsoft's minimal windows-drivers-rs UMDF example with the current supported Rust and WDK versions.
2. Use Microsoft VirtualSerial2 to inventory the required UMDF callbacks, serial IOCTLs, queue behavior, and device metadata without porting its C++ implementation wholesale.
3. Create one CatHub-owned software device backed by a pure Rust UMDF DLL that appears as a selectable COM port.
4. Replace loopback behavior with a private user-mode channel to a small CatHub-side Rust test process.
5. Transfer bytes bidirectionally with synchronous and overlapped I/O.
6. Implement cancellation, timeouts, purge, and WaitCommEvent sufficiently for the first client.
7. Connect N1MM's radio CAT interface to the virtual port and exercise read-only TS-590 traffic through a CatHub loopback backend.
8. Crash and restart the CatHub-side process and UMDF host, verifying bounded failure and reconnection.
9. Capture user-mode dumps and WPP/ETW diagnostics.
10. Document the development-signing procedure without changing production Secure Boot policy.
11. Inventory the resulting unsafe surface and any missing windows-drivers-rs bindings. Do not introduce a C or C++ shim unless this step demonstrates a blocking gap and records the fallback justification described above.
12. Produce the direct catalog-signed package and execute the signing and distribution decision gate on a clean Windows 11 VM or physical test system.

The PoC should live on an isolated development branch and test environment. It must not replace the currently working com0com installation on the main development station.

Production implementation phases

Phase 1: contract and harness

• Define the private interface contract and versioning rules.
• Build a serial API conformance harness.
• Record the actual API and IOCTL behavior used by each supported application.

Phase 2: pure Rust UMDF data plane

• Implement production-quality asynchronous queues, cancellation, timeouts, event masks, modem state, and failure recovery.
• Add unit, integration, stress, fuzz, and verifier coverage.

Phase 3: CatHub integration

• Add the Rust Windows adapter.
• Integrate radio and WinKeyer endpoint lifecycle.
• Enforce permissions and fail-safe PTT behavior.
• Add configuration validation and migration.

Phase 4: provisioning and packaging

• Add CLI provisioning and diagnostics.
• Build the optional installer feature.
• Establish reproducible catalog generation and Authenticode signing through the approved CI provenance path.
• Prove direct third-party-signed installation on clean Windows 11 before purchasing an EV certificate or starting WHCP/HLK certification.
• Add WHCP/HLK certification and Windows Update distribution only if required by the decision gate or later distribution goals.
• Establish update, repair, and rollback workflows.

Phase 5: application and platform acceptance

Validate on supported x64 Windows 11 releases with Secure Boot and Memory Integrity enabled:

• HDSDR through OmniRig using the TS-2000 dialect
• N1MM radio CAT using the TS-590 dialect
• ARCP-590
• N1MM WinKeyer
• WKTools maintenance

Exercise repeated open and close, application crashes, CatHub restart, driver-host restart, sleep and resume, high-rate traffic, buffer saturation, cancellation races, and installer upgrade and rollback.

Acceptance criteria

• A clean Windows 11 system can optionally install CatHub virtual COM support through a signed installer.
• Secure Boot and Memory Integrity remain enabled.
• Direct catalog-signed distribution is tested with no publisher certificate preinstalled and no test, developer, or preproduction signing configuration.
• The exact administrator elevation and publisher-trust experience is documented.
• If direct distribution is rejected, the failure is reproduced and documented before WHCP/HLK becomes the required production path.
• No CatHub-authored code executes in kernel mode.
• CatHub can provision and reconcile all required application-facing COM endpoints without com0com.
• All five currently configured legacy clients pass documented compatibility tests.
• TCP-only and gRPC-only installations remain driver-free.
• Existing externally managed serial transports continue working.
• Driver-host and daemon failures do not crash Windows and do not leave the station transmitting.
• Install, upgrade, repair, rollback, and uninstall are tested and documented.
• CI builds the Rust driver reproducibly with the pinned Rust, windows-drivers-rs, and supported WDK toolchain; runs formatting, Clippy, tests, and dependency checks; and treats warnings as errors.
• Release artifacts include symbols, provenance, checksums, and signing verification.

Non-goals

• A general-purpose replacement for every com0com use case
• Linux PTY support in this issue
• Moving CAT dialect, radio state, permission, PTT, or WinKeyer policy into the driver
• Removing Hamlib NET or gRPC interfaces
• Automatically modifying third-party virtual serial devices
• Shipping an unsigned or test-signed driver to operators
• A production C or C++ driver implementation unless the PoC documents a blocking Rust binding or toolchain constraint under the exception above

Open design questions

• Will SignPath Foundation approve CatHub and permit its open-source certificate to sign this UMDF driver-package catalog?
• Does a SignPath or other publicly trusted Authenticode-signed catalog install and load on every supported clean Windows 11 configuration without Hardware Dev Center submission?
• Is the direct-install publisher prompt acceptable for CatHub operators, or is silent Microsoft-trusted installation a product requirement?
• Which concrete requirement, failure, or distribution goal would justify EV purchase and WHCP/HLK certification?
• Should every CatHub endpoint receive its own WUDFHost.exe instance, or can selected endpoints safely share one host?
• Should COM numbers be explicit, automatically assigned, or both?
• How should the private interface authenticate the CatHub service and support service upgrades?
• Which installer technology will own driver staging and rollback?
• Can application-facing device creation use the Software Device API cleanly, or should the installer create persistent root-enumerated instances?
• Which windows-drivers-rs revision and dependency strategy should be pinned until its UMDF support is published and production-ready?
• Which missing bindings or build features should CatHub contribute upstream rather than carrying locally?
• What objective evidence is required before permitting the narrowly scoped C or C++ shim fallback?

References

• Microsoft VirtualSerial2 sample: https://learn.microsoft.com/en-us/samples/microsoft/windows-driver-samples/virtual-serial-driver-sample-v2/
• Microsoft windows-drivers-rs: https://github.com/microsoft/windows-drivers-rs
• windows-drivers-rs examples: https://github.com/microsoft/windows-drivers-rs/tree/main/examples
• UMDF architecture: https://learn.microsoft.com/en-us/windows-hardware/drivers/wdf/detailed-view-of-the-umdf-architecture
• UMDF failure diagnostics: https://learn.microsoft.com/en-us/windows-hardware/drivers/wdf/determining-why-the-reflector-terminated-the-host-process
• Windows driver package components and catalogs: https://learn.microsoft.com/en-us/windows-hardware/drivers/install/components-of-a-driver-package
• Catalog files and digital signatures: https://learn.microsoft.com/en-us/windows-hardware/drivers/install/catalog-files
• Signature categories and driver installation: https://learn.microsoft.com/en-us/windows-hardware/drivers/install/signature-categories-and-driver-installation
• Windows driver signing options: https://learn.microsoft.com/en-us/windows-hardware/drivers/dashboard/driver-signing-offerings
• SignPath Foundation open-source signing: https://signpath.org/
• SignPath catalog-file signing support: https://docs.signpath.io/artifact-configuration/reference
• Windows Resiliency Initiative: https://blogs.windows.com/windowsexperience/2025/06/26/the-windows-resiliency-initiative-building-resilience-for-a-future-ready-enterprise/