MFC Workbench

A guided Flipper workflow for authorized recovery and duplication of mifare classic credentials.

MFC Workbench keeps the process in one place:

1. Read and save the source fob.
2. Capture authentication nonce pairs from an authorized reader.
3. Recover sector keys inside MFC Workbench or optionally hand the job to a desktop computer.
4. Re-read the fob with the recovered dictionary and verify sector/key coverage.
5. Write the complete image to a compatible Gen1A or Gen2 magic mifare classic card inside MFC Workbench.

Important compatibility note

This project targets credentials that identify as mifare classic 1K/4K. It does not claim support for DESFire, Seos, 125 kHz proximity credentials, mobile credentials, or every mifare classic product.

Current state

The current development build includes:

• A buildable Flipper FAP with an authorization gate and a linear, lockable five-step checklist that marks completed stages with [x].
• Direct on-device NFC protocol scanning rejects non-mifare-classic credentials before recovery.
• Direct in-app source-card polling uses both the user and system key dictionaries, reports sector/key coverage, and saves /ext/nfc/MFC_<UID>.nfc without launching the stock NFC app.
• Direct in-app reader nonce capture collects the reader's complete authentication burst, stops after two seconds of reader inactivity, and writes MFKey32-compatible pairs without launching the stock NFC app.
• Embedded on-device Crypto-1/MFKey recovery runs on a cancellable worker and updates the user dictionary without launching another FAP.
• Direct in-app Gen1A and Gen2 magic-card writing copies the UID, keys, access bits, and readable blocks without launching NFC Magic. Gen2 targets are read and checked for type, keys, and writable access conditions before overwrite.
• Recovery reports distinguish newly added keys, nonce pairs that match keys already present in a dictionary, and pairs for which no valid key was recovered. 0 new keys can be a successful result when every captured pair matched an existing key.
• Artifact detection for saved NFC files, .mfkey32.log/.nested.log, and the user key dictionary.
• Semantic verification requires an explicit re-read of the source fob and marks the workflow complete only when that re-read yields every sector and both A/B key slots.
• An optional tested desktop handoff wrapper for mfkey_desktop_cli --auto.
• Host tests for workflow ordering, capture completion, filenames, recovery status, and desktop command construction.

All required workflow stages now execute inside MFC Workbench. The desktop solver remains an optional accelerator/interoperability path, not a required application dependency.

On-device workflow

1. Open MFC Workbench and accept the authorized-use gate.
2. Select 1. Scan/read source fob, then hold the fob against the Flipper until the read result appears. The app saves a standard .nfc file and reports Sectors: X/Y and Keys: A/B.
3. If coverage is incomplete, select 2. Capture reader and present the Flipper to the authorized reader. Keep it in place through the complete reader transaction; capture ends two seconds after the last authentication exchange.
4. Choose either recovery route directly from the checklist:
   • 3A. Recover on device runs the embedded MFKey/Crypto-1 engine. The progress screen shows the recovery phase, elapsed time, ETA, matched work, and newly recovered keys. Back cancels the worker.
   • 3B. Offload to PC keeps the optional USB offload path. Run python3 desktop/mfcw.py auto; after the solver reports dictionary upload success, confirm completion on the Flipper.
5. Interpret the result:
   • Added N new keys: new keys were appended to the user dictionary.
   • All nonce pairs matched keys already in dictionaries: recovery succeeded, but no dictionary update was needed.
   • No valid key recovered: capture the reader again, allowing its full transaction to finish.
6. Select 4. Re-read and verify. A complete result has all sectors and both A/B key slots covered. Partial coverage means additional reader authentication data or a known key source is still required.
7. Select 5. Write magic card, then choose Gen1A, Gen2, or Auto to detect an unknown target generation:
   • Gen1A supports complete mifare classic 1K images with a 4-byte UID and writes through the card's backdoor protocol.
   • Gen2 supports complete Classic 1K/4K images with a 4-byte UID. Workbench first reads the target's current keys/access conditions and refuses unsafe or incomplete writes.
8. Confirm the destructive operation and keep the target card still until Workbench reports success. Existing target contents are overwritten.

Nonce logs, recovered dictionaries, and NFC captures are sensitive local artifacts. They are ignored by Git and should not be attached to issues or committed to the repository.

Build

The physically tested target is Flipper running Unleashed unlshd-081 (FAP API 86). Configure uFBT with the matching SDK before building:

uvx --python 3.12 ufbt update --hw-target 7 --url https://github.com/DarkFlippers/unleashed-firmware/releases/download/unlshd-081/flipper-z-f7-sdk-unlshd-081.zip

uvx --python 3.12 ufbt

The FAP is written to:

dist/mfc_workbench.fap

Install it under apps/NFC/ on the device SD card. No separate NFC, MFKey, or NFC Magic application is required for reading, reader capture, recovery, saving, verification, or compatible magic-card writing.

To build, upload, and launch over USB:

uvx --python 3.12 ufbt launch FLIP_PORT=/dev/ttyACM0

Test

make test
uvx --python 3.12 ufbt lint
uvx --python 3.12 ufbt

Desktop handoff

Install a verified release of mfkey_desktop_cli, connect the Flipper over USB, close the companion app, and run:

python3 desktop/mfcw.py auto

If the solver is not on PATH:

python3 desktop/mfcw.py auto --solver /path/to/mfkey_desktop_cli

Optional flags:

--port /dev/ttyACM0
--out captures
--accept-disclaimer

The wrapper executes the solver directly without a shell. The upstream solver pulls nonce logs, performs recovery, and uploads merged dictionaries back to /ext/nfc/assets/.

Design

See docs/architecture.md for the state machine, in-process integrations, and file contracts.

Responsible use

Use this software only with credentials and readers you own or are explicitly authorized to test. It is intended for interoperability, migration, backup, education, and authorized security research. Access-control policy and local law still apply.

Credits

• Flipper Devices for the firmware, NFC stack, uFBT, and MFKey documentation.
• noproto and contributors for the MFKey app.
• RogueMaster/flipperzero-good-faps contributors for the GPLv3 Gen1A and Gen2 NFC Magic pollers adapted into the Workbench process.
• phntm-lab and contributors for mfkey_desktop_cli.
• RfidResearchGroup/Proxmark contributors for the underlying public Crypto-1 research.

License

GPL-3.0-or-later.