Running the Signing Host as a Virtual Machine: USB Passthrough Options

You will learn how to route physical USB cryptographic tokens to a virtualized Windows host running OneSigner, evaluate hypervisor-level passthrough options, and handle common stability issues during automated builds.

The Virtualization Constraint for Hardware Tokens

OneSigner requires one Windows machine that stays powered on with your hardware token physically plugged into a USB port. OneSigner handles PAdES PDF signing and Windows Authenticode code signing, and exposes a REST API, watched folders, and an Azure Key Vault-compatible proxy that AzureSignTool or OneSignTool can call from your CI/CD pipelines. Many teams prefer to run this Windows environment inside a hypervisor rather than dedicating bare-metal server hardware.

Since June 2023, the CA/Browser Forum requires certified hardware for Organisation Validation (OV) code-signing certificates as well as Extended Validation (EV) certificates. Software-only key storage is no longer permitted for code signing. This means your private keys reside on a physical USB token—such as a YubiKey, SafeNet eToken, or ePass2003—which must maintain an active connection to the operating system running OneSigner. Note that OneSigner produces PAdES signatures from a certificate you hold; the software does not make your setup inherently qualified under eIDAS or other regional regulations by itself. The legal validity of the signature depends entirely on your certificate and hardware token.

When you virtualize the signing host, your primary engineering challenge is maintaining an uninterrupted, low-latency communication channel between the guest operating system and the physical USB device plugged into the hypervisor host. USB isolation failures break automated folder watches, fail REST API calls, and cause signing queues to hang until a human physically resets the USB bus.

Hypervisor USB Passthrough Architecture

Different hypervisors handle USB device mapping through distinct architectural layers. Choosing the right platform dictates whether your signing host survives a hypervisor reboot or a virtual machine migration without dropping the cryptographic session.

When configuring your hypervisor, avoid sharing the physical USB controller with high-bandwidth peripherals like webcams or mass storage devices. Cryptographic tokens require stable interrupt requests and low bus latency. If your build pipeline triggers frequent concurrent signing requests via automated code signing in CI/CD without a cloud HSM, a dropped USB connection locks up the PKCS#11 or CryptoAPI provider inside Windows.

Configuring Proxmox VE for USB Token Passthrough

Proxmox VE runs on a Linux kernel that interacts directly with host USB buses. To pass a hardware token—such as a YubiKey—to your Windows VM running OneSigner, you can map the device using its vendor and product ID or by attaching the physical USB controller.

First, log in to your Proxmox host via SSH and list the connected USB devices to identify your token's vendor and product IDs:

lsusb

Locate your token in the output. For example, a YubiKey typically appears with vendor ID 1050 and a specific product ID like 0407. Next, configure your Windows virtual machine (supposing VM ID 100) to grab this device by editing the VM configuration file located at /etc/pve/qemu-server/100.conf or by using the Proxmox CLI tool:

qm set 100 -usb0 host=1050:0407

If you remove and reinsert the token into a different physical port on the Proxmox host, a vendor/product ID mapping can sometimes fail to re-initialize if multiple identical tokens are present. To ensure absolute stability across reboots, you can map the physical USB port path directly:

qm set 100 -usb0 host=3-4

Verify that the device appears inside your Windows guest operating system by opening Device Manager and checking for the smart card reader or security key device. Once the token is visible in the guest, install the vendor middleware or minidriver inside the VM exactly as you would on bare metal; OneSigner reaches the token through that middleware (PKCS#11 or the Windows CSP/KSP) for your automated invoice signing folder watch workflows.

Configuring VMware ESXi and Hyper-V

If your enterprise infrastructure standardizes on VMware ESXi, you must add a USB controller to the virtual machine hardware configuration before passing through individual devices. In the vSphere Client, edit your Windows VM settings, click Add Other Device, and select USB Controller (choose xHCI for modern tokens). Once the controller is attached, click Add Other Device again and select USB Device, choosing your specific hardware token from the dropdown list.

Be aware that the token stays physically attached to the original ESXi host. vSphere keeps a passed-through USB device connected across vMotion only if vMotion support was enabled when the device was added, and even then the connection depends on that original host staying up. If the host reboots or the device disconnects, OneSigner loses access to the private key until you reattach the device in the vSphere Client.

Microsoft Hyper-V presents unique challenges for hardware tokens. Hyper-V has no native USB device passthrough for either VM generation; the built-in route is Remote Desktop USB redirection through Enhanced Session Mode. A device redirected that way exists only while someone keeps a client connection open to the VM and disappears when it closes, which makes it unsuitable for an unattended signing host. If you must use Hyper-V, you should bypass native hypervisor passthrough entirely and deploy a network USB-over-IP solution.

Network USB-over-IP for Production Reliability

When virtual machine migrations, hypervisor upgrades, or port instability threaten your signing uptime, isolate the physical token entirely from the hypervisor host using a dedicated USB-over-IP device server, such as a hardware unit from Silex or Digi, or a software-based daemon running on a separate low-power Raspberry Pi or dedicated appliance.

A USB-over-IP setup encapsulates the USB protocol packets inside standard TCP/IP traffic. The physical token plugs into the USB-over-IP server, and the Windows virtual machine running OneSigner installs a lightweight client driver that makes the remote token appear as a local hardware device.

1. Plug your hardware token into the USB-over-IP hardware appliance connected to your local network switch.
2. Install the vendor-provided client software on your Windows virtual machine hosting OneSigner.
3. Connect to the appliance IP address through the client management utility and set the token to auto-connect upon Windows startup.
4. Configure the VM to log on to the desktop automatically after a reboot (auto-logon), because OneSigner uses the token from an interactive user session rather than from the service's Session 0.
5. Restart the VM and confirm that a test signature succeeds without human intervention.

This architecture completely eliminates hypervisor-specific passthrough limitations. You can live-migrate your virtual machine across different hosts, reboot your virtualization cluster, or scale your infrastructure without ever breaking the cryptographic session required for your production builds and document workflows. If your organization requires high availability or completely hands-off operations, evaluate whether a dedicated bare-metal mini-PC or a reliable USB-over-IP bridge fits your operational risk profile better than direct hypervisor passthrough.