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 manged 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 whith 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

Legacy tool for reading some parts of a SIM card

usage: pySim-read.py [-h] [-d DEV] [-b BAUD] [--pcsc-shared]
                     [-p PCSC | --pcsc-regex REGEX] [--modem-device DEV]
                     [--modem-baud BAUD] [--osmocon PATH] [--apdu-trace]

Named Arguments

--apdu-trace

Trace the command/response APDUs exchanged with the card

Default: False

Serial Reader

Use a simple/ultra-low-cost serial reader attached to a (physical or USB/virtual) RS232 port. This doesn’t work with all RS232-attached smart card readers, only with the very primitive readers following the ancient Phoenix or Smart Mouse design.

-d, --device

Serial Device for SIM access

Default: '/dev/ttyUSB0'

-b, --baud

Baud rate used for SIM access

Default: 9600

PC/SC Reader

Use a PC/SC card reader to talk to the SIM card. PC/SC is a standard API for how applications access smart card readers, and is available on a variety of operating systems, such as Microsoft Windows, MacOS X and Linux. Most vendors of smart card readers provide drivers that offer a PC/SC interface, if not even a generic USB CCID driver is used. You can use a tool like pcsc_scan -r to obtain a list of readers available on your system.

--pcsc-shared

Open PC/SC reaer in SHARED access (default: EXCLUSIVE)

Default: False

-p, --pcsc-device

Number of PC/SC reader to use for SIM access

--pcsc-regex

Regex matching PC/SC reader to use for SIM access

AT Command Modem Reader

Talk to a SIM Card inside a mobile phone or cellular modem which is attached to this computer and offers an AT command interface including the AT+CSIM interface for Generic SIM access as specified in 3GPP TS 27.007.

--modem-device

Serial port of modem for Generic SIM Access (3GPP TS 27.007)

--modem-baud

Baud rate used for modem port

Default: 115200

OsmocomBB Reader

Use an OsmocomBB compatible phone to access the SIM inserted to the phone SIM slot. This will require you to run the OsmocomBB firmware inside the phone (can be ram-loaded). It also requires that you run the osmocon program, which provides a unix domain socket to which this reader driver can attach.

--osmocon

Socket path for Calypso (e.g. Motorola C1XX) based reader (via OsmocomBB)