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