mirror of
https://gitea.osmocom.org/sim-card/pysim.git
synced 2026-03-17 02:48:34 +03:00
4ee99c18cd
Found via `codespell -S tests -L ist,adn,ciph,ue,ot,readd,te,oce,tye` Change-Id: I00a72e4f479dcef88f7d1058ce53edd0129d336a
246 lines
9.5 KiB
ReStructuredText
246 lines
9.5 KiB
ReStructuredText
Legacy tools
|
|
============
|
|
|
|
*legacy tools* are the classic ``pySim-prog`` and ``pySim-read`` programs that
|
|
existed long before ``pySim-shell``.
|
|
|
|
These days, it is highly recommended to use ``pySim-shell`` instead of these
|
|
legacy tools.
|
|
|
|
pySim-prog
|
|
----------
|
|
|
|
``pySim-prog`` was the first part of the pySim software suite. It started as a
|
|
tool to write ICCID, IMSI, MSISDN and Ki to very simplistic SIM cards, and was
|
|
later extended to a variety of other cards. As the number of features supported
|
|
became no longer bearable to express with command-line arguments, `pySim-shell`
|
|
was created.
|
|
|
|
Basic use cases can still use `pySim-prog`.
|
|
|
|
Program customizable SIMs
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Two modes are possible:
|
|
|
|
- one where the user specifies every parameter manually:
|
|
|
|
This is the most common way to use ``pySim-prog``. The user will specify all relevant parameters directly via the
|
|
commandline. A typical commandline would look like this:
|
|
|
|
``pySim-prog.py -p <pcsc_reader> --ki <ki_value> --opc <opc_value> --mcc <mcc_value> --mnc <mnc_value>
|
|
--country <country_code> --imsi <imsi_value> --iccid <iccid_value> --pin-adm <adm_pin>``
|
|
|
|
Please note, that this already lengthy commandline still only contains the most common card parameters. For a full
|
|
list of all possible parameters, use the ``--help`` option of ``pySim-prog``. It is also important to mention
|
|
that not all parameters are supported by all card types. In particular, very simple programmable SIM cards will only
|
|
support a very basic set of parameters, such as MCC, MNC, IMSI and KI values.
|
|
|
|
- one where the parameters are generated from a minimal set:
|
|
|
|
It is also possible to leave the generation of certain parameters to ``pySim-prog``. This is in particular helpful
|
|
when a large number of cards should be initialized with randomly generated key material.
|
|
|
|
``pySim-prog.py -p <pcsc_reader> --mcc <mcc_value> --mnc <mnc_value> --secret <random_secret> --num <card_number> --pin-adm <adm_pin>``
|
|
|
|
The parameter ``--secret`` specifies a random seed that is used to generate the card individual parameters. (IMSI).
|
|
The secret should contain enough randomness to avoid conflicts. It is also recommended to store the secret safely,
|
|
in case cards have to be re-generated or the current card batch has to be extended later. For security reasons, the
|
|
key material, which is also card individual, will not be derived from the random seed. Instead a new random set of
|
|
Ki and OPc will be generated during each programming cycle. This means fresh keys are generated, even when the
|
|
``--num`` remains unchanged.
|
|
|
|
The parameter ``--num`` specifies a card individual number. This number will be managed into the random seed so that
|
|
it serves as an identifier for a particular set of randomly generated parameters.
|
|
|
|
In the example above the parameters ``--mcc``, and ``--mnc`` are specified as well, since they identify the GSM
|
|
network where the cards should operate in, it is absolutely required to keep them static. ``pySim-prog`` will use
|
|
those parameters to generate a valid IMSI that thas the specified MCC/MNC at the beginning and a random tail.
|
|
|
|
Specifying the card type:
|
|
|
|
``pySim-prog`` usually autodetects the card type. In case auto detection does not work, it is possible to specify
|
|
the parameter ``--type``. The following card types are supported:
|
|
|
|
* Fairwaves-SIM
|
|
* fakemagicsim
|
|
* gialersim
|
|
* grcardsim
|
|
* magicsim
|
|
* OpenCells-SIM
|
|
* supersim
|
|
* sysmoISIM-SJA2
|
|
* sysmoISIM-SJA5
|
|
* sysmosim-gr1
|
|
* sysmoSIM-GR2
|
|
* sysmoUSIM-SJS1
|
|
* Wavemobile-SIM
|
|
|
|
Specifying the card reader:
|
|
|
|
It is most common to use ``pySim-prog`` together with a PCSC reader. The PCSC reader number is specified via the
|
|
``--pcsc-device`` or ``-p`` option. However, other reader types (such as serial readers and modems) are supported. Use
|
|
the ``--help`` option of ``pySim-prog`` for more information.
|
|
|
|
|
|
Card programming using CSV files
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To simplify the card programming process, ``pySim-prog`` also allows to read
|
|
the card parameters from a CSV file. When a CSV file is used as input, the
|
|
user does not have to craft an individual commandline for each card. Instead
|
|
all card related parameters are automatically drawn from the CSV file.
|
|
|
|
A CSV files may hold rows for multiple (hundreds or even thousands) of
|
|
cards. ``pySim-prog`` is able to identify the rows either by ICCID
|
|
(recommended as ICCIDs are normally not changed) or IMSI.
|
|
|
|
The CSV file format is a flexible format with mandatory and optional columns,
|
|
here the same rules as for the commandline parameters apply. The column names
|
|
match the command line options. The CSV file may also contain columns that are
|
|
unknown to pySim-prog, such as inventory numbers, nicknames or parameters that
|
|
are unrelated to the card programming process. ``pySim-prog`` will silently
|
|
ignore all unknown columns.
|
|
|
|
A CSV file may contain the following columns:
|
|
|
|
* name
|
|
* iccid (typically used as key)
|
|
* mcc
|
|
* mnc
|
|
* imsi (may be used as key, but not recommended)
|
|
* smsp
|
|
* ki
|
|
* opc
|
|
* acc
|
|
* pin_adm, adm1 or pin_adm_hex (must be present)
|
|
* msisdn
|
|
* epdgid
|
|
* epdgSelection
|
|
* pcscf
|
|
* ims_hdomain
|
|
* impi
|
|
* impu
|
|
* opmode
|
|
* fplmn
|
|
|
|
Due to historical reasons, and to maintain the compatibility between multiple different CSV file formats, the ADM pin
|
|
may be stored in three different columns. Only one of the three columns must be available.
|
|
|
|
* adm1: This column contains the ADM pin in numeric ASCII digit format. This format is the most common.
|
|
* pin_adm: Same as adm1, only the column name is different
|
|
* pin_adm_hex: If the ADM pin consists of raw HEX digits, rather then of numerical ASCII digits, then the ADM pin
|
|
can also be provided as HEX string using this column.
|
|
|
|
The following example shows a typical minimal example
|
|
::
|
|
|
|
"imsi","iccid","acc","ki","opc","adm1"
|
|
"999700000053010","8988211000000530108","0001","51ACE8BD6313C230F0BFE1A458928DF0","E5A00E8DE427E21B206526B5D1B902DF","65942330"
|
|
"999700000053011","8988211000000530116","0002","746AAFD7F13CFED3AE626B770E53E860","38F7CE8322D2A7417E0BBD1D7B1190EC","13445792"
|
|
"999700123053012","8988211000000530124","0004","D0DA4B7B150026ADC966DC637B26429C","144FD3AEAC208DFFF4E2140859BAE8EC","53540383"
|
|
"999700000053013","8988211000000530132","0008","52E59240ABAC6F53FF5778715C5CE70E","D9C988550DC70B95F40342298EB84C5E","26151368"
|
|
"999700000053014","8988211000000530140","0010","3B4B83CB9C5F3A0B41EBD17E7D96F324","D61DCC160E3B91F284979552CC5B4D9F","64088605"
|
|
"999700000053015","8988211000000530157","0020","D673DAB320D81039B025263610C2BBB3","4BCE1458936B338067989A06E5327139","94108841"
|
|
"999700000053016","8988211000000530165","0040","89DE5ACB76E06D14B0F5D5CD3594E2B1","411C4B8273FD7607E1885E59F0831906","55184287"
|
|
"999700000053017","8988211000000530173","0080","977852F7CEE83233F02E69E211626DE1","2EC35D48DBF2A99C07D4361F19EF338F","70284674"
|
|
|
|
The following commandline will instruct ``pySim-prog`` to use the provided CSV file as parameter source and the
|
|
ICCID (read from the card before programming) as a key to identify the card. To use the IMSI as a key, the parameter
|
|
``--read-imsi`` can be used instead of ``--read-iccid``. However, this option is only recommended to be used in very
|
|
specific corner cases.
|
|
|
|
``pySim-prog.py -p <pcsc_reader> --read-csv <path_to_csv_file> --source csv --read-iccid``
|
|
|
|
It is also possible to pick a row from the CSV file by manually providing an ICCID (option ``--iccid``) or an IMSI
|
|
(option ``--imsi``) that is then used as a key to find the matching row in the CSV file.
|
|
|
|
``pySim-prog.py -p <pcsc_reader> --read-csv <path_to_csv_file> --source csv --iccid <iccid_value>``
|
|
|
|
|
|
Writing CSV files
|
|
~~~~~~~~~~~~~~~~~
|
|
``pySim-prog`` is also able to generate CSV files that contain a subset of the parameters it has generated or received
|
|
from some other source (commandline, CSV-File). The generated file will be header-less and contain the following
|
|
columns:
|
|
|
|
* name
|
|
* iccid
|
|
* mcc
|
|
* mnc
|
|
* imsi
|
|
* smsp
|
|
* ki
|
|
* opc
|
|
|
|
A commandline that makes use of the CSV write feature would look like this:
|
|
|
|
``pySim-prog.py -p <pcsc_reader> --read-csv <path_to_input_csv_file> --read-iccid --source csv --write-csv <path_to_output_csv_file>``
|
|
|
|
|
|
Batch programming
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
In case larger card batches need to be programmed, it is possible to use the ``--batch`` parameter to run ``pySim-prog`` in batch mode.
|
|
|
|
The batch mode will prompt the user to insert a card. Once a card is detected in the reader, the programming is carried out. The user may then remove the card again and the process starts over. This allows for a quick and efficient card programming without permanent commandline interaction.
|
|
|
|
|
|
pySim-read
|
|
----------
|
|
|
|
``pySim-read`` allows to read some of the most important data items from a SIM
|
|
card. This means it will only read some files of the card, and will only read
|
|
files accessible to a normal user (without any special authentication)
|
|
|
|
These days, it is recommended to use the ``export`` command of ``pySim-shell``
|
|
instead. It performs a much more comprehensive export of all of the [standard]
|
|
files that can be found on the card. To get a human-readable decode instead of
|
|
the raw hex export, you can use ``export --json``.
|
|
|
|
Specifically, pySim-read will dump the following:
|
|
|
|
* MF
|
|
|
|
* EF.ICCID
|
|
|
|
* DF.GSM
|
|
|
|
* EF,IMSI
|
|
* EF.GID1
|
|
* EF.GID2
|
|
* EF.SMSP
|
|
* EF.SPN
|
|
* EF.PLMNsel
|
|
* EF.PLMNwAcT
|
|
* EF.OPLMNwAcT
|
|
* EF.HPLMNAcT
|
|
* EF.ACC
|
|
* EF.MSISDN
|
|
* EF.AD
|
|
* EF.SST
|
|
|
|
* ADF.USIM
|
|
|
|
* EF.EHPLMN
|
|
* EF.UST
|
|
* EF.ePDGId
|
|
* EF.ePDGSelection
|
|
|
|
* ADF.ISIM
|
|
|
|
* EF.PCSCF
|
|
* EF.DOMAIN
|
|
* EF.IMPI
|
|
* EF.IMPU
|
|
* EF.UICCIARI
|
|
* EF.IST
|
|
|
|
|
|
pySim-read usage
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
.. argparse::
|
|
:module: pySim-read
|
|
:func: option_parser
|
|
:prog: pySim-read.py
|