cvs.zerfleddert.de Git - proxmark3-svn/blob - README.txt

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