[proxmark3-svn] / index.html

<!DOCTYPE html>
<html>

  <head>
    <meta charset='utf-8' />
    <meta http-equiv="X-UA-Compatible" content="chrome=1" />
    <meta name="description" content="Proxmark3 : Proxmark 3" />

    <link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">

    <title>Proxmark3</title>
  </head>

  <body>

    <!-- HEADER -->
    <div id="header_wrap" class="outer">
        <header class="inner">
          <a id="forkme_banner" href="https://github.com/Proxmark/proxmark3">View on GitHub</a>

          <h1 id="project_title">Proxmark3</h1>
          <h2 id="project_tagline">Proxmark 3</h2>

            <section id="downloads">
              <a class="zip_download_link" href="https://github.com/Proxmark/proxmark3/zipball/master">Download this project as a .zip file</a>
              <a class="tar_download_link" href="https://github.com/Proxmark/proxmark3/tarball/master">Download this project as a tar.gz file</a>
            </section>
        </header>
    </div>

    <!-- MAIN CONTENT -->
    <div id="main_content_wrap" class="outer">
      <section id="main_content" class="inner">
        <p>NOTICE:
(2014-03-17)
Moving the repository from google code to GitHub is up for discussion!
Please check out the following thread and post your comments...
<a href="http://www.proxmark.org/forum/viewtopic.php?id=1902">http://www.proxmark.org/forum/viewtopic.php?id=1902</a>
Discussions will close on March 31st.</p>

<h1>
<a name="proxmark" class="anchor" href="#proxmark"><span class="octicon octicon-link"></span></a>Proxmark</h1>

<p>The Proxmark III is a device developed by Jonathan Westhues that enables sniffing, reading and cloning of RFID (Radio Frequency Identification) tags. For my master thesis I wanted to look at the communication of Mifare Classic cards. Mifare Classic is used in many applications and is the most popular contactless card around. It is used in e-ticketing, public transport and access control. The higher-level protocol is kept secret by the manufacturer (NXP). I made an implementation of the ISO14443 type A standard for the Proxmark since Mifare is based on this communication standard.</p>

<p>After a lot of debugging and many noisy traces the Proxmark was ready for some real analysis. I focused on the Mifare Classic card and was happy to let the communication between card and reader appear on my screen. I could see the anticollision phase where the reader selects the card to communicate with. This was followed by an authentication and after that all communication was encrypted. The findings of this research are published on arxiv.org as A Practical Attack on the Mifare Classic</p>

<p>In December 2007 I saw the presentation of Karsten Nohl and Henryk Plotz where they showed how they reverse engineered the Mifare Classic chip. I was working on the same subject in Nijmegen. The Mifare system relied on security by obscurity and now the secrets are revealed there is no card-level security left. A video on youtube shows a demo that we gave on March 12th. It shows how we access a building with a cloned card.</p>

<h2>
<a name="checkout-the-repo" class="anchor" href="#checkout-the-repo"><span class="octicon octicon-link"></span></a>Checkout the repo...</h2>

<pre><code>$ cd your_repo_root/repo_name
$ git fetch origin
$ git checkout gh-pages
</code></pre>

<p>If you're using the GitHub for Mac, simply sync your repository and you'll see the new branch.</p>

<h1>
<a name="intro-2" class="anchor" href="#intro-2"><span class="octicon octicon-link"></span></a>INTRO 2</h1>

<p>This file contains enough software, logic (for the FPGA), and design
documentation for the hardware that you could, at least in theory,
do something useful with a proxmark3. It has commands to:</p>

<pre><code>* read any kind of 125 kHz unidirectional tag
* simulate any kind of 125 kHz unidirectional tag
</code></pre>

<p>(This is enough to perform all of the silly cloning attacks, like the
ones that I did at the Capitol in Sacramento, or anything involving
a Verichip. From a technical standpoint, these are not that exciting,
although the `software radio' architecture of the proxmark3 makes it
easy and fun to support new formats.)</p>

<p>As a bonus, I include some code to use the 13.56 MHz hardware, so you can:</p>

<pre><code>* do anything that a (medium-range) ISO 15693 reader could
* read an ISO 14443 tag, if you know the higher-layer protocol
* pretend to be an ISO 14443 tag, if you know the higher-layer protocol
* snoop on an ISO 14443 transaction
</code></pre>

<p>I am not actively developing any of this. I have other projects that
seem to be more useful.</p>

<h2>
<a name="using-the-package" class="anchor" href="#using-the-package"><span class="octicon octicon-link"></span></a>USING THE PACKAGE</h2>

<p>The software tools required to build include:</p>

<ul>
<li>cygwin or other unix-like tools for Windows</li>
<li>devkitPro (<a href="http://wiki.devkitpro.org/index.php/Getting_Started/devkitARM">http://wiki.devkitpro.org/index.php/Getting_Started/devkitARM</a>)</li>
<li>Xilinx's WebPack tools</li>
<li>Modelsim (for test only)</li>
<li>perl</li>
</ul><p>When installing devkitPro, you only need to install the compiler itself. Additional
support libraries are  not required.</p>

<p>Documentation is minimal, but see the doc/ directory for what exists. A
previous familiarity with the ARM, with digital signal processing,
and with embedded programming in general is assumed.</p>

<p>The device is used through a specialized command line interface; for
example, to clone a Verichip, you might type:</p>

<pre><code>loread                          ; this reads the tag, and stores the
                                ; raw samples in memory on the ARM

losamples                       ; then we download the samples to
                                ; the PC

vchdemod clone                  ; demodulate the ID, and then put it
                                ; back in a format that we can replay

losim                           ; and then replay it
</code></pre>

<p>To read an ISO 15693 tag, you might type:</p>

<pre><code>hiread                          ; read the tag; this involves sending a
                                ; particular command, and then getting
                                ; the response (which is stored as raw
                                ; samples in memory on the ARM)

hisamples                       ; then download those samples to the PC

hi15demod                       ; and demod them to bits (and check the
                                ; CRC etc. at the same time)
</code></pre>

<p>Notice that in both cases the signal processing mostly happened on the PC
side; that is of course not practical for a real reader, but it is easier
to initially write your code and debug on the PC side than on the ARM. As
long as you use integer math (and I do), it's trivial to port it over
when you're done.</p>

<p>The USB driver and bootloader are documented (and available separately
for download, if you wish to use them in another project) at</p>

<pre><code>http://cq.cx/trivia.pl
</code></pre>

<h2>
<a name="obtaining-hardware" class="anchor" href="#obtaining-hardware"><span class="octicon octicon-link"></span></a>OBTAINING HARDWARE:</h2>

<p>Most of the ultra-low-volume contract assemblers that have sprung up
(Screaming Circuits, the various cheap Asian suppliers, etc.) could put
something like this together with a reasonable yield. A run of around
a dozen units is probably cost-effective. The BOM includes (possibly-
outdated) component pricing, and everything is available from Digikey
and the usual distributors.</p>

<p>If you've never assembled a modern circuit board by hand, then this is
not a good place to start. Some of the components (e.g. the crystals)
must not be assembled with a soldering iron, and require hot air.</p>

<p>The schematics are included; the component values given are not
necessarily correct for all situations, but it should be possible to do
nearly anything you would want with appropriate population options.</p>

<p>The printed circuit board artwork is also available, as Gerbers and an
Excellon drill file.</p>

<h2>
<a name="future-plans-enhancements-that-you-could-make" class="anchor" href="#future-plans-enhancements-that-you-could-make"><span class="octicon octicon-link"></span></a>FUTURE PLANS, ENHANCEMENTS THAT YOU COULD MAKE:</h2>

<p>At some point I should write software involving a proper real-time
operating system for the ARM. I would then provide interrupt-driven
drivers for many of the peripherals that are polled now (the USB,
the data stream from the FPGA), which would make it easier to develop
complex applications.</p>

<p>It would not be all that hard to implement the ISO 15693 reader properly
(with anticollision, all the commands supported, and so on)--the signal
processing is already written, so it is all straightforward applications
work.</p>

<p>I have basic support for ISO 14443 as well: a sniffer, a simulated
tag, and a reader. It won't do anything useful unless you fill in the
high-layer protocol.</p>

<p>Nicer (i.e., closer-to-optimal) implementations of all kinds of signal
processing would be useful as well.</p>

<p>A practical implementation of the learning-the-tag's-ID-from-what-the-
reader-broadcasts-during-anticollision attacks would be relatively
straightforward. This would involve some signal processing on the FPGA,
but not much else after that.</p>

<p>It would be neat to write a driver that could stream samples from the A/Ds
over USB to the PC, using the full available bandwidth of USB. I am not
yet sure what that would be good for, but surely something. This would
require a kernel-mode driver under Windows, though, which is more work.</p>

<h2>
<a name="licensing" class="anchor" href="#licensing"><span class="octicon octicon-link"></span></a>LICENSING:</h2>

<p>This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.</p>

<p>This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.</p>

<p>You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA</p>

<p>Jonathan Westhues
user jwesthues, at host cq.cx</p>

<p>May 2007, Cambridge MA</p>
      </section>
    </div>

    <!-- FOOTER  -->
    <div id="footer_wrap" class="outer">
      <footer class="inner">
        <p class="copyright">Proxmark3 maintained by <a href="https://github.com/Proxmark">Proxmark</a></p>
        <p>Published with <a href="http://pages.github.com">GitHub Pages</a></p>
      </footer>
    </div>

    

  </body>
</html>
Commit	Line	Data
8d692102 W	1	<!DOCTYPE html>
	2	<html>
	3
	4	<head>
	5	<meta charset='utf-8' />
	6	<meta http-equiv="X-UA-Compatible" content="chrome=1" />
	7	<meta name="description" content="Proxmark3 : Proxmark 3" />
	8
	9	<link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">
	10
	11	<title>Proxmark3</title>
	12	</head>
	13
	14	<body>
	15
	16	<!-- HEADER -->
	17	<div id="header_wrap" class="outer">
	18	<header class="inner">
	19	<a id="forkme_banner" href="https://github.com/Proxmark/proxmark3">View on GitHub</a>
	20
	21	<h1 id="project_title">Proxmark3</h1>
	22	<h2 id="project_tagline">Proxmark 3</h2>
	23
	24	<section id="downloads">
	25	<a class="zip_download_link" href="https://github.com/Proxmark/proxmark3/zipball/master">Download this project as a .zip file</a>
	26	<a class="tar_download_link" href="https://github.com/Proxmark/proxmark3/tarball/master">Download this project as a tar.gz file</a>
	27	</section>
	28	</header>
	29	</div>
	30
	31	<!-- MAIN CONTENT -->
	32	<div id="main_content_wrap" class="outer">
	33	<section id="main_content" class="inner">
	34	<p>NOTICE:
	35	(2014-03-17)
	36	Moving the repository from google code to GitHub is up for discussion!
	37	Please check out the following thread and post your comments...
	38	<a href="http://www.proxmark.org/forum/viewtopic.php?id=1902">http://www.proxmark.org/forum/viewtopic.php?id=1902</a>
	39	Discussions will close on March 31st.</p>
	40
	41	<h1>
	42	<a name="proxmark" class="anchor" href="#proxmark"><span class="octicon octicon-link"></span></a>Proxmark</h1>
	43
	44	<p>The Proxmark III is a device developed by Jonathan Westhues that enables sniffing, reading and cloning of RFID (Radio Frequency Identification) tags. For my master thesis I wanted to look at the communication of Mifare Classic cards. Mifare Classic is used in many applications and is the most popular contactless card around. It is used in e-ticketing, public transport and access control. The higher-level protocol is kept secret by the manufacturer (NXP). I made an implementation of the ISO14443 type A standard for the Proxmark since Mifare is based on this communication standard.</p>
	45
	46	<p>After a lot of debugging and many noisy traces the Proxmark was ready for some real analysis. I focused on the Mifare Classic card and was happy to let the communication between card and reader appear on my screen. I could see the anticollision phase where the reader selects the card to communicate with. This was followed by an authentication and after that all communication was encrypted. The findings of this research are published on arxiv.org as A Practical Attack on the Mifare Classic</p>
	47
	48	<p>In December 2007 I saw the presentation of Karsten Nohl and Henryk Plotz where they showed how they reverse engineered the Mifare Classic chip. I was working on the same subject in Nijmegen. The Mifare system relied on security by obscurity and now the secrets are revealed there is no card-level security left. A video on youtube shows a demo that we gave on March 12th. It shows how we access a building with a cloned card.</p>
	49
	50	<h2>
	51	<a name="checkout-the-repo" class="anchor" href="#checkout-the-repo"><span class="octicon octicon-link"></span></a>Checkout the repo...</h2>
	52
	53	<pre><code>$ cd your_repo_root/repo_name
	54	$ git fetch origin
	55	$ git checkout gh-pages
	56	</code></pre>
	57
	58	<p>If you're using the GitHub for Mac, simply sync your repository and you'll see the new branch.</p>
	59
	60	<h1>
	61	<a name="intro-2" class="anchor" href="#intro-2"><span class="octicon octicon-link"></span></a>INTRO 2</h1>
	62
	63	<p>This file contains enough software, logic (for the FPGA), and design
	64	documentation for the hardware that you could, at least in theory,
65	do something useful with a proxmark3. It has commands to:</p>
66
67	<pre><code>* read any kind of 125 kHz unidirectional tag
68	* simulate any kind of 125 kHz unidirectional tag
69	</code></pre>
70
71	<p>(This is enough to perform all of the silly cloning attacks, like the
72	ones that I did at the Capitol in Sacramento, or anything involving
73	a Verichip. From a technical standpoint, these are not that exciting,
74	although the `software radio' architecture of the proxmark3 makes it
75	easy and fun to support new formats.)</p>
76
77	<p>As a bonus, I include some code to use the 13.56 MHz hardware, so you can:</p>
78
79	<pre><code>* do anything that a (medium-range) ISO 15693 reader could
80	* read an ISO 14443 tag, if you know the higher-layer protocol
81	* pretend to be an ISO 14443 tag, if you know the higher-layer protocol
82	* snoop on an ISO 14443 transaction
83	</code></pre>
84
85	<p>I am not actively developing any of this. I have other projects that
86	seem to be more useful.</p>
87
88	<h2>
89	<a name="using-the-package" class="anchor" href="#using-the-package"><span class="octicon octicon-link"></span></a>USING THE PACKAGE</h2>
90
91	<p>The software tools required to build include:</p>
92
93	<ul>
94	<li>cygwin or other unix-like tools for Windows</li>
95	<li>devkitPro (<a href="http://wiki.devkitpro.org/index.php/Getting_Started/devkitARM">http://wiki.devkitpro.org/index.php/Getting_Started/devkitARM</a>)</li>
96	<li>Xilinx's WebPack tools</li>
97	<li>Modelsim (for test only)</li>
98	<li>perl</li>
99	</ul><p>When installing devkitPro, you only need to install the compiler itself. Additional
100	support libraries are not required.</p>
101
102	<p>Documentation is minimal, but see the doc/ directory for what exists. A
103	previous familiarity with the ARM, with digital signal processing,
104	and with embedded programming in general is assumed.</p>
105
106	<p>The device is used through a specialized command line interface; for
107	example, to clone a Verichip, you might type:</p>
108
109	<pre><code>loread ; this reads the tag, and stores the
110	; raw samples in memory on the ARM
111
112	losamples ; then we download the samples to
113	; the PC
114
115	vchdemod clone ; demodulate the ID, and then put it
116	; back in a format that we can replay
117
118	losim ; and then replay it
119	</code></pre>
120
121	<p>To read an ISO 15693 tag, you might type:</p>
122
123	<pre><code>hiread ; read the tag; this involves sending a
124	; particular command, and then getting
125	; the response (which is stored as raw
126	; samples in memory on the ARM)
127
128	hisamples ; then download those samples to the PC
129
130	hi15demod ; and demod them to bits (and check the
131	; CRC etc. at the same time)
132	</code></pre>
133
134	<p>Notice that in both cases the signal processing mostly happened on the PC
135	side; that is of course not practical for a real reader, but it is easier
136	to initially write your code and debug on the PC side than on the ARM. As
137	long as you use integer math (and I do), it's trivial to port it over
138	when you're done.</p>
139
140	<p>The USB driver and bootloader are documented (and available separately
141	for download, if you wish to use them in another project) at</p>
142
143	<pre><code>http://cq.cx/trivia.pl
144	</code></pre>
145
146	<h2>
147	<a name="obtaining-hardware" class="anchor" href="#obtaining-hardware"><span class="octicon octicon-link"></span></a>OBTAINING HARDWARE:</h2>
148
149	<p>Most of the ultra-low-volume contract assemblers that have sprung up
150	(Screaming Circuits, the various cheap Asian suppliers, etc.) could put
151	something like this together with a reasonable yield. A run of around
152	a dozen units is probably cost-effective. The BOM includes (possibly-
153	outdated) component pricing, and everything is available from Digikey
154	and the usual distributors.</p>
155
156	<p>If you've never assembled a modern circuit board by hand, then this is
157	not a good place to start. Some of the components (e.g. the crystals)
158	must not be assembled with a soldering iron, and require hot air.</p>
159
160	<p>The schematics are included; the component values given are not
161	necessarily correct for all situations, but it should be possible to do
162	nearly anything you would want with appropriate population options.</p>
163
164	<p>The printed circuit board artwork is also available, as Gerbers and an
165	Excellon drill file.</p>
166
167	<h2>
168	<a name="future-plans-enhancements-that-you-could-make" class="anchor" href="#future-plans-enhancements-that-you-could-make"><span class="octicon octicon-link"></span></a>FUTURE PLANS, ENHANCEMENTS THAT YOU COULD MAKE:</h2>
169
170	<p>At some point I should write software involving a proper real-time
171	operating system for the ARM. I would then provide interrupt-driven
172	drivers for many of the peripherals that are polled now (the USB,
173	the data stream from the FPGA), which would make it easier to develop
174	complex applications.</p>
175
176	<p>It would not be all that hard to implement the ISO 15693 reader properly
177	(with anticollision, all the commands supported, and so on)--the signal
178	processing is already written, so it is all straightforward applications
179	work.</p>
180
181	<p>I have basic support for ISO 14443 as well: a sniffer, a simulated
182	tag, and a reader. It won't do anything useful unless you fill in the
183	high-layer protocol.</p>
184
185	<p>Nicer (i.e., closer-to-optimal) implementations of all kinds of signal
186	processing would be useful as well.</p>
187
188	<p>A practical implementation of the learning-the-tag's-ID-from-what-the-
189	reader-broadcasts-during-anticollision attacks would be relatively
190	straightforward. This would involve some signal processing on the FPGA,
191	but not much else after that.</p>
192
193	<p>It would be neat to write a driver that could stream samples from the A/Ds
194	over USB to the PC, using the full available bandwidth of USB. I am not
195	yet sure what that would be good for, but surely something. This would
196	require a kernel-mode driver under Windows, though, which is more work.</p>
197
198	<h2>
199	<a name="licensing" class="anchor" href="#licensing"><span class="octicon octicon-link"></span></a>LICENSING:</h2>
200
201	<p>This program is free software; you can redistribute it and/or modify
202	it under the terms of the GNU General Public License as published by
203	the Free Software Foundation; either version 2 of the License, or
204	(at your option) any later version.</p>
205
206	<p>This program is distributed in the hope that it will be useful,
207	but WITHOUT ANY WARRANTY; without even the implied warranty of
208	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
209	GNU General Public License for more details.</p>
210
211	<p>You should have received a copy of the GNU General Public License
212	along with this program; if not, write to the Free Software
213	Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA</p>
214
215	<p>Jonathan Westhues
216	user jwesthues, at host cq.cx</p>
217
218	<p>May 2007, Cambridge MA</p>
219	</section>
220	</div>
221
222	<!-- FOOTER -->
223	<div id="footer_wrap" class="outer">
224	<footer class="inner">
225	<p class="copyright">Proxmark3 maintained by <a href="https://github.com/Proxmark">Proxmark</a></p>
226	<p>Published with <a href="http://pages.github.com">GitHub Pages</a></p>
227	</footer>
228	</div>
229
230
231
232	</body>
233	</html>