Repository files navigation

Project that provides a simple way to inspect and modify memory of NFC/RFID cards.

Through an in-browser web application, you can unlock and modify the card's memory blocks.

While developing alibrary for interacting with NFC cards using theMFRC522 reader, I gained significant knowledge about card memory structure and interaction. This knowledge came from reading datasheets and through trial and error. These resources are often technical and difficult for beginners, but they contain valuable information on how NFC cards work.

Although libraries for NFC card interaction are helpful, they usually hide the card's complexity, offering only a high-level API for reading and writing data. This project aims to provide a simple way to directly interact with NFC card memory, offering a detailed view of how the memory is structured, how to write data, and how to configure access conditions and sector keys.

The project consists of three main components:

• Device (ESP32 with an attached RC522 reader)
• Web Application (Single Page Application)
• Messaging Bus (MQTT)

Communication between the device and the web application is handled asynchronously via the MQTT bus. The device publishes messages to the bus, while the web application subscribes to these messages. To read or write data, the web application sends a request to the device, which processes the request and responds.

sequenceDiagram    participant D as Device    participant M as MQTT Broker    participant W as Web Application    D->>M: Hello, Im booted!    D->>M: New NFC card detected    M->>W: NFC card info (UID, SAQ, ...)    W->>M: Unlock and read sector 15    M->>D: App wants to read sector 15    D->>M: Blocks from sector 15    M->>W: Here is the content of sector 15    W->>M: Write data to block 0x3F    M->>D: App wants to write to block 0x3F    D->>M: Block 0x3F has been updated    M->>W: Updated content of block 0x3F

The diagram above shows a typical workflow for message exchange between the web application and the device.

The web application is a Single Page Application (SPA) built with Vue. It communicates with the device solely through the MQTT bus using WebSockets. The goal is to provide an easy-to-use interface for inspecting and modifying NFC cards.

If you've manually modified Mifare blocks before, you're aware of the complexity in properly building the data for the Sector Trailer block to avoid corrupting the card. This application simplifies that process by offering a user-friendly interface for modifying access bits, keys, and data blocks.

The application has a retro-hacker look and feel, with a synthwave color palette and a monospace font. Currently, it’s not fully responsive and is best viewed on desktop.

The device is an ESP32 microcontroller with an attachedMFRC522 reader. Once powered on, it connects to the local network and the MQTT bus, waiting for incoming messages from the web application. Upon receiving a message, the device processes it and sends a response back. Most messages from the web app involve operations on the NFC card, such as reading or writing data to memory sectors.

The firmware is written in C using theESP-IDF framework. It leverages ESP-IDF's MQTT library for broker communication and the MFRC522library for NFC card interaction.

The web application is located in theweb directory. To build it, you'll need Node.js and npm installed. To run the application in development mode with hot-reloading, use the following commands:

cd webnpm installnpm run dev

Once the commands run successfully, the terminal will display the local address where the application is hosted. Open that address in your browser.

The device consists of an ESP32 microcontroller and an MFRC522 reader. The wiring is as follows:

The device firmware is in thefirmware directory. To build and flash the firmware to the ESP32, you must have ESP-IDF installed. Follow the instructions in theofficial documentation.

Once ESP-IDF is installed, navigate to thefirmware directory. Execute next command to configure the project:

idf.py menuconfig

In the configuration menu, set the next options:

Save and exit the configuration menu. Then, build and flash the firmware:

idf.py build flash monitor

If the correct WiFi credentials are set, the terminal should show that the device has connected to the network and MQTT broker.

When you open the web application, the first step is to copy the root topic from the Device's terminal and paste it into the client configuration form.

Save configuration and click the connect button to connect to the MQTT broker. The configuration is saved in the browser's local storage, so you don’t need to re-enter it every time.

After connecting to the broker, place an NFC card on the reader. Once detected, the card info will appear in the app, and you can start reading and writing data to the card.

The project currently supports cards that are compatible with the underlying firmwarelibrary used for communication with the MFRC522 reader. This includes cards from the Mifare Classic family, such as Mifare 1k, 4k, and Mini.

This project is licensed under Apache License 2.0. See theLICENSE file for more details.

There are many features that can be added. If you have suggestions or want to contribute, feel free to open an issue or a pull request. All feedback and improvements are welcome.