pySim - Tools for reading, decoding, browsing SIM/USIM/ISIM/HPSIM/eUICC Cards

This repository contains a number of Python programs related to working withsubscriber identity modules of cellular networks, including but not limitedto SIM, UICC, USIM, ISIM, HPSIMs and eUICCs.

• pySim-shell.py can be used to interactively explore, read and decode contentsof any of the supported card models / card applications. Furthermore, ifyou have the credentials to your card (ADM PIN), you can also write to the card,i.e. edit its contents.
• pySim-read.py andpySim-prog.py arelegacy tools for batch programmingsome very common parameters to an entire batch of programmable cards
• pySim-trace.py is a tool to do an in-depth decode of SIM card protocol tracessuch as those obtained byOsmocom SIMtrace2orosmo-qcdiag.
• osmo-smdpp.py is a proof-of-concept GSMA SGP.22 Consumer eSIM SM-DP+ for lab/research
• there are more related tools, particularly in thecontrib directory.

Note that the access control configuration of normal production cardsissue by operators will restrict significantly which files a normaluser can read, and particularly write to.

The full functionality of pySim hence can only be used with on so-calledprogrammable SIM/USIM/ISIM/HPSIM cards, such as the varioussysmocom programmable card products.

Such SIM/USIM/ISIM/HPSIM cards are special cards, which - unlike thoseissued by regular commercial operators - come with the kind of keys thatallow you to write the files/fields that normally only an operator canprogram.

This is useful particularly if you are running your own cellularnetwork, and want to configure your own SIM/USIM/ISIM/HPSIM cards forthat network.

Homepage

Please visit theofficial homepagefor usage instructions, manual and examples.

Documentation

The pySim user manual can be built from this very source code by meansof sphinx (with sphinxcontrib-napoleon and sphinx-argparse). See theMakefile in the 'docs' directory.

A pre-rendered HTML user manual of the current pySim 'git master' isavailable fromhttps://downloads.osmocom.org/docs/latest/pysim/ anda downloadable PDF version is published athttps://downloads.osmocom.org/docs/latest/osmopysim-usermanual.pdf.

A slightly dated video presentation about pySim-shell can be found athttps://media.ccc.de/v/osmodevcall-20210409-laforge-pysim-shell.

pySim-shell vs. legacy tools

While you will find a lot of online resources still describing the use ofpySim-prog.py andpySim-read.py, those tools are considered legacy bynow and have by far been superseded by the much more capablepySim-shell.py. We strongly encourage users to adopt pySim-shell, unlessthey have very specific requirements like batch programming of largequantities of cards, which is about the only remaining use case for thelegacy tools.

Git Repository

You can clone from the official Osmocom git repository using

git clone https://gitea.osmocom.org/sim-card/pysim.git

There is a web interface athttps://gitea.osmocom.org/sim-card/pysim.

Installation

Please install the following dependencies:

• bidict
• cmd2 >= 1.5.0
• colorlog
• construct >= 2.9.51
• pyosmocom
• jsonpath-ng
• packaging
• pycryptodomex
• pyscard
• pyserial
• pytlv
• pyyaml >= 5.1
• smpp.pdu (fromgithub.com/hologram-io/smpp.pdu)
• termcolor

Example for Debian:

sudo apt-get install --no-install-recommends\pcscd libpcsclite-dev\python3\python3-setuptools\python3-pycryptodome\python3-pyscard\python3-pippip3 install --user -r requirements.txt

After installing all dependencies, the pySim applicationspySim-read.py,pySim-prog.py andpySim-shell.py may be started directly from the cloned repository.

In addition to the dependencies abovepySim-trace.py requirestshark and the python packagepyshark to be installed. It is known that thetshark packagein Debian versions before 11 may not work with pyshark.

Archlinux Package

Archlinux users may install the packagepython-pysim-gitfrom theArch User Repository (AUR).The most convenient way is the use of anAUR Helper,e.g.yay orpacaur.The following example shows the installation withyay.

# Installyay -Sy python-pysim-git# Uninstallsudo pacman -Rs python-pysim-git

Forum

We welcome any pySim related discussions in theSIM Card Technologysection of the osmocom discourse (web based Forum).

Mailing List

There is no separate mailing list for this project. However,discussions related to pySim are happening on the simtracesimtrace@lists.osmocom.org mailing list, please seehttps://lists.osmocom.org/mailman/listinfo/simtrace for subscriptionoptions and the list archive.

Please observe theOsmocom Mailing ListRuleswhen posting.

Issue Tracker

We use theissue tracker of the pysim project on osmocom.org fortracking the state of bug reports and feature requests. Feel free to submit any issues you may find, or helpus out by resolving existing issues.

Contributing

Our coding standards are described athttps://osmocom.org/projects/cellular-infrastructure/wiki/Coding_standards

We are using a gerrit-based patch review process explained athttps://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit