2021-05-17 16:08:45 +00:00
pySim - Read, Write and Browse Programmable SIM/USIM Cards
2017-03-17 17:08:09 +00:00
====================================================
2021-05-17 16:08:45 +00:00
This repository contains Python programs that can be used
to read, program (write) and browse certain fields/parameters on so-called programmable
2017-03-17 17:08:09 +00:00
SIM/USIM cards.
Such SIM/USIM cards are special cards, which - unlike those issued by
regular commercial operators - come with the kind of keys that allow you
to write the files/fields that normally only an operator can program.
This is useful particularly if you are running your own cellular
network, and want to issue your own SIM/USIM cards for that network.
2021-05-17 16:08:45 +00:00
Homepage and Manual
-------------------
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
Please visit the [official homepage ](https://osmocom.org/projects/pysim/wiki ) for usage instructions, manual and examples.
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
Git Repository
2017-03-17 17:08:09 +00:00
--------------
2021-05-17 16:08:45 +00:00
You can clone from the official Osmocom git repository using
```
git clone git://git.osmocom.org/pysim.git
```
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
There is a cgit interface at < https: / / git . osmocom . org / pysim >
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
Installation
2018-07-19 09:37:39 +00:00
------------
2021-05-17 16:08:45 +00:00
Please install the following dependencies:
2018-07-19 12:48:55 +00:00
2021-05-17 16:08:45 +00:00
- pyscard
- serial
- pytlv
2021-06-11 21:45:26 +00:00
- cmd2 >= 1.3.0 but < 2.0.0
2021-05-17 16:08:45 +00:00
- jsonpath-ng
- construct
- bidict
- gsm0338
2018-07-19 12:48:55 +00:00
Example for Debian:
2021-05-17 16:08:45 +00:00
```
2021-08-27 15:14:52 +00:00
apt-get install python3-pyscard python3-serial python3-pip python3-yaml
2021-05-17 16:08:45 +00:00
pip3 install -r requirements.txt
```
After installing all dependencies, the pySim applications ``pySim-read.py``, ``pySim-prog.py`` and ``pySim-shell.py`` may be started directly from the cloned repository.
### Archlinux Package
2021-03-12 14:45:17 +00:00
2021-05-17 16:08:45 +00:00
Archlinux users may install the package ``python-pysim-git``
[](https://aur.archlinux.org/packages/python-pysim-git)
from the [Arch User Repository (AUR) ](https://aur.archlinux.org ).
The most convenient way is the use of an [AUR Helper ](https://wiki.archlinux.org/index.php/AUR_helpers ),
e.g. [yay ](https://aur.archlinux.org/packages/yay ) or [pacaur ](https://aur.archlinux.org/packages/pacaur ).
The following example shows the installation with ``yay``.
```sh
# Install
yay -Sy python-pysim-git
# Uninstall
sudo pacman -Rs python-pysim-git
```
2021-03-12 14:45:17 +00:00
2018-07-19 09:37:39 +00:00
2017-03-17 17:08:09 +00:00
Mailing List
------------
2021-05-17 16:08:45 +00:00
There is no separate mailing list for this project. However,
2017-03-17 17:08:09 +00:00
discussions related to pysim-prog are happening on the
2021-05-17 16:08:45 +00:00
< openbsc @ lists . osmocom . org > mailing list, please see
2017-03-17 21:34:08 +00:00
< https: / / lists . osmocom . org / mailman / listinfo / openbsc > for subscription
2017-03-17 17:08:09 +00:00
options and the list archive.
Please observe the [Osmocom Mailing List
Rules](https://osmocom.org/projects/cellular-infrastructure/wiki/Mailing_List_Rules)
when posting.
2021-05-17 16:08:45 +00:00
2017-03-17 17:08:09 +00:00
Contributing
------------
Our coding standards are described at
2017-03-17 21:34:08 +00:00
< https: / / osmocom . org / projects / cellular-infrastructure / wiki / Coding_standards >
2017-03-17 17:08:09 +00:00
2021-04-11 09:19:44 +00:00
We are using a gerrit-based patch review process explained at
< https: / / osmocom . org / projects / cellular-infrastructure / wiki / Gerrit >
2017-03-17 17:08:09 +00:00
2021-04-11 09:21:00 +00:00
2021-05-17 16:08:45 +00:00
Usage Examples
--------------
2017-03-17 17:08:09 +00:00
* Program customizable SIMs. Two modes are possible:
2021-05-17 16:08:45 +00:00
- one where you specify every parameter manually:
```
2017-03-17 17:08:09 +00:00
./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -i < IMSI > -s < ICCID >
2021-05-17 16:08:45 +00:00
```
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
- one where they are generated from some minimal set:
```
2017-03-17 17:08:09 +00:00
./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -z < random_string_of_choice > -j < card_num >
2021-05-17 16:08:45 +00:00
```
With ``< random_string_of_choice > `` and ``< card_num > ``, the soft will generate
'predictable' IMSI and ICCID, so make sure you choose them so as not to
conflict with anyone. (for e.g. your name as ``< random_string_of_choice > `` and
0 1 2 ... for ``< card num > ``).
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
You also need to enter some parameters to select the device:
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
-t TYPE : type of card (``supersim``, ``magicsim``, ``fakemagicsim`` or try ``auto``)
-d DEV : Serial port device (default ``/dev/ttyUSB0``)
-b BAUD : Baudrate (default 9600)
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
* Interact with SIMs from a python interactive shell (e.g. ipython):
2017-03-17 17:08:09 +00:00
2021-05-17 16:08:45 +00:00
```
2017-03-17 17:08:09 +00:00
from pySim.transport.serial import SerialSimLink
from pySim.commands import SimCardCommands
sl = SerialSimLink(device='/dev/ttyUSB0', baudrate=9600)
sc = SimCardCommands(sl)
sl.wait_for_card()
# Print IMSI
2020-01-22 16:38:24 +00:00
print(sc.read_binary(['3f00', '7f20', '6f07']))
2017-03-17 17:08:09 +00:00
# Run A3/A8
2020-01-22 16:38:24 +00:00
print(sc.run_gsm('00112233445566778899aabbccddeeff'))
2021-05-17 16:08:45 +00:00
```