Doppelgänger is firmware that runs on ESP32 devices that can be embedded within commercially available RFID readers with the intent of capturing access control card data while performing physical security assessments. Doppelgänger keeps the operator's ease of access, maintenance, and operational communications in mind.
Doppelgänger Community Edition officially supports the processing of Wiegand data for the following card types:
- HID H10301 26-bit
- Indala 26-bit (requires Indala reader/module)
- Indala 27-bit (requires Indala reader/module)
- Indala 29-bit (requires Indala reader/module)
- HID D10202 33-bit
- HID H10306 34-bit
- HID Corporate 1000 35-bit
- HID H10304 37-bit
For expanded card support and keypad applications, consider purchasing Doppelgänger Pro, Stealth, or MFAS (Multi-Factor Stealth) from the Physical Exploitation Store. Below are the officially supported card types for premium devices:
| Card Types | Community Edition | Pro | Stealth | MFAS | Notes |
|---|---|---|---|---|---|
| Keypad PIN Codes | X | ||||
| HID H10301 26-bit | X | X | X | X | |
| Indala 26-bit | X | X | X | X | Requires Indala reader/module |
| Indala 27-bit | X | X | X | X | Requires Indala reader/module |
| 2804 WIEGAND 28-bit | X | X | X | ||
| Indala 29-bit | X | X | X | X | Requires Indala reader/module |
| ATS Wiegand 30-bit | X | X | X | ||
| HID ADT 31-Bit | X | X | X | ||
| EM4102 / Wiegand 32-bit | X | X | |||
| HID D10202 33-bit | X | X | X | X | |
| HID H10306 34-bit | X | X | X | X | |
| HID Corporate 1000 35-bit | X | X | X | X | |
| HID Simplex 36-bit (S12906) | X | X | X | ||
| HID H10304 37-bit | X | X | X | X | |
| HID Corporate 1000 48-bit | X | X | X | ||
| C910 PIVKey | X | X | |||
| MIFARE (Various Types) | X | X |
This project stemmed from the Raspberry Pi chip shortage, which drove up the cost of RPi Nano W boards making the cost to repair the team's long-range cloners not feasible. In addition, there were some limitations with existing tooling that I aimed to mitigate.
This project intended to accomplish the following:
- Use modern/actively supported CoTS equipment that can easily be replaced.
- The operator can't go into a comms blackhole while connected to the device.
- Egress for notifications, reducing the need to check for card reads while in the middle of an operation.
- Simplified WebGUI that only displays Bit Length, Facility Code, and Card Number. Option to download the complete data set(e.g., BL, FC, CC, HEX, BIN).
- Error handling, so the device doesn't display bad reads or EMI in the main card log.
- Easy configuration and reset functionality for team use.
The simpliest way to get going with Doppelgänger is to head over to the Practical Physical Exploitation Store and purchase a pre-built longrange reader, stealth, MFAS, or Breakout board. To view the support documents for premium hardware, you can reference the Practical Physical Exploitation Documentation.
- HID MaxiProx 5375 Longrange Wiegand Data Interpreter: Supports HID Prox card types. Inculdes Doppelgänger Pro Firmware.
- HID iCLASS R90SE Longrange Wiegand Data Interpreter: Supports iCLASS Legacy/SE/Seos card types. Inculdes Doppelgänger Pro Firmware.
-
Doppelgänger Breakout Board (Fully Assembled): Comes with Doppelgänger Community Edition firmware pre-installed.
-
Doppelgänger Breakout Board (DIY Kit): User will need to provide their own SparkFun Thing Plus C board.
-
Stealth Wiegand Data Interpreter: Supports Prox, EM, AWID, PIV, MIFARE, iCLASS Legacy/SE/Seos. Indala is supported on certain models but removes Prox, EM, and AWID. This is a hardware limitation by HID not a Doppelgänger limitation. Runs on Doppelgänger Stealth firmware.
-
COMING SOON Multi-Factor Stealth (MFAS) Wiegand Data Interpreter: Supports PIN Codes, Prox, EM, AWID, PIV, MIFARE, iCLASS Legacy/SE/Seos. Indala is supported on certain models but removes Prox, EM, and AWID. This is a hardware limitation by HID not a Doppelgänger limitation. Runs on Doppelgänger MFAS firmware.
- Doppelgänger Longrange Breakout Board: Supports HID MaxiProx 5375 and HID iCLASS R90SE
The Doppelgänger firmware is designed to work with the SparkFun Thing Plus - ESP32 WROOM (USB-C), which employs the Espressif ESP32-WROOM-32E chip. Note, other ESP32 boards may be used but modifications to the firmware will be required.
Only attempt to build this device if you know what you're doing. The developer is not responsible for damaged equipment/property. Doppelgänger has been tested on the following devices, but it should work on any reader that outputs a Weigand signal:
- HID MaxiProx 5375AGN00
- HID ICLASS SE R90 940NTNTEK00000 (this model has legacy support enabled)
- HID Indala ASR-620++ (No Longer Manufactured by HID)
To simplify the process, you can purchase a DIY Doppelgänger Breakout Board which will reduce wiring complexity and provides voltage regulation and logic conversion for you. If you want to go the true DIY route, we recommend purchasing the following items:
The following additional items are recommended to build a complete system:
| Item | Qty |
|---|---|
| SparkFun Thing Plus C | 1 |
| Powerbank (Omni Mobile 25600mah recommended) | 1 |
| Adhesive Standoffs 0.180" Height | 4 |
| 1.5' USB-C to USB-A Cable | 1 |
| 5.5x2.1mm Power Cable (Male) | 1 |
| SparkFun Logic Level Converter | 1 |
| 22 awg Solid Core Wire (Six Color Pack) | 1 |
| 1" Outdoor Zip Tie Mounts and Zip Ties | 2 |
| 2.54mm 0.1" Pitch PCB Mount Screw Terminal Block Connectors | 1 |
Below are the wiring diagrams for each reader. As the RFID readers below output a 5V signal, the use of a logic level converter is required to adapt the signal to 3.3V.
Note, you can use various ESP32's, the diagrams below are merely an example.
For setup purposes, I recommend using a computer to configure the device initially. Once the Doppelgänger has been configured to connect to a mobile device, there should be no need to use a computer again.
- Apply power to the reader and ESP-32.
- If the blue LED is illuminated, the device is in configuration mode. Connect to the doppelgänger_XXXX network using the default password UndertheRadar.
- The Captive Portal should automatically launch. If it does not, navigate to http://192.168.4.1/.
Captive Portal Menu Options:
- Configure WiFi - Performs a scan of wireless networks.
- Configure WiFi (No scan) - Same as above, but without scanning for wireless networks.
- Info - Provides general information about the device, including temp, memory usage, build date etc. Note that the "ERASE WiFi Button" only clears stored wireless network credentials. It does not clear email configuration data. The only way to clear e-mail configuration data is through the web application.
- Update - OTA firmware update. To choose this option, use your web browser and open the Captive Portal (http://192.168.4.1/).
- Restart - Self-explanatory
- Exit - Self-explanatory
Before selecting Configure WiFi in the captive portal, turn on your mobile device's Personal Hotspot.
iPhone:
- Ensure that you enable Maximize Compatibility in the Personal Hotspot menu.
- You must leave the Personal Hotspot menu open while scanning and connecting Doppelgänger to your device.
- If no wireless networks appear in the Configure WiFi menu, clicking Refresh at the bottom of the page will initiate a network scan. Doppelgänger is preconfigured to filter out weak wireless networks which should help reduce clutter in WiFi-dense areas.
- Connect to your Mobile Device's hotspot.
- Upon clicking the Save button, Doppelgänger will save the wireless configuration and reboot. Upon reboot, Doppelgänger will automatically attempt to connect to the assigned wireless network.
- Once connected: Open your web browser to http://rfid.local/ to access the Doppelgänger web application.
Android:
- Not tested: The process will be similar to the iPhone instructions.
If you want to enable e-mail notifications, navigate to the Notifications page on the Doppelgänger web application. Enter your SMTP credentials and recipient information. This data is stored on the internal flash storage and is not accessible from the SD Card/web application. The notification configuration can be wiped by using Doppelgänger's reset functionality from within the web application.
To send a text notification follow this schema:
Verizon: [email protected]
AT&T: [email protected]
Rogers: [email protected]
T-Mobile: [email protected]
Google-Fi: [email protected]
Sprint: [email protected]
Virgin Mobile: [email protected]
Ensure that you have the Personal Hotspot menu opened on your iPhone before powering Doppelgänger back up (I am uncertain if Andriod devices operate in the same manner). Otherwise, Doppelgänger may not see your hotspot and will enter configuration mode. If this happens, you can either wait out the 120-second reset timer, in which Doppelgänger will reboot and look for the stored wireless network again or enter into the Captive Portal and make changes/restart the device manually.
Here's a quick look at the web application for reference:
Should you want to dive deeper into what Doppelgänger is doing under the hood, You can connect to the device using the terminal or PlatformIO/vscode.
To connect to the device from the terminal:
ls /dev/tty.usb*
screen /dev/tty.usbserial-13440 115200To connect to the device from PlatformIO/vscode: Open a PlatformIO project (this repository) and click the monitor button.
Doppelgänger can be flashed using PlatformIO plugin in VSCode
Attach the SparkFun board to your computer and click on the alien (PlatformIO) icon inside of VSCode. If you're using the IoT Redboard, you will not need to change the boot mode. If you're using the Thing Plus C, you may need to press the BOOT button before writing firmware / performing filesystem operations.
- Under PROJECT TASKS -> Platform, click Build Filesystem Image. This will create the LittleFS filesystem.
- Under PROJECT TASKS -> Platform, click Upload Filesystem Image. This will upload the filesystem to the IoT RedBoard. Note, if you receive an error, it's likely that you have the serial monitor running. Close the serial monitor and try again.
- Click the Trashcan on the lower ribbon of VSCode. This will clean the project.
- Click the Checkmark on the lower ribbon of VSCode. This will build the firmware.
- Click the RightArrow on the lower ribbon of VSCode. This will upload the firmware to the device. You may need to press the boot button on the device.
As part of the Doppelgänger eco-system, I have created Doppelgänger Assistant. This tool is designed to make it easy to write captured card data with a Proxmark3. Below is a quick video demo of the usage:
Special thanks to the following folks:
Francis Brown - To this day, "RFID Hacking Live Free or RFID Hard" remains my favorite conference talk. Watching that talk blew my mind as I left the military many years ago and started penetration testing. Truly inspirational! Daniel Smith - For laying so much of the groundwork that has made all of these awesome tools possible.