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