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] [--script PATH]
[--csv FILE] [--csv-column-key FIELD:AES_KEY_HEX]
[--card_handler FILE] [-a PIN_ADM1 | -A PIN_ADM1_HEX]
[command] ...
Positional Arguments¶
- command
A pySim-shell command that would optionally be executed at startup
- command_args
Optional Arguments for command
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
- -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¶
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
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¶
Export files to script that can be imported back later
usage: export [-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¶
Export filesystem metadata and file contents of all files below current DF in machine-readable json format. This is similar to “export”, but much easier to parse by downstream processing tools. You usually may want to call this from the MF and verify the ADM1 PIN (if available) to maximize the amount of readable files.
usage: fsdump [-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¶
Verify the ADM (Administrator) PIN specified as argument. This is typically needed in order to get write/update permissions to most of the files on SIM cards.
usage: verify_adm [-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¶
Run script on multiple cards (bulk provisioning)
usage: bulk_script [-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¶
Echo (print) a string on the console
usage: echo [-h] string [string ...]
Positional Arguments¶
- string
string to echo on the shell
apdu¶
Send a raw APDU to the card, and print SW + Response. CAUTION: this command bypasses the logical channel handling of pySim-shell and card state changes are not tracked. Dpending on the raw APDU sent, pySim-shell may not continue to work as expected if you e.g. select a different file.
usage: apdu [-h] [--expect-sw EXPECT_SW] [--raw] APDU
Positional Arguments¶
- APDU
APDU as hex string
Named Arguments¶
- --expect-sw
expect a specified status word
- --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¶
Change PIN code to a new PIN code
usage: change_chv [-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¶
Disable PIN code using specified PIN code
usage: disable_chv [-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¶
Enable PIN code using specified PIN code
usage: enable_chv [-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¶
Unblock PIN code using specified PUK code
usage: unblock_chv [-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¶
Verify (authenticate) using specified CHV (PIN) code, which is how the specifications call it if you authenticate yourself using the specified PIN. There usually is at least PIN1 and PIN2.
usage: verify_chv [-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¶
Activate the specified EF by sending an ACTIVATE FILE apdu command (used to be called REHABILITATE in TS 11.11 for classic SIM).
usage: activate_file [-h] NAME
Positional Arguments¶
- NAME
File name or FID of file to activate
open_channel¶
Open a logical channel.
usage: open_channel [-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¶
Close a logical channel.
usage: close_channel [-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¶
Switch currently active logical channel.
usage: switch_channel [-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.
Perform the SUSPEND UICC command. Only supported on some UICC (check EF.UMPC).
usage: suspend_uicc [-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.
Perform the REUSME UICC operation. Only supported on some UICC. Also: A power-cycle of the card is required between SUSPEND and RESUME, and only very few non-RESUME commands are permitted between SUSPEND and RESUME. See TS 102 221 Section 11.1.22.
usage: resume_uicc [-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.
Perform the TERMINAL CAPABILITY function. Used to inform the UICC about terminal capability.
usage: terminal_capability [-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¶
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_arr_record [-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¶
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_arr_records [-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¶
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
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¶
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.
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¶
Decode command-line provided hex-string as if it was read from the file.
usage: decode_hex [-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¶
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
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¶
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:
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¶
Decode command-line provided hex-string as if it was read from the file.
usage: decode_hex [-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_data¶
Retrieve (Read) data from a BER-TLV EF
usage: retrieve_data [-h] tag
Positional Arguments¶
- tag
BER-TLV Tag of value to retrieve
set_data¶
Set (Write) data for a given tag in a BER-TLV EF
usage: set_data [-h] tag data
Positional Arguments¶
- tag
BER-TLV Tag of value to set
- data
Data bytes (hex format) to write
del_data¶
Delete data for a given tag in a BER-TLV EF
usage: delete_data [-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¶
Perform Authentication and Key Agreement (AKA).
usage: authenticate [-h] rand autn
Positional Arguments¶
- rand
Random challenge
- autn
Authentication Nonce
terminal_profile¶
Send a TERMINAL PROFILE command to the card. This is used to inform the card about which optional features the terminal (modem/phone) supports, particularly in the context of SIM Toolkit, Proactive SIM and OTA. You must specify a hex-string with the encoded terminal profile you want to send to the card.
usage: terminal_profile [-h] PROFILE
Positional Arguments¶
- PROFILE
Hexstring of encoded terminal profile
envelope¶
Send an ENVELOPE command to the card. This is how a variety of information is communicated from the terminal (modem/phone) to the card, particularly in the context of SIM Toolkit, Proactive SIM and OTA.
usage: envelope [-h] PAYLOAD
Positional Arguments¶
- PAYLOAD
Hexstring of encoded payload to ENVELOPE
envelope_sms¶
Send an ENVELOPE(SMS-PP-Download) command to the card. This emulates a terminal (modem/phone) having received a SMS with a PID of ‘SMS for the SIM card’. You can use this command in the context of testing OTA related features without a modem/phone or a cellular network.
usage: envelope_sms [-h] TPDU
Positional Arguments¶
- TPDU
Hexstring of encoded SMS TPDU
get_identity¶
Send a GET IDENTITY command to the card. This is part of the procedure for “SUCI calculation performed on USIM” supported by USIM with support for both EF.UST service 124 and 125.
usage: get_identity [-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¶
Delete the specified file. DANGEROUS! See TS 102 222 Section 6.4. This will permanently delete the specified file from the card. pySim has no support to re-create files yet, and even if it did, your card may not allow it!
usage: delete_file [-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¶
Terminate the specified DF. DANGEROUS! See TS 102 222 6.7. This is a permanent, one-way operation on the card. There is no undo, you can not recover a terminated DF. The only permitted command for a terminated DF is the DLETE FILE command.
usage: terminate_ef [-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¶
Terminate the specified DF. DANGEROUS! See TS 102 222 6.7. This is a permanent, one-way operation on the card. There is no undo, you can not recover a terminated DF. The only permitted command for a terminated DF is the DLETE FILE command.
usage: terminate_ef [-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¶
Terminate the Card. SUPER DANGEROUS! See TS 102 222 Section 6.9. This will permanently brick the card and can NOT be recovered from!
usage: terminate_card_usage [-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¶
Create a new EF below the currently selected DF. Requires related privileges.
usage: create_ef [-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¶
Create a new DF below the currently selected DF. Requires related privileges.
usage: create_df [-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¶
Resize an existing EF below the currently selected DF. Requires related privileges.
usage: resize_ef [-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¶
Perform STORE DATA [Command-Store-REF-AR-DO] to store a (new) access rule.
usage: aram_store_ref_ar_do [-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 hex bytes)
- --aid-empty
No specific SE application, applies to all applications
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¶
Perform the GlobalPlatform GET DATA command in order to obtain some card-specific data.
usage: get_data [-h] data_object_name
Positional Arguments¶
- data_object_name
Name of the data object to be retrieved from the card
get_status¶
Perform GlobalPlatform GET STATUS command in order to retrieve status information on Issuer Security Domain, Executable Load File, Executable Module or Applications.
usage: get_status [-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¶
set_status¶
Perform GlobalPlatform SET STATUS command in order to change the life cycle state of the Issuer Security Domain, Supplementary Security Domain or Application. This normally requires prior authentication with a Secure Channel Protocol.
usage: set_status [-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¶
Perform the GlobalPlatform GET DATA command in order to store some card-specific data. See GlobalPlatform CardSpecification v2.3Section 11.11 for details.
usage: store_data [-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¶
Perform the GlobalPlatform PUT KEY command in order to store a new key on the card. See GlobalPlatform CardSpecification v2.3 Section 11.8 for details.
usage: put_key [-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¶
Perform GlobalPlaform DELETE (Key) command. If both KID and KVN are specified, exactly one key is deleted. If only either of the two is specified, multiple matching keys may be deleted.
usage: delete_key [-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¶
Perform GlobalPlatform INSTALL [for personalization] command in order to inform a Security Domain that the following STORE DATA commands are meant for a specific AID (specified here).
usage: install_for_personalization [-h] application_aid
Positional Arguments¶
- application_aid
Application AID
install_for_install¶
Perform GlobalPlatform INSTALL [for install] command in order to install an application.
usage: install_for_install [-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
- --module-aid
Executable Module AID
- --application-aid
Application AID
- --install-parameters
Install Parameters
- --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)
- --make-selectable
Install and make selectable
Default:
False
delete_card_content¶
Perform a GlobalPlatform DELETE [card content] command in order to delete an Executable Load File, an Application or an Executable Load File and its related Applications.
usage: delete_card_content [-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¶
Establish a secure channel using the GlobalPlatform SCP02 protocol. It can be released again by using release_scp.
usage: establish_scp02 [-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¶
Establish a secure channel using the GlobalPlatform SCP03 protocol. It can be released again by using release_scp.
usage: establish_scp03 [-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¶
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¶
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¶
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¶
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¶
Example (successful):
pySIM-shell (00:MF/ADF.ISD-R)> disable_profile --iccid 89000123456789012358
{
"disable_result": "ok"
}
delete_profile¶
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¶
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