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