Finalized migration to new USB CDC interface
[proxmark3-svn] / README.txt
CommitLineData
770f7345 1INTRO:
2
3This file contains enough software, logic (for the FPGA), and design
4documentation for the hardware that you could, at least in theory,
5do something useful with a proxmark3. It has commands to:
6
7 * read any kind of 125 kHz unidirectional tag
8 * simulate any kind of 125 kHz unidirectional tag
9
10(This is enough to perform all of the silly cloning attacks, like the
11ones that I did at the Capitol in Sacramento, or anything involving
12a Verichip. From a technical standpoint, these are not that exciting,
13although the `software radio' architecture of the proxmark3 makes it
14easy and fun to support new formats.)
15
16As a bonus, I include some code to use the 13.56 MHz hardware, so you can:
17
18 * do anything that a (medium-range) ISO 15693 reader could
19 * read an ISO 14443 tag, if you know the higher-layer protocol
20 * pretend to be an ISO 14443 tag, if you know the higher-layer protocol
21 * snoop on an ISO 14443 transaction
22
23I am not actively developing any of this. I have other projects that
24seem to be more useful.
25
26USING THE PACKAGE:
27
28The software tools required to build include:
29
30 * cygwin or other unix-like tools for Windows
31 * devkitPro (http://wiki.devkitpro.org/index.php/Getting_Started/devkitARM)
32 * Xilinx's WebPack tools
33 * Modelsim (for test only)
34 * perl
35
36When installing devkitPro, you only need to install the compiler itself. Additional
37support libraries are not required.
38
39Documentation is minimal, but see the doc/ directory for what exists. A
40previous familiarity with the ARM, with digital signal processing,
41and with embedded programming in general is assumed.
42
43The device is used through a specialized command line interface; for
44example, to clone a Verichip, you might type:
45
46 loread ; this reads the tag, and stores the
47 ; raw samples in memory on the ARM
48
49 losamples ; then we download the samples to
50 ; the PC
51
52 vchdemod clone ; demodulate the ID, and then put it
53 ; back in a format that we can replay
54
55 losim ; and then replay it
56
57To read an ISO 15693 tag, you might type:
58
59 hiread ; read the tag; this involves sending a
60 ; particular command, and then getting
61 ; the response (which is stored as raw
62 ; samples in memory on the ARM)
63
64 hisamples ; then download those samples to the PC
65
66 hi15demod ; and demod them to bits (and check the
67 ; CRC etc. at the same time)
68
69Notice that in both cases the signal processing mostly happened on the PC
70side; that is of course not practical for a real reader, but it is easier
71to initially write your code and debug on the PC side than on the ARM. As
72long as you use integer math (and I do), it's trivial to port it over
73when you're done.
74
75The USB driver and bootloader are documented (and available separately
76for download, if you wish to use them in another project) at
77
78 http://cq.cx/trivia.pl
79
80
81OBTAINING HARDWARE:
82
83Most of the ultra-low-volume contract assemblers that have sprung up
84(Screaming Circuits, the various cheap Asian suppliers, etc.) could put
85something like this together with a reasonable yield. A run of around
86a dozen units is probably cost-effective. The BOM includes (possibly-
87outdated) component pricing, and everything is available from Digikey
88and the usual distributors.
89
90If you've never assembled a modern circuit board by hand, then this is
91not a good place to start. Some of the components (e.g. the crystals)
92must not be assembled with a soldering iron, and require hot air.
93
94The schematics are included; the component values given are not
95necessarily correct for all situations, but it should be possible to do
96nearly anything you would want with appropriate population options.
97
98The printed circuit board artwork is also available, as Gerbers and an
99Excellon drill file.
100
101
102FUTURE PLANS, ENHANCEMENTS THAT YOU COULD MAKE:
103
104At some point I should write software involving a proper real-time
105operating system for the ARM. I would then provide interrupt-driven
106drivers for many of the peripherals that are polled now (the USB,
107the data stream from the FPGA), which would make it easier to develop
108complex applications.
109
110It would not be all that hard to implement the ISO 15693 reader properly
111(with anticollision, all the commands supported, and so on)--the signal
112processing is already written, so it is all straightforward applications
113work.
114
115I have basic support for ISO 14443 as well: a sniffer, a simulated
116tag, and a reader. It won't do anything useful unless you fill in the
117high-layer protocol.
118
119Nicer (i.e., closer-to-optimal) implementations of all kinds of signal
120processing would be useful as well.
121
122A practical implementation of the learning-the-tag's-ID-from-what-the-
123reader-broadcasts-during-anticollision attacks would be relatively
124straightforward. This would involve some signal processing on the FPGA,
125but not much else after that.
126
127It would be neat to write a driver that could stream samples from the A/Ds
128over USB to the PC, using the full available bandwidth of USB. I am not
129yet sure what that would be good for, but surely something. This would
130require a kernel-mode driver under Windows, though, which is more work.
131
132
133LICENSING:
134
135This program is free software; you can redistribute it and/or modify
136it under the terms of the GNU General Public License as published by
137the Free Software Foundation; either version 2 of the License, or
138(at your option) any later version.
139
140This program is distributed in the hope that it will be useful,
141but WITHOUT ANY WARRANTY; without even the implied warranty of
142MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
143GNU General Public License for more details.
144
145You should have received a copy of the GNU General Public License
146along with this program; if not, write to the Free Software
147Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
148
149
150Jonathan Westhues
151user jwesthues, at host cq.cx
152
153May 2007, Cambridge MA
154
Impressum, Datenschutz