This project implements tools for performing deep analysis of FeliCa card capabilities and the extraction of available data.
This application enables users to:
- Extract information about FeliCa cards, including:
- Card identification (IDM, PMM);
- System codes and services;
- Block information and data;
- Card capabilities.
- View detailed scan progress with step-by-step execution timings;
- View scan results, with information assembled from performed commands:
- General information;
- Command support report;
- Per-system hierarchy overview:
- Count of child nodes;
- Key versions and types;
- Auxiliary node properties;
- Other node attributes;
- Block data;
- Related node annotation (names, etc).
- Android Studio;
- An Android device with NFC hardware and Android API level 31 or higher (Android 12);
- FeliCa targets to scan (transportation cards, mobile wallet passes, etc.).
- Build and install the application to your device using Android Studio;
- Enable NFC on your Android device if not already enabled;
- Open the FeliCa Tool application;
- Place a FeliCa card near the device's NFC antenna;
- The application will automatically detect the card and begin the scanning process;
- Monitor the scan progress through the step-by-step interface;
- View detailed results by expanding individual steps or accessing the scan overview;
- Remove the card when scanning is complete.
felica- Core FeliCa protocol implementation containing:- Protocol models and entities;
- Command classes validators & parsers;
- Response classes validators & parsers;
- Protocol constants and enumerations.
service- Application business logic (scanning, analysis);ui- User interface components;util- Helper functions and extensions for data processing.
At the current moment, "analysis" mode of the application attempts to detect support for the following commands:
| Command Name | Command Code (Hex) | IDM on Command | FeliCa Lite (0xF1) | Apple Wallet (0x16) | Osaifu-Keitai V4.1 (0x18) | Notes |
|---|---|---|---|---|---|---|
| Polling | 00 | ✗ | ✓ | ✓ | ✓ | Reading card IDM and PMM data |
| Polling (System Code) | 00 | ✗ | ✓ | ✓ | ✓ | Request primary system code of the card using polling command |
| Polling (Communication Performance) | 00 | ✗ | ✓ | ✓ | ✓ | Request information about supported communication speeds using polling command |
| Request Service | 02 | ✓ | ✗ | ✓ | ✓ | Request key versions for discovered nodes |
| Request Response | 04 | ✓ | ✗ | ✓ | ✓ | Request response from the card |
| Read Without Encryption | 06 | ✓ | ✓ | ✓ | ✓ | Read block data from services that don't require authentication |
| Search Service Code | 0A | ✓ | ✗ | ✓ | ✓ | Search all available nodes on the card iteratively |
| Request System Code | 0C | ✓ | ✗ | ✓ | ✓ | Request all system codes registered to the card |
| Request Block Information | 0E | ✓ | ✗ | ✗ | ✓ | Request the amount of blocks for nodes |
| Request Block Information Ex | 1E | ✓ | ✗ | ✗ | ✓ | Request the amount of allocated and free blocks for nodes |
| Request Code List | 1A | ✓ | ✗ | ✗ | ✓ | Request a list of nodes for a given root node iteratively |
| Set Parameter | 20 | ✓ | ✗ | ✗ | ✓ | Set card communication parameters (encryption type and node code size) |
| Get Container Issue Information | 22 | ✓ | ✗ | ✓ | ✓ | Get container-specific information including format version and mobile phone model |
| Get Area Information | 24 | ✓ | ✗ | ✗ | ✓ | Get information about a specific area (Official name and exact purpose are not known) |
| Get Container Property | 2E | ✗ | ✗ | ✗ | ✓ | Get container property data by index (Official name and exact purpose are not known) |
| Get Node Property (Value Limited Service) | 28 | ✓ | ✗ | ✗ | ✗ | Get value-limited purse service properties for discovered nodes |
| Get Node Property (MAC Communication) | 28 | ✓ | ✗ | ✗ | ✗ | Get MAC communication properties for discovered nodes |
| Request Service V2 | 32 | ✓ | ✗ | ✓ | ✓ | Request AES and DES key versions for nodes alongside the key type identifier |
| Get System Status | 38 | ✓ | ✗ | ✓ | ✓ | Get current system status information from the card |
| Get Platform Information | 3A | ✓ | ✗ | ✓ | ✓ | Get platform information from the card. (Official name is not known) |
| Request Specification Version | 3C | ✓ | ✗ | ✓ | ✓ | Get card feature version and supported option versions |
| Reset Mode | 3E | ✓ | ✗ | ✓ | ✓ | Reset card mode to Mode0 |
| Get Container ID | 70 | ✗ | ✗ | ✗ | ✓ | Get container IDM from mobile FeliCa targets |
| Echo | F000 | ✗ | ✓ (72 bytes) | ✓ (252 bytes) | ✓ (252 bytes) | Testing communication with the card |
Note: If you have tested this application with other FeliCa card types or targets and would like to contribute your results, we would gladly add them to this compatibility table. Please share your findings by opening an issue or submitting a pull request with the command support details for your specific card type.
Most models used in the project have comprehensive data parsing tests.
Run tests using:
./gradlew :app:testDebugUnitTest --infoBuild and install the debug version:
./gradlew :app:installDebug- Improve annotation of known system, area codes, and IC types;
- Improve/refactor the UI part of the project.
- Add testing for some more commands with unknown meaning;
- Add support for FALP commands (need hardware to test on);
- Implement support for DES authentication commands (WIP, waiting for an ability to properly test Authentication2);
- Support external readers (PN532, PCSC);
- Add desktop (macOS, Linux, Windows) support by moving over to Compose Multiplatform;
- Add root-related functionality:
- An ability to emulate a FeliCa standard card;
- Support for commands with two-byte codes, some of which may only be available on wired interface, while talking to the embedded Osaifu-Keitai applet or chip.
- Some tags may have partial block reading results due to an undiagnosed issue - waiting for test samples or user logs to help resolve this.
In case you've encountered an issue, or would like to help improving this project, please feel free to open an issue or submit a pull request.
For command compatibility results, include details about your specific card type and which commands work or don't work. Feel free to comment out the unique part of the IDM (bytes 3-6, zero-indexed), or the block data, if that makes you more comfortable to do so.
- This application is intended for educational and analysis purposes;
- FeliCa is a registered trademark of Sony Corporation.
-
Documentation:
- FeliCa card user's manual (Excerpted edition) - basic command reference, IDM, PMM, timeout meaning;
- FeliCa lite s user's manual - specifics of FeliCa lite tags (systems, services).
-
Online Resources:
- Android NFC Documentation - information on implementing NfcF tag reading in android;
- NUllableVoidPtr - NFCFInfo - list of command codes, system codes, and references to other resources;
- Metrodroid FeliCa Wiki - system codes;
- OnakaSuita Wiki - FeliCa Commands - command codes;
- Oliet - oliet.hatenablog.jp, blog.oliet.tech (removed) - insights into the operation of FeliCa protocol.
-
Existing Projects:
- nfcpy - Sony FeliCa implementation - timeout calculation, service codes;
- TRETJapanNFCReader - system codes and commands;
- felica-dumper - upcoming implementation of Authentication commands;
- HCE-F-Unlocker (removed) - example of an Xposed module to remove HCE-F system code limitation;
-
Analyzed applications:
- Osaifu-Keitai stack version 2.2 - source of some of the discovered commands.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.