The 'usim midifier v3.0' is for modify your 'TEST USIM' card, you can modify the content of USIM card with PC/SC card reader on multi-platform (Windows/MAC/Linux).
You can use this tool to do:
- Modify iccid/imsi/mccmnc/gid/spn for specific test
- Update msisdn to easy identify the USIM (Ex: Chunwau Telecom, FET NET, etc)
- Enable/disable the PIN1, and query the PIN1/ADM retry count
PS. If you have any suggestion, please raise the 'issues' or send mail to me directly.
- Add
Troubleshooting / Known Issueschapter
I’m currently refactoring this project and found an issue with the EZ100PU smart card reader on my M3 MacBook Air. I’ve ordered an ACR39U-UF reader for additional testing. Once the tests are complete, I’ll create a new project: usim_modifier_v3.1.
- Update: modify the AID read mechanism, will select the PIX numbers startwith "A0000000871002" (means this project only support USIM APP)
- Todo: Update the task to fetch the AID value from the USIM application
- Fixed: Handle MSISDN numbers with an odd number of digits correctly (Thanks for Simon Arlott)
- New: Add 'config' plugin to update 'usim_modifier.xml'
- Fixed bug#3: Add 'admhex' option, value '1' is for hex, else are digits.
- Only accept 8(digits) or 16(hex) key length of adm.
- Enhance 'pin' plugin, will update the correct 'pin' code if auto save pin option enabled.
- Fixed bug#4: Auto adm_verify did not stop when verify fail
- New 'ust' plugin to display the 'USIM Service Table'.
- Modified the input condition of ADM key, it can accept 8 ~ 16 digits hexadecimal and auto fill 'FF' to 16-digit.
- Update the task to fetch the AID value from the USIM applicationn (currently is query the 1st record from EF-DIR)
linux@ubuntu:/$ sudo apt install python3-colorama (PS. should be installed by default)
linux@ubuntu:/$ sudo apt install python3-lxml
linux@ubuntu:/$ sudo apt install python3-pyscard
linux@ubuntu:/$ pip3 install colorama
linux@ubuntu:/$ pip3 install lxml
linux@ubuntu:/$ sudo apt-get install swig pcscd ibpcsclite-dev
linux@ubuntu:/$ sudo pip3 install pyscard
Pre-condition: “HomeBrew” must be installed.
mac@osx:/$ pip3 install colorama
mac@osx:/$ pip3 install lxml
mac@osx:/$ brew install swig (PS. install “swig” by homebrew)
mac@osx:/$ pip3 install pyscard
When I installed python 3.10 from Microsoft Store directly (PIP included) on Windows 11 22H2 (build: 22621.1105), and install colorama, lxml & pyscard packages directly, then 'usim_modifier_v3' can works fine.
PS. As my previous experience, we need to install some packages first for "pip install pyscard", if you encounter install fail at 'pyscard' package, please check the error message to install dependency package, then try again.
git clone https://github.com/minghsu/usim_modifier_v3.git
- Multiple platform supported (Windows/MAC/Linux)
- Multi-language with extendable architecture
- Flexible plugin mechanism
- Dedicated language resource for 'plugin'
- Auto verify 'pin' & 'adm' code (from usim_modifier.xml file)
- Auto store 'pin' & 'adm' code by ICCID (configurable)
- Logging support (configurable)
- gid: Query or modify the value of GID1/GID2.
- mccmnc: Query or modify the value of MCC/MNC
- imsi: Query or modify the value of IMSI
- spn: Query or modify the value of SPN
- atr: Get and show the ATR value
- iccid: Query or modify the value of IMSI
- msisdn: Query or modify the value of MSISDN
- send: Send the 'APDU' to USIM directly
- pin: Enable/disable PIN1 and query the retry count of PIN1/ADM
- ust: Display the 'USIM Service Table' features
- cardinfo: Show the 'iccid', 'imsi', 'mccmnc', 'spn' & 'gid' info
- dir: list all records of EF_DIR (2F00)
- arr: List all records of EF_ARR(2F06 and 7FFF6F06)
- config: To configure the "usim_modifier.xml" file
You can type 'plugin' command to get all plugin info, the 'Updatable' column mean is able to modify in current session or not, and the 'AutoExec' mean the plugin will auto execute during startup stage or not.
On 'Linux/Mac' OS, just type './usim_modifier.py' command.
For 'Windows' OS, please type 'python3 usim_modifer.py' command.
The 1st step, if the USIM enabled the PIN code, you must input correct 'pin code' to verify for future operation.
For next step, you can type 'adm code' to verification 'adm', and we can press 'ENTER' key to skip if you didn't have the 'adm code', but some 'plugin' may not updatable.
All example are very simple, you can type 'help' argument to get more detail.
Please refer USIM Modifier V3 Tech Note
- ETSI TS 102 221 - Smart Cards; UICC-Terminal interface; Physical and logical characteristics
- ETSI TS 131 102 - UMTS; LTE;Characteristics of the Universal Subscriber Identity Module (USIM) application
- ETSI TS 101 220 - Smart Cards; ETSI numbering system for telecommunication application providers
- Unexpected keyword argument in toHexString()
- Error: TypeError: toHexString() got an unexpected keyword argument 'format'
- Root Cause: API changes in recent package versions no longer accept format as a keyword argument.
- Fix Applied: Updated the function call to use a positional argument. (Changed toHexString(aid_content[2:], format=PACK) to toHexString(aid_content[2:], PACK))
- pyscard Import Error on macOS (Apple Silicon / M-series chips)
- Error: ImportError: dynamic module does not define module export function (PyInit__scard)
- OS Platform: macOS with Apple Silicon (e.g., MacBook Air M3).
- Root Cause: pip might incorrectly install the pre-compiled x86_64 binary of pyscard, which is incompatible with the arm64 architecture.
- Solution: You need to install swig and force pip to compile pyscard from the source:
- brew install swig
- python3 -m pip install --no-cache-dir --no-binary :all: pyscard