pySim-shell

pySim-shell is an interactive command line shell for all kind of interactions with SIM cards, including classic GSM SIM, GSM-R SIM, UICC, USIM, ISIM, HPSIM and recently even eUICC.

If you’re familiar with Unix/Linux shells: Think of it like the bash for SIM cards.

The pySim-shell interactive shell provides commands 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 most files (where related file-specific encoder/decoder classes have been developed):

  • decoded reading (display file data represented in human and machine readable JSON format)

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

  • if your card supports it, and you have the related privileges: resizing, creating, enabling and disabling of files

  • performing GlobalPlatform operations, including establishment of Secure Channel Protocol (SCP), Installing applications, installing key material, etc.

  • listing/enabling/disabling/deleting eSIM profiles on Consumer eUICC

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

A typical interactive pySim workflow would look like this:

  • starting the program, specifying which smart card interface to use to talk to the card

  • verifying the PIN (if needed) or the ADM1 PIN in case you want to write/modify the card

  • selecting on-card application dedicated files like ADF.USIM and navigating the tree of DFs

  • reading and potentially modifying file contents, in raw binary (hex) or decoded JSON format

Video Presentation

There is a video recording of the presentation back when pySim-shell was originally released. While it is slightly dated, it should still provide a good introduction.

Running pySim-shell

pySim-shell has a variety of command line arguments to control

  • which transport to use (how to use a reader to talk to the SIM card)

  • whether to automatically verify an ADM pin (and in which format)

  • whether to execute a start-up script

interactive SIM card shell

usage: pySim-shell.py [-h] [-d DEV] [-b BAUD] [--pcsc-shared]
                      [-p PCSC | --pcsc-regex REGEX] [--modem-device DEV]
                      [--modem-baud BAUD] [--osmocon PATH] [--apdu-trace]
                      [--script PATH] [--csv FILE]
                      [--csv-column-key FIELD:AES_KEY_HEX]
                      [--card_handler FILE] [--noprompt] [--skip-card-init]
                      [-a PIN_ADM1 | -A PIN_ADM1_HEX] [-e EXECUTE_COMMAND]
                      [command] ...

Positional Arguments

command

A pySim-shell command that would optionally be executed at startup

command_args

Optional Arguments for command

Named Arguments

--apdu-trace

Trace the command/response APDUs exchanged with the card

Default: False

-e, --execute-command

A pySim-shell command that will be executed at startup

Default: []

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)

General Options

--script

script with pySim-shell commands to be executed automatically at start-up

--csv

Read card data from CSV file

--csv-column-key

per-CSV-column AES transport key

Default: []

--card_handler

Use automatic card handling machine

--noprompt

Run in non interactive mode

Default: False

--skip-card-init

Skip all card/profile initialization

Default: False

-a, --pin-adm

ADM PIN used for provisioning (overwrites default)

-A, --pin-adm-hex

ADM PIN used for provisioning, as hex string (16 characters long)

Usage Examples

Tutorials for pySIM-shell:

Advanced Topics

Advanced pySIM-shell topics

cmd2 basics

As pySim-shell is built upon cmd2, some generic cmd2 commands/features are available. You may want to check out the cmd2 Builtin commands to learn about those.

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

usage: build.py [-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

Example:

pySIM-shell (00:MF)> dir
MF
3f00
 ..          ADF.USIM    DF.SYSTEM   EF.DIR      EF.UMPC
 ADF.ARA-M   DF.EIRENE   DF.TELECOM  EF.ICCID    MF
 ADF.ISIM    DF.GSM      EF.ARR      EF.PL
14 files

export

usage: build.py [-h] [--filename FILENAME] [--json]

Named Arguments

--filename

only export specific file

--json

export as JSON (less reliable)

Default: False

Please note that export works relative to the current working directory, so if you are in MF, then the export will contain all known files on the card. However, if you are in ADF.ISIM, only files below that ADF will be part of the export.

Furthermore, it is strongly advised to first enter the ADM1 pin (verify_adm) to maximize the chance of having permission to read all/most files.

Example:

pySIM-shell (00:MF)> export --json > /tmp/export.json
EXCEPTION of type 'RuntimeError' occurred with message: 'unable to export 50 elementary file(s) and 2 dedicated file(s), also had to stop early due to exception:6e00: ARA-M - Invalid class'
To enable full traceback, run the following command: 'set debug true'
pySIM-shell (00:MF)>

The exception above is more or less expected. It just means that 50 files which are defined (most likely as optional files in some later 3GPP release) were not found on the card, or were invalidated/disabled when trying to SELECT them.

fsdump

usage: build.py [-h] [--filename FILENAME] [--json]

Named Arguments

--filename

only export specific (named) file

--json

export file contents as JSON (less reliable)

Default: False

Please note that fsdump works relative to the current working directory, so if you are in MF, then the dump will contain all known files on the card. However, if you are in ADF.ISIM, only files below that ADF will be part of the dump.

Furthermore, it is strongly advised to first enter the ADM1 pin (verify_adm) to maximize the chance of having permission to read all/most files.

One use case for this is to systematically analyze the differences between the contents of two cards. To do this, you can create fsdumps of the two cards, and then use some general-purpose JSON diffing tool like jycm –show (see https://github.com/eggachecat/jycm).

Example:

pySIM-shell (00:MF)> fsdump > /tmp/fsdump.json
pySIM-shell (00:MF)>

tree

Display a tree of the card filesystem. It is important to note that this displays a tree of files that might potentially exist (based on the card profile). In order to determine if a given file really exists on a given card, you have to try to select that file.

Example:

pySIM-shell (00:MF)> tree
EF.DIR                    2f00 Application Directory
EF.ICCID                  2fe2 ICC Identification
EF.PL                     2f05 Preferred Languages
EF.ARR                    2f06 Access Rule Reference
EF.UMPC                   2f08 UICC Maximum Power Consumption
DF.TELECOM                7f10 None
  EF.ADN                  6f3a Abbreviated Dialing Numbers
...

verify_adm

usage: build.py [-h] [--pin-is-hex]
                [--adm-type {ADM1,ADM2,ADM3,ADM4,ADM5,ADM6,ADM7,ADM8,ADM9,ADM10}]
                [ADM]

Positional Arguments

ADM

ADM pin value. If none given, CSV file will be queried

Named Arguments

--pin-is-hex

ADM pin value is specified as hex-string (not decimal)

Default: False

--adm-type

Possible choices: ADM1, ADM2, ADM3, ADM4, ADM5, ADM6, ADM7, ADM8, ADM9, ADM10

Override ADM number. Default is card-model-specific, usually 1

Example (successful):

pySIM-shell (00:MF)> verify_adm 11111111
pySIM-shell (00:MF)>

In the above case, the ADM was successfully verified. Please make always sure to use the correct ADM1 for the specific card you have inserted! If you present a wrong ADM1 value several times consecutively, your card ADM1 will likely be permanently locked, meaning you will never be able to reach ADM1 privilege level. For sysmoUSIM/ISIM products, three consecutive wrong ADM1 values will lock the ADM1.

Example (erroneous):

pySIM-shell (00:MF)> verify_adm 1
EXCEPTION of type 'RuntimeError' occurred with message: 'Failed to verify chv_no 0x0A with code 0x31FFFFFFFFFFFFFF, 2 tries left.'
To enable full traceback, run the following command: 'set debug true'

If you frequently work with the same set of cards that you need to modify using their ADM1, you can put a CSV file with those cards ICCID + ADM1 values into a CSV (comma separated value) file at ~/.osmocom/pysim/card_data.csv. In this case, you can use the verify_adm command without specifying an ADM1 value.

Example (successful):

pySIM-shell (00:MF)> verify_adm
found ADM-PIN '11111111' for ICCID '898821190000000512'
pySIM-shell (00:MF)>

In this case, the CSV file contained a record for the ICCID of the card (11111111) and that value was used to successfully verify ADM1.

Example (erroneous):

pySIM-shell (00:MF)> verify_adm
EXCEPTION of type 'ValueError' occurred with message: 'cannot find ADM-PIN for ICCID '898821190000000512''
To enable full traceback, run the following command: 'set debug true'

In this case there was no record for the ICCID of the card in the CSV file.

reset

Perform card reset and display the card ATR.

Example:

pySIM-shell (00:MF)> reset
Card ATR: 3b9f96801f878031e073fe211b674a357530350259c4
pySIM-shell (00:MF)> reset

intro

[Re-]Display the introductory banner

Example:

pySIM-shell (00:MF)> intro
Welcome to pySim-shell!
(C) 2021-2023 by Harald Welte, sysmocom - s.f.m.c. GmbH and contributors
Online manual available at https://downloads.osmocom.org/docs/pysim/master/html/shell.html

equip

Equip pySim-shell with a card; particularly useful if the program was started before a card was present, or after a card has been replaced by the user while pySim-shell was kept running.

bulk_script

usage: build.py [-h] [--halt_on_error] [--tries TRIES]
                [--on_stop_action ON_STOP_ACTION]
                [--pre_card_action PRE_CARD_ACTION]
                SCRIPT_PATH

Positional Arguments

SCRIPT_PATH

path to the script file

Named Arguments

--halt_on_error

stop card handling if an exeption occurs

Default: False

--tries

how many tries before trying the next card

Default: 2

--on_stop_action

commandline to execute when card handling has stopped

--pre_card_action

commandline to execute before actually talking to the card

echo

usage: build.py [-h] STRING [STRING ...]

Positional Arguments

STRING

string to echo on the shell

apdu

usage: build.py [-h] [--expect-sw EXPECT_SW]
                [--expect-response-regex EXPECT_RESPONSE_REGEX] [--raw]
                APDU

Positional Arguments

APDU

APDU as hex string

Named Arguments

--expect-sw

expect a specified status word

--expect-response-regex

match response against regex

--raw

Bypass the logical channel (and secure channel)

Default: False

Example:

pySIM-shell (00:MF)> apdu 00a40400023f00
SW: 6700

In the above case the raw APDU hex-string 00a40400023f00 was sent to the card, to which it responded with status word 6700. Keep in mind that pySim-shell has no idea what kind of raw commands you are sending to the card, and it hence is unable to synchronize its internal state (such as the currently selected file) with the card. The use of this command should hence be constrained to commands that do not have any high-level support in pySim-shell yet.

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 (00: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 (00:MF)> select ADF.USIM
{
    "file_descriptor": {
        "file_descriptor_byte": {
            "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": {
        "ps_do": "70",
        "key_reference": 11
    }

}
pySIM-shell (00:MF/ADF.USIM)>

status

The status command [re-]obtains the File Control Template of the currently-selected file and print its decoded output.

Example:

pySIM-shell (00:MF/ADF.ISIM)> status
{
    "file_descriptor": {
        "file_descriptor_byte": {
            "shareable": true,
            "file_type": "df",
            "structure": "no_info_given"
        },
        "record_len": null,
        "num_of_rec": null
    },
    "file_identifier": "ff01",
    "df_name": "a0000000871004ffffffff8907090000",
    "proprietary_information": {
        "uicc_characteristics": "71",
        "available_memory": 101640
    },
    "life_cycle_status_integer": "operational_activated",
    "security_attrib_compact": "00",
    "pin_status_template_do": {
        "ps_do": "70",
        "key_reference": 11
    }
}

change_chv

usage: build.py [-h] [--pin-nr PIN_NR] [NEWPIN] [PIN]

Positional Arguments

NEWPIN

PIN code value. If none given, CSV file will be queried

PIN

PIN code value. If none given, CSV file will be queried

Named Arguments

--pin-nr

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

Default: 1

disable_chv

usage: build.py [-h] [--pin-nr PIN_NR] [PIN]

Positional Arguments

PIN

PIN code value. If none given, CSV file will be queried

Named Arguments

--pin-nr

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

Default: 1

enable_chv

usage: build.py [-h] [--pin-nr PIN_NR] [PIN]

Positional Arguments

PIN

PIN code value. If none given, CSV file will be queried

Named Arguments

--pin-nr

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

Default: 1

unblock_chv

usage: build.py [-h] [--pin-nr PIN_NR] [PUK] [NEWPIN]

Positional Arguments

PUK

PUK code value. If none given, CSV file will be queried

NEWPIN

PIN code value. If none given, CSV file will be queried

Named Arguments

--pin-nr

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

Default: 1

verify_chv

usage: build.py [-h] [--pin-nr PIN_NR] [PIN]

Positional Arguments

PIN

PIN code value. If none given, CSV file will be queried

Named Arguments

--pin-nr

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

Default: 1

deactivate_file

Deactivate the currently selected file. A deactivated file can no longer be accessed for any further operation (such as selecting and subsequently reading or writing).

Any access to a file that is deactivated will trigger the error SW 6283 ‘Selected file invalidated/disabled’

In order to re-access a deactivated file, you need to activate it again, see the activate_file command below. Note that for deactivation the to-be-deactivated EF must be selected, but for activation, the DF above the to-be-activated EF must be selected!

This command sends a DEACTIVATE FILE APDU to the card (used to be called INVALIDATE in TS 11.11 for classic SIM).

activate_file

usage: build.py [-h] NAME

Positional Arguments

NAME

File name or FID of file to activate

open_channel

usage: build.py [-h] {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}

Positional Arguments

chan_nr

Possible choices: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

Channel Number

Default: 1

close_channel

usage: build.py [-h] {1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}

Positional Arguments

chan_nr

Possible choices: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

Channel Number

Default: 1

switch_channel

usage: build.py [-h] {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}

Positional Arguments

chan_nr

Possible choices: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

Channel Number

Default: 0

TS 102 221 commands

These are commands as specified in ETSI TS 102 221, the core UICC specification.

suspend_uicc

This command allows you to perform the SUSPEND UICC command on the card. This is a relatively recent power-saving addition to the UICC specifications, allowing for suspend/resume while maintaining state, as opposed to a full power-off (deactivate) and power-on (activate) of the card.

The pySim command just sends that SUSPEND UICC command and doesn’t perform the full related sequence including the electrical power down.

usage: build.py [-h] [--min-duration-secs MIN_DURATION_SECS]
                [--max-duration-secs MAX_DURATION_SECS]

Named Arguments

--min-duration-secs

Proposed minimum duration of suspension

Default: 60

--max-duration-secs

Proposed maximum duration of suspension

Default: 86400

resume_uicc

This command allows you to perform the SUSPEND UICC command for the RESUME operation on the card.

Suspend/Resume is a relatively recent power-saving addition to the UICC specifications, allowing for suspend/resume while maintaining state, as opposed to a full power-off (deactivate) and power-on (activate) of the card.

The pySim command just sends that SUSPEND UICC (RESUME) command and doesn’t perform the full related sequence including the electrical power down.

usage: build.py [-h] TOKEN

Positional Arguments

TOKEN

Token provided during SUSPEND

terminal_capability

This command allows you to perform the TERMINAL CAPABILITY command towards the card.

TS 102 221 specifies the TERMINAL CAPABILITY command using which the terminal (Software + hardware talking to the card) can expose their capabilities. This is also used in the eUICC universe to let the eUICC know which features are supported.

usage: build.py [-h] [--used-supply-voltage-class {a,b,c,d,e}]
                [--maximum-available-power-supply MAXIMUM_AVAILABLE_POWER_SUPPLY]
                [--actual-used-freq-100k ACTUAL_USED_FREQ_100K]
                [--extended-logical-channel] [--uicc-clf] [--lui-d] [--lpd-d]
                [--lds-d] [--lui-e-scws] [--metadata-update-alerting]
                [--enterprise-capable-device] [--lui-e-e4e] [--lpr]

Terminal Power Supply

--used-supply-voltage-class

Possible choices: a, b, c, d, e

Actual used Supply voltage class

--maximum-available-power-supply

Maximum available power supply of the terminal

--actual-used-freq-100k

Actual used clock frequency (in units of 100kHz)

Extended logical channels terminal support

--extended-logical-channel

Extended Logical Channel supported

Default: False

Additional interfaces support

--uicc-clf

Local User Interface in the Device (LUId) supported

Default: False

Linear Fixed EF commands

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

read_record

usage: build.py [-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

usage: build.py [-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

If this command fails, it means that the record is not decodable, and you should use the read_record command and proceed with manual decoding of the contents.

read_records

usage: build.py [-h]

read_records_decoded

usage: build.py [-h] [--oneline]

Named Arguments

--oneline

No JSON pretty-printing, dump as a single line

Default: False

If this command fails, it means that the record[s] are not decodable, and you should use the read_records command and proceed with manual decoding of the contents.

update_record

usage: build.py [-h] RECORD_NR DATA

Positional Arguments

RECORD_NR

Number of record to be read

DATA

Data bytes (hex format) to write

update_record_decoded

usage: build.py [-h] [--json-path JSON_PATH] RECORD_NR data

Positional Arguments

RECORD_NR

Number of record to be read

data

Abstract data (JSON format) to write

Named Arguments

--json-path

JSON path to modify specific element of record only

If this command fails, it means that the record is not encodable; please check your input and/or use the raw update_record command.

edit_record_decoded

usage: build.py [-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.

If this command fails before the editor is spawned, it means that the current record contents is not decodable, and you should use the update_record_decoded or update_record command.

If this command fails after making your modificatiosn in the editor, it means that the new file contents is not encodable; please check your input and/or us the raw update_record comamdn.

decode_hex

usage: build.py [-h] [--oneline] HEXSTR

Positional Arguments

HEXSTR

Hex-string of encoded data to decode

Named Arguments

--oneline

No JSON pretty-printing, dump as a single line

Default: False

Transparent EF commands

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

read_binary

usage: build.py [-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

usage: build.py [-h] [--oneline]

Named Arguments

--oneline

No JSON pretty-printing, dump as a single line

Default: False

If this command fails, it means that the file is not decodable, and you should use the read_binary command and proceed with manual decoding of the contents.

update_binary

usage: build.py [-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

usage: build.py [-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:

The below example demonstrates this by modifying the ciphering indicator field within EF.AD:

pySIM-shell (00:MF/ADF.USIM/EF.AD)> read_binary_decoded

{
    "ms_operation_mode": "normal_and_specific_facilities",
    "additional_info": {
        "ciphering_indicator": false,
        "csg_display_control": false,
        "prose_services": false,
        "extended_drx": true
    },
    "rfu": 0,
    "mnc_len": 2,
    "extensions": "ff"
}
pySIM-shell (00:MF/ADF.USIM/EF.AD)> update_binary_decoded --json-path additional_info.ciphering_indicator true
"01000902ff"
pySIM-shell (00:MF/ADF.USIM/EF.AD)> read_binary_decoded
{
    "ms_operation_mode": "normal_and_specific_facilities",
    "additional_info": {
        "ciphering_indicator": true,
        "csg_display_control": false,
        "prose_services": false,
        "extended_drx": true
    },
    "rfu": 0,
    "mnc_len": 2,
    "extensions": "ff"
}

If this command fails, it means that the file is not encodable; please check your input and/or use the raw update_binary command.

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.

If this command fails before the editor is spawned, it means that the current file contents is not decodable, and you should use the update_binary_decoded or update_binary command.

If this command fails after making your modificatiosn in the editor, it means that the new file contents is not encodable; please check your input and/or us the raw update_binary comamdn.

decode_hex

usage: build.py [-h] [--oneline] HEXSTR

Positional Arguments

HEXSTR

Hex-string of encoded data to decode

Named Arguments

--oneline

No JSON pretty-printing, dump as a single line

Default: False

BER-TLV EF commands

BER-TLV EFs are files that contain BER-TLV structured data. Every file can contain any number of variable-length IEs (DOs). The tag within a BER-TLV EF must be unique within the file.

The commands below become enabled only when your currently selected file is of BER-TLV EF type.

retrieve_tags

Retrieve a list of all tags present in the currently selected file.

retrieve_data

usage: build.py [-h] TAG

Positional Arguments

TAG

BER-TLV Tag of value to retrieve

set_data

usage: build.py [-h] TAG data

Positional Arguments

TAG

BER-TLV Tag of value to set

data

Data bytes (hex format) to write

del_data

usage: build.py [-h] TAG

Positional Arguments

TAG

BER-TLV Tag of value to set

USIM commands

These commands are available only while ADF.USIM (or ADF.ISIM, respectively) is selected.

authenticate

usage: build.py [-h] RAND AUTN

Positional Arguments

RAND

Random challenge

AUTN

Authentication Nonce

terminal_profile

usage: build.py [-h] PROFILE

Positional Arguments

PROFILE

Hexstring of encoded terminal profile

envelope

usage: build.py [-h] PAYLOAD

Positional Arguments

PAYLOAD

Hexstring of encoded payload to ENVELOPE

envelope_sms

usage: build.py [-h] TPDU

Positional Arguments

TPDU

Hexstring of encoded SMS TPDU

get_identity

usage: build.py [-h] [--nswo-context]

Named Arguments

--nswo-context

use SUCI 5G Non-Seamless WLAN Offload context

Default: False

File-specific commands

These commands are valid only if the respective file is currently selected. They perform some operation that’s specific to this file only.

EF.ARR: read_arr_record

Read one EF.ARR record in flattened, human-friendly form.

EF.ARR: read_arr_records

Read + decode all EF.ARR records in flattened, human-friendly form.

DF.GSM/EF.SST: sst_service_allocate

Mark a given single service as allocated in EF.SST. Requires service number as argument.

DF.GSM/EF.SST: sst_service_activate

Mark a given single service as activated in EF.SST. Requires service number as argument.

DF.GSM/EF.SST: sst_service_deallocate

Mark a given single service as deallocated in EF.SST. Requires service number as argument.

DF.GSM/EF.SST: sst_service_deactivate

Mark a given single service as deactivated in EF.SST. Requires service number as argument.

ADF.USIM/EF.EST: est_service_enable

Enables a single service in EF.EST. Requires service number as argument.

ADF.USIM/EF.EST: est_service_disable

Disables a single service in EF.EST. Requires service number as argument.

EF.IMSI: update_imsi_plmn

Change the PLMN part (MCC+MNC) of the IMSI. Requires a single argument consisting of 5/6 digits of concatenated MCC+MNC.

ADF.USIM/EF.UST: ust_service_activate

Activates a single service in EF.UST. Requires service number as argument.

ADF.USIM/EF.UST: ust_service_deactivate

Deactivates a single service in EF.UST. Requires service number as argument.

ADF.USIM/EF.UST: ust_service_check

Check consistency between services of this file and files present/activated. Many services determine if one or multiple files shall be present/activated or if they shall be absent/deactivated. This performs a consistency check to ensure that no services are activated for files that are not - and vice-versa, no files are activated for services that are not. Error messages are printed for every inconsistency found.

ADF.ISIM/EF.IST: ist_service_activate

Activates a single service in EF.IST. Requires service number as argument.

ADF.ISIM/EF.IST: ist_service_deactivate

Deactivates a single service in EF.UST. Requires service number as argument.

ADF.ISIM/EF.IST: ist_service_check

Check consistency between services of this file and files present/activated. Many services determine if one or multiple files shall be present/activated or if they shall be absent/deactivated. This performs a consistency check to ensure that no services are activated for files that are not - and vice-versa, no files are activated for services that are not. Error messages are printed for every inconsistency found.

UICC Administrative commands

ETSI TS 102 222 specifies a set of Administrative Commands, which can be used by the card issuer / operator to modify the file system structure (delete files, create files) or even to terminate individual files or the entire card.

pySim-shell supports those commands, but use extreme caution. Unless you know exactly what you’re doing, it’s very easy to render your card unusable. You’ve been warned!

delete_file

usage: build.py [-h] [--force-delete] NAME

Positional Arguments

NAME

File name or FID to delete

Named Arguments

--force-delete

I really want to permanently delete the file. I know pySim cannot re-create it yet!

Default: False

terminate_df

usage: build.py [-h] [--force] NAME

Positional Arguments

NAME

File name or FID

Named Arguments

--force

I really want to terminate the file. I know I can not recover from it!

Default: False

terminate_ef

usage: build.py [-h] [--force] NAME

Positional Arguments

NAME

File name or FID

Named Arguments

--force

I really want to terminate the file. I know I can not recover from it!

Default: False

terminate_card

usage: build.py [-h] [--force-terminate-card]

Named Arguments

--force-terminate-card

I really want to permanently terminate the card. It will not be usable afterwards!

Default: False

create_ef

usage: build.py [-h] --ef-arr-file-id EF_ARR_FILE_ID --ef-arr-record-nr
                EF_ARR_RECORD_NR --file-size FILE_SIZE --structure
                {transparent,linear_fixed,ber_tlv}
                [--short-file-id SHORT_FILE_ID] [--shareable]
                [--record-length RECORD_LENGTH]
                FILE_ID

Positional Arguments

FILE_ID

File Identifier as 4-character hex string

required arguments

--ef-arr-file-id

Referenced Security: File Identifier of EF.ARR

--ef-arr-record-nr

Referenced Security: Record Number within EF.ARR

--file-size

Size of file in octets

--structure

Possible choices: transparent, linear_fixed, ber_tlv

Structure of the to-be-created EF

optional arguments

--short-file-id

Short File Identifier as 2-digit hex string

--shareable

Should the file be shareable?

Default: False

--record-length

Length of each record in octets

create_df

usage: build.py [-h] --ef-arr-file-id EF_ARR_FILE_ID --ef-arr-record-nr
                EF_ARR_RECORD_NR [--shareable] [--aid AID]
                [--total-file-size TOTAL_FILE_SIZE] [--permit-rfm-create]
                [--permit-rfm-delete-terminate] [--permit-other-applet-create]
                [--permit-other-applet-delete-terminate]
                FILE_ID

Positional Arguments

FILE_ID

File Identifier as 4-character hex string

required arguments

--ef-arr-file-id

Referenced Security: File Identifier of EF.ARR

--ef-arr-record-nr

Referenced Security: Record Number within EF.ARR

optional arguments

--shareable

Should the file be shareable?

Default: False

--aid

Application ID (creates an ADF, instead of a DF)

--total-file-size

Physical memory allocated for DF/ADi in octets

sysmoISIM-SJA optional arguments

--permit-rfm-create

Default: False

--permit-rfm-delete-terminate

Default: False

--permit-other-applet-create

Default: False

--permit-other-applet-delete-terminate

Default: False

resize_ef

usage: build.py [-h] --file-size FILE_SIZE NAME

Positional Arguments

NAME

Name or FID of file to be resized

required arguments

--file-size

Size of file in octets

ARA-M commands

The ARA-M commands exist to manage the access rules stored in an ARA-M applet on the card.

ARA-M in the context of SIM cards is primarily used to enable Android UICC Carrier Privileges, please see https://source.android.com/devices/tech/config/uicc for more details on the background.

aram_get_all

Obtain and decode all access rules from the ARA-M applet on the card.

NOTE: if the total size of the access rules exceeds 255 bytes, this command will fail, as it doesn’t yet implement fragmentation/reassembly on rule retrieval. YMMV

pySIM-shell (00:MF/ADF.ARA-M)> aram_get_all

[
    {
        "response_all_ref_ar_do": [
            {
                "ref_ar_do": [
                    {
                        "ref_do": [
                            {
                                "aid_ref_do": "ffffffffffff"
                            },
                            {
                                "dev_app_id_ref_do": "e46872f28b350b7e1f140de535c2a8d5804f0be3"
                            }
                        ]
                    },
                    {
                        "ar_do": [
                            {
                                "apdu_ar_do": {
                                    "generic_access_rule": "always"
                                }
                            },
                            {
                                "perm_ar_do": {
                                    "permissions": "0000000000000001"
                                }
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

aram_get_config

Perform Config handshake with ARA-M applet: Tell it our version and retrieve its version.

NOTE: Not supported in all ARA-M implementations.

aram_store_ref_ar_do

usage: build.py [-h] --device-app-id DEVICE_APP_ID [--aid AID | --aid-empty]
                [--pkg-ref PKG_REF]
                [--apdu-never | --apdu-always | --apdu-filter APDU_FILTER]
                [--nfc-always | --nfc-never]
                [--android-permissions ANDROID_PERMISSIONS]

Named Arguments

--device-app-id

Identifies the specific device application that the rule appplies to. Hash of Certificate of Application Provider, or UUID. (20/32 hex bytes)

--aid

Identifies the specific SE application for which rules are to be stored. Can be a partial AID, containing for example only the RID. (5-16 or 0 hex bytes)

--aid-empty

No specific SE application, applies to implicitly selected application (all channels)

Default: False

--pkg-ref

Full Android Java package name (up to 127 chars ASCII)

--apdu-never

APDU access is not allowed

Default: False

--apdu-always

APDU access is allowed

Default: False

--apdu-filter

APDU filter: multiple groups of 8 hex bytes (4 byte CLA/INS/P1/P2 followed by 4 byte mask)

--nfc-always

NFC event access is allowed

Default: False

--nfc-never

NFC event access is not allowed

Default: False

--android-permissions

Android UICC Carrier Privilege Permissions (8 hex bytes)

For example, to store an Android UICC carrier privilege rule for the SHA1 hash of the certificate used to sign the CoIMS android app of Supreeth Herle (https://github.com/herlesupreeth/CoIMS_Wiki) you can use the following command:

pySIM-shell (00:MF/ADF.ARA-M)> aram_store_ref_ar_do --aid FFFFFFFFFFFF --device-app-id E46872F28B350B7E1F140DE535C2A8D5804F0BE3 --android-permissions 0000000000000001 --apdu-always

aram_delete_all

This command will request deletion of all access rules stored within the ARA-M applet. Use it with caution, there is no undo. Any rules later intended must be manually inserted again using aram_store_ref_ar_do

GlobalPlatform commands

pySim-shell has only the mots rudimentary support for GlobalPlatform at this point. Please use dedicated projects like GlobalPlatformPro meanwhile.

get_data

usage: build.py [-h] data_object_name

Positional Arguments

data_object_name

Name of the data object to be retrieved from the card

get_status

usage: build.py [-h] [--aid AID] {isd,applications,files,files_and_modules}

Positional Arguments

subset

Possible choices: isd, applications, files, files_and_modules

Subset of statuses to be included in the response

Named Arguments

--aid

AID Search Qualifier (search only for given AID)

Default: ````

set_status

usage: build.py [-h] [--aid AID]
                {isd,app_or_ssd,isd_and_assoc_apps}
                {loaded,installed,selectable,personalized,locked}

Positional Arguments

scope

Possible choices: isd, app_or_ssd, isd_and_assoc_apps

Defines the scope of the requested status change

status

Possible choices: loaded, installed, selectable, personalized, locked

Specify the new intended status

Named Arguments

--aid

AID of the target Application or Security Domain

store_data

usage: build.py [-h] [--data-structure {none,dgi,ber_tlv,rfu}]
                [--encryption {none,application_dependent,rfu,encrypted}]
                [--response {not_expected,may_be_returned}]
                DATA

Positional Arguments

DATA

Named Arguments

--data-structure

Possible choices: none, dgi, ber_tlv, rfu

Default: 'none'

--encryption

Possible choices: none, application_dependent, rfu, encrypted

Default: 'none'

--response

Possible choices: not_expected, may_be_returned

Default: 'not_expected'

put_key

usage: build.py [-h] [--old-key-version-nr OLD_KEY_VERSION_NR]
                --key-version-nr KEY_VERSION_NR --key-id KEY_ID --key-type
                {des,tls_psk,aes,hmac_sha1,hmac_sha1_160,rsa_public_exponent_e_cleartex,rsa_modulus_n_cleartext,rsa_modulus_n,rsa_private_exponent_d,rsa_chines_remainder_p,rsa_chines_remainder_q,rsa_chines_remainder_pq,rsa_chines_remainder_dpi,rsa_chines_remainder_dqi,ecc_public_key,ecc_private_key,ecc_field_parameter_p,ecc_field_parameter_a,ecc_field_parameter_b,ecc_field_parameter_g,ecc_field_parameter_n,ecc_field_parameter_k,ecc_key_parameters_reference,not_available}
                --key-data KEY_DATA [--key-check KEY_CHECK]
                [--suppress-key-check]

Named Arguments

--old-key-version-nr

Old Key Version Number

Default: 0

--key-version-nr

Key Version Number

--key-id

Key Identifier (base)

--key-type

Possible choices: des, tls_psk, aes, hmac_sha1, hmac_sha1_160, rsa_public_exponent_e_cleartex, rsa_modulus_n_cleartext, rsa_modulus_n, rsa_private_exponent_d, rsa_chines_remainder_p, rsa_chines_remainder_q, rsa_chines_remainder_pq, rsa_chines_remainder_dpi, rsa_chines_remainder_dqi, ecc_public_key, ecc_private_key, ecc_field_parameter_p, ecc_field_parameter_a, ecc_field_parameter_b, ecc_field_parameter_g, ecc_field_parameter_n, ecc_field_parameter_k, ecc_key_parameters_reference, not_available

Key Type

--key-data

Key Data Block

--key-check

Key Check Value

--suppress-key-check

Suppress generation of Key Check Values

Default: False

delete_key

usage: build.py [-h] [--key-id KEY_ID] [--key-ver KEY_VER]
                [--delete-related-objects]

Named Arguments

--key-id

Key Identifier (KID)

--key-ver

Key Version Number (KVN)

--delete-related-objects

Delete not only the object but also its related objects

Default: False

install_for_personalization

usage: build.py [-h] application_aid

Positional Arguments

application_aid

Application AID

install_for_install

usage: build.py [-h] [--load-file-aid LOAD_FILE_AID] [--module-aid MODULE_AID]
                --application-aid APPLICATION_AID
                [--install-parameters INSTALL_PARAMETERS]
                [--privilege {security_domain,dap_verification,delegated_management,card_lock,card_terminate,card_reset,cvm_management,mandated_dap_verification,trusted_path,authorized_management,token_management,global_delete,global_lock,global_registry,final_application,global_service,receipt_generation,ciphered_load_file_data_block,contactless_activation,contactless_self_activation}]
                [--install-token INSTALL_TOKEN] [--make-selectable]

Named Arguments

--load-file-aid

Executable Load File AID

Default: ````

--module-aid

Executable Module AID

Default: ````

--application-aid

Application AID

--install-parameters

Install Parameters

Default: ````

--privilege

Possible choices: security_domain, dap_verification, delegated_management, card_lock, card_terminate, card_reset, cvm_management, mandated_dap_verification, trusted_path, authorized_management, token_management, global_delete, global_lock, global_registry, final_application, global_service, receipt_generation, ciphered_load_file_data_block, contactless_activation, contactless_self_activation

Privilege granted to newly installed Application

Default: []

--install-token

Install Token (Section GPCS C.4.2/C.4.7)

Default: ````

--make-selectable

Install and make selectable

Default: False

delete_card_content

usage: build.py [-h] [--delete-related-objects] aid

Positional Arguments

aid

Executable Load File or Application AID

Named Arguments

--delete-related-objects

Delete not only the object but also its related objects

Default: False

establish_scp02

usage: build.py [-h] --key-ver KEY_VER [--host-challenge HOST_CHALLENGE]
                [--security-level SECURITY_LEVEL] [--key-enc KEY_ENC]
                [--key-mac KEY_MAC] [--key-dek KEY_DEK]
                [--key-provider-suffix KEY_PROVIDER_SUFFIX]

Named Arguments

--key-ver

Key Version Number (KVN)

--host-challenge

Hard-code the host challenge; default: random

--security-level

Security Level. Default: 0x01 (C-MAC only)

Default: 1

Manual key specification

--key-enc

Secure Channel Encryption Key

--key-mac

Secure Channel MAC Key

--key-dek

Data Encryption Key

Obtain keys from CardKeyProvider (e.g. CSV

--key-provider-suffix

Suffix for key names in CardKeyProvider

establish_scp03

usage: build.py [-h] --key-ver KEY_VER [--host-challenge HOST_CHALLENGE]
                [--security-level SECURITY_LEVEL] [--key-enc KEY_ENC]
                [--key-mac KEY_MAC] [--key-dek KEY_DEK]
                [--key-provider-suffix KEY_PROVIDER_SUFFIX] [--s16-mode]

Named Arguments

--key-ver

Key Version Number (KVN)

--host-challenge

Hard-code the host challenge; default: random

--security-level

Security Level. Default: 0x01 (C-MAC only)

Default: 1

--s16-mode

S16 mode (S8 is default)

Default: False

Manual key specification

--key-enc

Secure Channel Encryption Key

--key-mac

Secure Channel MAC Key

--key-dek

Data Encryption Key

Obtain keys from CardKeyProvider (e.g. CSV

--key-provider-suffix

Suffix for key names in CardKeyProvider

release_scp

Release any previously established SCP (Secure Channel Protocol)

eUICC ISD-R commands

These commands are to perform a variety of operations against eUICC for GSMA consumer eSIM. They implement the so-called ES10a, ES10b and ES10c interface. Basically they perform the tasks that usually would be done by the LPAd in the UE.

In order to use those commands, you need to go through the specified steps as documented in GSMA SGP.22:

  • open a new logical channel (and start to use it)

  • select the ISD-R application

Example:

pySIM-shell (00:MF)> open_channel 2
pySIM-shell (00:MF)> switch_channel 2
pySIM-shell (02:MF)> select ADF.ISD-R
{
    "application_id": "a0000005591010ffffffff8900000100",
    "proprietary_data": {
        "maximum_length_of_data_field_in_command_message": 255
    },
    "isdr_proprietary_application_template": {
        "supported_version_number": "020200"
    }
}
pySIM-shell (02:ADF.ISD-R)>

Once you are at this stage, you can issue the various eUICC related commands against the ISD-R application

es10x_store_data

usage: build.py [-h] TX_DO

Positional Arguments

TX_DO

Hexstring of encoded to-be-transmitted DO

get_euicc_configured_addresses

Obtain the configured SM-DP+ and/or SM-DS addresses using the ES10a GetEuiccConfiguredAddresses() function.

Example:

pySIM-shell (00:MF/ADF.ISD-R)> get_euicc_configured_addresses
{
    "root_ds_address": "testrootsmds.gsma.com"
}

set_default_dp_address

usage: build.py [-h] DP_ADDRESS

Positional Arguments

DP_ADDRESS

Default SM-DP+ address as UTF-8 string

get_euicc_challenge

Obtain an authentication challenge from the eUICC using the ES10b GetEUICCChallenge() function.

Example:

pySIM-shell (00:MF/ADF.ISD-R)> get_euicc_challenge
{
    "euicc_challenge": "3668f20d4e6c8e85609bbca8c14873fd"
}

get_euicc_info1

Obtain EUICC Information (1) from the eUICC using the ES10b GetEUICCCInfo() function.

Example:

pySIM-shell (00:MF/ADF.ISD-R)> get_euicc_info1
{
    "svn": "2.2.0",
    "euicc_ci_pki_list_for_verification": [
        {
            "subject_key_identifier_seq": {
                "unknown_ber_tlv_ie_c0": null
            }
        },
        {
            "subject_key_identifier_seq": {
                "unknown_ber_tlv_ie_f5": {
                    "raw": "72bdf98a95d65cbeb88a38a1c11d800a85c3"
                }
            }
        }
    ],
    "euicc_ci_pki_list_for_signing": [
        {
            "subject_key_identifier_seq": {
                "unknown_ber_tlv_ie_c0": null
            }
        },
        {
            "subject_key_identifier_seq": {
                "unknown_ber_tlv_ie_f5": {
                    "raw": "72bdf98a95d65cbeb88a38a1c11d800a85c3"
                }
            }
        }
    ]
}

get_euicc_info2

Obtain EUICC Information (2) from the eUICC using the ES10b GetEUICCCInfo() function.

Example:

pySIM-shell (00:MF/ADF.ISD-R)> get_euicc_info2
{
    "profile_version": "2.1.0",
    "svn": "2.2.0",
    "euicc_firmware_ver": "4.4.0",
    "ext_card_resource": "81010082040006ddc68304000016e0",
    "uicc_capability": "067f36c0",
    "ts102241_version": "9.2.0",
    "global_platform_version": "2.3.0",
    "rsp_capability": "0490",
    "euicc_ci_pki_list_for_verification": [
        {
            "subject_key_identifier_seq": {
                "unknown_ber_tlv_ie_c0": null
            }
        },
        {
            "subject_key_identifier_seq": {
                "unknown_ber_tlv_ie_f5": {
                    "raw": "72bdf98a95d65cbeb88a38a1c11d800a85c3"
                }
            }
        }
    ],
    "euicc_ci_pki_list_for_signing": [
        {
            "subject_key_identifier_seq": {
                "unknown_ber_tlv_ie_c0": null
            }
        },
        {
            "subject_key_identifier_seq": {
                "unknown_ber_tlv_ie_f5": {
                    "raw": "72bdf98a95d65cbeb88a38a1c11d800a85c3"
                }
            }
        }
    ],
    "unknown_ber_tlv_ie_99": {
        "raw": "06c0"
    },
    "pp_version": "0.0.1",
    "ss_acreditation_number": "G&DAccreditationNbr",
    "unknown_ber_tlv_ie_ac": {
        "raw": "801f312e322e3834302e313233343536372f6d79506c6174666f726d4c6162656c812568747470733a2f2f6d79636f6d70616e792e636f6d2f6d79444c4f41526567697374726172"
    }
}

list_notification

Obtain the list of notifications from the eUICC using the ES10b ListNotification() function.

Example:

pySIM-shell (00:MF/ADF.ISD-R)> list_notification
{
    "notification_metadata_list": {
        "notification_metadata": {
            "seq_number": 61,
            "profile_mgmt_operation": {
                "pmo": {
                    "install": true,
                    "enable": false,
                    "disable": false,
                    "delete": false
                }
            },
            "notification_address": "testsmdpplus1.example.com",
            "iccid": "89000123456789012358"
        }
    }
}

remove_notification_from_list

usage: build.py [-h] SEQ_NR

Positional Arguments

SEQ_NR

Sequence Number of the to-be-removed notification

Example:

pySIM-shell (00:MF/ADF.ISD-R)> remove_notification_from_list 60
{
    "delete_notification_status": "ok"
}

get_profiles_info

Obtain information about the profiles present on the eUICC using the ES10c GetProfilesInfo() function.

Example:

pySIM-shell (00:MF/ADF.ISD-R)> get_profiles_info
{
    "profile_info_seq": [
        {
            "profile_info": {
                "iccid": "89000123456789012341",
                "isdp_aid": "a0000005591010ffffffff8900001100",
                "profile_state": "disabled",
                "service_provider_name": "GSMA Test 1A",
                "profile_name": "GSMA Generic eUICC Test Profile 1A",
                "profile_class": "operational"
            }
        },
        {
            "profile_info": {
                "iccid": "89000123456789012358",
                "isdp_aid": "a0000005591010ffffffff8900001200",
                "profile_state": "disabled",
                "service_provider_name": "OsmocomSPN",
                "profile_name": "OsmocomProfile",
                "profile_class": "operational"
            }
        }
    ]
}

enable_profile

usage: build.py [-h] [--isdp-aid ISDP_AID | --iccid ICCID]
                [--refresh-required]

Named Arguments

--isdp-aid

Profile identified by its ISD-P AID

--iccid

Profile identified by its ICCID

--refresh-required

whether a REFRESH is required

Default: False

Example (successful):

pySIM-shell (00:MF/ADF.ISD-R)> enable_profile --iccid 89000123456789012358
{
    "enable_result": "ok"
}

Example (failed attempt enabling a profile that’s already enabled):

pySIM-shell (00:MF/ADF.ISD-R)> enable_profile --iccid 89000123456789012358
{
    "enable_result": "profileNotInDisabledState"
}

disable_profile

usage: build.py [-h] [--isdp-aid ISDP_AID | --iccid ICCID]
                [--refresh-required]

Named Arguments

--isdp-aid

Profile identified by its ISD-P AID

--iccid

Profile identified by its ICCID

--refresh-required

whether a REFRESH is required

Default: False

Example (successful):

pySIM-shell (00:MF/ADF.ISD-R)> disable_profile --iccid 89000123456789012358
{
    "disable_result": "ok"
}

delete_profile

usage: build.py [-h] [--isdp-aid ISDP_AID | --iccid ICCID]

Named Arguments

--isdp-aid

Profile identified by its ISD-P AID

--iccid

Profile identified by its ICCID

Example:

pySIM-shell (00:MF/ADF.ISD-R)> delete_profile --iccid 89000123456789012358
{
    "delete_result": "ok"
}

get_eid

Obtain the EID of the eUICC using the ES10c GetEID() function.

Example:

pySIM-shell (00:MF/ADF.ISD-R)> get_eid
{
    "eid_value": "89049032123451234512345678901235"
}

set_nickname

usage: build.py [-h] [--profile-nickname PROFILE_NICKNAME] ICCID

Positional Arguments

ICCID

ICCID of the profile whose nickname to set

Named Arguments

--profile-nickname

Nickname of the profile

Example:

pySIM-shell (00:MF/ADF.ISD-R)> set_nickname --profile-nickname asdf 89000123456789012358
{
    "set_nickname_result": "ok"
}

get_certs

Obtain the certificates from an IoT eUICC using the ES10c GetCerts() function.

get_eim_configuration_data

Obtain the eIM configuration data from an IoT eUICC using the ES10b GetEimConfigurationData() function.

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

apdu_trace

Boolean variable that determines if a hex-dump of the command + response APDU shall be printed.

numeric_path

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

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