OSSign Information

What's this?

This is a fork of the original repository, with the purpose of building binaries for regular code signing.

How are updates pushed?

Open a pull request to this repository with the changes you want to be built. Once the pipeline has succeeded, the code signing will happen manually in the background, and the changes will be published to the releases section of this repository.

Where are the signed binaries published?

The signed drivers are baked into the releases on [vadimgrn/usbip-win2], and the releases themselves are signed with the project certificate.

You can find fully signed binaries, including installer and uninstaller, in the releases section in this repository section of this repository.

Original Repository

This repository is a mirror of vadimgrn/usbip-win2 and is regularly synced with the upstream repository. Please refer to the original repository for the most up-to-date-information.

USB/IP Client for Windows

• Fully compatible with USB/IP protocol
• Works with Linux USB/IP server at least for kernels 4.19 - 6.14
• WHLK certified drivers
  • Download Microsoft Hardware Certification Report
  • Certification was made possible thanks to Open Source Codesigning Initiative
• Create a restore point before installing USBip
• Devices that work (the list is incomplete)

Requirements

• Windows 10 x64 Version 1903 (OS build 18362) and later
• Windows 11 ARM64
• USB/IP server must support protocol v.1.1.1

Key features

• UDE driver is an USB/IP client
• A device-specific upper filter driver usbip2_filter is used as companion for UDE driver
• Winsock Kernel NPI is used
  • The driver establishes TCP/IP connection with a server and does data exchange
  • This implies low latency and high throughput, absence of frequent CPU context switching and a lot of syscalls
• Zero copy of transfer buffers is implemented for network send and receive operations
  • Memory Descriptor List is used to send multiple buffers in a single call (vectored I/O)
  • WskSend reads data from URB transfer buffer
  • WskReceive writes data to URB transfer buffer
• A dedicated thread is created for each virtual device to receive data from a server

Differences with cezanne/usbip-win

• The 2-Clause BSD License since release 0.9.7.0
• WHLK certified drivers
• Brand new UDE driver, not inherited from the parent repo
• Full-featured GUI app
• Userspace code is fully rewritten (libusbip and usbip utility)
• SDK for third party developers (libusbip public API)
• InnoSetup installer is used for installation of drivers and userspace stuff
• Windows 10 version 1903 or later is required
• C++ 20 is used for all projects
• Visual Studio 2022 is used
• Server (stub driver) is removed
• x64/arm64 builds only

Build

Build Tools

• Visual Studio 2022
• SDK/WDK installation is not required, NuGet will install them automatically

Build Visual Studio solution

• Install git
  • Run Visual Studio Installer
  • Select "Individual components" tab
  • Type "git" in search box
  • Check "Git for Windows"
  • Install selected items
• Clone project using git or download an archive from github and extract source code
• Run bootstrap.bat
• Open usbip_win2.sln
• Set certificate driver signing for package project
  • Right-click on the Project > Properties > Driver Signing > Test Certificate
  • Enter usbip.pfx (password: usbip)
• Build the solution
• All output files are created under {x64,ARM64}/{Debug,Release} folders.

Setup USB/IP server on Ubuntu Linux

• Install required packages
  • Linux sudo apt install linux-tools-generic linux-cloud-tools-generic
  • Raspberry Pi sudo apt install usbip hwdata usbutils
• Load modules and run the daemon

sudo modprobe -a usbip-core usbip-host
sudo usbipd -D

• List available USB devices
  • usbip list -l

 - busid 3-2 (1005:b113)
   Apacer Technology, Inc. : Handy Steno/AH123 / Handy Steno 2.0/HT203 (1005:b113)
 - busid 3-3.2 (07ca:513b)
   AVerMedia Technologies, Inc. : unknown product (07ca:513b)

• Bind desired USB device
  • sudo usbip bind -b 3-2

usbip: info: bind device on busid 3-2: complete

• Your device 3-2 now can be used by usbip client

Setup USB/IP on Windows

Enable Windows Test Signing Mode if drivers are not signed by Microsoft

• bcdedit.exe /set testsigning on
• Reboot the system to apply
• Do not disable testsigning if USBip has test-signed drivers, otherwise all USB devices will not work

Install USB/IP

• Create a restore point to undo possible system crashes
  • In the search box on the taskbar, type 'Create a restore point', and select it from the list of results
  • On the System Protection tab in System Properties
    • Make sure system drive protection is enabled
    • Select Create
    • Type a description for the restore point, and then select Create
• Download and run an installer from
  • Releases
    • Drivers are signed by Microsoft, other binaries (*.exe, *.dll) are test-signed by project's certificate
  • OSSign
    • Drivers and all binaries, including the installer, are signed by Microsoft
    • Use it if officially signed binaries are a mandatory requirement
• Some antivirus programs issue false positives for InnoSetup installer
• All USB Hub 3.0 devices will be restarted during an installation
  • This means that all USB devices will stop working for a short time and then start working again.
  • Make sure you don't interrupt your important workflow, such as a video call using a USB webcam, an audio call using a USB headset, copying from/to USB drive, etc.

Use usbip.exe to attach remote device(s)

• Query available USB devices on the server
  • usbip.exe list -r <usbip server ip>

Exportable USB devices
======================
 - 192.168.1.9
        3-2: unknown vendor : unknown product (1005:b113)
           : /sys/devices/pci0000:00/0000:00:14.0/usb3/3-2
           : (Defined at Interface level) (00/00/00)

• Attach desired remote USB device using its busid
  • usbip.exe attach -r <usbip server ip> -b 3-2

successfully attached to port 1

• New USB device should appear in the system, use it as usual
• Detach the remote USB device using its usb port, pass -all to detach all remote devices
  • usbip.exe detach -p 1

port 1 is successfully detached

Uninstallation of USB/IP

• Uninstall USB/IP app
• Disable test signing if it was enabled during the installation
  • bcdedit.exe /set testsigning off
  • Reboot the system to apply
• If the uninstaller is corrupted, run these commands as Administrator
• If you copy commands to a .bat file, use %%P and %%~nxP in FOR statement

SET HWID=ROOT\USBIP_WIN2\UDE
set APPDIR=C:\Program Files\USBip

"%APPDIR%\devnode.exe" remove %HWID% root
rem alternative command since Windows 11, version 21H2
rem pnputil.exe /remove-device /deviceid %HWID% /subtree

rem WARNING: use %%P and %%~nxP if you run this command in a .bat file
FOR /f %P IN ('findstr /M /L /Q:u "usbip2_filter usbip2_ude" C:\WINDOWS\INF\oem*.inf') DO pnputil.exe /delete-driver %~nxP /uninstall

rd /S /Q "%APPDIR%"

Obtaining USB/IP logs on Windows

• WPP Software Tracing is used
• Use the tools for software tracing, such as TraceView, Tracelog, Tracefmt, and Tracepdb to configure, start, and stop tracing sessions and to display and filter trace messages
• These tools are included in the Windows Driver Kit
• Pick "Select Components/Program DataBase files" during USBip installation
• Start log sessions for drivers (run commands as Administrator)

rem change to your WDK version
set PATH=%PATH%;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64

set NAME=usbip

tracelog.exe -stop %NAME%-flt
tracelog.exe -stop %NAME%-ude

del /F %NAME%-*.*
tracepdb.exe -f "C:\Program Files\USBip\*.pdb" -s -p %TEMP%\%NAME%

tracelog.exe -start %NAME%-flt -guid #90c336ed-69fb-43d6-b800-1552d72d200b -f %NAME%-flt.etl -flag 0x3 -level 5
tracelog.exe -start %NAME%-ude -guid #ed18c9c5-8322-48ae-bf78-d01d898a1562 -f %NAME%-ude.etl -flag 0xF -level 5

• Reproduce the issue
• Stop log sessions and get plain text logs (run commands as Administrator)
• If you copy commands to a .bat file, double '%' in TRACE_FORMAT_PREFIX

rem change to your WDK version
set PATH=%PATH%;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x64

set NAME=usbip
set TRACE_FORMAT_PREFIX=[%9]%3!04x! %!LEVEL! %!FUNC!:

tracelog.exe -stop %NAME%-flt
tracelog.exe -stop %NAME%-ude

tracefmt.exe -nosummary -p %TEMP%\%NAME% -o %NAME%-flt.txt %NAME%-flt.etl
tracefmt.exe -nosummary -p %TEMP%\%NAME% -o %NAME%-ude.txt %NAME%-ude.etl

rem sed -i "s/TRACE_LEVEL_CRITICAL/CRT/;s/TRACE_LEVEL_ERROR/ERR/;s/TRACE_LEVEL_WARNING/WRN/;s/TRACE_LEVEL_INFORMATION/INF/;s/TRACE_LEVEL_VERBOSE/VRB/" %NAME%-*.txt
rem sed -i "s/`anonymous namespace':://" %NAME%-*.txt
rem del /F sed*

Debugging BSOD

• Enable kernel memory dump
  • Open "System Properties" dialog box
  • Select "Advanced" tab
  • Click on "Settings" in "Startup and Recovery"
  • "System failure", "Write debugging information", pick "Automatic Memory Dump" or "Kernel Memory Dump"
  • Check "Overwrite any existing file"
• Start WPP tracing session for drivers as described in the previous topic
• When BSOD has occured
  • Reboot PC if automatic reboot is not set
  • Run Windows debugger WinDbg.exe as Administrator
  • Press Ctrl+D to open crash dump in C:\Windows
  • Run following commands and copy the output

.sympath+ C:\Program Files\USBip
!wmitrace.searchpath +%TEMP%\usbip
!analyze -v
!wdfkd.wdfsearchpath %TEMP%\usbip
!wdfkd.wdfsettraceprefix [%9]%3!04x! %!LEVEL! %!FUNC!:
!wdfkd.wdflogdump usbip2_ude -d
!wdfkd.wdflogdump usbip2_ude -f

Obtaining USB/IP log on Linux

sudo killall usbipd
sudo modprobe -r usbip-host usbip-vudc vhci-hcd usbip-core
sudo modprobe usbip-core usbip_debug_flag=0xFFFFFFFF
sudo modprobe -a usbip-host usbip-vudc vhci-hcd
sudo usbipd -D
dmesg --follow | tee ~/usbip.log

Testing the driver

• Driver Verifier is used for testing
• Run verifier.exe as Administrator
• Enable testing

verifier /rc 1 2 4 5 6 8 9 12 18 34  10 11 14 15 16 17 20 24 26 33 35 36 /driver usbip2_filter.sys usbip2_ude.sys

• Be aware that rule class 26 "Code integrity checking" forces to use NonPagedPoolNx instead of NonPagedPool
• Query driver statistics

verifier /query

• Disable testing

verifier /reset

• To run Static Driver Verifier, set "Treat Warnings As Errors" to "No" for libdrv, usbip2_filter, usbip2_ude projects

If you like this project