blob: 3e68a831b976049aa78fca7e669d0f303c0aa2d2 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
|
USB Development Kit (UsbDk) Design and Architecture
=============================================================
USB Development Kit is a set of software modules meant to provide
user mode applications with direct and exclusive access to USB devices
by detaching those from Windows PNP manager and device drivers and
providing user mode with API for USB-specific operations on the device.
Original intention of the kit is USB device redirection support for
spice remote desktop application however it may be used for any other
purpose directly or via libusb (there is a libusb backend for UsbDk).
USB Development Kit software consists of following modules:
1. UsbDk.sys - USB bus filter driver for acquisition of exclusive
access to USB devices.
2. UsbDkHelper.dll - Helper DLL to install, uninstall and configure
the driver and forward USB requests to USB devices.
3. UsbDkController.exe - Simple command line application for system
API usage demonstration and verification.
Using USB Development Kit for USB devices redirection (exclusive access aquisition)
USB Development Kit software is used by virt-viewer for USB devices
discovery and access as required for redirection purposes.
Overall system architecture
---------------------------
+---------------------------+ +---------------------+
| | | UsbDkController.exe |
| virt-viewer | +---------------------+
| | ^ |
+------------+--------------+ | |
| libusb | libusbredir | | |
+------------+--------------+ | |
^ | | |
|----------------------------+ |
| |<---------------------------+
Notifications like: | | High-level API like:
Device inserted | | InstallDriver/UninstallDriver
Device removed | | RedirectDevice
| | WritePipe, ReadPipe
| |
| V
+-----------------+
| UsbDkHelper.dll |<--+
+-----------------+ |
^ |
| | User Mode
----------------------+------------+---------------------------
| | Kernel Mode
Control channel | |
| | Data channel for redirected
V | device Tx/Rx transfers
Control device o |
| |
+-----------+ +-----------+ V
|PNP Manager|<->| UsbDk.sys |------o Generic USB device
+-----------+ +-----------+ ^
^ |
| | Tx/Rx passthrough
Filter and patch | | done by UsbDk.sys
device discovery | |
messages | |
| |
V |
+-------+ V
|USB hub|--------o Redirected USB device
+-------+
^
|
V
+-------------------+
|USB host controller|
+-------------------+
Kernel mode component (UsbDk.sys) design and functionality
----------------------------------------------------------
UsbDk.sys is both USB filter driver and generic USB device driver.
On installation it is being registered as USB filter driver and
system invokes it for each new USB device being discovered including
USB hubs. On invocation UsbDk.sys checks type of underlying device
and creates filter instances for USB hubs only.
Being a filter of USB hub UsbDk.sys receives all requests from upper
part of USB stack including enumeration requests that originated by
PNP manager (IRP_MJ_PNP/IRP_MN_QUERY_DEVICE_RELATIONS).
Upon enumeration request completion by USB hub driver UsbDk.sys scans
array of child devices returned and in case there are devices to be
redirected (according to current configuration) it attaches as filter
to those devices as well.
As a result all PNP manager requests pass via UsbDk.sys callbacks and the
latter patches device ID properties as needed to make PNP manager recognize
the device as a generic USB device.
Besides that UsbDk.sys marks underlying device object as raw PDO so the system
assigns the driver who created it (UsbDk.sys) to be the device driver as well.
At this stage any request to this vendor specific device will be forwarded
to UsbDk.sys which in turn will patch and pass requests to/from original device
created by USB hub as needed.
There is also a separate API provided by UsbDkHelper.dll intended to detach
USB device from USB stack without acquiring actual access to the device (hider API).
This API may be useful for security applications that need to deny access
to USB devices according to security policy or to prevent Windows from showing
"New Hardware" pop-ups for devices solely managed by UsbDk. When UsbDk.sys
discovers device to be hidden during enumeration phase
(IRP_MJ_PNP/IRP_MN_QUERY_DEVICE_RELATIONS) it wipes corresponding PDO from
device array returned by underlying USB bus driver, this effectively hides
given device from PNP manager and OS driver stack.
Device stack after UsbDk.sys installation
------------------------------------
+-----------+
|PNP Manager|
+-----------+
^
|
V
+-----------+
| UsbDk.sys | as filter driver of USB Root Hub
+-----------+
^
|
V
+-------+
|USB hub|
+-------+
^
|
V
+-------------------+
|USB host controller|
+-------------------+
QUERY_DEVICE_RELATIONS request flow
----------------------------------------------------------------
PNP Manager UsbDk driver USB Root Hub
| | |
| | |
| enumerate devices | |
|------------------------------>| |
| | enumerate devices |
| |------------------------------>|
| | array of child devices |
| |<------------------------------|
| attach filters |
| and save the device list |
| | |
| array of devices | |
|<------------------------------| |
Device access acquisition flow
--------------------------------------
UsbDkHelper.dll UsbDk.sys Specific PDO
(Mouse, Keyboard, Storage)
| | |
| | |
| GetDeviceList | |
|------------------------------>| |
| | |
| Array of devices | |
|(include VID, PID, Serial Number) |
|<------------------------------| |
| | |
| Redirect specific device | |
| (VID, PID, Serial Number) | |
|------------------------------>| |
| | |
| set state for device (redirected) |
| | |
| | Reset device |
| |------------------------------>|
~ ~ ~
~ ~ ~
| Stop redirect | |
|------------------------------>| |
| | |
| reset state for device |
| | |
| | Reset device |
| |------------------------------>|
QUERY_DEVICE_RELATIONS flow with redirected device
----------------------------------------------------
PNP Manager UsbDk driver USB Root Hub
| | |
| | |
| enumerate devices | |
|------------------------------>| |
| | enumerate devices |
| |------------------------------>|
| | array of child devices |
| |<------------------------------|
| attach as filter |
| to the PDO being redirected |
| | |
| | |
| | |
| array of child devices | |
|<------------------------------| |
Device stack after redirection initiation
------------------------
+-----------------+
| UsbDkHelper.dll |
+-----------------+
^
| User Mode
----------------------+----------------------------------------
| Kernel Mode
|
|
|
+---------------+
| Filter DO |
| UsbDk.sys |
+---------------+
^
|
V
+-----------------------+
| Specific device PDO |
| (Mouse, Storage etc.) |
+-----------------------+
^
|
V
+-------+
|USB hub|
+-------+
^
|
V
+-------------------+
|USB host controller|
+-------------------+
|
