This is a Getting Started walk-through for our Proxmark3 Easy hardware.
The Proxmark was originally created as a PhD project by Jonathan Westhues to facilitate the research of RFID systems. At the time of its design, microcontrollers were unable to provide the the high-bandwidth signal processing and precise timing required by the RFID protocols. Likewise, Software Defined Radio, or SDR, was not yet an accessible technology, requiring an entirely custom solution to be built. As such, as split architecture was designed: a microcontroller provides the high-level functionality while an FPGA handled the heavy lifting.
The initial release of iteration 3 of the Proxmark (Proxmark3 / pm3 ) looked like this:
The Proxmark design was open sourced, and one particular company took up production of the pm3, selling it for well over $350. As RFID testing and hacking became more wide spread, other companies began iterating on the open source design, creating various versions and designs - while keeping the core hardware architecture the same. At the same time, the firmware that operates the device also began to fracture into many different versions. Even so, for the most part, the hardware architecture remained the same between versions, and so, for the most part, the various firmware versions are also interchangeable (for the most part).
The way the pm3 works is that you start by picking a firmware version you want to run that has the features you want. The most well-rounded and somewhat user friendly version of firmware was forked and currently maintained by Chris “Iceman” Herrmann. He has recently discontinued his open source repository for his pm3 firmware version and moved to the RFID Research Group’s public github repo.
We have chosen a version of this firmware to pre-load on to the our Proxmark3 Easy offering. You’ll see why this is important in a moment… but first, a word about GitHub - there are a few places on the internet where open source projects tend to call home… GitHub is one such place. Open source code is kept in public repositories called a “repo” for short, and it has a certain structure to how the source is kept, updated, and downloaded. It is not important for you to know how this all works, but we are going to be interacting with GitHub to get source code and compile it.
There are two parts to the proxmark3 firmware - the bootloader and the application firmware. The application firmware is called the “full image” within the proxmark3 firmware development realm, but it does not contain the bootloader… so it is not a “full” representation of all the firmware elements that must be flashed (loaded) to the pm3 hardware…
This annoyingly inaccurate naming convention is just the first small taste of how infuriatingly unfriendly the proxmark3 can be.
Bootloader and USB communication
The bootloader is a small chunk of code that gets the proxmark3 hardware up and running, and then it executes the application “full image” firmware. For the most part, you can update the bootloader and full image all in one go if you are simply updating your firmware to the next minor revision on the same fork… but if you are changing forks from say the factory firmware over to rrg/iceman, then it’s important to attempt to update just the bootloader first, then the application firmware. Doing so can be tricky of course, which is why we have gone through the trouble of jumping forks over to rrg/iceman for you.
The bootloader also determines how your Proxmark3 communicates over USB… and the pm3 has gone through a few iterations when it comes to USB communications. Originally the pm3 communicated over USB using a direct protocol that required drivers to be installed in order for your computer to communicate with the pm3 hardware. That was eventually changed so the USB hardware on the pm3 now acts like a virtual COM port using a very common HID (human interface device) driver interface, so no special drivers are necessary… you just plug it in and the hardware should be recognized immediately as a COM port.
In Windows, you can open the Device Manager to check that your Proxmark3 is showing up as a virtual COM port… I will walk you through this process further down. If you are on MacOS don’t worry, keep reading… you will be diverted to the Mac post shortly.
Firmware + Client =
The pm3 is a headless piece of hardware. There is only one user interface component on the board - “the button”… there are no screens or navigation buttons or anything… just a single button… oh and some indicator LEDs… but other than that, for the most part, the pm3 is meant to be operated while attached to a host of some kind (computer, laptop, smartphone). The pm3 runs firmware while the host runs the proxmark client software.
The client software is sort of integrated into the proxmark3 firmware source code. It is separate software that runs on the host device, but the source code for it comes as part of the firmware source bundle and is compiled along with the firmware itself. It is critical that the client software on your host computer be the same exact version that is compiled with the firmware running on it. If not, the client may not start… or worse… it may run just fine but give you random data or inaccurate details or just act unpredictably… sometimes without you even knowing there’s a problem. It is always very important to run the same client version as the firmware on your device.
For the most part, compiling firmware and client software from source code is the norm. This is common within the Linux realm, but not normal for Windows. Within Windows, we are used to running per-compiled binaries like installing .msi files and running .exe files etc. Well strap in, because we’re not doing that crap here. Yes some dark places on the internet offer per-compiled binaries for the proxmark3 but abandon all hope ye who enter here… we’re compiling our own binaries thank you very much.
IT’S WINDOWS FROM HERE ON DOWN
Testing the hardware
Now begins our journey. I’m assuming you are using our PM3 Easy hardware with Iceman firmware running on it, and you are on Windows.
The first thing we want to do is see if the hardware shows up as a virtual com port properly on your machine. Don’t install any drivers or do anything special to your machine before starting, just do this;
- Open device manager - click Windows button and type device and it should be at the top
- Expand the Ports (COM & LPT) section - take note of any existing ports first.
- Plug in the pm3 hardware - watch for new com ports to appear
Notice that there is a new device COM6… this means the pm3 hardware is talking to Windows just fine.
Preparing the ground
Now that we know the pm3 hardware is working, we need to focus on getting Windows to provide a welcoming environment for compiling, deploying firmware, and running the client software. We are going to do this with a software package called ProxSpace.
There are a few ways for software projects to be made available for downloading from GitHub, and one of the best ways is through a “release” which is a wrapped up nice and tidy package for you do download. Luckily ProxSpace uses the release feature of GitHub;
The one issue I have is that the release structure on GitHub is somewhat… messy. The releases are sort of just posted like blog post threads on a big long scroll screen and you have to kind of dig around inside the release posts to find the package download links. Usually they are at the bottom of the release post in a section called “Assets”. At the time of this writing, version 3.7.1 was the top release for ProxSpace;
…and if you scroll to the bottom of that release, you will see a little sideways arrow triangle thing next to the word “Assets”
…and if you click Assets, it will expand to show the actual stuff you care about;
…and what you actually want to download is the ProxSpace.7z file.
Notice though the 7z file format? This is not a normal zip file but a 7-zip file… ugh… you may need to download and install a 7-zip file extractor. Everyone in the world currently suggests WinRAR for this and other strange compression formats.
You may also notice that ProxSpace is huge… a 500mb (approximately) download… and by the time it’s fully deployed it will be over 1GB… but this shouldn’t be a serious concern for you… you’re on Windows after all. Once downloaded, open the 7z file…
Notice the one ProxSpace folder inside. Extract that to your location of choice… though I will say this… I suggest you put it into either the root of your hard drive or on your desktop. It may be tempting to place it into a Program Files type location, but those folders have special permissions and protections and all that nonsense can get in the way. I personally have a little C:\working folder on my system that I put all kinds of stuff inside of… little tools… current project folders… and that’s where I have my proxspace deployment as well… C:\working\ProxSpace … now watch this handy video about how to set up ProxSpace…
In short, run the runme64.bat file and get some coffee… it’s going to take a while. It has to download more stuff, compile stuff, deploy stuff, more downloads… etc.
You may come back to what looks like a hung installation… but if you read the last few lines carefully it will tell you that you need to break (CTRL-C) and re-run … so hold CTRL and tap C to break out, then re-run the runme64.bat file to finish deploying ProxSpace.
Once finished, you should end up inside ProxSpace with a green pm3 prompt;
This prompt provides a mix of Linux like functions and Windows together.
Getting the latest firmware
Now that we have our cozy comfy environment set up for doing Linux type stuff in Windows, we can grab the RRG/Iceman firmware from GitHub. To do this, simply enter this command at the pm3 prompt;
You will be left with a proxmark3 directory (folder). Notice the DOS style DIR command works as does the Linux style LS command… but the LS command is color coded. You should get comfortable with the Linux based command line.
The proxmark3 folder is where the source files live for the firmware and client, and it will be where the compiled versions live after we run the compile commands. Let’s hop in there now with a CD command;
Before we compile anything, we need to be sure the firmware is going to compile for the correct hardware. Remember before I said that there are now many versions of hardware and also many versions of firmware, and for the most part they are interchangeable… well the RRG firmware was made specifically for the Proxmark3 RDV4 hardware version, so before we compile it we need to tell it we are not using that hardware version. We do this by creating a Makefile.platform file and setting a value inside. Luckily there is a sample version of this file we will make a copy of, then edit. To do that, use the CP command… though I should say that in Linux everything is case sensitive so you must use the exact case letters;
cp Makefile.platform.sample Makefile.platform
Now you should have a Makefile.platform file we can edit with Windows notepad.
Notepad should open up and show something like this;
OR… depending on the version you are updating to… it might say this;
Notice the lines;
You will want to swap the # to the top line to comment it out and remove it from the bottom line to enable.
Save the file (CTRL-S) and close Notepad and go back to the pm3 prompt. The compile commands in Linux are bundled into a simple make command. Now we just tell ProxSpace to compile the firmware and client software.
make clean && make all
… get coffee …
After the make build process, you will have new files and folders… a collection of pm3-flash files and a client folder as well.
Flash your pm3
With your Proxmark3 connected and showing as a new virtual com port in the device manager, it’s time to flash the new firmware updates (bootloader and full image). Start with the bootloader by typing
… ok bloody hell… I just noticed this now… the bootloader firmware flash process file is called pm3-flash-bootrom when it’s clearly not a ROM because ROM means READ ONLY MEMORY and it can’t be READ ONLY if we are flashing an update to it… omfg… anyway… onward…
When you press enter you will see a series of things happen and the bootloader will be updated…
Now we need to flash the full image by typing…
Running the client
With the firmware updated to the current version, now it’s time to run the client. To do this change directory into the client folder with a CD command
Next type the proxmark client file and com port shown in device manager. For me that’s com6
The client should launch and you will be left at a proxmark3 command prompt;
Check your antennas
Now the first thing you want to do with any new proxmark3 hardware is check the tuning of your antennas. To do this make sure the pm3 is sitting on a wood table (not metal) with no RFID or NFC tags around it and type the command hw tune;
You will get some data back, a graph, and a slider window…
You can ignore the graph and slider windows for now… just close them. The important thing to look at right now is the text output. You’re looking for the lines
[+] LF antenna is OK [+] HF antenna is OK
At this point you are in the Proxmark3 client, inside the ProxSpace environment. To get back here in the future, you have to use the runme64.bat file to get into ProxSpace, then cd proxmark3/client, then ./proxmark3 com6 to launch the pm3 client software.
Updating firmware in the future
If you should ever want to update firmware in the future, the simplest way at this point is to launch ProxSpace with runme64.bat then rename the existing proxmark3 folder with the linux MV command;
mv proxmark3 proxmark3.old
Then use the github command git to pull down the current rrg/iceman repo and follow those steps again.
- navigate into the proxmark3 folder
- pull down the latest source code by issuing git pull
- set the Makefile.platform file
- change the lines to activate PM3OTHER
- run make clean && make all
- flash your pm3 bootloader and app image
- run the proxmark3.exe client in the proxmark3/client folder
A simple trick to speed things up
Since ProxSpace is really just about providing a useful Linux environment for doing one thing and one thing only - using your proxmark3, then there is no reason why it should not start the client immediately for you once you enter the ProxSpace environment. To get ProxSpace to do this, you have to edit the .bashrc file by issuing the command notepad .bashrc at the prompt as soon as you enter ProxSpace. Then notepad will open and you’ll see something like this;
Just scroll to the very end of the file and add the line;
Take note that “com6” is the com port my proxmark3 connects via, but yours may be different so change it accordingly. Then save the file, and the next time you enter ProxSpace the proxmark3 client will immediately launch! Of course if you ever want out of the client to issue commands in ProxSpace for things like updating the proxmark3 source code and re-compiling, then you can just use the quit command to get out of the proxmark3 client and go back to ProxSpace.