proxmark3/README.md

240 lines
12 KiB
Markdown
Raw Normal View History

2021-01-14 19:48:48 +08:00
# RRG / Iceman - Proxmark3
2020-05-20 16:24:20 +08:00
2021-10-13 02:34:19 +08:00
| Latest Release | Coverity | Contributors |
|:--------------:|:--------:|:------------:|
2021-01-14 19:08:44 +08:00
| [![Latest release](https://img.shields.io/github/v/release/rfidresearchgroup/proxmark3)](https://github.com/RfidResearchGroup/proxmark3/releases/latest) | [![Coverity Status](https://scan.coverity.com/projects/19334/badge.svg)](https://scan.coverity.com/projects/proxmark3-rrg-iceman-repo)| ![GitHub contributors](https://img.shields.io/github/contributors/rfidresearchgroup/proxmark3) |
2019-12-03 03:28:29 +08:00
2021-10-13 02:34:19 +08:00
| Actions OSX CI | Actions Ubuntu CI | Actions Windows CI |
|:--------------:|:------------------:|:------------------:|
| ![MacOS Build and Test](https://github.com/RfidResearchGroup/proxmark3/workflows/MacOS%20Build%20and%20Test/badge.svg?branch=master) | ![Ubuntu Build and Test](https://github.com/RfidResearchGroup/proxmark3/workflows/Ubuntu%20Build%20and%20Test/badge.svg?branch=master) | [![Windows Build and Test](https://github.com/RfidResearchGroup/proxmark3/actions/workflows/windows.yml/badge.svg?branch=master)](https://github.com/RfidResearchGroup/proxmark3/actions/workflows/windows.yml) |
2021-01-05 22:20:57 +08:00
2017-06-09 20:58:11 +08:00
2021-09-18 18:37:36 +08:00
# Table of Contents
1. [PROXMARK3 INSTALLATION AND OVERVIEW](#proxmark3-installation-and-overview)
2. [Notes / helpful documents](#notes--helpful-documents)
3. [How to build?](#how-to-build)
1. [Proxmark3 RDV4](#proxmark3-rdv4)
2. [Generic Proxmark3 platforms](#generic-proxmark3-platforms)
4. [What has changed?](#what-has-changed)
5. [Development](#development)
6. [Supported operative systems](#supported-operative-systems)
7. [Precompiled binaries](#precompiled-binaries)
8. [Proxmark3 GUI](#proxmark3-gui)
9. [Official channels](#official-channels)
10. [Maintainers](#maintainers)
11. [Citation](#citation)
2022-01-06 07:24:15 +08:00
12. [Copyright and licensing terms](#copyright-and-licensing-terms)
2021-01-14 19:48:48 +08:00
# PROXMARK3 INSTALLATION AND OVERVIEW
| Installation | Use of the Proxmark3 |
| :------------------: | :------------------: |
| [Linux - Setup and Build](/doc/md/Installation_Instructions/Linux-Installation-Instructions.md) | [Compilation Instructions](/doc/md/Use_of_Proxmark/0_Compilation-Instructions.md)|
| [Linux - Important notes on ModemManager](/doc/md/Installation_Instructions/ModemManager-Must-Be-Discarded.md) | [Validating Proxmark3 Client Functionality](/doc/md/Use_of_Proxmark/1_Validation.md)|
| [Mac OS X - Homebrew & Upgrading HomeBrew Tap Formula](/doc/md/Installation_Instructions/Mac-OS-X-Homebrew-Installation-Instructions.md) | [First Use and Verification](/doc/md/Use_of_Proxmark/2_Configuration-and-Verification.md)|
| [Mac OS X - MacPorts](/doc/md/Installation_Instructions/Mac-OS-X-MacPorts-Installation-Instructions.md) | [Commands & Features](/doc/md/Use_of_Proxmark/3_Commands-and-Features.md)|
| [Windows - Setup and Build](/doc/md/Installation_Instructions/Windows-Installation-Instructions.md) ||
| [Termux / Android - Setup and Build](/doc/termux_notes.md) ||
| [Blue Shark Manual](/doc/bt_manual_v10.md) | [Command Cheat Sheet](/doc/cheatsheet.md)|
| [Advanced Compilation Parameters](/doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md) | [More Cheat Sheets](https://github.com/RfidResearchGroup/proxmark3/wiki/More-cheat-sheets)|
| [Troubleshooting](/doc/md/Installation_Instructions/Troubleshooting.md) | [Complete Client Command Set](/doc/commands.md) |
| [JTAG](/doc/jtag_notes.md) | [T5577 Introduction Guide](/doc/T5577_Guide.md)|
2019-12-03 03:28:29 +08:00
2020-05-19 15:42:54 +08:00
## Notes / helpful documents
2020-05-20 16:24:20 +08:00
2020-05-19 15:42:54 +08:00
| Notes |||
2020-05-19 15:40:25 +08:00
| ------------------- |:-------------------:| -------------------:|
|[Notes on UART](/doc/uart_notes.md)|[Notes on Termux / Android](/doc/termux_notes.md)|[Notes on paths](/doc/path_notes.md)|
2020-05-19 16:14:39 +08:00
|[Notes on frame format](/doc/new_frame_format.md)|[Notes on tracelog / wireshark](/doc/trace_notes.md)|[Notes on EMV](/doc/emv_notes.md)|
2020-10-07 02:16:23 +08:00
|[Notes on external flash](/doc/ext_flash_notes.md)|[Notes on loclass](/doc/loclass_notes.md)|[Notes on Coverity Scan Config & Run](/doc/md/Development/Coverity-Scan-Config-and-Run.md)|
2020-06-03 00:51:57 +08:00
|[Notes on file formats used with Proxmark3](/doc/extensions_notes.md)|[Notes on MFU binary format](/doc/mfu_binary_format_notes.md)|[Notes on FPGA & ARM](/doc/fpga_arm_notes.md)|
2020-09-10 06:37:48 +08:00
|[Developing standalone mode](/armsrc/Standalone/readme.md)|[Wiki about standalone mode](https://github.com/RfidResearchGroup/proxmark3/wiki/Standalone-mode)|[Notes on Magic cards](/doc/magic_cards_notes.md)|
2020-09-15 10:30:30 +08:00
|[Notes on Color usage](/doc/colors_notes.md)|[Makefile vs CMake](/doc/md/Development/Makefile-vs-CMake.md)|[Notes on Cloner guns](/doc/cloner_notes.md)|
2021-12-31 18:27:03 +08:00
|[Notes on cliparser usage](/doc/cliparser.md)|[Notes on clocks](/doc/clocks.md)|[Notes on MIFARE DESFire](/doc/desfire.md)|
2020-05-20 16:24:20 +08:00
2021-04-08 15:02:37 +08:00
# How to build?
2021-09-18 18:37:36 +08:00
2021-04-08 15:02:37 +08:00
## Proxmark3 RDV4
2021-09-18 18:37:36 +08:00
2021-01-14 19:48:48 +08:00
See the instruction links in the tables above to build, flash and run for your Proxmark3 RDV4 device.
2019-09-03 19:11:49 +08:00
2021-04-08 15:02:37 +08:00
## Generic Proxmark3 platforms
2021-09-18 18:37:36 +08:00
2021-01-14 19:48:48 +08:00
In order to build this repo for generic Proxmark3 platforms we urge you to read [Advanced compilation parameters](/doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md)
2019-08-26 15:12:26 +08:00
2021-04-14 03:52:48 +08:00
We define generic Proxmark3 platforms as following devices.
**Supported**
2021-04-07 05:43:01 +08:00
- RDV1, RDV2, RDV3 easy
2021-04-14 03:52:48 +08:00
- Ryscorp green PCB version
2021-01-14 18:45:37 +08:00
- Radiowar black PCB version
- numerous Chinese adapted versions of the RDV3 easy (kkmoon, PiSwords etc)
2021-01-14 18:45:37 +08:00
2021-04-14 03:52:48 +08:00
**Not supported**
- ⚠ Proxmark Evolution (EVO)
- **Note**: unknown pin assignments.
- ⚠ Ryscorp Proxmark3 Pro
- **Note**: device has different fpga and unknown pin assignments.
2021-08-22 07:31:10 +08:00
- ⚠ iCopy-X
- **Note**: experimental support, currently incompatible with iCopy-X GUI as Proxmark client commands are now using cliparser.
- **Note**: see also [icopyx-community repos](https://github.com/iCopy-X-Community/) for upstream sources, reversed hw etc.
2021-04-14 03:52:48 +08:00
**Unknown support status**
- ⚠ VX
2021-04-24 21:35:32 +08:00
- **Note**: unknown device hw
2021-07-10 18:06:52 +08:00
2021-04-14 03:52:48 +08:00
**256kb flash memory size of generic Proxmark3 platforms**
> ⚠ **Note**:
> You need to keep a eye on how large your ARM chip built-in flash memory is.
> With 512kb you are fine but if its 256kb you need to compile this repo with even less functionality.
> When running the `./pm3-flash-all` you can see which size your device have if you have the bootloader from this repo installed.
> Otherwise you will find the size reported in the start message when running the Proxmark3 client `./pm3`.
>
> [OBS! Read the 256kb flash memory advisory](/doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md#256kb-versions)
2019-12-03 03:28:29 +08:00
2021-09-18 18:37:36 +08:00
# What has changed?
2019-05-05 06:18:18 +08:00
2021-04-08 14:55:26 +08:00
Proxmark3 RDV4 hardware modifications:
* added flash memory 256kb
2019-05-05 06:18:18 +08:00
* added smart card module
2021-04-14 03:22:33 +08:00
* added FPC connector for peripherals such as Bluetooth+battery addon
2021-04-08 15:02:37 +08:00
* improved antennas
* swappable
* LF Q factor switch
2021-04-14 03:22:33 +08:00
* LF 125/134 frequency switch
2021-04-08 14:55:26 +08:00
* tiny PCB form factor
* ABS case
This repo vs official Proxmark3 repo:
2021-04-14 03:22:33 +08:00
see the [Changelog file](CHANGELOG.md) which we try to keep updated. In short this repo gives you a completely different user experience when it comes to Proxmark3.
2021-04-08 14:55:26 +08:00
* richer CLI with use of colors / emojis
* help text system implemented everywhere
* hints system
* user preference settings
2021-04-14 03:22:33 +08:00
* extensive testing with continuous integration build systems on Linux, OSX and Windows, and regular usage of static analysis tools like
* [Coverity Scan](https://scan.coverity.com/projects/proxmark3-rrg-iceman-repo/)
* Cppcheck
* GCC and Clang aggressive enforcement of diagnostic flags
* auto detection of serial ports and seamless integration with Bluetooth addon
2021-04-14 15:08:00 +08:00
* reconnect to device from inside client
2021-04-14 15:08:57 +08:00
* Supports tearoff attacks
2021-09-18 18:37:36 +08:00
* Supports NFC NDEF type1, type2, type4a, type4b, mifare, barcode
* Supports pm3 client scripts, lua scripts, python scripts
* Most comprehensive collection of scripts available
* Wiegand encoding, decoding.
* Supports EMV
* Most standalone modes available with easy compilation
* extensive test script for client and external tools
* Most comprehensive compiled known keys dictionaries
2021-04-14 15:08:00 +08:00
* Slimed down usb communications with NG-frames
* the most compiled public known key recovery software
* the fastest implementations of said software
* support multiple fileformats for dump files (BIN/EML/JSON)
* interoperability of said fileformats with libnfc, MFC tool app etc
* Supports more RFID based protocols than ever
* Easy install for package maintainers, distro maintainers
2021-09-18 18:37:36 +08:00
* Supports cmake, make
* Builds without errors or warnings on more OS/platforms than ever.
2021-04-14 15:08:00 +08:00
* More documentation
2021-04-14 15:08:57 +08:00
2021-09-18 18:37:36 +08:00
# Development
2019-09-03 19:11:49 +08:00
2019-10-11 15:36:09 +08:00
> ⚠ **Note**: This is a bleeding edge repository. The maintainers actively is working out of this repository and will be periodically re-structuring the code to make it easier to comprehend, navigate, build, test, and contribute to, so **DO expect significant changes to code layout on a regular basis**.
2019-10-11 15:32:51 +08:00
2021-05-30 06:13:36 +08:00
> 👉 **Remember!** If you intend to contribute to the code, please read the [coding style notes](CONTRIBUTING.md) first.
2021-04-08 14:55:26 +08:00
We usually merge your contributions fast since we do like the idea of getting a functionality in the Proxmark3 and weed out the bugs afterwards.
The [public roadmap](https://github.com/RfidResearchGroup/proxmark3/wiki/Public-Roadmap) is an excellent start to read if you are interesting in contributing.
## Supported operative systems
2021-09-18 18:37:36 +08:00
2019-10-11 15:32:51 +08:00
This repo compiles nicely on
2021-04-08 14:55:26 +08:00
- WSL1 on Windows 10
2021-10-17 05:43:31 +08:00
- Proxspace environment [release v3.10](https://github.com/Gator96100/ProxSpace/releases)
2021-04-14 03:26:00 +08:00
- Windows/MinGW environment
- Ubuntu, ParrotOS, Gentoo, Pentoo, Kali, NetHunter, Arch Linux, Fedora, Debian, Raspbian
2020-05-19 15:49:53 +08:00
- Android / Termux
2021-07-04 02:41:43 +08:00
- Mac OS X / Homebrew (or MacPorts, experimental) / Apple Silicon M1
2017-03-07 21:39:30 +08:00
- Docker container
2020-05-20 16:24:20 +08:00
- [ RRG / Iceman repo based ubuntu 18.04 container ](https://hub.docker.com/r/secopsconsult/proxmark3)
- [ Iceman fork based container v1.7 ](https://hub.docker.com/r/iceman1001/proxmark3/)
2019-05-05 06:41:20 +08:00
2020-06-04 15:22:17 +08:00
## Precompiled binaries
2021-09-18 18:37:36 +08:00
2021-09-17 23:57:08 +08:00
See [Proxmark3 precompiled builds](https://www.proxmarkbuilds.org/)
2020-06-04 15:22:17 +08:00
2021-09-18 18:37:36 +08:00
## Proxmark3 GUI
The official PM3-GUI from Gaucho will not work. Not to mention is quite old and not maintained any longer.
- [Proxmark3 Universal GUI](https://github.com/burma69/PM3UniversalGUI) will work more or less.
- [Proxmark3 GUI cross-compiled](https://github.com/wh201906/Proxmark3GUI/) which is recently updated and claims to support latest source of this repo.
- [Proxmark3_GUI](https://github.com/Phreak87/Proxmark3_GUI) simple gui in vb.net
2021-04-14 03:26:00 +08:00
## Official channels
2021-04-08 14:55:26 +08:00
Where do you find the community?
2021-01-14 19:30:30 +08:00
- [RFID Hacking community discord server](https://discord.gg/QfPvGFRQxH)
2021-06-25 17:27:41 +08:00
- [Proxmark3 IRC channel](https://web.libera.chat/?channels=#proxmark3)
2020-05-20 16:24:20 +08:00
- [Proxmark3 sub reddit](https://www.reddit.com/r/proxmark3/)
2021-01-14 18:45:37 +08:00
- [Proxmark3 forum](http://www.proxmark.org/forum/index.php)
2020-05-20 16:24:20 +08:00
2021-01-14 19:30:30 +08:00
2021-09-18 18:37:36 +08:00
## Maintainers
2019-09-03 19:11:49 +08:00
2021-01-14 18:45:37 +08:00
To all distro, package maintainers, we tried to make your life easier.
`make install` is now available and if you want to know more.
2021-09-18 18:37:36 +08:00
This document will be helpful for you
- [Notes for maintainers](/doc/md/Development/Maintainers.md)
2021-03-29 04:34:03 +08:00
2021-04-21 14:46:12 +08:00
## Citation
2021-05-08 03:01:23 +08:00
Use this bibtex to cite this repository globally:
2021-04-21 14:46:12 +08:00
```
2021-05-08 03:01:23 +08:00
@misc{proxmark3rrg,
author = {C. {Herrmann} and P. {Teuwen} and O. {Moiseenko} and M. {Walker} and others},
title = {{Proxmark3 -- RRG / Iceman repo}},
howpublished = {\url{https://github.com/RfidResearchGroup/proxmark3}},
keywords = {rfid nfc iceman proxmark3 125khz 134khz 13.56mhz},
2021-04-21 14:46:12 +08:00
}
```
2021-05-08 03:01:23 +08:00
If you need to refer to a specific state of the repository, use a commit number or a date of access, e.g.:
```
note = {Accessed: commit 12327f71a27da23831901847886aaf20e8ad3ca0}
note = {Accessed: 2021-01-01}
```
Adding AUTHORS and changing licensing terms from 'GPLv2 or later' to 'GPLv3 or later' to comply with components available only under 'GPLv3 or later'. Details: Initial releases by Jonathan Westhues in 2005-2007 were made under GPL "either version 2 of the License, or (at your option) any later version" Since then, a number of dependencies and files were integrated to the project, but under a "GPLv3 or later" license. These components are reveng, desfire_crypto and lrpcrypto. Note that compnents cryptorf, hitag2crack and fpga-xc3s100e are also under GPLv3+ but not bound to the firmware or client source code. Therefore, we must mechanically upgrade the license of the whole project to GPLv3+, as made possible by the initial licensing terms and as mandated by the inclusion of GPLv3+ code. Still to do: update each source file header: Copyright (C) Proxmark3 contributors. See AUTHORS.md for details. 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 3 of the License, or (at your option) any later version. 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. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
2022-01-06 07:15:40 +08:00
## Copyright and licensing terms
Each contribution is under the copyright of its author. See [AUTHORS](AUTHORS.md).
The Proxmark3 source code is covered by the following licensing terms, usually referred as **GPLv3 or later**.
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 3 of the License, or
(at your option) any later version.
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.
2022-01-06 07:37:34 +08:00
A copy of the GPLv3 is available in [LICENSE](LICENSE.txt).
Adding AUTHORS and changing licensing terms from 'GPLv2 or later' to 'GPLv3 or later' to comply with components available only under 'GPLv3 or later'. Details: Initial releases by Jonathan Westhues in 2005-2007 were made under GPL "either version 2 of the License, or (at your option) any later version" Since then, a number of dependencies and files were integrated to the project, but under a "GPLv3 or later" license. These components are reveng, desfire_crypto and lrpcrypto. Note that compnents cryptorf, hitag2crack and fpga-xc3s100e are also under GPLv3+ but not bound to the firmware or client source code. Therefore, we must mechanically upgrade the license of the whole project to GPLv3+, as made possible by the initial licensing terms and as mandated by the inclusion of GPLv3+ code. Still to do: update each source file header: Copyright (C) Proxmark3 contributors. See AUTHORS.md for details. 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 3 of the License, or (at your option) any later version. 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. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
2022-01-06 07:15:40 +08:00
Some dependencies may be under other free licensing terms compatible with the Proxmark3 licensing terms, see their respective description.