pySim-shell¶

pySim-shell is an interactive command line shell for all kind of interactions with SIM cards.

The interactive shell provides command for

navigating the on-card filesystem hierarchy
authenticating with PINs such as ADM1
CHV/PIN management (VERIFY, ENABLE, DISABLE, UNBLOCK)
decoding of SELECT response (file control parameters)
reading and writing of files and records in raw, hex-encoded binary format
for some files where related support has been developed:

decoded reading (display file data in JSON format)

decoded writing (encode from JSON to binary format, then write)

By means of using the python cmd2 module, various useful features improve usability:

history of commands (persistent across restarts)
output re-direction to files on your computer
output piping through external tools like ‘grep’
tab completion of commands and SELECT-able files/directories
interactive help for all commands

cmd2 basics¶

FIXME

ISO7816 commands¶

This category of commands relates to commands that originate in the ISO 7861-4 specifications, most of them have a 1:1 resemblance in the specification.

select¶

The select command is used to select a file, either by its FID, AID or by its symbolic name.

Try select with tab-completion to get a list of all current selectable items:

pySIM-shell (MF)> select
..                2fe2              a0000000871004    EF.ARR            MF
2f00              3f00              ADF.ISIM          EF.DIR
2f05              7f10              ADF.USIM          EF.ICCID
2f06              7f20              DF.GSM            EF.PL
2f08              a0000000871002    DF.TELECOM        EF.UMPC

Use select with a specific FID or name to select the new file.

This will

output the [JSON decoded, if possible] select response
change the prompt to the newly selected file
enable any commands specific to the newly-selected file

pySIM-shell (MF)> select ADF.USIM
{
    "file_descriptor": {
        "shareable": true,
        "file_type": "df",
        "structure": "no_info_given"
    },
    "df_name": "A0000000871002FFFFFFFF8907090000",
    "proprietary_info": {
        "uicc_characteristics": "71",
        "available_memory": 101640
    },
    "life_cycle_status_int": "operational_activated",
    "security_attrib_compact": "00",
    "pin_status_template_do": "90017083010183018183010A83010B"
}
pySIM-shell (MF/ADF.USIM)>

change_chv¶

Change PIN code to a new PIN code

usage: change_chv [-h] [--pin-nr PIN_NR] pin_code new_pin_code

Positional Arguments¶

pin_code: PIN code digits “PIN1” or “PIN2” to get PIN code from external data source
new_pin_code: PIN code digits “PIN1” or “PIN2” to get PIN code from external data source

Named Arguments¶

--pin-nr

PUK Number, 1=PIN1, 2=PIN2 or custom value (decimal)

Default: 1

disable_chv¶

Disable PIN code using specified PIN code

usage: disable_chv [-h] [--pin-nr PIN_NR] pin_code

Positional Arguments¶

pin_code: PIN code digits, “PIN1” or “PIN2” to get PIN code from external data source

Named Arguments¶

--pin-nr

PIN Number, 1=PIN1, 2=PIN2 or custom value (decimal)

Default: 1

enable_chv¶

Enable PIN code using specified PIN code

usage: enable_chv [-h] [--pin-nr PIN_NR] pin_code

Positional Arguments¶

pin_code: PIN code digits, “PIN1” or “PIN2” to get PIN code from external data source

Named Arguments¶

--pin-nr

PIN Number, 1=PIN1, 2=PIN2 or custom value (decimal)

Default: 1

unblock_chv¶

Unblock PIN code using specified PUK code

usage: unblock_chv [-h] [--pin-nr PIN_NR] puk_code new_pin_code

Positional Arguments¶

puk_code: PUK code digits “PUK1” or “PUK2” to get PUK code from external data source
new_pin_code: PIN code digits “PIN1” or “PIN2” to get PIN code from external data source

Named Arguments¶

--pin-nr

PUK Number, 1=PIN1, 2=PIN2 or custom value (decimal)

Default: 1

verify_chv¶

This command allows you to verify a CHV (PIN), which is how the specifications call it if you authenticate yourself with the said CHV/PIN.

Verify (authenticate) using specified PIN code

usage: verify_chv [-h] [--pin-nr PIN_NR] pin_code

Positional Arguments¶

pin_code: PIN code digits, “PIN1” or “PIN2” to get PIN code from external data source

Named Arguments¶

--pin-nr

PIN Number, 1=PIN1, 2=PIN2 or custom value (decimal)

Default: 1

pySim commands¶

Commands in this category are pySim specific; they do not have a 1:1 correspondence to ISO 7816 or 3GPP commands. Mostly they will operate either only on local (in-memory) state, or execute a complex sequence of card-commands.

desc¶

Display human readable file description for the currently selected file.

dir¶

Show a listing of files available in currently selected DF or MF

usage: dir [-h] [--fids] [--names] [--apps] [--all]

Named Arguments¶

--fids

Show file identifiers

Default: False

--names

Show file names

Default: False

--apps

Show applications

Default: False

--all

Show all selectable identifiers and names

Default: False

export¶

Export files to script that can be imported back later

usage: export [-h] [--filename FILENAME]

Named Arguments¶

--filename: only export specific file

tree¶

FIXME

verify_adm¶

FIXME

Linear Fixed EF commands¶

These commands become enabled only when your currently selected file is of Linear Fixed EF type.

read_record¶

Read one or multiple records from a record-oriented EF

usage: read_record [-h] [--count COUNT] record_nr

Positional Arguments¶

record_nr: Number of record to be read

Named Arguments¶

--count

Number of records to be read, beginning at record_nr

Default: 1

read_record_decoded¶

Read + decode a record from a record-oriented EF

usage: read_record_decoded [-h] [--oneline] record_nr

Positional Arguments¶

record_nr: Number of record to be read

Named Arguments¶

--oneline

No JSON pretty-printing, dump as a single line

Default: False

read_records¶

Read all records from a record-oriented EF

usage: read_records [-h]

read_records_decoded¶

Read + decode all records from a record-oriented EF

usage: read_records_decoded [-h] [--oneline]

Named Arguments¶

--oneline

No JSON pretty-printing, dump as a single line

Default: False

update_record¶

Update (write) data to a record-oriented EF

usage: update_record [-h] record_nr data

Positional Arguments¶

record_nr: Number of record to be read
data: Data bytes (hex format) to write

update_record_decoded¶

Encode + Update (write) data to a record-oriented EF

usage: update_record_decoded [-h] [--json-path JSON_PATH] record_nr data

Positional Arguments¶

record_nr: Number of record to be read
data: Data bytes (hex format) to write

Named Arguments¶

--json-path: JSON path to modify specific element of record only

edit_record_decoded¶

Edit the JSON representation of one record in an editor.

usage: edit_record_decoded [-h] record_nr

Positional Arguments¶

record_nr: Number of record to be edited

This command will read the selected record, decode it to its JSON representation, save that JSON to a temporary file on your computer, and launch your configured text editor.

You may then perform whatever modifications to the JSON representation, save + leave your text editor.

Afterwards, the modified JSON will be re-encoded to the binary format, and the result written back to the record on the SIM card.

This allows for easy interactive modification of records.

Transparent EF commands¶

These commands become enabled only when your currently selected file is of Transparent EF type.

read_binary¶

Read binary data from a transparent EF

usage: read_binary [-h] [--offset OFFSET] [--length LENGTH]

Named Arguments¶

--offset

Byte offset for start of read

Default: 0

--length

Number of bytes to read

read_binary_decoded¶

Read + decode data from a transparent EF

usage: read_binary_decoded [-h] [--oneline]

Named Arguments¶

--oneline

No JSON pretty-printing, dump as a single line

Default: False

update_binary¶

Update (Write) data of a transparent EF

usage: update_binary [-h] [--offset OFFSET] data

Positional Arguments¶

data: Data bytes (hex format) to write

Named Arguments¶

--offset

Byte offset for start of read

Default: 0

update_binary_decoded¶

Encode + Update (Write) data of a transparent EF

usage: update_binary_decoded [-h] [--json-path JSON_PATH] data

Positional Arguments¶

data: Abstract data (JSON format) to write

Named Arguments¶

--json-path: JSON path to modify specific element of file only

In normal operation, update_binary_decoded needs a JSON document representing the entire file contents as input. This can be inconvenient if you want to keep 99% of the content but just toggle one specific parameter. That’s where the JSONpath support comes in handy: You can specify a JSONpath to an element inside the document as well as a new value for tat field:

Th below example demonstrates this by modifying the ofm field within EF.AD:

pySIM-shell (MF/ADF.USIM/EF.AD)> read_binary_decoded
{
    "ms_operation_mode": "normal",
    "specific_facilities": {
        "ofm": true
    },
    "len_of_mnc_in_imsi": 2
}
pySIM-shell (MF/ADF.USIM/EF.AD)> update_binary_decoded --json-path specific_facilities.ofm false
pySIM-shell (MF/ADF.USIM/EF.AD)> read_binary_decoded
{
    "ms_operation_mode": "normal",
    "specific_facilities": {
        "ofm": false
    },
    "len_of_mnc_in_imsi": 2
}

edit_binary_decoded¶

This command will read the selected binary EF, decode it to its JSON representation, save that JSON to a temporary file on your computer, and launch your configured text editor.

You may then perform whatever modifications to the JSON representation, save + leave your text editor.

Afterwards, the modified JSON will be re-encoded to the binary format, and the result written to the SIM card.

This allows for easy interactive modification of file contents.

cmd2 settable parameters¶

cmd2 has the concept of settable parameters which act a bit like environment variables in an OS-level shell: They can be read and set, and they will influence the behavior somehow.

conserve_write¶

If enabled, pySim will (when asked to write to a card) always first read the respective file/record and verify if the to-be-written value differs from the current on-card value. If not, the write will be skipped. Writes will only be performed if the new value is different from the current on-card value.

If disabled, pySim will always write irrespective of the current/new value.

json_pretty_print¶

This parameter determines if generated JSON output should (by default) be pretty-printed (multi-line output with indent level of 4 spaces) or not.

The default value of this parameter is ‘true’.

debug¶

If enabled, full python back-traces will be displayed in case of exceptions

numeric_path¶

Boolean variable that determines if path (e.g. in prompt) is displayed with numeric FIDs or string names.

pySIM-shell (MF/EF.ICCID)> set numeric_path True
numeric_path - was: False
now: True
pySIM-shell (3f00/2fe2)> set numeric_path False
numeric_path - was: True
now: False
pySIM-shell (MF/EF.ICCID)> help set