-
Notifications
You must be signed in to change notification settings - Fork 10
/
README.usbreplay
194 lines (135 loc) · 7.74 KB
/
README.usbreplay
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
========
Replayer
========
The purpose of the Replayer is to replay a packet stream to a usb device.
The packet stream may or may not have been modified by the modifier or
other modules as described elsewhere in this document.
1. GETTING STARTED
Like other tools in the USB REVue toolkit, the Replayer reads a
pcap-formatted stream or file. Unlike other tools, it does not
output a pcap stream. Instead, the output is usb packets replayed
to a usb device. Thus, the Replayer reads from standard input
and writes to a usb device.
Command line help may be found by executing:
$ sudo ./usbreplay.py -h
OR
$ sudo ./usbreplay.py --help
To determine vendor and product id's of USB devices on your system,
you may execute the command, 'lsusb'.
To connect an input source and output destination, you may use a pipeline.
For example, to read from a pcap file called "usbmon.pcap" and replay to
a usb device with vendor id 0x1111 and product id 0x2222, you may do
the following:
$ cat usbmon.pcap | sudo usbreplay.py --vid 0x1111 --pid 0x2222
Another method using command line arguments, is to send a dev.pcap file
for a keyboard device on interface 3 as follows. Note that This particular
device has vendor id 0x413c and product id 0x2105:
$ sudo ./usbreplay.py -v 0x413c -p 0x2105 -i 3 -f dev.pcap
1.1 A Replayer Use Case
1.1.1 Use case 1: Toggling capslock and numlock leds
When capslock or numlock is toggled, a corresponding led light on the
keyboard is also toggled. This use case shows how to generate a pcap
file containing commands to toggle the keyboard capslock and numlock leds.
To replay the capslock and numlock leds, I did the following:
1) Executed 'lsusb' to list the usb devices along with their vendor and
product ids. This produced the following output.
Bus 007 Device 009: ID 413c:2003 Dell Computer Corp. Keyboard
Bus 007 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
Bus 006 Device 044: ID 0461:4d22 Primax Electronics, Ltd
Bus 006 Device 040: ID 413c:2105 Dell Computer Corp. Model L100 Keyboard
Bus 006 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
2) I then determined the bus used for the keyboard was bus 6 for device 40.
3) To capture traffic on bus 6 I executed the following command.
sudo tcpdump -i usbmon6u -w keyboard.pcap
4) I then toggled the capslock and numlock keys again and again so that
usb traffic from the keyboard could be captured into the keyboard.pcap
file by usbmon. When I was through, I hit CNTRL-C to abort usbmon.
5) Note that the usbmon command captures all traffic on bus 6, including
keyboard traffic. Therefore, to eliminate all but the keyboard traffic,
I piped the keyboard.pcap file into the Viewer so I could filter out
all traffic on bus 6 except for the keyboard device which according
to lsusb is device 40.
I also used 2 keyboards, since once the replayer starts it disables the
kernel driver for the keyboard device being replayed.
The command I executed was therefore:
cat keyboard.pcap | ./usbview.py \
| sudo ./usbreplay.py --vid 0x413c --pic 0x2105
6) Once the Viewer came up, I filtered out everything except device number 40
as follows by inserting the following command into the Display filter:
devnum==40
7) I then selected some packets and replayed them by using the 'Dump selected'
menu item. After playing around with replaying selected packets, I
then replayed everything so I could see the led visual toggle pattern I
had originally created. I did this by selecting all packets in the
Viewer, and then using the 'Dump selected' menu item to dump all
selected packets into the Replayer to be replayed en mass to the usb
device.
8) As all packets were replayed, the capslock and numlock leds toggled on
and off according to the pattern I originally created. Success!
9) To get the keyboard back, I then closed the Viewer and used the second
keyboard to CTRL-C out of the Replayer, since the keyboard being
replayed had its kernel driver disabled. Note that CTRL-C'ing out
of the replayer will re-enable the kernel driver.
2. THE USB DESCRIPTORS
Note that much of the information below is derived from 'USB in a NutShell'.
The Replayer needs at a minumum a device designated by its vendor id and
product id. All other arguments may then be either derived from this
device if it exists, or given as command line arguments. If no vendor or
product id is given, then vendor and products id defaults are used, which
only work for one specific computer. Therefore, it is recommended to
always specify the vendor and product id for your device.
You may execute lsusb at any time to see a listing of USB devices on
your system.
2.1 Device descriptor
A basic usb class hierarchy is shown below.
Note that a device descriptor, as shown below at the top of the hierarchy,
includes all sub-descriptors and therefore represents an entire device.
This, of course, means that any USB device can only have one device
descriptor.
device
/ \
configuration configuration
/ \
interface interface ...
/ \
endpoint endpoint ... ...
2.2 Configuration descriptor
Each USB device can have more than one configuration, although most
USB devices tend to only have one configuration. The configuration
descriptor specifies values for each configuration the device has,
such as amount of power a configuration uses, if device is self or bus
powered and number of interfaces it has. Since very few devices have more
than 1 configuration, the cfg index will usually be empty and we will
simply select the only active configuration, which happens to be at
index 0. Note that only 1 configuration may be enabled at a time.
2.3 Interface descriptor
The interface descriptor represents a group for performing a specific
function on the bus.
For example, for an all-in-one printer, interface 1 may represent
and describe the endpoints of the fax function, interface 2 may
describe the endpoints of the copy function, and interface 3 may
describe the endpoints of the printer function. Note that more
than one interface may be enabled at a time, and that the altsetting
function allows the interface to dynamically change interface settings.
2.3 Endpoint descriptor
Endpoint descriptors are used to describe any endpoints other than
endpoint zero. Endpoint zero is the control endpoint, is the only
required endpoint and is configured first.
USB devices are host-centric, so with respect to the host, an endpoint
is viewed as either a source or sink for data. For example, if you send
a packet to your device at endpoint 1, the data flows out from host
to device, ending up in the endpoint 1 buffer. At that point, your
firmware decides when to read the data. Alternatively, if the device
has data to send to the host, it cannot initiate this transaction
since the bus is controlled by the host and not the device. It can
however write to the endpoint 1 IN buffer. The host then can send
an IN packet at any time requesting that data. This explains why the
Replayer requires polling threads, since it never knows when data
is being presented from the device to the host.
Note that, as previously stated, all devices must support endpoint zero.
This is necessary since all control and status requests are sent
through endpoint zero.
3. CAVEATS
It is possible that due to resolution issues, replayer timing will not
be exact. This may or may not result in issues.
Note that to abort the replayer, it is necessary to hit CNTL-C.