osmopysim-usermanual

Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle, Merli

Jun 06, 2025

 CONTENTS:

1 Introduction 1
1.1 pySim-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.1 Video Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.2 Running pySim-shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.3 Usage Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.4 Advanced Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.1.5 cmd2 basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.1.6 pySim commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.1.7 ISO7816 commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.1.8 TS 102 221 commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.1.9 Linear Fixed EF commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.1.10 Transparent EF commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
1.1.11 BER-TLV EF commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
1.1.12 USIM commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
1.1.13 File-specific commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
1.1.14 UICC Administrative commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
1.1.15 ARA-M commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
1.1.16 GlobalPlatform commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
1.1.17 eUICC ISD-R commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
1.1.18 cmd2 settable parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
1.2 pySim-trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
1.2.1 Demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.2.2 Running pySim-trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.2.3 pySim-trace command line reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.2.4 Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.3 Legacy tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.3.1 pySim-prog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
1.3.2 pySim-read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
1.4 pySim-smpp2sim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
1.4.1 Running pySim-smpp2sim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
1.4.2 Example execution with sample output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
1.5 pySim library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
1.5.1 pySim filesystem abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
1.5.2 pySim commands abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
1.5.3 pySim Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
1.5.4 pySim utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
1.5.5 pySim exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
1.5.6 pySim card_handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
1.5.7 pySim card_key_provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
1.6 pySim eSIM libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

i
 1.6.1 GSMA SGP.21/22 Remote SIM Provisioning (RSP) - High Level . . . . . . . . . . . . . . . 89
1.6.2 GSMA SGP.21/22 Remote SIM Provisioning (RSP) - Low Level . . . . . . . . . . . . . . . 91
1.6.3 SIMalliance / TCA Interoperable Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
1.7 osmo-smdpp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
1.7.1 Running osmo-smdpp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
1.8 sim-rest-server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
1.8.1 REST API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
1.8.2 Concrete example using the included sysmoISIM-SJA2 . . . . . . . . . . . . . . . . . . . . 117
1.9 suci-keytool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
1.9.1 Generating keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
1.9.2 Dumping public keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
1.9.3 suci-keytool syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
1.10 saip-tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
1.10.1 Profile Package Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
1.10.2 JAVA card applets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
1.10.3 saip-tool syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

2 Indices and tables 127

Python Module Index 129

Index 131

ii
 CHAPTER

ONE

INTRODUCTION

pySim is a python implementation of various software that helps you with managing subscriber identity cards for
cellular networks, so-called SIM cards.
Many Osmocom (Open Source Mobile Communications) projects relate to operating private / custom cellular networks,
and provisioning SIM cards for said networks is in many cases a requirement to operate such networks.
To make use of most of pySim’s features, you will need a programmable SIM card, i.e. a card where you are the
owner/operator and have sufficient credentials (such as the ADM PIN) in order to write to many if not most of the files
on the card.
Such cards are, for example, available from sysmocom, a major contributor to pySim. See https://www.sysmocom.de/
products/lab/sysmousim/ for more details.
pySim supports classic GSM SIM cards as well as ETSI UICC with 3GPP USIM and ISIM applications. It is easily
extensible, so support for additional files, card applications, etc. can be added easily by any python developer. We do
encourage you to submit your contributions to help this collaborative development project.
pySim consists of several parts:
• a python library containing plenty of objects and methods that can be used for writing custom programs inter-
facing with SIM cards.
• the [new] interactive pySim-shell command line program
• the [new] pySim-trace APDU trace decoder
• the [legacy] pySim-prog and pySim-read tools

1.1 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):

1
osmopysim-usermanual

• 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

1.1.1 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.

1.1.2 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] ...

2 Chapter 1. Introduction
 osmopysim-usermanual

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)

1.1. pySim-shell 3
osmopysim-usermanual

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)

1.1.3 Usage Examples

Guide: Enabling 5G SUCI
SUPI/SUCI Concealment is a feature of 5G-Standalone (SA) to encrypt the IMSI/SUPI with a network operator public
key. 3GPP Specifies two different variants for this:
• SUCI calculation in the UE, using key data from the SIM
• SUCI calculation on the card itself
pySim supports writing the 5G-specific files for SUCI calculation in the UE on USIM cards, assuming that your cards
contain the required files, and you have the privileges/credentials to write to them. This is the case using sysmocom
sysmoISIM-SJA2 or any flavor of sysmoISIM-SJA5.
There is no 3GPP/ETSI standard method for configuring SUCI calculation on the card; pySim currently supports the
vendor-specific method for the sysmoISIM-SJA5-S17).
This document describes both methods.

Technical References

This guide covers the basic workflow of provisioning SIM cards with the 5G SUCI feature. For detailed information
on the SUCI feature and file contents, the following documents are helpful:
• USIM files and structure: 3GPP TS 31.102
• USIM tests (incl. file content examples): 3GPP TS 31.121
• Test keys for SUCI calculation: 3GPP TS 33.501
For specific information on sysmocom SIM cards, refer to
• the sysmoISIM-SJA5 User Manual for the curent sysmoISIM-SJA5 product
• the sysmoISIM-SJA2 User Manual for the older sysmoISIM-SJA2 product

4 Chapter 1. Introduction
 osmopysim-usermanual

Enabling 5G SUCI calculated in the UE

In short, you can enable SUCI calculation in the UE with these steps:
• activate USIM Service 124
• make sure USIM Service 125 is disabled
• store the public keys in EF.SUCI_Calc_Info
• set the Routing Indicator (required)
If you want to disable the feature, you can just disable USIM Service 124 (and 125) in EF.UST.

Admin PIN

The usual way to authenticate yourself to the card as the cellular operator is to validate the so-called ADM1 (admin)
PIN. This may differ from card model/vendor to card model/vendor.
Start pySIM-shell and enter the admin PIN for your card. If you bought the SIM card from your network operator and
don’t have the admin PIN, you cannot change SIM contents!
Launch pySIM:

$ ./pySim-shell.py -p 0

Using PC/SC reader interface

Autodetected card type: sysmoISIM-SJA2
Welcome to pySim-shell!
pySIM-shell (00:MF)>

Enter the ADM PIN:

pySIM-shell (00:MF)> verify_adm XXXXXXXX

Otherwise, write commands will fail with SW Mismatch: Expected 9000 and got 6982.

Key Provisioning

pySIM-shell (00:MF)> select MF

pySIM-shell (00:MF)> select ADF.USIM
pySIM-shell (00:MF/ADF.USIM)> select DF.5GS
pySIM-shell (00:MF/ADF.USIM/DF.5GS)> select EF.SUCI_Calc_Info

By default, the file is present but empty:

pySIM-shell (00:MF/ADF.USIM/DF.5GS/EF.SUCI_Calc_Info)> read_binary_decoded

missing Protection Scheme Identifier List data object tag
9000:␣
˓→ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

˓→-> {}

The following JSON config defines the testfile from 3GPP TS 31.121, Section 4.9.4 with test keys from 3GPP TS
33.501, Annex C.4. Highest priority (0) has a Profile-B (identifier: 2) key in key slot 1, which means the key
with hnet_pubkey_identifier: 27.

1.1. pySim-shell 5
osmopysim-usermanual

{
"prot_scheme_id_list": [
{"priority": 0, "identifier": 2, "key_index": 1},
{"priority": 1, "identifier": 1, "key_index": 2},
{"priority": 2, "identifier": 0, "key_index": 0}],
"hnet_pubkey_list": [
{"hnet_pubkey_identifier": 27,
"hnet_pubkey":
˓→"0472DA71976234CE833A6907425867B82E074D44EF907DFB4B3E21C1C2256EBCD15A7DED52FCBB097A4ED250E036C7B9C8C70

˓→"},

{"hnet_pubkey_identifier": 30,
"hnet_pubkey": "5A8D38864820197C3394B92613B20B91633CBD897119273BF8E4A6F4EEC0A650
˓→"}]

Write the config to file (must be single-line input as for now):

pySIM-shell (00:MF/ADF.USIM/DF.5GS/EF.SUCI_Calc_Info)> update_binary_decoded '{ "prot_

˓→scheme_id_list": [ {"priority": 0, "identifier": 2, "key_index": 1}, {"priority": 1,

˓→"identifier": 1, "key_index": 2}, {"priority": 2, "identifier": 0, "key_index": 0}],

˓→"hnet_pubkey_list": [ {"hnet_pubkey_identifier": 27, "hnet_pubkey":

˓→"0472DA71976234CE833A6907425867B82E074D44EF907DFB4B3E21C1C2256EBCD15A7DED52FCBB097A4ED250E036C7B9C8C70

˓→"}, {"hnet_pubkey_identifier": 30, "hnet_pubkey":

˓→"5A8D38864820197C3394B92613B20B91633CBD897119273BF8E4A6F4EEC0A650"}]}'

WARNING: These are TEST KEYS with publicly known/specified private keys, and hence unsafe for live/secure de-
ployments! For use in production networks, you need to generate your own set[s] of keys.

Routing Indicator

The Routing Indicator must be present for the SUCI feature. By default, the contents of the file is invalid (ffffffff):

pySIM-shell (00:MF)> select MF

pySIM-shell (00:MF)> select ADF.USIM
pySIM-shell (00:MF/ADF.USIM)> select DF.5GS
pySIM-shell (00:MF/ADF.USIM/DF.5GS)> select EF.Routing_Indicator
pySIM-shell (00:MF/ADF.USIM/DF.5GS/EF.Routing_Indicator)> read_binary_decoded
9000: ffffffff -> {'raw': 'ffffffff'}

The Routing Indicator is a four-byte file but the actual Routing Indicator goes into bytes 0 and 1 (the other bytes are
reserved). To set the Routing Indicator to 0x71:

pySIM-shell (00:MF/ADF.USIM/DF.5GS/EF.Routing_Indicator)> update_binary 17ffffff

You can also set the routing indicator to 0x0, which is valid and means “routing indicator not specified”, leaving it to
the modem.

USIM Service Table

First, check out the USIM Service Table (UST):

pySIM-shell (00:MF)> select MF

pySIM-shell (00:MF)> select ADF.USIM
(continues on next page)

6 Chapter 1. Introduction
 osmopysim-usermanual

(continued from previous page)

pySIM-shell (00:MF/ADF.USIM)> select EF.UST
pySIM-shell (00:MF/ADF.USIM/EF.UST)> read_binary_decoded
9000: beff9f9de73e0408400170730000002e00000000 -> [2, 3, 4, 5, 6, 9, 10, 11, 12, 13, 14,␣
˓→15, 17, 18, 19, 20, 21, 25, 27, 28, 29, 33, 34, 35, 38, 39, 42, 43, 44, 45, 46, 51, 60,

˓→ 71, 73, 85, 86, 87, 89, 90, 93, 94, 95, 122, 123, 124, 126]

Table 1: From 3GPP TS 31.102

Service No. Description
122 5GS Mobility Management Information
123 5G Security Parameters
124 Subscription identifier privacy support
125 SUCI calculation by the USIM
126 UAC Access Identities support
129 5GS Operator PLMN List

If you’d like to enable/disable any UST service:

pySIM-shell (00:MF/ADF.USIM/EF.UST)> ust_service_deactivate 124

pySIM-shell (00:MF/ADF.USIM/EF.UST)> ust_service_activate 124
pySIM-shell (00:MF/ADF.USIM/EF.UST)> ust_service_deactivate 125

In this case, UST Service 124 is already enabled and you’re good to go. The sysmoISIM-SJA2 does not support on-SIM
calculation, so service 125 must be disabled.

USIM Error with 5G and sysmoISIM

sysmoISIM-SJA2 come 5GS-enabled. By default however, the configuration stored in the card file-system is not valid
for 5G networks: Service 124 is enabled, but EF.SUCI_Calc_Info and EF.Routing_Indicator are empty files (hence do
not contain valid data).
At least for Qualcomm’s X55 modem, this results in an USIM error and the whole modem shutting 5G down. If you
don’t need SUCI concealment but the smartphone refuses to connect to any 5G network, try to disable the UST service
124.
sysmoISIM-SJA5 are shipped with a more forgiving default, with valid EF.Routing_Indicator contents and disabled
Service 124

SUCI calculation by the USIM

The SUCI calculation can also be performed by the USIM application on the UICC directly. The UE then uses the
GET IDENTITY command (see also 3GPP TS 31.102, section 7.5) to retrieve a SUCI value.
The sysmoISIM-SJA5-S17 supports SUCI calculation by the USIM. The configuration is not much different to the
above described configuration of SUCI calculation in the UE.
The main difference is how the key provisioning is done. When the SUCI calculation is done by the USIM, then the
key material is not accessed by the UE. The specification (see also 3GPP TS 31.102, section 7.5.1.1), also does not
specify any file or file format to store the key material. This means the exact way to perform the key provisioning is an
implementation detail of the USIM card application.
In the case of sysmoISIM-SJA5-S17, the key material for SUCI calculation by the USIM is stored in
ADF.USIM/DF.SAIP/EF.SUCI_Calc_Info (not in ADF.USIM/DF.5GS/EF.SUCI_Calc_Info!).

1.1. pySim-shell 7
osmopysim-usermanual

pySIM-shell (00:MF)> select MF

pySIM-shell (00:MF)> select ADF.USIM
pySIM-shell (00:MF/ADF.USIM)> select DF.SAIP
pySIM-shell (00:MF/ADF.USIM/DF.SAIP)> select EF.SUCI_Calc_Info

The file format is exactly the same as specified in 3GPP TS 31.102, section 4.4.11.8. This means the above described
key provisioning procedure can be applied without any changes, except that the file location is different.
To signal to the UE that the USIM is setup up for SUCI calculation, service 125 must be enabled in addition to service
124 (see also 3GPP TS 31.102, section 5.3.48)

pySIM-shell (00:MF/ADF.USIM/EF.UST)> ust_service_activate 124

pySIM-shell (00:MF/ADF.USIM/EF.UST)> ust_service_activate 125

To verify that the SUCI calculation works as expected, it is possible to issue a GET IDENTITY command using pySim-
shell:

select ADF.USIM
get_identity

The USIM should then return a SUCI TLV Data object that looks like this:

SUCI TLV Data Object:␣

˓→0199f90717ff021b027a2c58ce1c6b89df088a9eb4d242596dd75746bb5f3503d2cf58a7461e4fd106e205c86f76544e9d7322

Guide: Installing JAVA-card applets

Almost all modern-day UICC cards have some form of JAVA-card / Sim-Toolkit support, which allows the installation
of customer specific JAVA-card applets. The installation of JAVA-card applets is usually done via the standardized
GlobalPlatform (GPC_SPE_034) ISD (Issuer Security Domain) application interface during the card provisioning pro-
cess. (it is also possible to load JAVA-card applets in field via OTA-SMS, but that is beyond the scope of this guide).
In this guide we will go through the individual steps that are required to load JAVA-card applet onto an UICC card.

Preparation

In this example we will install the CAP file HelloSTK_09122024.cap [1] on an sysmoISIM-SJA2 card. Since the
interface is standardized, the exact card model does not matter.
The example applet makes use of the STK (Sim-Toolkit), so we must supply STK installation parame-
ters. Those parameters are supplied in the form of a hexstring and should be provided by the applet man-
ufacturer. The available parameters and their exact encoding is specified in ETSI TS 102 226, section
8.2.1.3.2.1. The installation of HelloSTK_09122024.cap [1], will require the following STK installation parameters:
“010001001505000000000000000000000000”
During the installation, we also have to set a memory quota for the volatile and for the non volatile card memory. Those
values also should be provided by the applet manufacturer. In this example, we will allow 255 bytes of volatile memory
and 255 bytes of non volatile memory to be consumed by the applet.
To install JAVA-card applets, one must be in the possession of the key material belonging to the card. The keys are
usually provided by the card manufacturer. The following example will use the following keyset:

Keyname Keyvalue
DEK/KIK 5524F4BECFE96FB63FC29D6BAAC6058B
ENC/KIC 542C37A6043679F2F9F71116418B1CD5
MAC/KID 34F11BAC8E5390B57F4E601372339E3C

8 Chapter 1. Introduction
 osmopysim-usermanual

[1] https://osmocom.org/projects/cellular-infrastructure/wiki/HelloSTK

Applet Installation

To prepare the installation, a secure channel to the ISD must be established first:

pySIM-shell (00:MF)> select ADF.ISD

{
"application_id": "a000000003000000",
"proprietary_data": {
"maximum_length_of_data_field_in_command_message": 255
}
}
pySIM-shell (00:MF/ADF.ISD)> establish_scp02 --key-dek 5524F4BECFE96FB63FC29D6BAAC6058B -
˓→-key-enc 542C37A6043679F2F9F71116418B1CD5 --key-mac 34F11BAC8E5390B57F4E601372339E3C --

˓→security-level 1

Successfully established a SCP02[01] secure channel

Warning

In case you get an “EXCEPTION of type ‘ValueError’ occurred with message: card cryptogram doesn’t match”
error message, it is very likely that there is a problem with the key material. The card may lock the ISD access after
a certain amount of failed tries. Carefully check the key material any try again.

When the secure channel is established, we are ready to install the applet. The installation normally is a multi step
procedure, where the loading of an executable load file is announced first, then loaded and then installed in a final step.
The pySim-shell command install_cap automatically takes care of those three steps.

pySIM-shell (SCP02[01]:00:MF/ADF.ISD)> install_cap /home/user/HelloSTK_09122024.cap --

˓→install-parameters-non-volatile-memory-quota 255 --install-parameters-volatile-memory-

˓→quota 255 --install-parameters-stk 010001001505000000000000000000000000

loading cap file: /home/user/HelloSTK_09122024.cap ...

parameters:
security-domain-aid: a000000003000000
load-file: 569 bytes
load-file-aid: d07002ca44
module-aid: d07002ca44900101
application-aid: d07002ca44900101
install-parameters: c900ef1cc80200ffc70200ffca12010001001505000000000000000000000000
step #1: install for load...
step #2: load...
Loaded a total of 573 bytes in 3 blocks. Don't forget install_for_install (and make␣
˓→selectable) now!

step #3: install_for_install (and make selectable)...

done.

The applet is now installed on the card. We can now quit pySim-shell and remove the card from the reader and test the
applet in a mobile phone. There should be a new STK application with one menu entry shown, that will greet the user
when pressed.

1.1. pySim-shell 9
osmopysim-usermanual

Applet Removal

To remove the applet, we must establish a secure channel to the ISD (see above). Then we can delete the applet using
the delete_card_content command.

pySIM-shell (SCP02[01]:00:MF/ADF.ISD)> delete_card_content D07002CA44 --delete-related-

˓→objects

The parameter “D07002CA44” is the load-file-AID of the applet. The load-file-AID is encoded in the .cap file and
also displayed during the installation process. It is also important to note that when the applet is installed, it cannot be
installed (under the same AID) again until it is removed.

1.1.4 Advanced Topics

Retrieving card-individual keys via CardKeyProvider
When working with a batch of cards, or more than one card in general, it is a lot of effort to manually retrieve the
card-specific PIN (like ADM1) or key material (like SCP02/SCP03 keys).
To increase productivity in that regard, pySim has a concept called the CardKeyProvider. This is a generic mechanism
by which different parts of the pySim[-shell] code can programmatically request card-specific key material from some
data source (provider).
For example, when you want to verify the ADM1 PIN using the verify_adm command without providing an ADM1
value yourself, pySim-shell will request the ADM1 value for the ICCID of the card via the CardKeyProvider.
There can in theory be multiple different CardKeyProviders. You can for example develop your own CardKeyProvider
that queries some kind of database for the key material, or that uses a key derivation function to derive card-specific
key material from a global master key.
The only actual CardKeyProvider implementation included in pySim is the CardKeyProviderCsv which retrieves the
key material from a [potentially encrypted] CSV file.

The CardKeyProviderCsv

The CardKeyProviderCsv allows you to retrieve card-individual key material from a CSV (comma separated value) file
that is accessible to pySim.
The CSV file must have the expected column names, for example ICCID and ADM1 in case you would like to use that
CSV to obtain the card-specific ADM1 PIN when using the verify_adm command.
You can specify the CSV file to use via the –csv command-line option of pySim-shell. If you do not specify a CSV file,
pySim will attempt to open a CSV file from the default location at ~/.osmocom/pysim/card_data.csv, and use that, if it
exists.

Column-Level CSV encryption

pySim supports column-level CSV encryption. This feature will make sure that your key material is not stored in
plaintext in the CSV file.
The encryption mechanism uses AES in CBC mode. You can use any key length permitted by AES (128/192/256 bit).
Following GSMA FS.28, the encryption works on column level. This means different columns can be decrypted using
different key material. This means that leakage of a column encryption key for one column or set of columns (like a
specific security domain) does not compromise various other keys that might be stored in other columns.
You can specify column-level decryption keys using the –csv-column-key command line argument. The syntax is
FIELD:AES_KEY_HEX, for example:
pySim-shell.py –csv-column-key SCP03_ENC_ISDR:000102030405060708090a0b0c0d0e0f

10 Chapter 1. Introduction
 osmopysim-usermanual

In order to avoid having to repeat the column key for each and every column of a group of keys within a keyset, there
are pre-defined column group aliases, which will make sure that the specified key will be used by all columns of the
set:
• UICC_SCP02 is a group alias for UICC_SCP02_KIC1, UICC_SCP02_KID1, UICC_SCP02_KIK1
• UICC_SCP03 is a group alias for UICC_SCP03_KIC1, UICC_SCP03_KID1, UICC_SCP03_KIK1
• SCP03_ECASD is a group alias for SCP03_ENC_ECASD, SCP03_MAC_ECASD, SCP03_DEK_ECASD
• SCP03_ISDA is a group alias for SCP03_ENC_ISDA, SCP03_MAC_ISDA, SCP03_DEK_ISDA
• SCP03_ISDR is a group alias for SCP03_ENC_ISDR, SCP03_MAC_ISDR, SCP03_DEK_ISDR

Field naming

• For look-up of UICC/SIM/USIM/ISIM or eSIM profile specific key material, pySim uses the ICCID field as
lookup key.
• For look-up of eUICC specific key material (like SCP03 keys for the ISD-R, ECASD), pySim uses the EID field
as lookup key.
As soon as the CardKeyProviderCsv finds a line (row) in your CSV where the ICCID or EID match, it looks for the
column containing the requested data.

ADM PIN

The verify_adm command will attempt to look up the ADM1 column indexed by the ICCID of the SIM/UICC.

SCP02 / SCP03

SCP02 and SCP03 each use key triplets consisting if ENC, MAC and DEK keys. For more details, see the applicable
GlobalPlatform specifications.
If you do not want to manually enter the key material for each specific card as arguments to the establish_scp02 or
establish_scp03 commands, you can make use of the –key-provider-suffix option. pySim uses this suffix to compose
the column names for the CardKeyProvider as follows.
• SCP02_ENC_ + suffix for the SCP02 ciphering key
• SCP02_MAC_ + suffix for the SCP02 MAC key
• SCP02_DEK_ + suffix for the SCP02 DEK key
• SCP03_ENC_ + suffix for the SCP03 ciphering key
• SCP03_MAC_ + suffix for the SCP03 MAC key
• SCP03_DEK_ + suffix for the SCP03 DEK key
So for example, if you are using a command like establish_scp03 –key-provider-suffix ISDR, then the column names
for the key material look-up are SCP03_ENC_ISDR, SCP03_MAC_ISDR and SCP03_DEK_ISDR, respectively.
The identifier used for look-up is determined by the definition of the Security Domain. For example, the eUICC ISD-R
and ECASD will use the EID of the eUICC. On the other hand, the ISD-P of an eSIM or the ISD of an UICC will use
the ICCID.

1.1. pySim-shell 11
osmopysim-usermanual

Remote access to an UICC/eUICC

To access a card with pySim-shell, it is not strictly necessary to have physical access to it. There are solutions that
allow remote access to UICC/eUICC cards. In this section we will give a brief overview.

osmo-remsim

osmo-remsim is a suite of software programs enabling physical/geographic separation of a cellular phone (or modem)
on the one hand side and the UICC/eUICC card on the other side.
Using osmo-remsim, you can operate an entire fleet of modems/phones, as well as banks of SIM cards and dynamically
establish or remove the connections between modems/phones and cards.
To access remote cards with pySim-shell via osmo-remseim (RSPRO), the provided libifd_remsim_client would be
used to provide a virtual PC/SC reader on the local machine. pySim-shell can then access this reader like any other
PC/SC reader.
More information on osmo-remsim can be found under:
• https://osmocom.org/projects/osmo-remsim/wiki
• https://ftp.osmocom.org/docs/osmo-remsim/master/osmo-remsim-usermanual.pdf

Android APDU proxy

Android APDU proxy is an Android app that provides a bridge between a host computer and the UICC/eUICC slot of
an Android smartphone.
The APDU proxy connects to VPCD server that runs on the remote host (in this case the local machine where pySim-
shell is running). The VPCD server then provides a virtual PC/SC reader, that pySim-shell can access like any other
PC/SC reader.
On the Android side the UICC/eUICC is accessed via OMAPI (Open Mobile API), which is available in Android since
API level Android 8 (API level 29).
More information Android APDU proxy can be found under:
• https://gitea.osmocom.org/sim-card/android-apdu-proxy

1.1.5 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.

1.1.6 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

12 Chapter 1. Introduction
 osmopysim-usermanual

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 permis-
sion 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)>

1.1. pySim-shell 13
osmopysim-usermanual

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 permis-
sion 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
...

14 Chapter 1. Introduction
 osmopysim-usermanual

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):

1.1. pySim-shell 15
osmopysim-usermanual

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

16 Chapter 1. Introduction
 osmopysim-usermanual

--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]

[--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.

1.1. pySim-shell 17
osmopysim-usermanual

1.1.7 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:

18 Chapter 1. Introduction
 osmopysim-usermanual

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]

1.1. pySim-shell 19
osmopysim-usermanual

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]

20 Chapter 1. Introduction
 osmopysim-usermanual

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.

1.1. pySim-shell 21
osmopysim-usermanual

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

1.1.8 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

22 Chapter 1. Introduction
 osmopysim-usermanual

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

1.1. pySim-shell 23
osmopysim-usermanual

Additional interfaces support

--uicc-clf Local User Interface in the Device (LUId) supported

Default: False

Additional Terminal capability indications related to eUICC

--lui-d Local User Interface in the Device (LUId) supported

Default: False
--lpd-d Local Profile Download in the Device (LPDd) supported
Default: False
--lds-d Local Discovery Service in the Device (LPDd) supported
Default: False
--lui-e-scws LUIe based on SCWS supported
Default: False
--metadata-update-alerting Metadata update alerting supported
Default: False
--enterprise-capable-device Enterprise Capable Device
Default: False
--lui-e-e4e LUIe using E4E (ENVELOPE tag E4) supported
Default: False
--lpr LPR (LPA Proxy) supported
Default: False

1.1.9 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

24 Chapter 1. Introduction
 osmopysim-usermanual

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

1.1. pySim-shell 25
osmopysim-usermanual

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 up-
date_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.

26 Chapter 1. Introduction
 osmopysim-usermanual

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

1.1.10 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.

1.1. pySim-shell 27
osmopysim-usermanual

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.
(continues on next page)

28 Chapter 1. Introduction
 osmopysim-usermanual

(continued from previous page)

˓→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

1.1. pySim-shell 29
osmopysim-usermanual

1.1.11 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

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

1.1.12 USIM commands

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

30 Chapter 1. Introduction
 osmopysim-usermanual

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

1.1. pySim-shell 31
osmopysim-usermanual

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

1.1.13 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.

32 Chapter 1. Introduction
 osmopysim-usermanual

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.

1.1.14 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

1.1. pySim-shell 33
osmopysim-usermanual

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 after-
wards!
Default: False

34 Chapter 1. Introduction
 osmopysim-usermanual

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

Named 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

1.1. pySim-shell 35
osmopysim-usermanual

required arguments

--ef-arr-file-id Referenced Security: File Identifier of EF.ARR

--ef-arr-record-nr Referenced Security: Record Number within EF.ARR

Named 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

1.1.15 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

[
(continues on next page)

36 Chapter 1. Introduction
 osmopysim-usermanual

(continued from previous page)

{
"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]

1.1. pySim-shell 37
osmopysim-usermanual

Named Arguments

--device-app-id Identifies the specific device application that the rule appplies to. Hash of Certifi-
cate 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

aram_lock
This command allows to lock the access to the STORE DATA command. This renders all access rules stored within
the ARA-M applet effectively read-only. The lock can only be removed via a secure channel to the security domain
and is therefore suitable to prevent unauthorized changes to ARA-M rules.
Removal of the lock:

pySIM-shell (SCP02[01]:00:MF/ADF.ISD)> install_for_personalization A00000015141434C00

pySIM-shell (SCP02[01]:00:MF/ADF.ISD)> apdu --expect-sw 9000 80E2900001A2

NOTE: ARA-M Locking is a proprietary feature that is specific to sysmocom’s fork of Bertrand Martel’s ARA-M
implementation. ARA-M Locking is supported in newer (2025) applet versions from v0.1.0 onward.

38 Chapter 1. Introduction
 osmopysim-usermanual

1.1.16 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

--aid AID Search Qualifier (search only for given AID)

Default: “”

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

1.1. pySim-shell 39
osmopysim-usermanual

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 Card-
Specification 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

40 Chapter 1. Introduction
 osmopysim-usermanual

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

load

Perform a GlobalPlatform LOAD command. (We currently only support loading without DAP and without ciphering.)

usage: load [-h]

(--from-hex FROM_HEX | --from-file FROM_FILE | --from-cap-file FROM_CAP_FILE)

Named Arguments

--from-hex load from hex string

--from-file load from binary file
--from-cap-file load from JAVA-card CAP file

1.1. pySim-shell 41
osmopysim-usermanual

install_cap

Perform a .cap file installation using GlobalPlatform LOAD and INSTALL commands.

usage: install_cap [-h] [--install-parameters INSTALL_PARAMETERS]

[--install-parameters-volatile-memory-quota INSTALL_PARAMETERS_
˓→VOLATILE_MEMORY_QUOTA]

[--install-parameters-non-volatile-memory-quota INSTALL_PARAMETERS_
˓→NON_VOLATILE_MEMORY_QUOTA]

[--install-parameters-stk INSTALL_PARAMETERS_STK]
FILE

Positional Arguments

FILE JAVA-CARD CAP file to install

Named Arguments

--install-parameters install Parameters (GPC_SPE_034, section 11.5.2.3.7, table 11-49)

install_for_personalization

Perform GlobalPlatform INSTALL [for personalization] command in order to inform a Security Domain that the fol-
lowing 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]

42 Chapter 1. Introduction
 osmopysim-usermanual

Named Arguments

--load-file-aid Executable Load File AID

Default: “”
--module-aid Executable Module AID
Default: “”
--application-aid Application AID
--install-parameters Install Parameters (GPC_SPE_034, section 11.5.2.3.7, table 11-49)
Default: “”
--privilege Possible choices: security_domain, dap_verification, delegated_management,
card_lock, card_terminate, card_reset, cvm_management, man-
dated_dap_verification, trusted_path, authorized_management, to-
ken_management, global_delete, global_lock, global_registry, final_application,
global_service, receipt_generation, ciphered_load_file_data_block, contact-
less_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

install_for_load

Perform GlobalPlatform INSTALL [for load] command in order to prepare to load an application.

usage: install_for_load [-h] --load-file-aid LOAD_FILE_AID

[--security-domain-aid SECURITY_DOMAIN_AID]
[--load-file-hash LOAD_FILE_HASH]
[--load-parameters LOAD_PARAMETERS]
[--load-token LOAD_TOKEN]

Named Arguments

--load-file-aid AID of the loded file

--security-domain-aid AID of the Security Domain into which the file shalle be added
Default: “”
--load-file-hash Load File Data Block Hash (GPC_SPE_034, section C.2)
Default: “”
--load-parameters Load Parameters (GPC_SPE_034, section 11.5.2.3.7, table 11-49)
Default: “”

1.1. pySim-shell 43
osmopysim-usermanual

--load-token Load Token (GPC_SPE_034, section C.4.1)

Default: “”

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)

Default: 0
--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

44 Chapter 1. Introduction
 osmopysim-usermanual

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)

Default: 0
--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)

1.1.17 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

1.1. pySim-shell 45
osmopysim-usermanual

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

Perform a raw STORE DATA command as defined for the ES10x eUICC interface.

usage: es10x_store_data [-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

Perform an ES10a SetDefaultDpAddress function.

usage: set_default_dp_address [-h] DP_ADDRESS

Positional Arguments

DP_ADDRESS Default SM-DP+ address as UTF-8 string

46 Chapter 1. Introduction
 osmopysim-usermanual

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:

1.1. pySim-shell 47
osmopysim-usermanual

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":
˓→"801f312e322e3834302e313233343536372f6d79506c6174666f726d4c6162656c812568747470733a2f2f6d79636f6d70616

˓→"

}
}

48 Chapter 1. Introduction
 osmopysim-usermanual

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

Perform an ES10b RemoveNotificationFromList function.

usage: remove_notification_from_list [-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",
(continues on next page)

1.1. pySim-shell 49
osmopysim-usermanual

(continued from previous page)

"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

Perform an ES10c EnableProfile function.

usage: enable_profile [-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"
}

50 Chapter 1. Introduction
 osmopysim-usermanual

disable_profile

Perform an ES10c DisableProfile function.

usage: disable_profile [-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

Perform an ES10c DeleteProfile function.

usage: delete_profile [-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"
}

euicc_memory_reset

Perform an ES10c eUICCMemoryReset function. This will permanently delete the selected subset of profiles from the
eUICC.

usage: euicc_memory_reset [-h] [--delete-operational]

[--delete-test-field-installed]
[--reset-smdp-address]

1.1. pySim-shell 51
osmopysim-usermanual

Named Arguments

--delete-operational Delete all operational profiles

Default: False
--delete-test-field-installed Delete all test profiles, except pre-installed ones
Default: False
--reset-smdp-address Reset the SM-DP+ address
Default: False

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

Perform an ES10c SetNickname function.

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

52 Chapter 1. Introduction
 osmopysim-usermanual

1.1.18 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

1.2 pySim-trace
pySim-trace is a utility for high-level decode of APDU protocol traces such as those obtained with Osmocom SIMtrace2
or osmo-qcdiag.
pySim-trace leverages the existing knowledge of pySim-shell on anything related to SIM cards, including the struc-
ture/encoding of the various files on SIM/USIM/ISIM/HPSIM cards, and applies this to decoding protocol traces. This
means that it shows not only the name of the command (like READ BINARY), but actually understands what the
currently selected file is, and how to decode the contents of that file.
pySim-trace also understands the parameters passed to commands and how to decode them, for example of the AU-
THENTICATE command within the USIM/ISIM/HPSIM application.

1.2. pySim-trace 53
osmopysim-usermanual

1.2.1 Demo
To get an idea how pySim-trace usage looks like, you can watch the relevant part of the 11/2022 SIMtrace2 tutorial
whose recording is freely accessible.

1.2.2 Running pySim-trace

Running pySim-trace requires you to specify the source of the to-be-decoded APDUs. There are several supported
options, each with their own respective parameters (like a file name for PCAP decoding).
See the detailed command line reference below for details.
A typical execution of pySim-trace for doing live decodes of GSMTAP (SIM APDU) e.g. from SIMtrace2 or osmo-
qcdiag would look like this:

./pySim-trace.py gsmtap-udp

This binds to the default UDP port 4729 (GSMTAP) on localhost (127.0.0.1), and decodes any APDUs received there.

1.2.3 pySim-trace command line reference

1.2.4 Constraints
• In order to properly track the current location in the filesystem tree and other state, it is important that the trace
you’re decoding includes all of the communication with the SIM, ideally from the very start (power up).
• pySim-trace currently only supports ETSI UICC (USIM/ISIM/HPSIM) and doesn’t yet support legacy GSM
SIM. This is not a fundamental technical constraint, it’s just simply that nobody got around developing and
testing that part. Contributions are most welcome.

1.3 Legacy tools

legacy tools are the classic pySim-prog and pySim-read programs that existed long before pySim-shell.
These days, it is highly recommended to use pySim-shell instead of these legacy tools.

1.3.1 pySim-prog
pySim-prog was the first part of the pySim software suite. It started as a tool to write ICCID, IMSI, MSISDN and Ki
to very simplistic SIM cards, and was later extended to a variety of other cards. As the number of features supported
became no longer bearable to express with command-line arguments, pySim-shell was created.
Basic use cases can still use pySim-prog.

Program customizable SIMs

Two modes are possible:
• one where the user specifies every parameter manually:
This is the most common way to use pySim-prog. The user will specify all relevant parameters directly via the
commandline. A typical commandline would look like this:
pySim-prog.py -p <pcsc_reader> --ki <ki_value> --opc <opc_value> --mcc <mcc_value>
--mnc <mnc_value> --country <country_code> --imsi <imsi_value> --iccid <iccid_value>
--pin-adm <adm_pin>
Please note, that this already lengthy commandline still only contains the most common card parameters. For a
full list of all possible parameters, use the --help option of pySim-prog. It is also important to mention that

54 Chapter 1. Introduction
 osmopysim-usermanual

not all parameters are supported by all card types. In particular, very simple programmable SIM cards will only
support a very basic set of parameters, such as MCC, MNC, IMSI and KI values.
• one where the parameters are generated from a minimal set:
It is also possible to leave the generation of certain parameters to pySim-prog. This is in particular helpful when
a large number of cards should be initialized with randomly generated key material.
pySim-prog.py -p <pcsc_reader> --mcc <mcc_value> --mnc <mnc_value> --secret
<random_secret> --num <card_number> --pin-adm <adm_pin>
The parameter --secret specifies a random seed that is used to generate the card individual parameters. (IMSI).
The secret should contain enough randomness to avoid conflicts. It is also recommended to store the secret safely,
in case cards have to be re-generated or the current card batch has to be extended later. For security reasons, the
key material, which is also card individual, will not be derived from the random seed. Instead a new random
set of Ki and OPc will be generated during each programming cycle. This means fresh keys are generated, even
when the --num remains unchanged.
The parameter --num specifies a card individual number. This number will be manged into the random seed so
that it serves as an identifier for a particular set of randomly generated parameters.
In the example above the parameters --mcc, and --mnc are specified as well, since they identify the GSM
network where the cards should operate in, it is absolutely required to keep them static. pySim-prog will use
those parameters to generate a valid IMSI that thas the specified MCC/MNC at the beginning and a random tail.
Specifying the card type:
pySim-prog usually autodetects the card type. In case auto detection does not work, it is possible to specify the
parameter --type. The following card types are supported:
• Fairwaves-SIM
• fakemagicsim
• gialersim
• grcardsim
• magicsim
• OpenCells-SIM
• supersim
• sysmoISIM-SJA2
• sysmoISIM-SJA5
• sysmosim-gr1
• sysmoSIM-GR2
• sysmoUSIM-SJS1
• Wavemobile-SIM
Specifying the card reader:
It is most common to use pySim-prog together whith a PCSC reader. The PCSC reader number is specified via the
--pcsc-device or -p option. However, other reader types (such as serial readers and modems) are supported. Use
the --help option of pySim-prog for more information.

1.3. Legacy tools 55

osmopysim-usermanual

Card programming using CSV files

To simplify the card programming process, pySim-prog also allows to read the card parameters from a CSV file. When
a CSV file is used as input, the user does not have to craft an individual commandline for each card. Instead all card
related parameters are automatically drawn from the CSV file.
A CSV files may hold rows for multiple (hundreds or even thousands) of cards. pySim-prog is able to identify the
rows either by ICCID (recommended as ICCIDs are normally not changed) or IMSI.
The CSV file format is a flexible format with mandatory and optional columns, here the same rules as for the comman-
dline parameters apply. The column names match the command line options. The CSV file may also contain columns
that are unknown to pySim-prog, such as inventory numbers, nicknames or parameters that are unrelated to the card
programming process. pySim-prog will silently ignore all unknown columns.
A CSV file may contain the following columns:
• name
• iccid (typically used as key)
• mcc
• mnc
• imsi (may be used as key, but not recommended)
• smsp
• ki
• opc
• acc
• pin_adm, adm1 or pin_adm_hex (must be present)
• msisdn
• epdgid
• epdgSelection
• pcscf
• ims_hdomain
• impi
• impu
• opmode
• fplmn
Due to historical reasons, and to maintain the compatibility between multiple different CSV file formats, the ADM pin
may be stored in three different columns. Only one of the three columns must be available.
• adm1: This column contains the ADM pin in numeric ASCII digit format. This format is the most common.
• pin_adm: Same as adm1, only the column name is different
• pin_adm_hex: If the ADM pin consists of raw HEX digits, rather then of numerical ASCII digits, then the ADM
pin can also be provided as HEX string using this column.
The following example shows a typical minimal example

56 Chapter 1. Introduction
 osmopysim-usermanual

"imsi","iccid","acc","ki","opc","adm1"
"999700000053010","8988211000000530108","0001","51ACE8BD6313C230F0BFE1A458928DF0",
˓→"E5A00E8DE427E21B206526B5D1B902DF","65942330"

"999700000053011","8988211000000530116","0002","746AAFD7F13CFED3AE626B770E53E860",
˓→"38F7CE8322D2A7417E0BBD1D7B1190EC","13445792"

"999700123053012","8988211000000530124","0004","D0DA4B7B150026ADC966DC637B26429C",
˓→"144FD3AEAC208DFFF4E2140859BAE8EC","53540383"

"999700000053013","8988211000000530132","0008","52E59240ABAC6F53FF5778715C5CE70E",
˓→"D9C988550DC70B95F40342298EB84C5E","26151368"

"999700000053014","8988211000000530140","0010","3B4B83CB9C5F3A0B41EBD17E7D96F324",
˓→"D61DCC160E3B91F284979552CC5B4D9F","64088605"

"999700000053015","8988211000000530157","0020","D673DAB320D81039B025263610C2BBB3",
˓→"4BCE1458936B338067989A06E5327139","94108841"

"999700000053016","8988211000000530165","0040","89DE5ACB76E06D14B0F5D5CD3594E2B1",
˓→"411C4B8273FD7607E1885E59F0831906","55184287"

"999700000053017","8988211000000530173","0080","977852F7CEE83233F02E69E211626DE1",
˓→"2EC35D48DBF2A99C07D4361F19EF338F","70284674"

The following commandline will instruct pySim-prog to use the provided CSV file as parameter source and the ICCID
(read from the card before programming) as a key to identify the card. To use the IMSI as a key, the parameter
--read-imsi can be used instead of --read-iccid. However, this option is only recommended to be used in very
specific corner cases.
pySim-prog.py -p <pcsc_reader> --read-csv <path_to_csv_file> --source csv --read-iccid
It is also possible to pick a row from the CSV file by manually providing an ICCID (option --iccid) or an IMSI
(option --imsi) that is then used as a key to find the matching row in the CSV file.
pySim-prog.py -p <pcsc_reader> --read-csv <path_to_csv_file> --source csv --iccid
<iccid_value>

Writing CSV files

pySim-prog is also able to generate CSV files that contain a subset of the parameters it has generated or received from
some other source (commandline, CSV-File). The generated file will be header-less and contain the following columns:
• name
• iccid
• mcc
• mnc
• imsi
• smsp
• ki
• opc
A commandline that makes use of the CSV write feature would look like this:
pySim-prog.py -p <pcsc_reader> --read-csv <path_to_input_csv_file> --read-iccid --source
csv --write-csv <path_to_output_csv_file>

1.3. Legacy tools 57

osmopysim-usermanual

Batch programming
In case larger card batches need to be programmed, it is possible to use the --batch parameter to run pySim-prog in
batch mode.
The batch mode will prompt the user to insert a card. Once a card is detected in the reader, the programming is carried
out. The user may then remove the card again and the process starts over. This allows for a quick and efficient card
programming without permanent commandline interaction.

1.3.2 pySim-read
pySim-read allows to read some of the most important data items from a SIM card. This means it will only read some
files of the card, and will only read files accessible to a normal user (without any special authentication)
These days, it is recommended to use the export command of pySim-shell instead. It performs a much more
comprehensive export of all of the [standard] files that can be found on the card. To get a human-readable decode
instead of the raw hex export, you can use export --json.
Specifically, pySim-read will dump the following:
• MF
• EF.ICCID
• DF.GSM
• EF,IMSI
• EF.GID1
• EF.GID2
• EF.SMSP
• EF.SPN
• EF.PLMNsel
• EF.PLMNwAcT
• EF.OPLMNwAcT
• EF.HPLMNAcT
• EF.ACC
• EF.MSISDN
• EF.AD
• EF.SST
• ADF.USIM
• EF.EHPLMN
• EF.UST
• EF.ePDGId
• EF.ePDGSelection
• ADF.ISIM
• EF.PCSCF
• EF.DOMAIN

58 Chapter 1. Introduction
 osmopysim-usermanual

• EF.IMPI
• EF.IMPU
• EF.UICCIARI
• EF.IST

pySim-read usage

Legacy tool for reading some parts of a SIM card

usage: pySim-read.py [-h] [-d DEV] [-b BAUD] [--pcsc-shared]

[-p PCSC | --pcsc-regex REGEX] [--modem-device DEV]
[--modem-baud BAUD] [--osmocon PATH] [--apdu-trace]

Named Arguments

--apdu-trace Trace the command/response APDUs exchanged with the card

Default: False

Serial Reader

Use a simple/ultra-low-cost serial reader attached to a (physical or USB/virtual) RS232 port. This doesn’t work with
all RS232-attached smart card readers, only with the very primitive readers following the ancient Phoenix or Smart
Mouse design.
-d, --device Serial Device for SIM access
Default: “/dev/ttyUSB0”
-b, --baud Baud rate used for SIM access
Default: 9600

PC/SC Reader

Use a PC/SC card reader to talk to the SIM card. PC/SC is a standard API for how applications access smart card
readers, and is available on a variety of operating systems, such as Microsoft Windows, MacOS X and Linux. Most
vendors of smart card readers provide drivers that offer a PC/SC interface, if not even a generic USB CCID driver is
used. You can use a tool like pcsc_scan -r to obtain a list of readers available on your system.
--pcsc-shared Open PC/SC reaer in SHARED access (default: EXCLUSIVE)
Default: False
-p, --pcsc-device Number of PC/SC reader to use for SIM access
--pcsc-regex Regex matching PC/SC reader to use for SIM access

AT Command Modem Reader

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

1.3. Legacy tools 59

osmopysim-usermanual

--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)

1.4 pySim-smpp2sim
This is a program to emulate the entire communication path SMSC-CN-RAN-ME that is usually between an OTA
backend and the SIM card. This allows to play with SIM OTA technology without using a mobile network or even a
mobile phone.
An external application can act as SMPP ESME and must encode (and encrypt/sign) the OTA SMS and submit them
via SMPP to this program, just like it would submit it normally to a SMSC (SMS Service Centre). The program then
re-formats the SMPP-SUBMIT into a SMS DELIVER TPDU and passes it via an ENVELOPE APDU to the SIM card
that is locally inserted into a smart card reader.
The path from SIM to external OTA application works the opposite way.
The default SMPP system_id is test. Likewise, the default SMPP password is test

1.4.1 Running pySim-smpp2sim

The command accepts the same command line arguments for smart card interface device selection as pySim-shell, as
well as a few SMPP specific arguments:

usage: pySim-smpp2sim.py [-h] [-d DEV] [-b BAUD] [--pcsc-shared]

[-p PCSC | --pcsc-regex REGEX] [--modem-device DEV]
[--modem-baud BAUD] [--osmocon PATH] [--apdu-trace]
[--smpp-bind-port SMPP_BIND_PORT]
[--smpp-bind-ip SMPP_BIND_IP]
[--smpp-system-id SMPP_SYSTEM_ID]
[--smpp-password SMPP_PASSWORD]

Named Arguments
--apdu-trace Trace the command/response APDUs exchanged with the card
Default: False

Serial Reader
Use a simple/ultra-low-cost serial reader attached to a (physical or USB/virtual) RS232 port. This doesn’t work with
all RS232-attached smart card readers, only with the very primitive readers following the ancient Phoenix or Smart
Mouse design.
-d, --device Serial Device for SIM access
Default: “/dev/ttyUSB0”
-b, --baud Baud rate used for SIM access
Default: 9600

60 Chapter 1. Introduction
 osmopysim-usermanual

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)

SMPP Options
--smpp-bind-port TCP Port to bind the SMPP socket to
Default: 2775
--smpp-bind-ip IPv4/IPv6 address to bind the SMPP socket to
Default: “::”
--smpp-system-id SMPP System-ID used by ESME to bind
Default: “test”
--smpp-password SMPP Password used by ESME to bind
Default: “test”

1.4.2 Example execution with sample output

So for a simple system with a single PC/SC device, you would typically use something like ./pySim-smpp2sim.py -p0
to start the program. You will see output like this at start-up

Using reader PCSC[HID Global OMNIKEY 3x21 Smart Card Reader [OMNIKEY 3x21 Smart Card␣
˓→Reader] 00 00]

INFO root: Binding Virtual SMSC to TCP Port 2775 at ::

The application has hence bound to local TCP port 2775 and expects your SMS-sending applications to send their SMS
there. Once you do, you will see log output like below:

1.4. pySim-smpp2sim 61
osmopysim-usermanual

WARNING smpp.twisted.protocol: SMPP connection established from ::ffff:127.0.0.1 to␣

˓→port 2775

INFO smpp.twisted.server: Added CommandId.bind_transceiver bind for 'test'. Active␣

˓→binds: CommandId.bind_transceiver: 1, CommandId.bind_transmitter: 0, CommandId.bind_

˓→receiver: 0. Max binds: 2

INFO smpp.twisted.protocol: Bind request succeeded for test. 1 active binds

And once your external program is sending SMS to the simulated SMSC, it will log something like

INFO root: SMS_DELIVER(MTI=0, MMS=False, LP=False, RP=False, UDHI=True, SRI=False,␣

˓→OA=AddressField(TON=international, NPI=unknown, 12), PID=7f, DCS=f6, SCTS=bytearray(b'

˓→"pR\x00\x00\x00\x00'), UDL=45, UD=b"\x02p\x00\x00(\x15\x16\x19\x12\x12\xb0\x00\x01'\

˓→xfa(\xa5\xba\xc6\x9d<^\x9d\xf2\xc7\x15]\xfd\xdeD\x9c\x82k#b\x15Ve0x{0\xe8\xbe]")

SMSPPDownload(DeviceIdentities({'source_dev_id': 'network', 'dest_dev_id': 'uicc'}),

˓→Address({'ton_npi': 0, 'call_number': '0123456'}),SMS_TPDU({'tpdu':

˓→'400290217ff6227052000000002d02700000281516191212b0000127fa28a5bac69d3c5e9df2c7155dfdde449c826b2362155

˓→'}))

INFO root: ENVELOPE:␣

˓→d147820283818604001032548b3b400290217ff6227052000000002d02700000281516191212b0000127fa28a5bac69d3c5e9d

INFO root: SW 9000:␣

˓→027100002412b000019a551bb7c28183652de0ace6170d0e563c5e949a3ba56747fe4c1dbbef16642c

1.5 pySim library

1.5.1 pySim filesystem abstraction
Representation of the ISO7816-4 filesystem model.
The File (and its derived classes) represent the structure / hierarchy of the ISO7816-4 smart card file system with the
MF, DF, EF and ADF entries, further sub-divided into the EF sub-types Transparent, Linear Fixed, etc.
The classes are intended to represent the specification of the filesystem, not the actual contents / runtime state of
interacting with a given smart card.
class pySim.filesystem.BerTlvEF(fid: str, sfid: str = None, name: str = None, desc: str = None, parent:
CardDF = None, size: Tuple[int, int | None] = (1, None), **kwargs)
BER-TLV EF (Entry File) in the smart card filesystem. A BER-TLV EF is a binary file with a BER (Basic
Encoding Rules) TLV structure
NOTE: We currently don’t really support those, this class is simply a wrapper around TransparentEF as a place-
holder, so we can already define EFs of BER-TLV type without fully supporting them.
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)
• name – Brief name of the file, lik EF_ICCID
• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• size – tuple of (minimum_size, recommended_size)
class ShellCommands
Shell commands specific for BER-TLV EFs.

62 Chapter 1. Introduction
 osmopysim-usermanual

do_delete_all(opts)
Delete all data from a BER-TLV EF
do_delete_data(opts)
Delete data for a given tag in a BER-TLV EF
do_retrieve_data(opts)
Retrieve (Read) data from a BER-TLV EF
do_retrieve_tags(_opts)
List tags available in a given BER-TLV EF
do_set_data(opts)
Set (Write) data for a given tag in a BER-TLV EF
static export(as_json: bool, lchan)
Export the file contents of a BerTlvEF. This method returns a shell command string (See also ShellCom-
mand definition in this class) that can be used to write the file contents back.
class pySim.filesystem.CardADF(aid: str, has_fs: bool = False, **kwargs)
ADF (Application Dedicated File) in the smart card filesystem
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)
• name – Brief name of the file, like EF_ICCID
• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• profile – Card profile that this file should be part of
• service – Service (SST/UST/IST) associated with the file
static export(as_json: bool, lchan)
Export application specific parameters that are not part of the UICC filesystem.
class pySim.filesystem.CardApplication(name, adf: CardADF | None = None, aid: str = None, sw: dict =
None)
A card application is represented by an ADF (with contained hierarchy) and optionally some SW definitions.
Parameters
• adf – ADF name
• sw – Dict of status word conversions
static export(as_json: bool, lchan)
Export application specific parameters, in the form of commandline script. (see also comment in the export
method of class “CardFile”)
interpret_sw(sw)
Interpret a given status word within the application.
Parameters
sw – Status word as string of 4 hex digits
Returns
Tuple of two strings

1.5. pySim library 63

osmopysim-usermanual

class pySim.filesystem.CardDF(**kwargs)
DF (Dedicated File) in the smart card filesystem. Those are basically sub-directories.
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)
• name – Brief name of the file, like EF_ICCID
• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• profile – Card profile that this file should be part of
• service – Service (SST/UST/IST) associated with the file
class ShellCommands

add_file(child: CardFile, ignore_existing: bool = False)

Add a child (DF/EF) to this DF. :param child: The new DF/EF to be added :param ignore_existing: Ignore,
if file with given FID already exists. Old one will be kept.
add_files(children: Iterable[CardFile], ignore_existing: bool = False)
Add a list of child (DF/EF) to this DF
Parameters
• children – List of new DF/EFs to be added
• ignore_existing – Ignore, if file[s] with given FID already exists. Old one[s] will be
kept.
get_selectables(flags=[]) → dict
Return a dict of {‘identifier’: File} that is selectable from the current DF.
Parameters
flags – Specify which selectables to return ‘FIDS’ and/or ‘NAMES’; If not specified, all
selectables will be returned.
Returns
dict containing all selectable items. Key is identifier (string), value a reference to a CardFile
(or derived class) instance.
lookup_file_by_fid(fid: str) → CardFile | None
Find a file with given file ID within current DF.
lookup_file_by_name(name: str | None) → CardFile | None
Find a file with given name within current DF.
lookup_file_by_sfid(sfid: str | None) → CardFile | None
Find a file with given short file ID within current DF.
class pySim.filesystem.CardEF(* (Keyword-only parameters separator (PEP 3102)), fid, **kwargs)
EF (Entry File) in the smart card filesystem
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)

64 Chapter 1. Introduction
 osmopysim-usermanual

• name – Brief name of the file, like EF_ICCID

• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• profile – Card profile that this file should be part of
• service – Service (SST/UST/IST) associated with the file
get_selectables(flags=[]) → dict
Return a dict of {‘identifier’: File} that is selectable from the current DF.
Parameters
flags – Specify which selectables to return ‘FIDS’ and/or ‘NAMES’; If not specified, all
selectables will be returned.
Returns
dict containing all selectable items. Key is identifier (string), value a reference to a CardFile
(or derived class) instance.
class pySim.filesystem.CardFile(fid: str = None, sfid: str = None, name: str = None, desc: str = None,
parent: CardDF | None = None, profile: CardProfile | None = None,
service: int | List[int] | Tuple[int, ...] | None = None)
Base class for all objects in the smart card filesystem. Serve as a common ancestor to all other file types; rarely
used directly.
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)
• name – Brief name of the file, like EF_ICCID
• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• profile – Card profile that this file should be part of
• service – Service (SST/UST/IST) associated with the file
build_select_path_to(target: CardFile) → List[CardFile] | None
Build the relative sequence of files we need to traverse to get from us to ‘target’.
decode_select_response(data_hex: str)
Decode the response to a SELECT command.
Parameters
data_hex – Hex string of the select response
static export(as_json: bool, lchan)
Export file contents in the form of commandline script. This method is meant to be overloaded by a sub-
class in case any exportable contents are present. The generated script may contain multiple command
lines separated by line breaks (”n”), where the last commandline shall have no line break at the end (e.g.
“update_record 1 112233nupdate_record 1 445566”). Naturally this export method will always refer to the
currently selected file of the presented lchan.
fully_qualified_path(prefer_name: bool = True) → List[str]
Return fully qualified path to file as list of FID or name strings.
Parameters
prefer_name – Preferably build path of names; fall-back to FIDs as required

1.5. pySim library 65

osmopysim-usermanual

fully_qualified_path_fobj() → List[CardFile]
Return fully qualified path to file as list of CardFile instance references.
fully_qualified_path_str(prefer_name: bool = True) → str
Return fully qualified path to file as string.
Parameters
prefer_name – Preferably build path of names; fall-back to FIDs as required
get_mf() → CardMF | None
Return the MF (root) of the file system.
get_profile()
Get the profile associated with this file. If this file does not have any profile assigned, try to find a file above
(usually the MF) in the filesystem hirarchy that has a profile assigned
get_selectable_names(flags=[]) → List[str]
Return a dict of {‘identifier’: File} that is selectable from the current file.
Parameters
flags – Specify which selectables to return ‘FIDS’ and/or ‘NAMES’; If not specified, all
selectables will be returned.
Returns
list containing all selectable names.
get_selectables(flags=[]) → Dict[str, CardFile]
Return a dict of {‘identifier’: File} that is selectable from the current file.
Parameters
flags – Specify which selectables to return ‘FIDS’ and/or ‘NAMES’; If not specified, all
selectables will be returned.
Returns
dict containing all selectable items. Key is identifier (string), value a reference to a CardFile
(or derived class) instance.
should_exist_for_services(services: List[int])
Assuming the provided list of activated services, should this file exist and be activated?.
class pySim.filesystem.CardMF(**kwargs)
MF (Master File) in the smart card filesystem
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)
• name – Brief name of the file, like EF_ICCID
• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• profile – Card profile that this file should be part of
• service – Service (SST/UST/IST) associated with the file
add_application_df(app: CardADF)
Add an Application to the MF

66 Chapter 1. Introduction
 osmopysim-usermanual

decode_select_response(data_hex: str | None) → object

Decode the response to a SELECT command.
This is the fall-back method which automatically defers to the standard decoding method defined by the
card profile. When no profile is set, then no decoding is performed. Specific derived classes (usually ADF)
can overload this method to install specific decoding.
get_app_names()
Get list of completions (AID names)
get_app_selectables(flags=[]) → dict
Get applications by AID + name
get_selectables(flags=[]) → dict
Return a dict of {‘identifier’: File} that is selectable from the current DF.
Parameters
flags – Specify which selectables to return ‘FIDS’ and/or ‘NAMES’; If not specified, all
selectables will be returned.
Returns
dict containing all selectable items. Key is identifier (string), value a reference to a CardFile
(or derived class) instance.
class pySim.filesystem.CardModel
A specific card model, typically having some additional vendor-specific files. All you need to do is to define a
sub-class with a list of ATRs or an overridden match method.
abstractmethod classmethod add_files(rs: RuntimeState)
Add model specific files to given RuntimeState.
static apply_matching_models(scc: SimCardCommands, rs: RuntimeState)
Check if any of the CardModel sub-classes ‘match’ the currently inserted card (by ATR or overriding the
‘match’ method). If so, call their ‘add_files’ method.
classmethod match(scc: SimCardCommands) → bool
Test if given card matches this model.
class pySim.filesystem.CyclicEF(fid: str, sfid: str = None, name: str = None, desc: str = None, parent:
CardDF = None, rec_len: Tuple[int, int | None] = (1, None), **kwargs)
Cyclic EF (Entry File) in the smart card filesystem
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)
• name – Brief name of the file, lik EF_ICCID
• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• rec_len – Tuple of (minimum_length, recommended_length)
• leftpad – On write, data must be padded from the left to fit pysical record length
class pySim.filesystem.LinFixedEF(fid: str, sfid: str = None, name: str = None, desc: str = None, parent:
CardDF | None = None, rec_len: Tuple[int, int | None] = (1, None),
leftpad: bool = False, **kwargs)

1.5. pySim library 67

osmopysim-usermanual

Linear Fixed EF (Entry File) in the smart card filesystem.

Linear Fixed EFs are record oriented files. They consist of a number of fixed-size records. The records can be
individually read/updated.
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)
• name – Brief name of the file, lik EF_ICCID
• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• rec_len – Tuple of (minimum_length, recommended_length)
• leftpad – On write, data must be padded from the left to fit pysical record length
class ShellCommands
Shell commands specific for Linear Fixed EFs.
do_decode_hex(opts)
Decode command-line provided hex-string as if it was read from the file.
do_edit_record_decoded(opts)
Edit the JSON representation of one record in an editor.
do_read_record(opts)
Read one or multiple records from a record-oriented EF
do_read_record_decoded(opts)
Read + decode a record from a record-oriented EF
do_read_records(_opts)
Read all records from a record-oriented EF
do_read_records_decoded(opts)
Read + decode all records from a record-oriented EF
do_update_record(opts)
Update (write) data to a record-oriented EF
do_update_record_decoded(opts)
Encode + Update (write) data to a record-oriented EF
decode_record_bin(raw_bin_data: bytearray, record_nr: int) → dict
Decode raw (binary) data into abstract representation.
A derived class would typically provide a _decode_record_bin() or _decode_record_hex() method for im-
plementing this specifically for the given file. This function checks which of the method exists, add calls
them (with conversion, as needed).
Parameters
• raw_bin_data – binary encoded data
• record_nr – record number (1 for first record, . . . )
Returns
abstract_data; dict representing the decoded data

68 Chapter 1. Introduction
 osmopysim-usermanual

decode_record_hex(raw_hex_data: str, record_nr: int = 1) → dict

Decode raw (hex string) data into abstract representation.
A derived class would typically provide a _decode_record_bin() or _decode_record_hex() method for im-
plementing this specifically for the given file. This function checks which of the method exists, add calls
them (with conversion, as needed).
Parameters
• raw_hex_data – hex-encoded data
• record_nr – record number (1 for first record, . . . )
Returns
abstract_data; dict representing the decoded data
encode_record_bin(abstract_data: dict, record_nr: int, total_len: int | None = None) → bytearray
Encode abstract representation into raw (binary) data.
A derived class would typically provide an _encode_record_bin() or _encode_record_hex() method for
implementing this specifically for the given file. This function checks which of the method exists, add calls
them (with conversion, as needed).
Parameters
• abstract_data – dict representing the decoded data
• record_nr – record number (1 for first record, . . . )
• total_len – expected total length of the encoded data (record length)
Returns
binary encoded data
encode_record_hex(abstract_data: dict, record_nr: int, total_len: int | None = None) → str
Encode abstract representation into raw (hex string) data.
A derived class would typically provide an _encode_record_bin() or _encode_record_hex() method for
implementing this specifically for the given file. This function checks which of the method exists, add calls
them (with conversion, as needed).
Parameters
• abstract_data – dict representing the decoded data
• record_nr – record number (1 for first record, . . . )
• total_len – expected total length of the encoded data (record length)
Returns
hex string encoded data
static export(as_json: bool, lchan)
Export the file contents of a LinFixedEF (or a CyclicEF). This method returns a shell command string (See
also ShellCommand definition in this class) that can be used to write the file contents back.
class pySim.filesystem.Path(p: str | List[str] | List[int])
Representation of a file-system path.
is_parent(other: Path) → bool
Is this instance a parent of the given other instance?

1.5. pySim library 69

osmopysim-usermanual

relative_to_mf() → Path
Return a path relative to MF, i.e. without initial explicit MF.
class pySim.filesystem.TransRecEF(fid: str, rec_len: int, sfid: str = None, name: str = None, desc: str =
None, parent: CardDF | None = None, size: Tuple[int, int | None] = (1,
None), **kwargs)
Transparent EF (Entry File) containing fixed-size records.
These are the real odd-balls and mostly look like mistakes in the specification: Specified as ‘transparent’ EF, but
actually containing several fixed-length records inside. We add a special class for those, so the user only has to
provide encoder/decoder functions for a record, while this class takes care of split / merge of records.
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)
• name – Brief name of the file, like EF_ICCID
• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• rec_len – Length of the fixed-length records within transparent EF
• size – tuple of (minimum_size, recommended_size)
decode_record_bin(raw_bin_data: bytearray) → dict
Decode raw (binary) data into abstract representation.
A derived class would typically provide a _decode_record_bin() or _decode_record_hex() method for im-
plementing this specifically for the given file. This function checks which of the method exists, add calls
them (with conversion, as needed).
Parameters
raw_bin_data – binary encoded data
Returns
abstract_data; dict representing the decoded data
decode_record_hex(raw_hex_data: str) → dict
Decode raw (hex string) data into abstract representation.
A derived class would typically provide a _decode_record_bin() or _decode_record_hex() method for im-
plementing this specifically for the given file. This function checks which of the method exists, add calls
them (with conversion, as needed).
Parameters
raw_hex_data – hex-encoded data
Returns
abstract_data; dict representing the decoded data
encode_record_bin(abstract_data: dict, total_len: int | None = None) → bytearray
Encode abstract representation into raw (binary) data.
A derived class would typically provide an _encode_record_bin() or _encode_record_hex() method for
implementing this specifically for the given file. This function checks which of the method exists, add calls
them (with conversion, as needed).
Parameters
• abstract_data – dict representing the decoded data

70 Chapter 1. Introduction
 osmopysim-usermanual

• total_len – expected total length of the encoded data (record length)

Returns
binary encoded data
encode_record_hex(abstract_data: dict, total_len: int | None = None) → str
Encode abstract representation into raw (hex string) data.
A derived class would typically provide an _encode_record_bin() or _encode_record_hex() method for
implementing this specifically for the given file. This function checks which of the method exists, add calls
them (with conversion, as needed).
Parameters
• abstract_data – dict representing the decoded data
• total_len – expected total length of the encoded data (record length)
Returns
hex string encoded data
class pySim.filesystem.TransparentEF(fid: str, sfid: str = None, name: str = None, desc: str = None,
parent: CardDF = None, size: Tuple[int, int | None] = (1, None),
**kwargs)
Transparent EF (Entry File) in the smart card filesystem.
A Transparent EF is a binary file with no formal structure. This is contrary to Record based EFs which have
[fixed size] records that can be individually read/updated.
Parameters
• fid – File Identifier (4 hex digits)
• sfid – Short File Identifier (2 hex digits, optional)
• name – Brief name of the file, lik EF_ICCID
• desc – Description of the file
• parent – Parent CardFile object within filesystem hierarchy
• size – tuple of (minimum_size, recommended_size)
class ShellCommands
Shell commands specific for transparent EFs.
do_decode_hex(opts)
Decode command-line provided hex-string as if it was read from the file.
do_edit_binary_decoded(_opts)
Edit the JSON representation of the EF contents in an editor.
do_read_binary(opts)
Read binary data from a transparent EF
do_read_binary_decoded(opts)
Read + decode data from a transparent EF
do_update_binary(opts)
Update (Write) data of a transparent EF
do_update_binary_decoded(opts)
Encode + Update (Write) data of a transparent EF

1.5. pySim library 71

osmopysim-usermanual

decode_bin(raw_bin_data: bytearray) → dict

Decode raw (binary) data into abstract representation.
A derived class would typically provide a _decode_bin() or _decode_hex() method for implementing this
specifically for the given file. This function checks which of the method exists, add calls them (with con-
version, as needed).
Parameters
raw_bin_data – binary encoded data
Returns
abstract_data; dict representing the decoded data
decode_hex(raw_hex_data: str) → dict
Decode raw (hex string) data into abstract representation.
A derived class would typically provide a _decode_bin() or _decode_hex() method for implementing this
specifically for the given file. This function checks which of the method exists, add calls them (with con-
version, as needed).
Parameters
raw_hex_data – hex-encoded data
Returns
abstract_data; dict representing the decoded data
encode_bin(abstract_data: dict, total_len: int | None = None) → bytearray
Encode abstract representation into raw (binary) data.
A derived class would typically provide an _encode_bin() or _encode_hex() method for implementing this
specifically for the given file. This function checks which of the method exists, add calls them (with con-
version, as needed).
Parameters
• abstract_data – dict representing the decoded data
• total_len – expected total length of the encoded data (file size)
Returns
binary encoded data
encode_hex(abstract_data: dict, total_len: int | None = None) → str
Encode abstract representation into raw (hex string) data.
A derived class would typically provide an _encode_bin() or _encode_hex() method for implementing this
specifically for the given file. This function checks which of the method exists, add calls them (with con-
version, as needed).
Parameters
• abstract_data – dict representing the decoded data
• total_len – expected total length of the encoded data (file size)
Returns
hex string encoded data
static export(as_json: bool, lchan)
Export the file contents of a TransparentEF. This method returns a shell command string (See also Shell-
Command definition in this class) that can be used to write the file contents back.

72 Chapter 1. Introduction
 osmopysim-usermanual

pySim.filesystem.interpret_sw(sw_data: dict, sw: str)

Interpret a given status word.
Parameters
• sw_data – Hierarchical dict of status word matches
• sw – status word to match (string of 4 hex digits)
Returns
tuple of two strings (class_string, description)

1.5.2 pySim commands abstraction

pySim: SIM Card commands according to ISO 7816-4 and TS 11.11
class pySim.commands.SimCardCommands(transport: LinkBase, lchan_nr: int = 0)
Class providing methods for various card-specific commands such as SELECT, READ BINARY, etc. Historically
one instance exists below CardBase, but with the introduction of multiple logical channels there can be multiple
instances. The lchan number will then be patched into the CLA byte by the respective instance.
activate_file(fid: Hexstr) → Tuple[Hexstr, SwHexstr]
Execute ACTIVATE FILE command as per TS 102 221 Section 11.1.15.
Parameters
fid – file identifier as hex string
authenticate(rand: Hexstr, autn: Hexstr, context: str = '3g') → Tuple[Hexstr, SwHexstr]
Execute AUTHENTICATE (USIM/ISIM).
Parameters
• rand – 16 byte random data as hex string (RAND)
• autn – 8 byte Autentication Token (AUTN)
• context – 16 byte random data (‘3g’ or ‘gsm’)
binary_size(ef: Hexstr | List[Hexstr]) → int
Determine the size of given transparent file.
Parameters
ef – string or list of strings indicating name or path of transparent EF
change_chv(chv_no: int, pin_code: Hexstr, new_pin_code: Hexstr) → Tuple[Hexstr, SwHexstr]
Change a given CHV (Card Holder Verification == PIN)
Parameters
• chv_no – chv number (1=CHV1, 2=CHV2, . . . )
• pin_code – current chv code as hex string
• new_pin_code – new chv code as hex string
create_file(payload: Hexstr) → Tuple[Hexstr, SwHexstr]
Execute CREATE FILE command as per TS 102 222 Section 6.3
deactivate_file() → Tuple[Hexstr, SwHexstr]
Execute DECATIVATE FILE command as per TS 102 221 Section 11.1.14.

1.5. pySim library 73

osmopysim-usermanual

delete_file(fid: Hexstr) → Tuple[Hexstr, SwHexstr]

Execute DELETE FILE command as per TS 102 222 Section 6.4
disable_chv(chv_no: int, pin_code: Hexstr) → Tuple[Hexstr, SwHexstr]
Disable a given CHV (Card Holder Verification == PIN)
Parameters
• chv_no – chv number (1=CHV1, 2=CHV2, . . . )
• pin_code – current chv code as hex string
• new_pin_code – new chv code as hex string
enable_chv(chv_no: int, pin_code: Hexstr) → Tuple[Hexstr, SwHexstr]
Enable a given CHV (Card Holder Verification == PIN)
Parameters
• chv_no – chv number (1=CHV1, 2=CHV2, . . . )
• pin_code – chv code as hex string
envelope(payload: Hexstr) → Tuple[Hexstr, SwHexstr]
Send one ENVELOPE command to the SIM
Parameters
payload – payload as hex string
fork_lchan(lchan_nr: int) → SimCardCommands
Fork a per-lchan specific SimCardCommands instance off the current instance.
get_atr() → Hexstr
Return the ATR of the currently inserted card.
manage_channel(mode: str = 'open', lchan_nr: int = 0) → Tuple[Hexstr, SwHexstr]
Execute MANAGE CHANNEL command as per TS 102 221 Section 11.1.17.
Parameters
• mode – logical channel operation code (‘open’ or ‘close’)
• lchan_nr – logical channel number (1-19, 0=assigned by UICC)
property max_cmd_len: int
Maximum length of the command apdu data section. Depends on secure channel protocol used.
read_binary(ef: Hexstr | List[Hexstr], length: int = None, offset: int = 0) → Tuple[Hexstr, SwHexstr]
Execute READD BINARY.
Parameters
• ef – string or list of strings indicating name or path of transparent EF
• length – number of bytes to read
• offset – byte offset in file from which to start reading
read_record(ef: Hexstr | List[Hexstr], rec_no: int) → Tuple[Hexstr, SwHexstr]
Execute READ RECORD.
Parameters
• ef – string or list of strings indicating name or path of linear fixed EF

74 Chapter 1. Introduction
 osmopysim-usermanual

• rec_no – record number to read

record_count(ef: Hexstr | List[Hexstr]) → int
Determine the number of records in given file.
Parameters
ef – string or list of strings indicating name or path of linear fixed EF
record_size(ef: Hexstr | List[Hexstr]) → int
Determine the record size of given file.
Parameters
ef – string or list of strings indicating name or path of linear fixed EF
reset_card() → Hexstr
Physically reset the card
resize_file(payload: Hexstr) → Tuple[Hexstr, SwHexstr]
Execute RESIZE FILE command as per TS 102 222 Section 6.10
resume_uicc(token: Hexstr) → Tuple[Hexstr, SwHexstr]
Send SUSPEND UICC (resume) to the card.
retrieve_data(ef: Hexstr | List[Hexstr], tag: int) → Tuple[Hexstr, SwHexstr]
Execute RETRIEVE DATA, see also TS 102 221 Section 11.3.1.
Args
ef : string or list of strings indicating name or path of transparent EF tag : BER-TLV Tag of value to
be retrieved
run_gsm(rand: Hexstr) → Tuple[Hexstr, SwHexstr]
Execute RUN GSM ALGORITHM.
Parameters
rand – 16 byte random data as hex string (RAND)
select_adf(aid: Hexstr) → Tuple[Hexstr, SwHexstr]
Execute SELECT a given Applicaiton ADF.
Parameters
aid – application identifier as hex string
select_file(fid: Hexstr) → Tuple[Hexstr, SwHexstr]
Execute SELECT a given file by FID.
Parameters
fid – file identifier as hex string
select_parent_df() → Tuple[Hexstr, SwHexstr]
Execute SELECT to switch to the parent DF
select_path(dir_list: Hexstr | List[Hexstr]) → List[Hexstr]
Execute SELECT for an entire list/path of FIDs.
Parameters
dir_list – list of FIDs representing the path to select
Returns
list of return values (FCP in hex encoding) for each element of the path

1.5. pySim library 75

osmopysim-usermanual

send_apdu(pdu: Hexstr, apply_lchan: bool = True) → Tuple[Hexstr, SwHexstr]

Sends an APDU and auto fetch response data
Parameters
• pdu – string of hexadecimal characters (ex. “A0A40000023F00”)
• apply_lchan – apply the currently selected lchan to the CLA byte before sending
Returns
tuple(data, sw), where
data : string (in hex) of returned data (ex. “074F4EFFFF”) sw : string (in hex) of status
word (ex. “9000”)
send_apdu_checksw(pdu: Hexstr, sw: SwMatchstr = '9000', apply_lchan: bool = True) → Tuple[Hexstr,
SwHexstr]
Sends an APDU and check returned SW
Parameters
• pdu – string of hexadecimal characters (ex. “A0A40000023F00”)
• sw – string of 4 hexadecimal characters (ex. “9000”). The user may mask out certain digits
using a ‘?’ to add some ambiguity if needed.
• apply_lchan – apply the currently selected lchan to the CLA byte before sending
Returns
tuple(data, sw), where
data : string (in hex) of returned data (ex. “074F4EFFFF”) sw : string (in hex) of status
word (ex. “9000”)
send_apdu_constr(cla: Hexstr, ins: Hexstr, p1: Hexstr, p2: Hexstr, cmd_constr: Construct, cmd_data:
Hexstr, resp_constr: Construct, apply_lchan: bool = True) → Tuple[dict, SwHexstr]
Build and sends an APDU using a ‘construct’ definition; parses response.
Parameters
• cla – string (in hex) ISO 7816 class byte
• ins – string (in hex) ISO 7816 instruction byte
• p1 – string (in hex) ISO 7116 Parameter 1 byte
• p2 – string (in hex) ISO 7116 Parameter 2 byte
• cmd_cosntr – defining how to generate binary APDU command data
• cmd_data – command data passed to cmd_constr
• resp_cosntr – defining how to decode binary APDU response data
• apply_lchan – apply the currently selected lchan to the CLA byte before sending
Returns
Tuple of (decoded_data, sw)
send_apdu_constr_checksw(cla: Hexstr, ins: Hexstr, p1: Hexstr, p2: Hexstr, cmd_constr: Construct,
cmd_data: Hexstr, resp_constr: Construct, sw_exp: SwMatchstr = '9000',
apply_lchan: bool = True) → Tuple[dict, SwHexstr]
Build and sends an APDU using a ‘construct’ definition; parses response.
Parameters

76 Chapter 1. Introduction
 osmopysim-usermanual

• cla – string (in hex) ISO 7816 class byte

• ins – string (in hex) ISO 7816 instruction byte
• p1 – string (in hex) ISO 7116 Parameter 1 byte
• p2 – string (in hex) ISO 7116 Parameter 2 byte
• cmd_cosntr – defining how to generate binary APDU command data
• cmd_data – command data passed to cmd_constr
• resp_cosntr – defining how to decode binary APDU response data
• exp_sw – string (in hex) of status word (ex. “9000”)
Returns
Tuple of (decoded_data, sw)
set_data(ef , tag: int, value: str, verify: bool = False, conserve: bool = False) → Tuple[Hexstr, SwHexstr]
Execute SET DATA.
Args
ef : string or list of strings indicating name or path of transparent EF tag : BER-TLV Tag of value to
be stored value : BER-TLV value to be stored
status() → Tuple[Hexstr, SwHexstr]
Execute a STATUS command as per TS 102 221 Section 11.1.2.
suspend_uicc(min_len_secs: int = 60, max_len_secs: int = 43200) → Tuple[int, Hexstr, SwHexstr]
Send SUSPEND UICC to the card.
Parameters
• min_len_secs – mimumum suspend time seconds
• max_len_secs – maximum suspend time seconds
terminal_profile(payload: Hexstr) → Tuple[Hexstr, SwHexstr]
Send TERMINAL PROFILE to card
Parameters
payload – payload as hex string
terminate_card_usage() → Tuple[Hexstr, SwHexstr]
Execute TERMINATE CARD USAGE command as per TS 102 222 Section 6.9
terminate_df(fid: Hexstr) → Tuple[Hexstr, SwHexstr]
Execute TERMINATE DF command as per TS 102 222 Section 6.7
terminate_ef(fid: Hexstr) → Tuple[Hexstr, SwHexstr]
Execute TERMINATE EF command as per TS 102 222 Section 6.8
try_select_path(dir_list: List[Hexstr]) → List[Tuple[Hexstr, SwHexstr]]
Try to select a specified path
Parameters
dir_list – list of hex-string FIDs
unblock_chv(chv_no: int, puk_code: str, pin_code: str)
Unblock a given CHV (Card Holder Verification == PIN)
Parameters

1.5. pySim library 77

osmopysim-usermanual

• chv_no – chv number (1=CHV1, 2=CHV2, . . . )

• puk_code – puk code as hex string
• pin_code – new chv code as hex string
update_binary(ef: Hexstr | List[Hexstr], data: Hexstr, offset: int = 0, verify: bool = False, conserve: bool
= False) → Tuple[Hexstr, SwHexstr]
Execute UPDATE BINARY.
Parameters
• ef – string or list of strings indicating name or path of transparent EF
• data – hex string of data to be written
• offset – byte offset in file from which to start writing
• verify – Whether or not to verify data after write
update_record(ef: Hexstr | List[Hexstr], rec_no: int, data: Hexstr, force_len: bool = False, verify: bool =
False, conserve: bool = False, leftpad: bool = False) → Tuple[Hexstr, SwHexstr]
Execute UPDATE RECORD.
Parameters
• ef – string or list of strings indicating name or path of linear fixed EF
• rec_no – record number to read
• data – hex string of data to be written
• force_len – enforce record length by using the actual data length
• verify – verify data by re-reading the record
• conserve – read record and compare it with data, skip write on match
• leftpad – apply 0xff padding from the left instead from the right side.
verify_chv(chv_no: int, code: Hexstr) → Tuple[Hexstr, SwHexstr]
Verify a given CHV (Card Holder Verification == PIN)
Parameters
• chv_no – chv number (1=CHV1, 2=CHV2, . . . )
• code – chv code as hex string
pySim.commands.cla_with_lchan(cla_byte: Hexstr, lchan_nr: int) → Hexstr
Embed a logical channel number into the hex-string encoded CLA value.
pySim.commands.lchan_nr_to_cla(cla: int, lchan_nr: int) → int
Embed a logical channel number into the CLA byte.

1.5.3 pySim Transport

The pySim.transport classes implement specific ways how to communicate with a SIM card. A “transport” provides
ways to transceive APDUs with the card.
The most commonly used transport uses the PC/SC interface to utilize a variety of smart card interfaces (“readers”).

78 Chapter 1. Introduction
 osmopysim-usermanual

Transport base class

pySim: PCSC reader transport link base
class pySim.transport.LinkBase(sw_interpreter=None, apdu_tracer: ApduTracer | None = None,
proactive_handler: ProactiveHandler | None = None)
Base class for link/transport to card.
abstractmethod connect()
Connect to a card immediately
abstractmethod disconnect()
Disconnect from card
abstractmethod get_atr() → Hexstr
Retrieve card ATR
reset_card()
Resets the card (power down/up)
send_apdu(apdu: Hexstr) → Tuple[Hexstr, SwHexstr]
Sends an APDU with minimal processing
Parameters
apdu – string of hexadecimal characters (ex. “A0A40000023F00”, must comply to ISO/IEC
7816-3, section 12.1)
Returns
tuple(data, sw), where
data : string (in hex) of returned data (ex. “074F4EFFFF”) sw : string (in hex) of status
word (ex. “9000”)
send_apdu_checksw(apdu: Hexstr, sw: SwMatchstr = '9000') → Tuple[Hexstr, SwHexstr]
Sends an APDU and check returned SW
Parameters
• apdu – string of hexadecimal characters (ex. “A0A40000023F00”, must comply to
ISO/IEC 7816-3, section 12.1)
• sw – string of 4 hexadecimal characters (ex. “9000”). The user may mask out certain digits
using a ‘?’ to add some ambiguity if needed.
Returns
tuple(data, sw), where
data : string (in hex) of returned data (ex. “074F4EFFFF”) sw : string (in hex) of status
word (ex. “9000”)
set_sw_interpreter(interp)
Set an (optional) status word interpreter.
abstractmethod wait_for_card(timeout: int | None = None, newcardonly: bool = False)
Wait for a card and connect to it
Parameters
• timeout – Maximum wait time in seconds (None=no timeout)
• newcardonly – Should we wait for a new card, or an already inserted one ?

1.5. pySim library 79

osmopysim-usermanual

class pySim.transport.LinkBaseTpdu(sw_interpreter=None, apdu_tracer: ApduTracer | None = None,

proactive_handler: ProactiveHandler | None = None)

abstractmethod send_tpdu(tpdu: Hexstr) → Tuple[Hexstr, SwHexstr]

Implementation specific method for sending the resulting TPDU. This method must accept TPDUs as de-
fined in ETSI TS 102 221, section 7.3.1 and 7.3.2, depending on the protocol selected.
set_tpdu_format(protocol: int)
Set TPDU format. Each transport protocol has its specific TPDU format. This method allows the concrete
transport layer implementation to set the TPDU format it expects. (This method must not be called by
higher layers. Switching the TPDU format does not switch the transport protocol that the reader uses on
the wire)
Parameters
protocol – number of the transport protocol used. (0 => T=0, 1 => T=1)
class pySim.transport.ProactiveHandler
Abstract base class representing the interface of some code that handles the proactive commands, as returned by
the card in responses to the FETCH command.
receive_fetch(pcmd: ProactiveCommand)
Default handler for not otherwise handled proactive commands.
class pySim.transport.StdoutApduTracer
Minimalistic APDU tracer, printing commands to stdout.
pySim.transport.argparse_add_reader_args(arg_parser: ArgumentParser)
Add all reader related arguments to the given argparse.Argumentparser instance.
pySim.transport.init_reader(opts, **kwargs) → LinkBase
Init card reader driver

calypso / OsmocomBB transport

This allows the use of the SIM slot of an OsmocomBB compatible phone with the TI Calypso chipset, using the L1CTL
interface to talk to the layer1.bin firmware on the phone.
class pySim.transport.calypso.CalypsoSimLink(opts: Namespace =
Namespace(osmocon_sock='/tmp/osmocom_l2'),
**kwargs)
Transport Link for Calypso based phones.
connect()
Connect to a card immediately
disconnect()
Disconnect from card
get_atr() → Hexstr
Retrieve card ATR
send_tpdu(tpdu: Hexstr) → Tuple[Hexstr, SwHexstr]
Implementation specific method for sending the resulting TPDU. This method must accept TPDUs as de-
fined in ETSI TS 102 221, section 7.3.1 and 7.3.2, depending on the protocol selected.

80 Chapter 1. Introduction
 osmopysim-usermanual

wait_for_card(timeout: int | None = None, newcardonly: bool = False)

Wait for a card and connect to it
Parameters
• timeout – Maximum wait time in seconds (None=no timeout)
• newcardonly – Should we wait for a new card, or an already inserted one ?

AT-command Modem transport

This transport uses AT commands of a cellular modem in order to get access to the SIM card inserted in such a modem.

class pySim.transport.modem_atcmd.ModemATCommandLink(opts: Namespace =

Namespace(modem_dev='/dev/ttyUSB0',
modem_baud=115200), **kwargs)
Transport Link for 3GPP TS 27.007 compliant modems.
connect()
Connect to a card immediately
disconnect()
Disconnect from card
get_atr() → Hexstr
Retrieve card ATR
send_tpdu(tpdu: Hexstr) → Tuple[Hexstr, SwHexstr]
Implementation specific method for sending the resulting TPDU. This method must accept TPDUs as de-
fined in ETSI TS 102 221, section 7.3.1 and 7.3.2, depending on the protocol selected.
wait_for_card(timeout: int | None = None, newcardonly: bool = False)
Wait for a card and connect to it
Parameters
• timeout – Maximum wait time in seconds (None=no timeout)
• newcardonly – Should we wait for a new card, or an already inserted one ?

PC/SC transport
PC/SC is the standard API for accessing smart card interfaces on all major operating systems, including the MS Win-
dows Family, OS X as well as Linux / Unix OSs.
class pySim.transport.pcsc.PcscSimLink(opts: Namespace = Namespace(pcsc_dev=0), **kwargs)
pySim: PCSC reader transport link.
connect()
Connect to a card immediately
disconnect()
Disconnect from card
get_atr() → Hexstr
Retrieve card ATR

1.5. pySim library 81

osmopysim-usermanual

send_tpdu(tpdu: Hexstr) → Tuple[Hexstr, SwHexstr]

Implementation specific method for sending the resulting TPDU. This method must accept TPDUs as de-
fined in ETSI TS 102 221, section 7.3.1 and 7.3.2, depending on the protocol selected.
wait_for_card(timeout: int | None = None, newcardonly: bool = False)
Wait for a card and connect to it
Parameters
• timeout – Maximum wait time in seconds (None=no timeout)
• newcardonly – Should we wait for a new card, or an already inserted one ?

Serial/UART transport
This transport implements interfacing smart cards via very simplistic UART readers. These readers basically wire
together the Rx+Tx pins of a RS232 UART, provide a fixed crystal oscillator for clock, and operate the UART at 9600
bps. These readers are sometimes called Phoenix.
class pySim.transport.serial.SerialSimLink(opts=Namespace(device='/dev/ttyUSB0', baudrate=9600),
rst: str = '-rts', debug: bool = False, **kwargs)
pySim: Transport Link for serial (RS232) based readers included with simcard
connect()
Connect to a card immediately
disconnect()
Disconnect from card
get_atr() → Hexstr
Retrieve card ATR
send_tpdu(tpdu: Hexstr) → Tuple[Hexstr, SwHexstr]
Implementation specific method for sending the resulting TPDU. This method must accept TPDUs as de-
fined in ETSI TS 102 221, section 7.3.1 and 7.3.2, depending on the protocol selected.
wait_for_card(timeout: int | None = None, newcardonly: bool = False)
Wait for a card and connect to it
Parameters
• timeout – Maximum wait time in seconds (None=no timeout)
• newcardonly – Should we wait for a new card, or an already inserted one ?

1.5.4 pySim utility functions

pySim: various utilities
class pySim.utils.CardCommand(name, ins, cla_list=None, desc=None)
A single card command / instruction.
match_cla(cla)
Does the given CLA match the CLA list of the command?.
class pySim.utils.CardCommandSet(name, cmds=[])
A set of card instructions, typically specified within one spec.
lookup(ins, cla=None)
look-up the command within the CommandSet.

82 Chapter 1. Introduction
 osmopysim-usermanual

class pySim.utils.DataObject(name: str, desc: str | None = None, tag: int | None = None)
A DataObject (DO) in the sense of ISO 7816-4. Contrary to ‘normal’ TLVs where one simply has any number
of different TLVs that may occur in any order at any point, ISO 7816 has the habit of specifying TLV data but
with very spcific ordering, or specific choices of tags at specific points in a stream. This class tries to represent
this.
Parameters
• name – A brief, all-lowercase, underscore separated string identifier
• desc – A human-readable description of what this DO represents
• tag – The tag associated with this DO
decode(binary: bytes) → Tuple[dict, bytes]
Decode a single DOs from the input data. :param binary: binary bytes of encoded data
Returns
tuple of (decoded_result, binary_remainder)
abstractmethod from_bytes(do: bytes)
Parse the value part of the DO into the internal state of this instance. :param do: binary encoded bytes
from_tlv(do: bytes) → bytes
Parse binary TLV representation into internal state. The resulting decoded representation is _not_ returned,
but just internalized in the object instance! :param do: input bytes containing TLV-encoded representation
Returns
bytes remaining at end of ‘do’ after parsing one TLV/DO.
abstractmethod to_bytes() → bytes
Encode the internal state of this instance into the TLV value part. :returns: binary bytes encoding the
internal state
to_dict() → dict
Return a dict in form “name: decoded_value”
to_tlv() → bytes
Encode internal representation to binary TLV. :returns: bytes encoded in TLV format.
class pySim.utils.DataObjectChoice(name: str, desc: str | None = None, members=None)
One Data Object from within a choice, identified by its tag. This means that exactly one member of the choice
must occur, and which one occurs depends on the tag.
decode(binary: bytes) → Tuple[dict, bytes]
Decode a single DOs from the choice based on the tag. :param binary: binary bytes of encoded data
Returns
tuple of (decoded_result, binary_remainder)
class pySim.utils.DataObjectCollection(name: str, desc: str | None = None, members=None)
A DataObjectCollection consits of multiple Data Objects identified by their tags. A given encoded DO may
contain any of them in any order, and may contain multiple instances of each DO.
decode(binary: bytes) → Tuple[List, bytes]
Decode any number of DOs from the collection until the end of the input data, or uninitialized memory
(0xFF) is found. :param binary: binary bytes of encoded data
Returns
tuple of (decoded_result, binary_remainder)

1.5. pySim library 83

osmopysim-usermanual

class pySim.utils.DataObjectSequence(name: str, desc: str | None = None, sequence=None)

A sequence of DataObjects or DataObjectChoices. This allows us to express a certain ordered sequence of DOs
or choices of DOs that have to appear as per the specification. By wrapping them into this formal DataObject-
Sequence, we can offer convenience methods for encoding or decoding an entire sequence.
decode(binary: bytes) → Tuple[list, bytes]
Decode a sequence by calling the decoder of each element in the sequence. :param binary: binary bytes of
encoded data
Returns
tuple of (decoded_result, binary_remainder)
decode_multi(do: bytes) → Tuple[list, bytes]
Decode multiple occurrences of the sequence from the binary input data. :param do: binary input data to
be decoded
Returns
list of results of the decoder of this sequences
encode(decoded) → bytes
Encode a sequence by calling the encoder of each element in the sequence.
encode_multi(decoded) → bytes
Encode multiple occurrences of the sequence from the decoded input data. :param decoded: list of json-
serializable input data; one sequence per list item
Returns
binary encoded output data
class pySim.utils.TL0_DataObject(name: str, desc: str, tag: int, val=None)
Data Object that has Tag, Len=0 and no Value part.
Parameters
• name – A brief, all-lowercase, underscore separated string identifier
• desc – A human-readable description of what this DO represents
• tag – The tag associated with this DO
from_bytes(binary: bytes)
Parse the value part of the DO into the internal state of this instance. :param do: binary encoded bytes
to_bytes() → bytes
Encode the internal state of this instance into the TLV value part. :returns: binary bytes encoding the
internal state
pySim.utils.boxed_heading_str(heading, width=80)
Generate a string that contains a boxed heading.
pySim.utils.calculate_luhn(cc) → int
Calculate Luhn checksum used in e.g. ICCID and IMEI
pySim.utils.dec_imsi(ef: Hexstr) → str | None
Converts an EF value to the IMSI string representation
pySim.utils.derive_mcc(digit1: int, digit2: int, digit3: int) → int
Derive decimal representation of the MCC (Mobile Country Code) from three given digits.

84 Chapter 1. Introduction
 osmopysim-usermanual

pySim.utils.derive_milenage_opc(ki_hex: Hexstr, op_hex: Hexstr) → Hexstr

Run the milenage algorithm to calculate OPC from Ki and OP
pySim.utils.derive_mnc(digit1: int, digit2: int, digit3: int = 15) → int
Derive decimal representation of the MNC (Mobile Network Code) from two or (optionally) three given digits.
pySim.utils.enc_imsi(imsi: str)
Converts a string IMSI into the encoded value of the EF
pySim.utils.enc_plmn(mcc: Hexstr, mnc: Hexstr) → Hexstr
Converts integer MCC/MNC into 3 bytes for EF
pySim.utils.expand_hex(hexstring, length)

Expand a given hexstring to a specified length by replacing “.” or “..”

with a filler that is derived from the neighboring nibbles respective bytes. Usually this will be the nibble
respective byte before “.” or “..”, execpt when the string begins with “.” or “..”, then the nibble respective
byte after “.” or “..” is used.”. In case the string cannot be expanded for some reason, the input string is
returned unmodified.

Parameters
• hexstring – hexstring to expand
• length – desired length of the resulting hexstring.
Returns
expanded hexstring

pySim.utils.get_addr_type(addr)
Validates the given address and returns it’s type (FQDN or IPv4 or IPv6) Return: 0x00 (FQDN), 0x01 (IPv4),
0x02 (IPv6), None (Bad address argument given)
TODO: Handle IPv6
pySim.utils.mcc_from_imsi(imsi: str) → str | None
Derive the MCC (Mobile Country Code) from the first three digits of an IMSI
pySim.utils.mnc_from_imsi(imsi: str, long: bool = False) → str | None
Derive the MNC (Mobile Country Code) from the 4th to 6th digit of an IMSI
pySim.utils.parse_command_apdu(apdu: bytes) → int
Parse a given command APDU and return case (see also ISO/IEC 7816-3, Table 12 and Figure 26), lc, le and the
data field.
Parameters
apdu – hexstring that contains the command APDU
Returns
tuple containing case, lc and le values of the APDU (case, lc, le, data)
pySim.utils.sanitize_pin_adm(pin_adm, pin_adm_hex=None) → Hexstr
The ADM pin can be supplied either in its hexadecimal form or as ascii string. This function checks the supplied
opts parameter and returns the pin_adm as hex encoded string, regardless in which form it was originally supplied
by the user
pySim.utils.sw_match(sw: str, pattern: str) → bool
Match given SW against given pattern.

1.5. pySim library 85

osmopysim-usermanual

pySim.utils.tabulate_str_list(str_list, width: int = 79, hspace: int = 2, lspace: int = 1, align_left: bool =
True) → str
Pretty print a list of strings into a tabulated form.
Parameters
• width – total width in characters per line
• space – horizontal space between cells
• lspace – number of spaces before row
• align_lef – Align text to the left side
Returns
multi-line string containing formatted table
pySim.utils.verify_luhn(digits: str)
Verify the Luhn check digit; raises ValueError if it is incorrect.

1.5.5 pySim exceptions

pySim: Exceptions
exception pySim.exceptions.NoCardError
No card was found in the reader.
exception pySim.exceptions.ProtocolError
Some kind of protocol level error interfacing with the card.
exception pySim.exceptions.ReaderError
Some kind of general error with the card reader.
exception pySim.exceptions.SwMatchError(sw_actual: str, sw_expected: str, rs=None)
Raised when an operation specifies an expected SW but the actual SW from the card doesn’t match.
Parameters
• sw_actual – the SW we actually received from the card (4 hex digits)
• sw_expected – the SW we expected to receive from the card (4 hex digits)
• rs – interpreter class to convert SW to string

1.5.6 pySim card_handler

pySim: card handler utilities. A ‘card handler’ is some method by which cards can be inserted/removed into the card
reader. For normal smart card readers, this has to be done manually. However, there are also automatic card feeders.
class pySim.card_handler.CardHandler(sl: LinkBase)
Manual card handler: User is prompted to insert/remove card from the reader.
class pySim.card_handler.CardHandlerAuto(sl: LinkBase, config_file: str)
Automatic card handler: A machine is used to handle the cards.
class pySim.card_handler.CardHandlerBase(sl: LinkBase)
Abstract base class representing a mechanism for card insertion/removal.
done()
Method called when pySim failed to program a card. Move card to ‘good’ batch.

86 Chapter 1. Introduction
 osmopysim-usermanual

error()
Method called when pySim failed to program a card. Move card to ‘bad’ batch.
get(first: bool = False)
Method called when pySim needs a new card to be inserted.
Parameters
first – set to true when the get method is called the first time. This is required to prevent
blocking when a card is already inserted into the reader. The reader API would not recognize
that card as “new card” until it would be removed and re-inserted again.

1.5.7 pySim card_key_provider

Obtaining card parameters (mostly key data) from external source.
This module contains a base class and a concrete implementation of obtaining card key material (or other card-
individual parameters) from an external data source.
This is used e.g. to keep PIN/PUK data in some file on disk, avoiding the need of manually entering the related card-
individual data on every operation with pySim-shell.
class pySim.card_key_provider.CardKeyProvider
Base class, not containing any concrete implementation.
abstractmethod get(fields: List[str], key: str, value: str) → Dict[str, str]
Get multiple card-individual fields for identified card.
Parameters
• fields – list of valid field names such as ‘ADM1’, ‘PIN1’, . . . which are to be obtained
• key – look-up key to identify card data, such as ‘ICCID’
• value – value for look-up key to identify card data
Returns
dictionary of {field, value} strings for each requested field from ‘fields’
get_field(field: str, key: str = 'ICCID', value: str = '') → str | None
get a single field from CSV file using a specified key/value pair
class pySim.card_key_provider.CardKeyProviderCsv(filename: str, transport_keys: dict)
Card key provider implementation that allows to query against a specified CSV file. Supports column-based
encryption as it is generally a bad idea to store cryptographic key material in plaintext. Instead, the key material
should be encrypted by a “key-encryption key”, occasionally also known as “transport key” (see GSMA FS.28).
Parameters
• filename – file name (path) of CSV file containing card-individual key/data
• transport_keys – a dict indexed by field name, whose values are hex-encoded AES keys
for the respective field (column) of the CSV. This is done so that different fields (columns)
can use different transport keys, which is strongly recommended by GSMA FS.28
get(fields: List[str], key: str, value: str) → Dict[str, str]
Get multiple card-individual fields for identified card.
Parameters
• fields – list of valid field names such as ‘ADM1’, ‘PIN1’, . . . which are to be obtained
• key – look-up key to identify card data, such as ‘ICCID’

1.5. pySim library 87

osmopysim-usermanual

• value – value for look-up key to identify card data

Returns
dictionary of {field, value} strings for each requested field from ‘fields’
static process_transport_keys(transport_keys: dict)
Apply a single transport key to multiple fields/columns, if the name is a group.
pySim.card_key_provider.card_key_provider_get(fields, key: str, value: str, provider_list=[]) → Dict[str,
str]
Query all registered card data providers for card-individual [key] data.
Parameters
• fields – list of valid field names such as ‘ADM1’, ‘PIN1’, . . . which are to be obtained
• key – look-up key to identify card data, such as ‘ICCID’
• value – value for look-up key to identify card data
• provider_list – override the list of providers from the global default
Returns
dictionary of {field, value} strings for each requested field from ‘fields’
pySim.card_key_provider.card_key_provider_get_field(field: str, key: str, value: str, provider_list=[])
→ str | None
Query all registered card data providers for a single field.
Parameters
• field – name valid field such as ‘ADM1’, ‘PIN1’, . . . which is to be obtained
• key – look-up key to identify card data, such as ‘ICCID’
• value – value for look-up key to identify card data
• provider_list – override the list of providers from the global default
Returns
dictionary of {field, value} strings for the requested field
pySim.card_key_provider.card_key_provider_register(provider: CardKeyProvider, provider_list=[])
Register a new card key provider.
Parameters
• provider – the to-be-registered provider
• provider_list – override the list of providers from the global default

1.6 pySim eSIM libraries

The pySim eSIM libraries implement a variety of functionality related to the GSMA eSIM universe, including the
various interfaces of SGP.21 + SGP.22, as well as Interoperable Profile decioding, validation, personalization and
encoding.
class pySim.esim.ActivationCode(hostname: str, token: str, oid: str | None = None, cc_required: bool | None
= False)
SGP.22 section 4.1 Activation Code

88 Chapter 1. Introduction
 osmopysim-usermanual

static decode_str(ac: str) → dict

decode an activation code from its string representation.
classmethod from_string(ac: str) → ActivationCode
Create new instance from SGP.22 section 4.1 string representation.
to_qrcode()
Encode internal representation to QR code.
to_string(for_qrcode: bool = False) → str
Convert from internal representation to SGP.22 section 4.1 string representation.
class pySim.esim.PMO(op: str)
Convenience conversion class for ProfileManagementOperation as used in ES9+ notifications.
classmethod from_bitstring(bstr: Tuple[bytes, int]) → PMO
Parse a asn1tools BITSTRING representation.
classmethod from_int(i: int) → PMO
Parse an integer representation.
to_bitstring() → Tuple[bytes, int]
return value in a format as used by asn1tools for BITSTRING.
pySim.esim.compile_asn1_subdir(subdir_name: str, codec='der')
Helper function that compiles ASN.1 syntax from all files within given subdir

1.6.1 GSMA SGP.21/22 Remote SIM Provisioning (RSP) - High Level

pySim.esim.rsp
Implementation of GSMA eSIM RSP (Remote SIM Provisioning) as per SGP22 v3.0
class pySim.esim.rsp.RspSessionState(transactionId: str, serverChallenge: bytes, ci_cert_id: bytes)
Encapsulates the state of a RSP session. It is created during the initiateAuthentication and subsequently used by
further API calls using the same transactionId. The session state is removed either after cancelSession or after
notification. TODO: add some kind of time based expiration / garbage collection.
class pySim.esim.rsp.RspSessionStore(filename, flag='c', protocol=None, writeback=False)
A derived class as wrapper around the database-backed non-volatile storage ‘shelve’, in case we might need to
extend it in the future. We use it to store RspSessionState objects indexed by transactionId.
pySim.esim.rsp.extract_euiccSigned1(authenticateServerResponse: bytes) → bytes
Extract the raw, DER-encoded binary euiccSigned1 field from the given AuthenticateServerResponse. This is
needed due to the very peculiar SGP.22 notion of signing sections of DER-encoded ASN.1 objects.
pySim.esim.rsp.extract_euiccSigned2(prepareDownloadResponse: bytes) → bytes
Extract the raw, DER-encoded binary euiccSigned2 field from the given prepareDownloadrResponse. This is
needed due to the very peculiar SGP.22 notion of signing sections of DER-encoded ASN.1 objects.

pySim.esim.es2p
GSMA eSIM RSP ES2+ interface according to SGP.22 v2.5
class pySim.esim.es2p.CancelOrder(url_prefix: str, func_req_id: str | None, session: Session)

class pySim.esim.es2p.ConfirmOrder(url_prefix: str, func_req_id: str | None, session: Session)

1.6. pySim eSIM libraries 89

osmopysim-usermanual

class pySim.esim.es2p.DownloadOrder(url_prefix: str, func_req_id: str | None, session: Session)

class pySim.esim.es2p.Es2PlusApiFunction(url_prefix: str, func_req_id: str | None, session: Session)

Base classs for representing an ES2+ API Function.
class pySim.esim.es2p.Es2pApiClient(url_prefix: str, func_req_id: str, server_cert_verify: str = None,
client_cert: str = None)
Main class representing a full ES2+ API client. Has one method for each API function.
call_cancelOrder(data: dict) → dict
Perform ES2+ CancelOrder function (SGP.22 section 5.3.3).
call_confirmOrder(data: dict) → dict
Perform ES2+ ConfirmOrder function (SGP.22 section 5.3.2).
call_downloadOrder(data: dict) → dict
Perform ES2+ DownloadOrder function (SGP.22 section 5.3.1).
call_handleDownloadProgressInfo(data: dict) → dict
Perform ES2+ HandleDownloadProgressInfo function (SGP.22 section 5.3.5).
call_releaseProfile(data: dict) → dict
Perform ES2+ CancelOrder function (SGP.22 section 5.3.4).
class pySim.esim.es2p.HandleDownloadProgressInfo(url_prefix: str, func_req_id: str | None, session:
Session)

class pySim.esim.es2p.ReleaseProfile(url_prefix: str, func_req_id: str | None, session: Session)

pySim.esim.es8p
Implementation of GSMA eSIM RSP (Remote SIM Provisioning) ES8+ as per SGP22 v3.0 Section 5.5
class pySim.esim.es8p.BoundProfilePackage(metadata: ProfileMetadata | None = None)
Representing a bound profile package (BPP) as defined in SGP.22 Section 2.5.4
decode(euicc_ot, eid: str, bpp_bin: bytes)
Decode a BPP into the PPP and subsequently UPP. This is what happens inside an eUICC.
encode(ss: RspSessionState, dp_pb: CertAndPrivkey) → bytes
Generate a bound profile package (SGP.22 2.5.4).
class pySim.esim.es8p.ProfileMetadata(iccid_bin: bytes, spn: str, profile_name: str)
Representation of Profile metadata. Right now only the mandatory bits are supported, but in general this should
follow the StoreMetadataRequest of SGP.22 5.5.3
add_notification(event: str, address: str)
Add an ‘other’ notification to the notification configuration of the metadata
gen_store_metadata_request() → bytes
Generate encoded (but unsigned) StoreMetadataRequest DO (SGP.22 5.5.3)
set_icon(is_png: bool, icon_data: bytes)
Set the icon that is part of the metadata.
class pySim.esim.es8p.ProtectedProfilePackage(metadata: ProfileMetadata | None = None)
Representing a protected profile package (PPP) as defined in SGP.22 Section 2.5.3

90 Chapter 1. Introduction
 osmopysim-usermanual

classmethod from_upp(upp: UnprotectedProfilePackage, bsp: BspInstance) → ProtectedProfilePackage

Generate the PPP as a sequence of encrypted and MACed Command TLVs representing the UPP
class pySim.esim.es8p.UnprotectedProfilePackage(metadata: ProfileMetadata | None = None)
Representing an unprotected profile package (UPP) as defined in SGP.22 Section 2.5.2
classmethod from_der(der: bytes, metadata: ProfileMetadata | None = None) →
UnprotectedProfilePackage
Load an UPP from its DER representation.
to_der()
Return the DER representation of the UPP.
pySim.esim.es8p.gen_init_sec_chan_signed_part(iscsp: Dict) → bytes
Generate the concatenated remoteOpId, transactionId, controlRefTemplate and smdpOtpk data objects without
the outer SEQUENCE tag / length or the remainder of initialiseSecureChannel, as is required for signing purpose.
pySim.esim.es8p.gen_initialiseSecureChannel(transactionId: str, host_id: bytes, smdp_otpk: bytes,
euicc_otpk: bytes, dp_pb)
Generate decoded representation of (signed) initialiseSecureChannel (SGP.22 5.5.2)
pySim.esim.es8p.gen_replace_session_keys(ppk_enc: bytes, ppk_cmac: bytes, initial_mcv: bytes) → bytes
Generate encoded (but unsigned) ReplaceSessionKeysReqest DO (SGP.22 5.5.4)
pySim.esim.es8p.wrap_as_der_tlv(tag: int, val: bytes) → bytes
Wrap the ‘value’ into a DER-encoded TLV.

pySim.esim.es9p
GSMA eSIM RSP ES9+ interface according ot SGP.22 v2.5
class pySim.esim.es9p.AuthenticateClient(url_prefix: str, func_req_id: str | None, session: Session)

class pySim.esim.es9p.CancelSession(url_prefix: str, func_req_id: str | None, session: Session)

class pySim.esim.es9p.Es9PlusApiFunction(url_prefix: str, func_req_id: str | None, session: Session)

class pySim.esim.es9p.GetBoundProfilePackage(url_prefix: str, func_req_id: str | None, session: Session)

class pySim.esim.es9p.HandleNotification(url_prefix: str, func_req_id: str | None, session: Session)

class pySim.esim.es9p.InitiateAuthentication(url_prefix: str, func_req_id: str | None, session: Session)

1.6.2 GSMA SGP.21/22 Remote SIM Provisioning (RSP) - Low Level

pySim.esim.bsp
Implementation of GSMA eSIM RSP (Remote SIM Provisioning BSP (BPP Protection Protocol), where BPP is the
Bound Profile Package. So the full expansion is the “GSMA eSIM Remote SIM Provisioning Bound Profile Packate
Protection Protocol”
Originally (SGP.22 v2.x) this was called SCP03t, but it has since been renamed to BSP.
class pySim.esim.bsp.BspAlgo
Base class representing a cryptographic algorithm within the BSP (BPP Security Protocol).
class pySim.esim.bsp.BspAlgoCrypt(s_enc: bytes)
Base class representing an encryption/decryption algorithm within the BSP (BPP Security Protocol).

1.6. pySim eSIM libraries 91

osmopysim-usermanual

decrypt(data: bytes) → bytes

Decrypt given input bytes using the key material given in constructor.
encrypt(data: bytes) → bytes
Encrypt given input bytes using the key material given in constructor.
class pySim.esim.bsp.BspAlgoCryptAES128(s_enc: bytes)
AES-CBC-128 implementation of the BPP Security Protocol for GSMA SGP.22 eSIM.
class pySim.esim.bsp.BspAlgoMac(s_mac: bytes, initial_mac_chaining_value: bytes)
Base class representing a message authentication code algorithm within the BSP (BPP Security Protocol).
class pySim.esim.bsp.BspAlgoMacAES128(s_mac: bytes, initial_mac_chaining_value: bytes)
AES-CMAC-128 implementation of the BPP Security Protocol for GSMA SGP.22 eSIM.
class pySim.esim.bsp.BspInstance(s_enc: bytes, s_mac: bytes, initial_mcv: bytes)
An instance of the BSP crypto. Initialized once with the key material via constructor, then the user can call any
number of encrypt_and_mac cycles to protect plaintext and generate the respective ciphertext.
encrypt_and_mac_one(tag: int, plaintext: bytes) → bytes
Encrypt + MAC a single plaintext TLV. Returns the protected ciphertext.
classmethod from_kdf(shared_secret: bytes, key_type: int, key_length: int, host_id: bytes, eid: bytes)
Convenience constructor for constructing an instance with keys from KDF.
mac_only_one(tag: int, plaintext: bytes) → bytes
MAC a single plaintext TLV. Returns the protected ciphertext.
pySim.esim.bsp.bsp_key_derivation(shared_secret: bytes, key_type: int, key_length: int, host_id: bytes, eid,
l: int = 16)
BSP protocol key derivation as per SGP.22 v3.0 Section 2.6.4.2

pySim.esim.http_json_api
GSMA eSIM RSP HTTP/REST/JSON interface according to SGP.22 v2.5
exception pySim.esim.http_json_api.ApiError(func_ex_status: dict)
Exception representing an error at the API level (status != Executed).
class pySim.esim.http_json_api.ApiParam
A class representing a single parameter in the API.
classmethod decode(data)
[Validate and] Decode the given value.
classmethod encode(data)
[Validate and] Encode the given value.
classmethod verify_decoded(data)
Verify the decoded representation of a value. Should raise an exception if something is odd.
classmethod verify_encoded(data)
Verify the encoded representation of a value. Should raise an exception if something is odd.
class pySim.esim.http_json_api.ApiParamBase64

class pySim.esim.http_json_api.ApiParamBoolean
Base class representing an API parameter of ‘boolean’ type.

92 Chapter 1. Introduction
 osmopysim-usermanual

class pySim.esim.http_json_api.ApiParamFqdn
String, as a list of domain labels concatenated using the full stop (dot, period) character as separator between
labels. Labels are restricted to the Alphanumeric mode character set defined in table 5 of ISO/IEC 18004
classmethod verify_encoded(data)
Verify the encoded representation of a value. Should raise an exception if something is odd.
class pySim.esim.http_json_api.ApiParamInteger
Base class representing an API parameter of ‘integer’ type.
classmethod verify_decoded(data)
Verify the decoded representation of a value. Should raise an exception if something is odd.
classmethod verify_encoded(data)
Verify the encoded representation of a value. Should raise an exception if something is odd.
class pySim.esim.http_json_api.ApiParamString
Base class representing an API parameter of ‘string’ type.
exception pySim.esim.http_json_api.HttpHeaderError

exception pySim.esim.http_json_api.HttpStatusError

class pySim.esim.http_json_api.JsonHttpApiFunction(url_prefix: str, func_req_id: str | None, session:

Session)
Base classs for representing an HTTP[s] API Function.
call(data: dict, func_call_id: str | None = None, timeout=10) → dict | None
Make an API call to the HTTP API endpoint represented by this object. Input data is passed in data as
json-serializable dict. Output data is returned as json-deserialized dict.
decode(data: dict) → dict
[further] Decode and validate the JSON-Dict of the response body.
encode(data: dict, func_call_id: str | None = None) → dict
Validate an encode input dict into JSON-serializable dict for request body.
class pySim.esim.http_json_api.JsonResponseHeader
SGP.22 section 6.5.1.4.
classmethod verify_decoded(data)
Verify the decoded representation of a value. Should raise an exception if something is odd.
class pySim.esim.http_json_api.SmdpAddress

pySim.esim.x509_cert
Implementation of X.509 certificate handling in GSMA eSIM as per SGP22 v3.0
class pySim.esim.x509_cert.CertAndPrivkey(required_policy_oid: ObjectIdentifier | None = None, cert:
Certificate | None = None, priv_key=None)
A pair of certificate and private key, as used for ECDSA signing.
ecdsa_sign(plaintext: bytes) → bytes
Sign some input-data using an ECDSA signature compliant with SGP.22, which internally refers to Global
Platform 2.2 Annex E, which in turn points to BSI TS-03111 which states “concatenated raw R + S values”.

1.6. pySim eSIM libraries 93

osmopysim-usermanual

get_authority_key_identifier() → AuthorityKeyIdentifier
Return the AuthorityKeyIdentifier X.509 extension of the certificate.
get_cert_as_der() → bytes
Return certificate encoded as DER.
get_subject_alt_name() → SubjectAlternativeName
Return the SubjectAlternativeName X.509 extension of the certificate.
class pySim.esim.x509_cert.CertificateSet(root_cert: Certificate)
A set of certificates consisting of a trusted [self-signed] CA root certificate, and an optional number of interme-
diate certificates. Can be used to verify the certificate chain of any given other certificate.
add_intermediate_cert(cert: Certificate)
Add a potential intermediate certificate to the CertificateSet.
verify_cert_chain(cert: Certificate, max_depth: int = 100)
Verify if a given certificate’s signature chain can be traced back to the root CA of this CertificateSet.
exception pySim.esim.x509_cert.VerifyError
An error during certificate verification,
pySim.esim.x509_cert.cert_get_auth_key_id(cert: Certificate) → bytes
Obtain the authority key identifier of the given cert object (as raw bytes).
pySim.esim.x509_cert.cert_get_subject_key_id(cert: Certificate) → bytes
Obtain the subject key identifier of the given cert object (as raw bytes).
pySim.esim.x509_cert.cert_policy_has_oid(cert: Certificate, match_oid: ObjectIdentifier) → bool
Determine if given certificate has a certificatePolicy extension of matching OID.
pySim.esim.x509_cert.check_signed(signed: Certificate, signer: Certificate) → bool
Verify if ‘signed’ certificate was signed using ‘signer’.
pySim.esim.x509_cert.ecdsa_dss_to_tr03111(sig: bytes) → bytes
convert from DER format to BSI TR-03111; first get long integers; then convert those to bytes.

1.6.3 SIMalliance / TCA Interoperable Profile

pySim.esim.saip
Implementation of SimAlliance/TCA Interoperable Profile handling
class pySim.esim.saip.File(pename: str, l: List[Tuple] | None = None, template: FileTemplate | None =
None, name: str | None = None)
Internal representation of a file in a profile filesystem.
Parameters
• pename – Name string of the profile element
• l – List of tuples [fileDescriptor, fillFileContent, fillFileOffset profile elements]
• template – Applicable FileTemplate describing defaults as per SAIP spec
• name – Human-readable name like EF.IMSI, DF.TELECOM, ADF.USIM, . . .
check_template_modification_rules()
Check template modification rules as per SAIP section 8.3.3.

94 Chapter 1. Introduction
 osmopysim-usermanual

expand_fill_pattern() → bytes
Expand the fill/repeat pattern as per TS 102 222 Section 6.3.2.2.2
file_content_from_tuples(l: List[Tuple]) → bytes | None
linearize a list of fillFileContent / fillFileOffset tuples into a stream of bytes.
property file_size: int | None
Return the size of the file in bytes.
from_fileDescriptor(fileDescriptor: dict)
Convert from ‘fileDescriptor’ as used by asn1tools for SAIP to internal representation
from_template(template: FileTemplate)
Determine defaults for file based on given FileTemplate.
from_tuples(l: List[Tuple])
Parse a list of fileDescriptor, fillFileContent, fillFileOffset tuples into this instance.
static get_tuplelist_item(l: List[Tuple], key: str)
get the [first] value matching given key from a list of (key, value) tuples.
static path_from_gfm(bin_path: bytes)
convert from byte-array of 16bit FIDs to list of integers
static path_to_gfm(path: List[int]) → bytes
convert from list of 16bit integers to byte-array
to_fileDescriptor() → dict
Convert from internal representation to ‘fileDescriptor’ as used by asn1tools for SAIP
to_gfm() → List[Tuple]
Generate a list of filePath, createFCP, fillFileContent, fillFileOffset tuples into this instance.
to_tuples() → List[Tuple]
Generate a list of fileDescriptor, fillFileContent, fillFileOffset tuples into this instance.
class pySim.esim.saip.FsNode(fid: int, parent: FsNode | None, file: File | None = None, name: str | None =
None)
A node in the filesystem hierarchy.
property fid_path: List[int]
Return the path of the node as list of integers.
property mf: FsNodeMF
Return the MF (root) of the hierarchy.
property name_path: List[str]
Return the path of the node as list of integers.
walk(fn, **kwargs)
call ‘fn(self, **kwargs) for the File.
class pySim.esim.saip.FsNodeADF(df_name: Hexstr, fid: int | None = None, parent: FsNodeDF | None =
None, file: File | None = None, name: str | None = None)
An ADF (Application Dedicated File) in the filesystem hierarchy.

1.6. pySim eSIM libraries 95

osmopysim-usermanual

class pySim.esim.saip.FsNodeDF(fid: int, parent: FsNodeDf , file: File | None = None, name: str | None =
None)
A DF (Dedicated File) in the filesystem hierarchy.
add_child(child: FsNode)
Add a child to the list of children of this DF.
add_file(file: File) → FsNodeDF
Create and link an appropriate FsNode for the given ‘file’ and insert it. Returns the new current DF (it
might have changed).
lookup_by_fidpath(path: List[int]) → FsNode
Look-up a FsNode based on the [fid baesd] given (absolute) path.
lookup_by_path(path: Path) → FsNode
Look-up a FsNode based on the [name based] given (absolute) path.
walk(fn, **kwargs)
call ‘fn(self, **kwargs) for the DF and recursively for all children.
class pySim.esim.saip.FsNodeEF(fid: int, parent: FsNode | None, file: File | None = None, name: str | None =
None)
An EF (Entry File) in the filesystem hierarchy.
class pySim.esim.saip.FsNodeMF(file: File | None = None)
The MF (Master File) in the filesystem hierarchy.
class pySim.esim.saip.FsProfileElement(decoded=None, mandated: bool = True, **kwargs)
A file-system bearing profile element, like MF, USIM, . . . .
We keep two major representations of the data: * The “decoded” member, as introduced by our parent class,
containing asn1tools syntax * the “files” dict, consisting of File values indexed by PE-name strings
The methods pe2files and files2pe convert between those two representations.
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
add_file(file: File)
Add a File to the ProfileElement.
create_file(pename: str) → File
Programatically create a file by its PE-Name.
file_template_for_path(path: Path, adf: str | None = None) → FileTemplate | None
Resolve the FileTemplate for given path, if we have any matching.
Parameters
• path – the path for which we would like to resolve the FileTemplate
• adf – string name of the ADF which might be used with this PE

96 Chapter 1. Introduction
 osmopysim-usermanual

files2pe()
Update the “decoded” member with the contents of the “files” member.
pe2files()
Update the “files” member with the contents of the “decoded” member.
supports_file_for_path(path: Path, adf: str | None = None) → bool
Does this ProfileElement support a file of given path?
class pySim.esim.saip.Naa
A class defining a Network Access Application (NAA)
class pySim.esim.saip.NaaCsim
A class representing the CSIM (CDMA) Network Access Application (NAA)
class pySim.esim.saip.NaaIsim
A class representing the ISIM Network Access Application (NAA)
class pySim.esim.saip.NaaUsim
A class representing the USIM Network Access Application (NAA)
class pySim.esim.saip.ProfileElement(decoded=None, mandated: bool = True, pe_sequence:
ProfileElementSequence | None = None)
Generic Class representing a Profile Element (PE) within a SAIP Profile. This may be used directly, but ist
more likely sub-classed with a specific class for the specific profile element type, like e.g ProfileElementHeader,
ProfileElementMF, . . .
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
classmethod class_for_petype(pe_type: str) → ProfileElement | None
Return the subclass implementing the given pe-type string.
classmethod from_der(der: bytes, pe_sequence: ProfileElementSequence | None = None) →
ProfileElement
Construct an instance from given raw, DER encoded bytes.
Parameters
• der – raw, DER-encoded bytes of a single PE
• pe_sequence – back-reference to the PE-Sequence of which this PE is part of
property header
The decoded ProfileHeader.
property header_name: str
Return the name of the header field within the profile element.

1.6. pySim eSIM libraries 97

osmopysim-usermanual

property identification
An unique number for the PE within the PE-Sequence.
Type
The identification value
property templateID
Return the decoded templateID used by this profile element (if any).
to_der() → bytes
Build an encoded DER representation of the instance.
class pySim.esim.saip.ProfileElementAKA(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for Authentication and Key Agreement (AKA).
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
set_mapping(aid: bytes, options: int = 6)
Configure akaParametes for a mapping from another AID.
set_milenage(k: bytes, opc: bytes)
Configure akaParametes for MILENAGE.
set_tuak(k: bytes, topc: bytes, num_of_keccak: int = 1)
Configure akaParametes for TUAK.
set_xor3g(k: bytes)
Configure akaParametes for XOR-3G.
class pySim.esim.saip.ProfileElementApplication(decoded: dict | None = None, **kwargs)
Class representing an application ProfileElement.
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
add_instance(aid: Hexstr, class_aid: Hexstr, inst_aid: Hexstr, app_privileges: Hexstr, app_spec_pars:
Hexstr, uicc_toolkit_app_spec_pars: Hexstr = None, uicc_access_app_spec_pars: Hexstr =
None, uicc_adm_access_app_spec_pars: Hexstr = None, volatile_memory_quota: Hexstr =
None, non_volatile_memory_quota: Hexstr = None, process_data: list[Hexstr] = None)
Create a new instance and add it to the instanceList

98 Chapter 1. Introduction
 osmopysim-usermanual

classmethod from_file(filename: str, aid: Hexstr, sd_aid: Hexstr = None, non_volatile_code_limit: int =
None, volatile_data_limit: int = None, non_volatile_data_limit: int = None,
hash_value: Hexstr = None) → ProfileElementApplication
Fill contents of application ProfileElement from a .cap file.
remove_instance(inst_aid: Hexstr)
Remove an instance from the instanceList
to_file(filename: str)
Write loadBlockObject contents of application ProfileElement to a .cap or .ijc file.
class pySim.esim.saip.ProfileElementCD(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for DF.CD
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementDf5GProSe(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for DF.5GProSe
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementDf5GS(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for ADF.USIM/DF.5GS
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementDfSAIP(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for DF.SAIP
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters

1.6. pySim eSIM libraries 99

osmopysim-usermanual

• decoded – asn1tools-generated decoded structure for this PE

• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementDfSNPN(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for DF.SNPN
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementEAP(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for DF.EAP
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementEnd(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for the End of the PE-Sequence.
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementGFM(decoded=None, mandated: bool = True, **kwargs)
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of

100 Chapter 1. Introduction

 osmopysim-usermanual

files2pe()
Update the “decoded” member from the “files” member.
pe2files()
Update the “files” member with the contents of the “decoded” member.
supports_file_for_path(path: Path, adf: str | None = None) → bool
Does this ProfileElement support a file of given path?
class pySim.esim.saip.ProfileElementGsmAccess(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for ADF.USIM/DF.GSM-ACCESS
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementHeader(decoded: dict | None = None, ver_major: int | None = 2,
ver_minor: int | None = 3, iccid: Hexstr | None =
'00000000000000000000', profile_type: str | None = None,
**kwargs)
Class representing the ProfileElement for the Header of the PE-Sequence.
You would usually initialize an instance either with a “decoded” argument (as read from a DER-encoded SAIP
file via asn1tools), or [some of] the othe arguments in case you’re constructing a Profile Header from scratch.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• ver_major – Major SAIP version
• ver_minor – Minor SAIP version
• iccid – ICCID of the profile
• profile_type – operational, testing or bootstrap
class pySim.esim.saip.ProfileElementISIM(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for ADF.ISIM Mandatory Files
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of

1.6. pySim eSIM libraries 101

osmopysim-usermanual

class pySim.esim.saip.ProfileElementMF(decoded: dict | None = None, **kwargs)

Class representing the ProfileElement for the MF (Master File)
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementOptISIM(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for ADF.ISIM Optional Files
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementOptUSIM(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for ADF.USIM Optional Files
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementPhonebook(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for DF.PHONEBOOK
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementPin(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for a PIN (Personal Identification Number)
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.

102 Chapter 1. Introduction

 osmopysim-usermanual

Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
add_pin(key_ref: int, pin_value: bytes, max_attempts: int = 3, retries_left: int = 3, unblock_ref: int | None =
None, pin_attrib: int = 7)
Add a PIN to the pinCodes ProfileElement
class pySim.esim.saip.ProfileElementPuk(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for a PUK (PIN Unblocking Code)
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
add_puk(key_ref: int, puk_value: bytes, max_attempts: int = 10, retries_left: int = 10)
Add a PUK to the pukCodes ProfileElement
class pySim.esim.saip.ProfileElementRFM(decoded: dict | None = None, inst_aid: bytes | None = None,
sd_aid: bytes | None = None, adf_aid: bytes | None = None,
tar_list: List[bytes] | None = [], msl: int | None = 6, **kwargs)
Class representing the ProfileElement for RFM (Remote File Management).
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementSD(decoded: dict | None = None, **kwargs)
Class representing a securityDomain ProfileElement.
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class C9(**kwargs)

1.6. pySim eSIM libraries 103

osmopysim-usermanual

nested_collection_cls
alias of UiccSdInstallParams
add_key(key: SecurityDomainKey)
Add a given SecurityDomainKey to the keyList of the securityDomain.
add_scp(scp: int, i: int)
Add given SCP (and i parameter) to list of SCP of the Security Domain Install Params. Example:
add_scp(0x03, 0x70) for SCP03, or add_scp(0x02, 0x55) for SCP02.
find_key(key_version_number: int, key_id: int) → SecurityDomainKey | None
Find and return (if any) the SecurityDomainKey for given KVN + KID.
has_scp(scp: int) → bool
Determine if SD Installation parameters already specify given SCP.
remove_scp(scp: int)
Remove given SCP from list of SCP of the Security Domain Install Params.
class pySim.esim.saip.ProfileElementSSD(decoded: dict | None = None, **kwargs)
Class representing a securityDomain ProfileElement for a SSD.
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementSequence
A sequence of ProfileElement objects, which is the overall representation of an eSIM profile.
This primarily contains a list of PEs (pe_list member) as well as a number of convenience indexes like the
pe_by_type and pes_by_naa dicts that allow easier access to individual PEs within the sequence.
After calling the constructor, you have to further initialize the instance by either calling the parse_der() method,
or by manually adding individual PEs, including the header and end PEs.
add_file_at_path(path: Path, l: List)
Add a file at given path. This assumes that there’s only one instance of USIM/ISIM/CSIM inside the profile,
as otherwise the path name would not be globally unique.
add_hdr_and_end()
Initialize the PE Sequence with a header and end PE.
add_ssd(ssd: ProfileElementSSD)
Add a SSD (Supplementary Security Domain) After MNO-SD/ISD-P.
append(pe: ProfileElement)
Append a given PE to the end of the PE Sequence
cd(path: List[int])
Change the current directory to the [absolute] “path”.

104 Chapter 1. Introduction

 osmopysim-usermanual

property cur_df: FsNodeDF | None

Current DF; this is where the next files are created.
classmethod from_der(der: bytes) → ProfileElementSequence
Construct an instance from given raw, DER encoded bytes.
get_closest_prev_pe_for_templateID(cur: ProfileElement, tid: OID) → ProfileElement | None
Return the PE of given templateID that is the closest PE prior to the given PE in the PE-Sequence.
get_index_by_pe(pe: ProfileElement) → int
Return a list with the indicies of all instances of PEs of petype.
get_index_by_type(petype: str) → List[int]
Return a list with the indicies of all instances of PEs of petype.
get_pe_for_type(tname: str) → ProfileElement | None
Return a single profile element for given profile element type. Works only for types of which there is only
a single instance in the PE Sequence!
get_pes_for_templateID(tid: OID) → List[ProfileElement]
Return list of profile elements present for given profile element type.
get_pes_for_type(tname: str) → List[ProfileElement]
Return list of profile elements present for given profile element type.
property iccid: str | None
The ICCID of the profile.
insert_after_pe(pe_before: ProfileElement, pe_new: ProfileElement) → None
Insert a given [new] ProfileElement after a given [existing] PE in the PE Sequence.
insert_at_index(idx: int, pe: ProfileElement) → None
Insert a given [new] ProfileElement at given index into the PE Sequence.
static naa_for_path(path: Path) → Naa | None
determine the NAA for the given path
parse_der(der: bytes) → None
Parse a sequence of PE from SAIP DER format and store the result in self.pe_list.
pe_for_path(path: Path) → ProfileElement | None
Return the ProfileElement instance that can contain a file with matching path. This will either be an existing
PE within the sequence, or it will be a newly-allocated PE that is inserted into the sequence.
static peclass_for_path(path: Path) → ProfileElement | None
Return the ProfileElement class that can contain a file with given path.
rebuild_mandatory_gfstelist()
(Re-)build the eUICC Mandatory GFSTEList of the ProfileHeader based on what’s in the PE-Sequence.
You would normally call this at the very end, before encoding a PE-Sequence to its DER format.
rebuild_mandatory_services()
(Re-)build the eUICC Mandatory services list of the ProfileHeader based on what’s in the PE-Sequence.
You would normally call this at the very end, before encoding a PE-Sequence to its DER format.

1.6. pySim eSIM libraries 105

osmopysim-usermanual

remove_naas_of_type(naa: Naa) → None

Remove all instances of NAAs of given type. This can be used, for example, to remove all CSIM NAAs from
a profile. Will not just remove the PEs, but also any records in ‘eUICC-Mandatory-services’ or ‘eUICC-
Mandatory-GFSTEList’.
renumber_identification()
Re-generate the ‘identification’ numbering of all PE headers.
to_der() → bytes
Build an encoded DER representation of the instance.
class pySim.esim.saip.ProfileElementTelecom(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for DF.TELECOM
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.ProfileElementUSIM(decoded: dict | None = None, **kwargs)
Class representing the ProfileElement for ADF.USIM Mandatory Files
Instantiate a new ProfileElement. This is usually either called with the ‘decoded’ argument after reading a SAIP-
DER-encoded PE. Alternatively, when constructing a PE from scratch, decoded is None, and a minimal PE-
Header is generated.
Parameters
• decoded – asn1tools-generated decoded structure for this PE
• mandated – Whether or not the PE-Header should contain the mandated attribute
• pe_sequence – back-reference to the PE-Sequence of which we’re part of
class pySim.esim.saip.SecurityDomainKey(key_version_number: int, key_id: int, key_usage_qualifier: dict,
key_components: List[SecurityDomainKeyComponent])
Representation of a key used for SCP access to a security domain.
classmethod from_saip_dict(saip: dict) → SecurityDomainKey
Construct instance from the dict as generated by SAIP asn.1 decoder.
to_saip_dict() → dict
Express instance in the dict format required by SAIP asn.1 encoder.
class pySim.esim.saip.SecurityDomainKeyComponent(key_type: str, key_data: bytes, mac_length: int = 8)
Representation of a key-component of a key for a security domain.
classmethod from_saip_dict(saip: dict) → SecurityDomainKeyComponent
Construct instance from the dict as generated by SAIP asn.1 decoder.
to_saip_dict() → dict
Express instance in the dict format required by SAIP asn.1 encoder.
pySim.esim.saip.bertlv_first_segment(binary: bytes) → Tuple[bytes, bytes]
obtain the first segment of a binary concatenation of BER-TLV objects. Returns: tuple of first TLV and remainder.

106 Chapter 1. Introduction

 osmopysim-usermanual

pySim.esim.saip.oid
Implementation of SimAlliance/TCA Interoperable Profile OIDs
class pySim.esim.saip.oid.eOID(initializer)
OID helper for TCA eUICC prefix

pySim.esim.saip.personalization
Implementation of Personalization of eSIM profiles in SimAlliance/TCA Interoperable Profile.
class pySim.esim.saip.personalization.Adm1(input_value)

class pySim.esim.saip.personalization.Adm2(input_value)

class pySim.esim.saip.personalization.AlgoConfig(input_value)
Configurable Algorithm parameter.
validate()
Optional validation method. Can be used by derived classes to perform validation of the input value
(self.value). Will raise an exception if validation fails.
class pySim.esim.saip.personalization.AlgorithmID(input_value)

validate()
Optional validation method. Can be used by derived classes to perform validation of the input value
(self.value). Will raise an exception if validation fails.
class pySim.esim.saip.personalization.AppPin(input_value)
Configurable PIN (Personal Identification Number). String of digits.
validate()
Optional validation method. Can be used by derived classes to perform validation of the input value
(self.value). Will raise an exception if validation fails.
class pySim.esim.saip.personalization.ClassVarMeta(name, bases, namespace, **kwargs)
Metaclass that puts all additional keyword-args into the class. We use this to have one class definition for some-
thing like a PIN, and then have derived classes for PIN1, PIN2, . . .
class pySim.esim.saip.personalization.ConfigurableParameter(input_value)
Base class representing a part of the eSIM profile that is configurable during the personalization process (with
dynamic data from elsewhere).
validate()
Optional validation method. Can be used by derived classes to perform validation of the input value
(self.value). Will raise an exception if validation fails.
class pySim.esim.saip.personalization.Iccid(input_value)
Configurable ICCID. Expects the value to be a string of decimal digits. If the string of digits is only 18 digits
long, a Luhn check digit will be added.
validate()
Optional validation method. Can be used by derived classes to perform validation of the input value
(self.value). Will raise an exception if validation fails.
class pySim.esim.saip.personalization.Imsi(input_value)
Configurable IMSI. Expects value to be a string of digits. Automatically sets the ACC to the last digit of the
IMSI.

1.6. pySim eSIM libraries 107

osmopysim-usermanual

validate()
Optional validation method. Can be used by derived classes to perform validation of the input value
(self.value). Will raise an exception if validation fails.
class pySim.esim.saip.personalization.K(input_value)

class pySim.esim.saip.personalization.Opc(input_value)

class pySim.esim.saip.personalization.Pin(input_value)
Configurable PIN (Personal Identification Number). String of digits.
validate()
Optional validation method. Can be used by derived classes to perform validation of the input value
(self.value). Will raise an exception if validation fails.
class pySim.esim.saip.personalization.Pin1(input_value)

class pySim.esim.saip.personalization.Pin2(input_value)

class pySim.esim.saip.personalization.Puk(input_value)
Configurable PUK (Pin Unblock Code). String ASCII-encoded digits.
validate()
Optional validation method. Can be used by derived classes to perform validation of the input value
(self.value). Will raise an exception if validation fails.
class pySim.esim.saip.personalization.Puk1(input_value)

class pySim.esim.saip.personalization.Puk2(input_value)

class pySim.esim.saip.personalization.SdKey(input_value)
Configurable Security Domain (SD) Key. Value is presented as bytes.
validate()
Optional validation method. Can be used by derived classes to perform validation of the input value
(self.value). Will raise an exception if validation fails.
class pySim.esim.saip.personalization.SdKeyScp02_20(input_value)

class pySim.esim.saip.personalization.SdKeyScp02_20Dek(input_value)

class pySim.esim.saip.personalization.SdKeyScp02_20Enc(input_value)

class pySim.esim.saip.personalization.SdKeyScp02_20Mac(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_30(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_30Dek(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_30Enc(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_30Mac(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_31(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_31Dek(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_31Enc(input_value)

108 Chapter 1. Introduction

 osmopysim-usermanual

class pySim.esim.saip.personalization.SdKeyScp03_31Mac(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_32(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_32Dek(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_32Enc(input_value)

class pySim.esim.saip.personalization.SdKeyScp03_32Mac(input_value)

class pySim.esim.saip.personalization.SdKeyScp80_01(input_value)

class pySim.esim.saip.personalization.SdKeyScp80_01Kic(input_value)

class pySim.esim.saip.personalization.SdKeyScp80_01Kid(input_value)

class pySim.esim.saip.personalization.SdKeyScp80_01Kik(input_value)

class pySim.esim.saip.personalization.SdKeyScp81_01(input_value)

class pySim.esim.saip.personalization.SdKeyScp81_01Dek(input_value)

class pySim.esim.saip.personalization.SdKeyScp81_01Psk(input_value)

pySim.esim.saip.personalization.file_replace_content(file: List[Tuple], new_content: bytes)

Completely replace all fillFileContent of a decoded ‘File’ with the new_content.
pySim.esim.saip.personalization.remove_unwanted_tuples_from_list(l: List[Tuple], unwanted_keys:
List[str]) → List[Tuple]
In a list of tuples, remove all tuples whose first part equals ‘unwanted_key’.

pySim.esim.saip.templates
Implementation of SimAlliance/TCA Interoperable Profile Templates.
class pySim.esim.saip.templates.FileTemplate(fid: int, name: str, ftype, nb_rec: int | None, size: int |
None, arr: int, sfi: int | None = None, default_val: str |
None = None, content_rqd: bool = True, params: List |
None = None, ass_serv: List[int] | None = None,
high_update: bool = False, pe_name: str | None = None,
repeat: bool = False, ppath: List[int] = [])
Representation of a single file in a SimAlliance/TCA Profile Template. The argument order is done to match that
of the tables in Section 9 of the SAIP specification.
Parameters
• fid – The 16bit file-identifier of the file
• name – The name of the file in human-readable “EF.FOO”, “DF.BAR” notation
• ftype – The type of the file; can be ‘MF’, ‘ADF’, ‘DF’, ‘TR’, ‘LF’, ‘CY’, ‘BT’
• nb_rec – Then number of records (only valid for ‘LF’ and ‘CY’)
• size – The size of the file (‘TR’, ‘BT’); size of each record (‘LF, ‘CY’)
• arr – The record number of EF.ARR for referenced access rules
• sfi – The short file identifier, if any
• default_val – The default value [pattern] of the file
• content_rqd – Whether an instance of template must specify file contents

1.6. pySim eSIM libraries 109

osmopysim-usermanual

• params – A list of parameters that an instance of the template must specify

• ass_serv – The associated service[s] of the service table
• high_update – Is this file of “high update frequency” type?
• pe_name – The name of this file in the ASN.1 type of the PE. Auto-generated for most.
• repeat – Whether the default_val pattern is a repeating pattern.
• ppath – The intermediate path between the base_df of the ProfileTemplate and this file. If
not specified, the file will be created immediately underneath the base_df.
expand_default_value_pattern(length: int | None = None) → bytes | None
Expand the default value pattern to the specified length.
get_file_by_path(path: List[str]) → FileTemplate | None
Return a FileTemplate matching the given path within this ProfileTemplate.
property path
Return the path of the given File within the hierarchy.
print_tree(indent: str = '')
recursive printing of FileTemplate tree structure.
class pySim.esim.saip.templates.FilesAtMF
Files at MF as per Section 9.2
class pySim.esim.saip.templates.FilesCD
Files at DF.CD as per Section 9.3
class pySim.esim.saip.templates.FilesDf5GProSe
DF.ProSe Files at ADF.USIM as per Section 9.5.14
parent
alias of FilesUsimMandatory
class pySim.esim.saip.templates.FilesDfSnpn
DF.SNPN Files at ADF.USIM as per Section 9.5.13
parent
alias of FilesUsimMandatory
class pySim.esim.saip.templates.FilesEap
Files at DF.EAP as per Section 9.8
class pySim.esim.saip.templates.FilesIsimMandatory
Mandatory Files at ADF.ISIM as per Section 9.6.1
class pySim.esim.saip.templates.FilesIsimOptional
Optional Files at ADF.ISIM as per Section 9.6.2 of v2.3.1
extends
alias of FilesIsimMandatory
class pySim.esim.saip.templates.FilesIsimOptionalv2
Optional Files at ADF.ISIM as per Section 9.6.2
extends
alias of FilesIsimMandatory

110 Chapter 1. Introduction

 osmopysim-usermanual

class pySim.esim.saip.templates.FilesTelecom
Files at DF.TELECOM as per Section 9.4 v2.3.1
class pySim.esim.saip.templates.FilesTelecomV2
Files at DF.TELECOM as per Section 9.4
class pySim.esim.saip.templates.FilesUsimDf5GS
DF.5GS Files at ADF.USIM as per Section 9.5.11 v2.3.1
parent
alias of FilesUsimMandatory
class pySim.esim.saip.templates.FilesUsimDf5GSv2
DF.5GS Files at ADF.USIM as per Section 9.5.11.2
parent
alias of FilesUsimMandatory
class pySim.esim.saip.templates.FilesUsimDf5GSv3
DF.5GS Files at ADF.USIM as per Section 9.5.11.3
parent
alias of FilesUsimMandatory
class pySim.esim.saip.templates.FilesUsimDf5GSv4
DF.5GS Files at ADF.USIM as per Section 9.5.11.4
parent
alias of FilesUsimMandatory
class pySim.esim.saip.templates.FilesUsimDfGsmAccess
DF.GSM-ACCESS Files at ADF.USIM as per Section 9.5.4
parent
alias of FilesUsimMandatory
class pySim.esim.saip.templates.FilesUsimDfPhonebook
DF.PHONEBOOK Files at ADF.USIM as per Section 9.5.3
class pySim.esim.saip.templates.FilesUsimDfSaip
DF.SAIP Files at ADF.USIM as per Section 9.5.12
parent
alias of FilesUsimMandatory
class pySim.esim.saip.templates.FilesUsimMandatory
Mandatory Files at ADF.USIM as per Section 9.5.1 v2.3.1
class pySim.esim.saip.templates.FilesUsimMandatoryV2
Mandatory Files at ADF.USIM as per Section 9.5.1
class pySim.esim.saip.templates.FilesUsimOptional
Optional Files at ADF.USIM as per Section 9.5.2 v2.3.1
extends
alias of FilesUsimMandatory

1.6. pySim eSIM libraries 111

osmopysim-usermanual

class pySim.esim.saip.templates.FilesUsimOptionalV2
Optional Files at ADF.USIM as per Section 9.5.2
extends
alias of FilesUsimMandatoryV2
class pySim.esim.saip.templates.FilesUsimOptionalV3
Optional Files at ADF.USIM as per Section 9.5.2.3 v3.3.1
extends
alias of FilesUsimMandatoryV2
class pySim.esim.saip.templates.ProfileTemplate
Representation of a SimAlliance/TCA Profile Template. Each Template is identified by its OID and consists of
a number of file definitions. We implement each profile template as a class derived from this base class. Each
such derived class is a singleton and has no instances.
classmethod base_df() → FileTemplate
Return the FileTemplate for the base DF of the given template. This may be a DF or ADF within this
template, or refer to another template (e.g. mandatory USIM if we are optional USIM.
class pySim.esim.saip.templates.ProfileTemplateRegistry
A registry of profile templates. Exists as a singleton class with no instances and only classmethods.
classmethod add(tpl: ProfileTemplate)
Add a ProfileTemplate to the registry. There can only be one Template per OID.
classmethod get_by_oid(oid: List[int] | str) → ProfileTemplate | None
Look-up the ProfileTemplate based on its OID. The OID can be given either in dotted-string format, or as
a list of integers.
class pySim.esim.saip.templates.SaipSpecVersion
Represents a specific version of the SIMalliance / TCA eUICC Profile Package: Interoperable Format Technical
Specification.
static for_version(req_version: str) → SaipSpecVersion | None
Return the subclass for the requested version number string.
classmethod suports_template_OID(OID: OID) → bool
Return if a given spec version supports a template of given OID.
classmethod version_match(ver: str) → bool
Check if the given version-string matches the classes version. trailing zeroes are ignored, so that for example
2.2.0 will be considered equal to 2.2
class pySim.esim.saip.templates.SaipSpecVersion101

class pySim.esim.saip.templates.SaipSpecVersion20

class pySim.esim.saip.templates.SaipSpecVersion21

class pySim.esim.saip.templates.SaipSpecVersion22

class pySim.esim.saip.templates.SaipSpecVersion23

class pySim.esim.saip.templates.SaipSpecVersion231

class pySim.esim.saip.templates.SaipSpecVersion31

112 Chapter 1. Introduction

 osmopysim-usermanual

class pySim.esim.saip.templates.SaipSpecVersion32

class pySim.esim.saip.templates.SaipSpecVersion331

pySim.esim.saip.validation
Implementation of SimAlliance/TCA Interoperable Profile validation.
class pySim.esim.saip.validation.CheckBasicStructure
ProfileConstraintChecker for the basic profile structure constraints.
check_identification_unique(pes: ProfileElementSequence)
Ensure that each PE has a unique identification value.
check_mandatory_services(pes: ProfileElementSequence)
Ensure that the PE for the mandatory services exist.
check_number_of_occurrence(pes: ProfileElementSequence)
Check The number of occurrence of various ProfileElements.
check_optional_ordering(pes: ProfileElementSequence)
Check the ordering of optional PEs following the respective mandatory ones.
check_start_and_end(pes: ProfileElementSequence)
Check for mandatory header and end ProfileElements at the right position.
class pySim.esim.saip.validation.FileCheckBasicStructure
Validator for the basic structure of a decoded file.
check_forbidden(l: List[Tuple])
Perform checks for forbidden parameters as described in Section 8.3.3.
check_seqence(l: List[Tuple])
Check the sequence/ordering.
exception pySim.esim.saip.validation.FileError
Raised when a FileConstraintChecker finds an error in a file [structure].
class pySim.esim.saip.validation.ProfileConstraintChecker
Base class of a constraint checker for a ProfileElementSequence.
check(pes: ProfileElementSequence)
Execute all the check_* methods of the ProfileConstraintChecker against the given ProfileElementSequence
exception pySim.esim.saip.validation.ProfileError
Raised when a ProfileConstraintChecker finds an error in a file [structure].

1.7 osmo-smdpp
osmo-smdpp is a proof-of-concept implementation of a minimal SM-DP+ as specified for the GSMA Consumer eSIM
Remote SIM provisioning.
At least at this point, it is intended to be used for research and development, and not as a production SM-DP+.
Unless you are a GSMA SAS-SM accredited SM-DP+ operator and have related DPtls, DPauth and DPpb certifi-
cates signed by the GSMA CI, you can not use osmo-smdpp with regular production eUICC. This is due to how
the GSMA eSIM security architecture works. You can, however, use osmo-smdpp with so-called test-eUICC, which
contain certificates/keys signed by GSMA test certificates as laid out in GSMA SGP.26.

1.7. osmo-smdpp 113

osmopysim-usermanual

At this point, osmo-smdpp does not support anything beyond the bare minimum required to download eSIM profiles
to an eUICC. Specifically, there is no ES2+ interface, and there is no built-in support for profile personalization yet.
osmo-smdpp currently
• [by default] uses test certificates copied from GSMA SGP.26 into ./smdpp-data/certs, assuming that your osmo-
smdpp would be running at the host name testsmdpplus1.example.com. You can of course replace those certifi-
cates with your own, whether SGP.26 derived or part of a private root CA setup with mathcing eUICCs.
• doesn’t understand profile state. Any profile can always be downloaded any number of times, irrespective of the
EID or whether it was donwloaded before. This is actually very useful for R&D and testing, as it doesn’t require
you to generate new profiles all the time. This logic of course is unsuitable for production usage.
• doesn’t perform any personalization, so the IMSI/ICCID etc. are always identical (the ones that are stored in the
respective UPP .der files)
• is absolutely insecure, as it
• does not perform all of the mandatory certificate verification (it checks the certificate chain, but not the expiration
dates nor any CRL)
• does not evaluate/consider any Confirmation Code
• stores the sessions in an unencrypted python shelve and is hence leaking one-time key materials used for profile
encryption and signing.

1.7.1 Running osmo-smdpp

osmo-smdpp does not have built-in TLS support as the used twisted framework appears to have problems when using
the example elliptic curve certificates (both NIST and Brainpool) from GSMA.
So in order to use it, you have to put it behind a TLS reverse proxy, which terminates the ES9+ HTTPS from the LPA,
and then forwards it as plain HTTP to osmo-smdpp.

nginx as TLS proxy

If you use nginx as web server, you can use the following configuration snippet:

upstream smdpp {
server localhost:8000;
}

server {
listen 443 ssl;
server_name testsmdpplus1.example.com;

ssl_certificate /my/path/to/pysim/smdpp-data/certs/DPtls/CERT_S_SM_DP_TLS_NIST.
˓→pem;
ssl_certificate_key /my/path/to/pysim/smdpp-data/certs/DPtls/SK_S_SM_DP_TLS_NIST.
˓→pem;

location / {
proxy_read_timeout 600s;

proxy_hide_header X-Powered-By;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
(continues on next page)

114 Chapter 1. Introduction

 osmopysim-usermanual

(continued from previous page)

proxy_set_header X-Forwarded-Port $proxy_port;
proxy_set_header Host $host;

proxy_pass http://smdpp/;
}
}

You can of course achieve a similar functionality with apache, lighttpd or many other web server software.

supplementary files
The smdpp-data/certs directory contains the DPtls, DPauth and DPpb as well as CI certificates used; they are copied
from GSMA SGP.26 v2. You can of course replace them with custom certificates if you’re operating eSIM with a
private root CA.
The smdpp-data/upp directory contains the UPP (Unprotected Profile Package) used. The file names (without .der
suffix) are looked up by the matchingID parameter from the activation code presented by the LPA.

commandline options
Typically, you just run it without any arguments, and it will bind its plain-HTTP ES9+ interface to localhost TCP port
8000.
osmo-smdpp currently doesn’t have any configuration file.
There are command line options for binding:
Bind the HTTP ES9+ to a port other than 8000:

./osmo-smdpp.py -p 8001

Bind the HTTP ES9+ to a different local interface:

./osmo-smdpp.py -H 127.0.0.1

DNS setup for your LPA

The LPA must resolve testsmdpplus1.example.com to the IP address of your TLS proxy.
It must also accept the TLS certificates used by your TLS proxy.

Supported eUICC
If you run osmo-smdpp with the included SGP.26 certificates, you must use an eUICC with matching SGP.26 certifi-
cates, i.e. the EUM certificate must be signed by a SGP.26 test root CA and the eUICC certificate in turn must be signed
by that SGP.26 EUM certificate.
sysmocom (sponsoring development and maintenance of pySim and osmo-smdpp) is selling SGP.26 test eUICC as
sysmoEUICC1-C2T. They are publicly sold in the sysmocom webshop.
In general you can use osmo-smdpp also with certificates signed by any other certificate authority. You just always
must ensure that the certificates of the SM-DP+ are signed by the same root CA as those of your eUICCs.
Hypothetically, osmo-smdpp could also be operated with GSMA production certificates, but it would require that
somebody brings the code in-line with all the GSMA security requirements (HSM support, . . . ) and operate it in a
GSMA SAS-SM accredited environment and pays for the related audits.

1.7. osmo-smdpp 115

osmopysim-usermanual

1.8 sim-rest-server
Sometimes there are use cases where a [remote] application will need access to a USIM for authentication purposes.
This is, for example, in case an IMS test client needs to perform USIM based authentication against an IMS core.
The pysim repository contains two programs: sim-rest-server.py and sim-rest-client.py that implement a simple ap-
proach to achieve the above:
sim-rest-server.py speaks to a [usually local] USIM via the PC/SC API and provides a high-level REST API towards
[local or remote] applications that wish to perform UMTS AKA using the USIM.
sim-rest-client.py implements a small example client program to illustrate how the REST API provided by sim-rest-
server.py can be used.

1.8.1 REST API Calls

POST /sim-auth-api/v1/slot/SLOT_NR
where SLOT_NR is the integer-encoded slot number (corresponds to PC/SC reader number). When using a single
sysmoOCTSIM board, this is in the range of 0..7
Example: /sim-auth-api/v1/slot/0 for the first slot.

Request Body

The request body is a JSON document, comprising of

1. the RAND and AUTN parameters as hex-encoded string
2. the application against which to authenticate (USIM, ISIM)
Example:

{
"rand": "bb685a4b2fc4d697b9d6a129dd09a091",
"autn": "eea7906f8210000004faf4a7df279b56"
}

HTTP Status Codes

HTTP status codes are used to represent errors within the REST server and the SIM reader hardware. They are not
used to communicate protocol level errors reported by the SIM Card. An unsuccessful authentication will hence have
a 200 OK HTTP Status code and then encode the SIM specific error information in the Response Body.

Status Code Description

200 OK Successful execution
400 Bad Request Request body is malformed
404 Not Found Specified SIM Slot doesn’t exist
410 Gone No SIM card inserted in slot

Response Body

The response body is a JSON document, either

1. a successful outcome; encoding RES, CK, IK as hex-encoded string
2. a sync failure; encoding AUTS as hex-encoded string

116 Chapter 1. Introduction

 osmopysim-usermanual

3. errors #. authentication error (incorrect MAC) #. authentication error (security context not supported) #. key
freshness failure #. unspecified card error
Example (succcess):

{
"successful_3g_authentication": {
"res": "b15379540ec93985",
"ck": "713fde72c28cbd282a4cd4565f3d6381",
"ik": "2e641727c95781f1020d319a0594f31a",
"kc": "771a2c995172ac42"
}
}

Example (re-sync case):

{
"synchronisation_failure": {
"auts": "dc2a591fe072c92d7c46ecfe97e5"
}
}

1.8.2 Concrete example using the included sysmoISIM-SJA2

This was tested using SIMs ending in IMSI numbers 45890. . . 45899
The following command were executed successfully:
Slot 0

$ /usr/local/src/pysim/contrib/sim-rest-client.py -c 1 -n 0 -k␣
˓→841EAD87BC9D974ECA1C167409357601 -o 3211CACDD64F51C3FD3013ECD9A582A0

-> {'rand': 'fb195c7873b20affa278887920b9dd57', 'autn': 'd420895a6aa2000089cd016f8d8ae67c

˓→'}

<- {'successful_3g_authentication': {'res': '131004db2ff1ce8e', 'ck':

˓→'d42eb5aa085307903271b2422b698bad', 'ik': '485f81e6fd957fe3cad374adf12fe1ca', 'kc':

˓→'64d3f2a32f801214'}}

Slot 1

$ /usr/local/src/pysim/contrib/sim-rest-client.py -c 1 -n 1 -k␣
˓→5C2CE9633FF9B502B519A4EACD16D9DF -o 9834D619E71A02CD76F00CC7AA34FB32

-> {'rand': '433dc5553db95588f1d8b93870930b66', 'autn': '126bafdcbe9e00000026a208da61075d

˓→'}

<- {'successful_3g_authentication': {'res': '026d7ac42d379207', 'ck':

˓→'83a90ba331f47a95c27a550b174c4a1f', 'ik': '31e1d10329ffaf0ca1684a1bf0b0a14a', 'kc':

˓→'d15ac5b0fff73ecc'}}

1.9 suci-keytool
Subscriber concealment is an important feature of the 5G SA architecture: It avoids the many privacy issues associated
with having a permanent identifier (SUPI, traditionally the IMSI) transmitted in plain text over the air interface. Using
SUCI solves this issue not just for the air interface; it even ensures the SUPI/IMSI is not known to the visited network
(VPLMN) at all.

1.9. suci-keytool 117

osmopysim-usermanual

In principle, the SUCI mechanism works by encrypting the SUPI by asymmetric (public key) cryptography: Only the
HPLMN is in possession of the private key and hence can decrypt the SUCI to the SUPI, while each subscriber has the
public key in order to encrypt their SUPI into the SUCI. In reality, the details are more complex, as there are ephemeral
keys and cryptographic MAC involved.
In any case, in order to operate a SUCI-enabled 5G SA network, you will have to
1. generate a ECC key pair of public + private key
2. deploy the public key on your USIMs
3. deploy the private key on your 5GC, specifically the UDM function
pysim contains (int its contrib directory) a small utility program that can make it easy to generate such keys: suci-
keytool.py

1.9.1 Generating keys

Example: Generating a secp256r1 ECC public key pair and storing it to /tmp/suci.key:

$ ./contrib/suci-keytool.py --key-file /tmp/suci.key generate-key --curve secp256r1

1.9.2 Dumping public keys

In order to store the key to SIM cards as part of ADF.USIM/DF.5GS/EF.SUCI_Calc_Info, you will need a hexadecimal
representation of the public key. You can achieve that using the dump-pub-key operation of suci-keytool:
Example: Dumping the public key part from a previously generated key file:

$ ./contrib/suci-keytool.py --key-file /tmp/suci.key dump-pub-key

0473152f32523725f5175d255da2bd909de97b1d06449a9277bc629fe42112f8643e6b69aa6dce6c86714ccbe6f2e0f4f4898d10

If you want the point-compressed representation, you can use the –compressed option:

$ ./contrib/suci-keytool.py --key-file /tmp/suci.key dump-pub-key --compressed

0373152f32523725f5175d255da2bd909de97b1d06449a9277bc629fe42112f864

1.9.3 suci-keytool syntax

Generate or export SUCI keys for 5G SA networks

usage: contrib/suci-keytool.py [-h] --key-file KEY_FILE

{generate-key,dump-pub-key} ...

Positional Arguments
command Possible choices: generate-key, dump-pub-key
The command to perform

Named Arguments
--key-file The key file to use

118 Chapter 1. Introduction

 osmopysim-usermanual

Sub-commands
generate-key

Generate a new key pair

contrib/suci-keytool.py generate-key [-h] --curve {secp256r1,curve25519}

Named Arguments

--curve Possible choices: secp256r1, curve25519

The ECC curve to use

dump-pub-key

Dump the public key

contrib/suci-keytool.py dump-pub-key [-h] [--compressed]

Named Arguments

--compressed Use point compression

Default: False

1.10 saip-tool
eSIM profiles are stored as a sequence of profile element (PE) objects in an ASN.1 DER encoded binary file. To inspect,
verify or make changes to those files, the saip-tool.py utility can be used.
NOTE: The file format, eSIM SAIP (SimAlliance Interoperable Profile) is specified in TCA eUICC Profile Package:
Interoperable Format Technical Specification

1.10.1 Profile Package Examples

pySim ships with a set of TS48 profile package examples. Those examples can be found in pysim/smdpp-data/upp. The
files can be used as input for saip-tool.py. (see also GSMA TS.48 - Generic eUICC Test Profile for Device Testing)
See also: https://github.com/GSMATerminals/Generic-eUICC-Test-Profile-for-Device-Testing-Public

1.10.2 JAVA card applets

The saip-tool.py can also be used to manage JAVA-card applets (Application PE) inside a profile package. The user has
the option to add, remove and inspect applications and their instances. In the following we will discuss a few JAVA-card
related use-cases of saip-tool.py
NOTE: see also contrib folder for script examples (saip-tool_example_*.sh)

Inserting applications
An application is usually inserted in two steps. In the first step, the application PE is created and populated with the
executable code from a provided .cap or .ijc file. The user also has to pick a suitable load block AID.
The application instance, which exists inside the application PE, is created in a second step. Here the user must reference
the load block AID and pick, among other application related parameters, a suitable class and instance AID.
Example: Adding a JAVA-card applet to an existing profile package

1.10. saip-tool 119

osmopysim-usermanual

# Step #1: Create the application PE and load the ijc contents from the .cap file:
$ ./contrib/saip-tool.py upp.der add-app --output-file upp_with_app.der --applet-file␣
˓→app.cap --aid '1122334455'

Read 28 PEs from file 'upp.der'

Applying applet file: 'app.cap'...
application PE inserted into PE Sequence after securityDomain PE AID: a000000151000000
Writing 29 PEs to file 'upp_with_app.der'...

# Step #2: Create the application instance inside the application PE created in step #1:
$ ./contrib/saip-tool.py upp_with_app.der add-app-inst --output-file upp_with_app_and_
˓→instance.der \

--aid '1122334455' \
--class-aid '112233445501' \
--inst-aid '112233445501' \
--app-privileges '00' \
--app-spec-pars '00' \
--uicc-toolkit-app-spec-pars '01001505000000000000000000000000'
Read 29 PEs from file 'upp_with_app.der'
Found Load Package AID: 1122334455, adding new instance AID: 112233445501 to Application␣
˓→PE...

Writing 29 PEs to file 'upp_with_app_and_instance.der'...

NOTE: The parameters of the sub-commands add-app and add-app-inst are application specific. It is up to the ap-
plication developer to pick parameters that suit the application correctly. For an exact command reference see section
saip-tool syntax. For parameter details see TCA eUICC Profile Package: Interoperable Format Technical Specification,
section 8.7 and ETSI TS 102 226, section 8.2.1.3.2

Inspecting applications
To inspect the application PE contents of an existing profile package, sub-command info with parameter ‘–apps’ can
be used. This command lists out all application and their parameters in detail. This allows an application developer to
check if the applet insertaion was carried out as expected.
Example: Listing applications and their parameters

$ ./contrib/saip-tool.py upp_with_app_and_instance.der info --apps

Read 29 PEs from file 'upp_with_app_and_instance.der'
Application #0:
loadBlock:
loadPackageAID: '1122334455' (5 bytes)
loadBlockObject: '01000fdecaffed010204000105d07002ca440200...
˓→681080056810a00633b44104b431066800a10231' (569 bytes)

instanceList[0]:
applicationLoadPackageAID: '1122334455' (5 bytes)
classAID: '112233445501' (8 bytes)
instanceAID: '112233445501' (8 bytes)
applicationPrivileges: '00' (1 bytes)
lifeCycleState: '07' (1 bytes)
applicationSpecificParametersC9: '00' (1 bytes)
applicationParameters:
uiccToolkitApplicationSpecificParametersField:
˓→'01001505000000000000000000000000' (16 bytes)

In case further analysis with external tools or transfer of applications from one profile package to another is necessary,

120 Chapter 1. Introduction

 osmopysim-usermanual

the executable code in the loadBlockObject field can be extracted to an .ijc or an .cap file.
Example: Extracting applications from a profile package

$ ./contrib/saip-tool.py upp_with_app_and_instance.der extract-apps --output-dir ./apps -

˓→-format ijc

Read 29 PEs from file 'upp_with_app_and_instance.der'

Writing Load Package AID: 1122334455 to file ./apps/8949449999999990023f-1122334455.ijc

Removing applications
An application PE can be removed using sub-command remove-app. The user passes the load package AID as param-
eter. Then saip-tool.py will search for the related application PE and delete it from the PE sequence.
Example: Remove an application from a profile package

$ ./contrib/saip-tool.py upp_with_app_and_instance.der remove-app --output-file upp_

˓→without_app.der --aid '1122334455'

Read 29 PEs from file 'upp_with_app_and_instance.der'

Found Load Package AID: 1122334455, removing related PE (id=23) from Sequence...
Removing PE application (id=23) from Sequence...
Writing 28 PEs to file 'upp_without_app.der'...

In some cases it is useful to remove only an instance from an existing application PE. This may be the case when the
an application developer wants to modify parameters of an application by removing and re-adding the instance. The
operation basically rolls the state back to step 1 explained in section Inserting applications
Example: Remove an application instance from an application PE

$ ./contrib/saip-tool.py upp_with_app_and_instance.der remove-app-inst --output-file upp_

˓→without_app.der --aid '1122334455' --inst-aid '112233445501'

Read 29 PEs from file 'upp_with_app_and_instance.der'

Found Load Package AID: 1122334455, removing instance AID: 112233445501 from Application␣
˓→PE...

Removing instance from Application PE...

Writing 29 PEs to file 'upp_with_app.der'...

1.10.3 saip-tool syntax

Utility program to work with eSIM SAIP (SimAlliance Interoperable Profile) files.

usage: contrib/saip-tool.py [-h]

[--loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
[--debug]
INPUT_UPP
{split,dump,check,extract-pe,remove-pe,remove-naa,info,
˓→extract-apps,add-app,remove-app,add-app-inst,remove-app-inst,edit-mand-srv-list,tree}

...

1.10. saip-tool 121

osmopysim-usermanual

Positional Arguments
INPUT_UPP Unprotected Profile Package Input file
command Possible choices: split, dump, check, extract-pe, remove-pe, remove-naa, info,
extract-apps, add-app, remove-app, add-app-inst, remove-app-inst, edit-mand-
srv-list, tree
The command to perform

Named Arguments
--loglevel Possible choices: DEBUG, INFO, WARNING, ERROR, CRITICAL
Set the logging level
Default: “INFO”
--debug Enable DEBUG logging
Default: False

Sub-commands
split

Split PE-Sequence into individual PEs

contrib/saip-tool.py split [-h] [--output-prefix OUTPUT_PREFIX]

Named Arguments

--output-prefix Prefix path/filename for output files

Default: “.”

dump

Dump information on PE-Sequence

contrib/saip-tool.py dump [-h] [--dump-decoded]

{all_pe,all_pe_by_type,all_pe_by_naa}

Positional Arguments

mode Possible choices: all_pe, all_pe_by_type, all_pe_by_naa

Named Arguments

--dump-decoded Dump decoded PEs

Default: False

check

Run constraint checkers on PE-Sequence

contrib/saip-tool.py check [-h]

122 Chapter 1. Introduction

 osmopysim-usermanual

extract-pe

Extract specified PE to (DER encoded) file

contrib/saip-tool.py extract-pe [-h] --pe-file PE_FILE

[--identification IDENTIFICATION]

Named Arguments

--pe-file PE file name

--identification Extract PE matching specified identification

remove-pe

Remove specified PEs from PE-Sequence

contrib/saip-tool.py remove-pe [-h] --output-file OUTPUT_FILE

[--identification IDENTIFICATION] [--type TYPE]

Named Arguments

--output-file Output file name

--identification Remove PEs matching specified identification
Default: []
--type Remove PEs matching specified type
Default: []

remove-naa

Remove speciifed NAAs from PE-Sequence

contrib/saip-tool.py remove-naa [-h] --output-file OUTPUT_FILE --naa-type

{csim,usim,isim}

Named Arguments

--output-file Output file name

--naa-type Possible choices: csim, usim, isim
Network Access Application type to remove

info

Display information about the profile

contrib/saip-tool.py info [-h] [--apps]

1.10. saip-tool 123

osmopysim-usermanual

Named Arguments

--apps List applications and their related instances

Default: False

extract-apps

Extract applications as loadblock file

contrib/saip-tool.py extract-apps [-h] [--output-dir OUTPUT_DIR]

[--format {ijc,cap}]

Named Arguments

--output-dir Output directory (where to store files)

Default: “.”
--format Possible choices: ijc, cap
Data format of output files
Default: “cap”

add-app

Add application to PE-Sequence

contrib/saip-tool.py add-app [-h] --output-file OUTPUT_FILE --applet-file

APPLET_FILE --aid AID [--sd-aid SD_AID]
[--non-volatile-code-limit NON_VOLATILE_CODE_LIMIT]
[--volatile-data-limit VOLATILE_DATA_LIMIT]
[--non-volatile-data-limit NON_VOLATILE_DATA_LIMIT]
[--hash-value HASH_VALUE]

Named Arguments

--output-file Output file name

--applet-file Applet file name
--aid Load package AID
--sd-aid Security Domain AID
--non-volatile-code-limit Non volatile code limit (C6)
--volatile-data-limit Volatile data limit (C7)
--non-volatile-data-limit Non volatile data limit (C8)
--hash-value Hash value

remove-app

Remove application from PE-Sequence

contrib/saip-tool.py remove-app [-h] --output-file OUTPUT_FILE --aid AID

124 Chapter 1. Introduction

 osmopysim-usermanual

Named Arguments

--output-file Output file name

--aid Load package AID

add-app-inst

Add application instance to Application PE

contrib/saip-tool.py add-app-inst [-h] --output-file OUTPUT_FILE --aid AID

--class-aid CLASS_AID --inst-aid INST_AID
[--app-privileges APP_PRIVILEGES]
[--volatile-memory-quota VOLATILE_MEMORY_QUOTA]
[--non-volatile-memory-quota NON_VOLATILE_MEMORY_QUOTA]
[--app-spec-pars APP_SPEC_PARS]
[--uicc-toolkit-app-spec-pars UICC_TOOLKIT_APP_SPEC_
˓→PARS]

[--uicc-access-app-spec-pars UICC_ACCESS_APP_SPEC_PARS]
[--uicc-adm-access-app-spec-pars UICC_ADM_ACCESS_APP_
˓→SPEC_PARS]

[--process-data PROCESS_DATA]

Named Arguments

--output-file Output file name

--aid Load package AID
--class-aid Class AID
--inst-aid Instance AID (must match Load package AID)
--app-privileges Application privileges
Default: “000000”
--volatile-memory-quota Volatile memory quota (C7)
--non-volatile-memory-quota Non volatile memory quota (C8)
--app-spec-pars Application specific parameters (C9)
Default: “00”
--uicc-toolkit-app-spec-pars UICC toolkit application specific parameters field
--uicc-access-app-spec-pars UICC Access application specific parameters field
--uicc-adm-access-app-spec-pars UICC Administrative access application specific parameters field
--process-data Process personalization APDUs
Default: []

remove-app-inst

Remove application instance from Application PE

contrib/saip-tool.py remove-app-inst [-h] --output-file OUTPUT_FILE --aid AID

--inst-aid INST_AID

1.10. saip-tool 125

osmopysim-usermanual

Named Arguments

--output-file Output file name

--aid Load package AID
--inst-aid Instance AID

edit-mand-srv-list

Add/Remove service flag from/to mandatory services list

contrib/saip-tool.py edit-mand-srv-list [-h] --output-file OUTPUT_FILE

[--add-flag {contactless,usim,isim,csim,milenage,
˓→tuak128,cave,gba-usim,gba-isim,mbms,eap,javacard,multos,multiple-usim,multiple-isim,

˓→multiple-csim,tuak256,usim-test-algorithm,ber-tlv,dfLink,cat-tp,get-identity,profile-a-

˓→x25519,profile-b-p256,suciCalculatorApi,dns-resolution,scp11ac,scp11c-authorization-

˓→mechanism,s16mode,eaka}]

[--remove-flag {contactless,usim,isim,csim,
˓→milenage,tuak128,cave,gba-usim,gba-isim,mbms,eap,javacard,multos,multiple-usim,

˓→multiple-isim,multiple-csim,tuak256,usim-test-algorithm,ber-tlv,dfLink,cat-tp,get-

˓→identity,profile-a-x25519,profile-b-p256,suciCalculatorApi,dns-resolution,scp11ac,

˓→scp11c-authorization-mechanism,s16mode,eaka}]

Named Arguments

--output-file Output file name

--add-flag Possible choices: contactless, usim, isim, csim, milenage, tuak128, cave, gba-
usim, gba-isim, mbms, eap, javacard, multos, multiple-usim, multiple-isim,
multiple-csim, tuak256, usim-test-algorithm, ber-tlv, dfLink, cat-tp, get-identity,
profile-a-x25519, profile-b-p256, suciCalculatorApi, dns-resolution, scp11ac,
scp11c-authorization-mechanism, s16mode, eaka
Add flag to mandatory services list
Default: []
--remove-flag Possible choices: contactless, usim, isim, csim, milenage, tuak128, cave, gba-
usim, gba-isim, mbms, eap, javacard, multos, multiple-usim, multiple-isim,
multiple-csim, tuak256, usim-test-algorithm, ber-tlv, dfLink, cat-tp, get-identity,
profile-a-x25519, profile-b-p256, suciCalculatorApi, dns-resolution, scp11ac,
scp11c-authorization-mechanism, s16mode, eaka
Remove flag from mandatory services list
Default: []

tree

Display the filesystem tree

contrib/saip-tool.py tree [-h]

126 Chapter 1. Introduction

 CHAPTER

TWO

INDICES AND TABLES

• genindex
• modindex
• search

127
osmopysim-usermanual

128 Chapter 2. Indices and tables

 PYTHON MODULE INDEX

p
pySim.card_handler, 86
pySim.card_key_provider, 87
pySim.commands, 73
pySim.esim, 88
pySim.esim.bsp, 91
pySim.esim.es2p, 89
pySim.esim.es8p, 90
pySim.esim.es9p, 91
pySim.esim.http_json_api, 92
pySim.esim.rsp, 89
pySim.esim.saip, 94
pySim.esim.saip.oid, 107
pySim.esim.saip.personalization, 107
pySim.esim.saip.templates, 109
pySim.esim.saip.validation, 113
pySim.esim.x509_cert, 93
pySim.exceptions, 86
pySim.filesystem, 62
pySim.transport, 79
pySim.transport.calypso, 80
pySim.transport.modem_atcmd, 81
pySim.transport.pcsc, 81
pySim.transport.serial, 82
pySim.utils, 82

129
osmopysim-usermanual

130 Python Module Index

 INDEX

A 107
activate_file() (pySim.commands.SimCardCommands ApiError, 92
method), 73 ApiParam (class in pySim.esim.http_json_api), 92
ActivationCode (class in pySim.esim), 88 ApiParamBase64 (class in pySim.esim.http_json_api),
add() (pySim.esim.saip.templates.ProfileTemplateRegistry 92
class method), 112 ApiParamBoolean (class in pySim.esim.http_json_api),
add_application_df() (pySim.filesystem.CardMF 92
method), 66 ApiParamFqdn (class in pySim.esim.http_json_api), 92
add_child() (pySim.esim.saip.FsNodeDF method), 96 ApiParamInteger (class in pySim.esim.http_json_api),
add_file() (pySim.esim.saip.FsNodeDF method), 96 93
add_file() (pySim.esim.saip.FsProfileElement ApiParamString (class in pySim.esim.http_json_api),
method), 96 93
add_file() (pySim.filesystem.CardDF method), 64 append() (pySim.esim.saip.ProfileElementSequence
add_file_at_path() (pySim.esim.saip.ProfileElementSequence method), 104
method), 104 apply_matching_models()
add_files() (pySim.filesystem.CardDF method), 64 (pySim.filesystem.CardModel static method),
add_files() (pySim.filesystem.CardModel class 67
method), 67 AppPin (class in pySim.esim.saip.personalization), 107
add_hdr_and_end() (pySim.esim.saip.ProfileElementSequenceargparse_add_reader_args() (in module
method), 104 pySim.transport), 80
add_instance() (pySim.esim.saip.ProfileElementApplicationauthenticate() (pySim.commands.SimCardCommands
method), 98 method), 73
add_intermediate_cert() AuthenticateClient (class in pySim.esim.es9p), 91
(pySim.esim.x509_cert.CertificateSet method),
94 B
add_key() (pySim.esim.saip.ProfileElementSD method), base_df() (pySim.esim.saip.templates.ProfileTemplate
104 class method), 112
add_notification() (pySim.esim.es8p.ProfileMetadata bertlv_first_segment() (in module
method), 90 pySim.esim.saip), 106
add_pin() (pySim.esim.saip.ProfileElementPin BerTlvEF (class in pySim.filesystem), 62
method), 103 BerTlvEF.ShellCommands (class in pySim.filesystem),
add_puk() (pySim.esim.saip.ProfileElementPuk 62
method), 103 binary_size() (pySim.commands.SimCardCommands
add_scp() (pySim.esim.saip.ProfileElementSD method), method), 73
104 BoundProfilePackage (class in pySim.esim.es8p), 90
add_ssd() (pySim.esim.saip.ProfileElementSequence boxed_heading_str() (in module pySim.utils), 84
method), 104 bsp_key_derivation() (in module pySim.esim.bsp),
Adm1 (class in pySim.esim.saip.personalization), 107 92
Adm2 (class in pySim.esim.saip.personalization), 107 BspAlgo (class in pySim.esim.bsp), 91
AlgoConfig (class in pySim.esim.saip.personalization), BspAlgoCrypt (class in pySim.esim.bsp), 91
107 BspAlgoCryptAES128 (class in pySim.esim.bsp), 92
AlgorithmID (class in pySim.esim.saip.personalization), BspAlgoMac (class in pySim.esim.bsp), 92

131
osmopysim-usermanual

BspAlgoMacAES128 (class in pySim.esim.bsp), 92 cert_get_subject_key_id() (in module

BspInstance (class in pySim.esim.bsp), 92 pySim.esim.x509_cert), 94
build_select_path_to() (pySim.filesystem.CardFile cert_policy_has_oid() (in module
method), 65 pySim.esim.x509_cert), 94
CertAndPrivkey (class in pySim.esim.x509_cert), 93
C CertificateSet (class in pySim.esim.x509_cert), 94
calculate_luhn() (in module pySim.utils), 84 change_chv() (pySim.commands.SimCardCommands
call() (pySim.esim.http_json_api.JsonHttpApiFunction method), 73
method), 93 check() (pySim.esim.saip.validation.ProfileConstraintChecker
call_cancelOrder() (pySim.esim.es2p.Es2pApiClient method), 113
method), 90 check_forbidden() (pySim.esim.saip.validation.FileCheckBasicStructure
call_confirmOrder() method), 113
(pySim.esim.es2p.Es2pApiClient method), check_identification_unique()
90 (pySim.esim.saip.validation.CheckBasicStructure
call_downloadOrder() method), 113
(pySim.esim.es2p.Es2pApiClient method), check_mandatory_services()
90 (pySim.esim.saip.validation.CheckBasicStructure
call_handleDownloadProgressInfo() method), 113
(pySim.esim.es2p.Es2pApiClient method), check_number_of_occurrence()
90 (pySim.esim.saip.validation.CheckBasicStructure
call_releaseProfile() method), 113
(pySim.esim.es2p.Es2pApiClient method), check_optional_ordering()
90 (pySim.esim.saip.validation.CheckBasicStructure
CalypsoSimLink (class in pySim.transport.calypso), 80 method), 113
CancelOrder (class in pySim.esim.es2p), 89 check_seqence() (pySim.esim.saip.validation.FileCheckBasicStructure
CancelSession (class in pySim.esim.es9p), 91 method), 113
card_key_provider_get() (in module check_signed() (in module pySim.esim.x509_cert), 94
pySim.card_key_provider), 88 check_start_and_end()
card_key_provider_get_field() (in module (pySim.esim.saip.validation.CheckBasicStructure
pySim.card_key_provider), 88 method), 113
card_key_provider_register() (in module check_template_modification_rules()
pySim.card_key_provider), 88 (pySim.esim.saip.File method), 94
CardADF (class in pySim.filesystem), 63 CheckBasicStructure (class in
CardApplication (class in pySim.filesystem), 63 pySim.esim.saip.validation), 113
CardCommand (class in pySim.utils), 82 cla_with_lchan() (in module pySim.commands), 78
CardCommandSet (class in pySim.utils), 82 class_for_petype() (pySim.esim.saip.ProfileElement
CardDF (class in pySim.filesystem), 63 class method), 97
CardDF.ShellCommands (class in pySim.filesystem), 64 ClassVarMeta (class in
CardEF (class in pySim.filesystem), 64 pySim.esim.saip.personalization), 107
CardFile (class in pySim.filesystem), 65 compile_asn1_subdir() (in module pySim.esim), 89
CardHandler (class in pySim.card_handler), 86 ConfigurableParameter (class in
CardHandlerAuto (class in pySim.card_handler), 86 pySim.esim.saip.personalization), 107
CardHandlerBase (class in pySim.card_handler), 86 ConfirmOrder (class in pySim.esim.es2p), 89
CardKeyProvider (class in pySim.card_key_provider), connect() (pySim.transport.calypso.CalypsoSimLink
87 method), 80
CardKeyProviderCsv (class in connect() (pySim.transport.LinkBase method), 79
pySim.card_key_provider), 87 connect() (pySim.transport.modem_atcmd.ModemATCommandLink
CardMF (class in pySim.filesystem), 66 method), 81
CardModel (class in pySim.filesystem), 67 connect() (pySim.transport.pcsc.PcscSimLink method),
cd() (pySim.esim.saip.ProfileElementSequence method), 81
104 connect() (pySim.transport.serial.SerialSimLink
cert_get_auth_key_id() (in module method), 82
pySim.esim.x509_cert), 94 create_file() (pySim.commands.SimCardCommands
method), 73

132 Index
 osmopysim-usermanual

create_file() (pySim.esim.saip.FsProfileElement disconnect() (pySim.transport.calypso.CalypsoSimLink

method), 96 method), 80
cur_df (pySim.esim.saip.ProfileElementSequence prop- disconnect() (pySim.transport.LinkBase method), 79
erty), 104 disconnect() (pySim.transport.modem_atcmd.ModemATCommandLink
CyclicEF (class in pySim.filesystem), 67 method), 81
disconnect() (pySim.transport.pcsc.PcscSimLink
D method), 81
DataObject (class in pySim.utils), 82 disconnect() (pySim.transport.serial.SerialSimLink
DataObjectChoice (class in pySim.utils), 83 method), 82
DataObjectCollection (class in pySim.utils), 83 do_decode_hex() (pySim.filesystem.LinFixedEF.ShellCommands
DataObjectSequence (class in pySim.utils), 83 method), 68
deactivate_file() (pySim.commands.SimCardCommands do_decode_hex() (pySim.filesystem.TransparentEF.ShellCommands
method), 73 method), 71
dec_imsi() (in module pySim.utils), 84 do_delete_all() (pySim.filesystem.BerTlvEF.ShellCommands
decode() (pySim.esim.es8p.BoundProfilePackage method), 62
method), 90 do_delete_data() (pySim.filesystem.BerTlvEF.ShellCommands
decode() (pySim.esim.http_json_api.ApiParam class method), 63
method), 92 do_edit_binary_decoded()
decode() (pySim.esim.http_json_api.JsonHttpApiFunction (pySim.filesystem.TransparentEF.ShellCommands
method), 93 method), 71
decode() (pySim.utils.DataObject method), 83 do_edit_record_decoded()
decode() (pySim.utils.DataObjectChoice method), 83 (pySim.filesystem.LinFixedEF.ShellCommands
decode() (pySim.utils.DataObjectCollection method), method), 68
83 do_read_binary() (pySim.filesystem.TransparentEF.ShellCommands
decode() (pySim.utils.DataObjectSequence method), 84 method), 71
decode_bin() (pySim.filesystem.TransparentEF do_read_binary_decoded()
method), 71 (pySim.filesystem.TransparentEF.ShellCommands
decode_hex() (pySim.filesystem.TransparentEF method), 71
method), 72 do_read_record() (pySim.filesystem.LinFixedEF.ShellCommands
decode_multi() (pySim.utils.DataObjectSequence method), 68
method), 84 do_read_record_decoded()
decode_record_bin() (pySim.filesystem.LinFixedEF (pySim.filesystem.LinFixedEF.ShellCommands
method), 68 method), 68
decode_record_bin() (pySim.filesystem.TransRecEF do_read_records() (pySim.filesystem.LinFixedEF.ShellCommands
method), 70 method), 68
decode_record_hex() (pySim.filesystem.LinFixedEF do_read_records_decoded()
method), 69 (pySim.filesystem.LinFixedEF.ShellCommands
decode_record_hex() (pySim.filesystem.TransRecEF method), 68
method), 70 do_retrieve_data() (pySim.filesystem.BerTlvEF.ShellCommands
decode_select_response() method), 63
(pySim.filesystem.CardFile method), 65 do_retrieve_tags() (pySim.filesystem.BerTlvEF.ShellCommands
decode_select_response() method), 63
(pySim.filesystem.CardMF method), 66 do_set_data() (pySim.filesystem.BerTlvEF.ShellCommands
decode_str() (pySim.esim.ActivationCode static method), 63
method), 88 do_update_binary() (pySim.filesystem.TransparentEF.ShellCommands
decrypt() (pySim.esim.bsp.BspAlgoCrypt method), 91 method), 71
delete_file() (pySim.commands.SimCardCommands do_update_binary_decoded()
method), 73 (pySim.filesystem.TransparentEF.ShellCommands
derive_mcc() (in module pySim.utils), 84 method), 71
derive_milenage_opc() (in module pySim.utils), 84 do_update_record() (pySim.filesystem.LinFixedEF.ShellCommands
derive_mnc() (in module pySim.utils), 85 method), 68
disable_chv() (pySim.commands.SimCardCommands do_update_record_decoded()
method), 74 (pySim.filesystem.LinFixedEF.ShellCommands
method), 68

Index 133
osmopysim-usermanual

done() (pySim.card_handler.CardHandlerBase method), export() (pySim.filesystem.CardApplication static

86 method), 63
DownloadOrder (class in pySim.esim.es2p), 89 export() (pySim.filesystem.CardFile static method), 65
export() (pySim.filesystem.LinFixedEF static method),
E 69
ecdsa_dss_to_tr03111() (in module export() (pySim.filesystem.TransparentEF static
pySim.esim.x509_cert), 94 method), 72
ecdsa_sign() (pySim.esim.x509_cert.CertAndPrivkey extends (pySim.esim.saip.templates.FilesIsimOptional
method), 93 attribute), 110
enable_chv() (pySim.commands.SimCardCommands extends (pySim.esim.saip.templates.FilesIsimOptionalv2
method), 74 attribute), 110
enc_imsi() (in module pySim.utils), 85 extends (pySim.esim.saip.templates.FilesUsimOptional
enc_plmn() (in module pySim.utils), 85 attribute), 111
encode() (pySim.esim.es8p.BoundProfilePackage extends (pySim.esim.saip.templates.FilesUsimOptionalV2
method), 90 attribute), 112
encode() (pySim.esim.http_json_api.ApiParam class extends (pySim.esim.saip.templates.FilesUsimOptionalV3
method), 92 attribute), 112
encode() (pySim.esim.http_json_api.JsonHttpApiFunction extract_euiccSigned1() (in module pySim.esim.rsp),
method), 93 89
encode() (pySim.utils.DataObjectSequence method), 84 extract_euiccSigned2() (in module pySim.esim.rsp),
encode_bin() (pySim.filesystem.TransparentEF 89
method), 72
encode_hex() (pySim.filesystem.TransparentEF F
method), 72 fid_path (pySim.esim.saip.FsNode property), 95
encode_multi() (pySim.utils.DataObjectSequence File (class in pySim.esim.saip), 94
method), 84 file_content_from_tuples() (pySim.esim.saip.File
encode_record_bin() (pySim.filesystem.LinFixedEF method), 95
method), 69 file_replace_content() (in module
encode_record_bin() (pySim.filesystem.TransRecEF pySim.esim.saip.personalization), 109
method), 70 file_size (pySim.esim.saip.File property), 95
encode_record_hex() (pySim.filesystem.LinFixedEF file_template_for_path()
method), 69 (pySim.esim.saip.FsProfileElement method),
encode_record_hex() (pySim.filesystem.TransRecEF 96
method), 71 FileCheckBasicStructure (class in
encrypt() (pySim.esim.bsp.BspAlgoCrypt method), 92 pySim.esim.saip.validation), 113
encrypt_and_mac_one() (pySim.esim.bsp.BspInstance FileError, 113
method), 92 files2pe() (pySim.esim.saip.FsProfileElement
envelope() (pySim.commands.SimCardCommands method), 96
method), 74 files2pe() (pySim.esim.saip.ProfileElementGFM
eOID (class in pySim.esim.saip.oid), 107 method), 100
error() (pySim.card_handler.CardHandlerBase FilesAtMF (class in pySim.esim.saip.templates), 110
method), 86 FilesCD (class in pySim.esim.saip.templates), 110
Es2pApiClient (class in pySim.esim.es2p), 90 FilesDf5GProSe (class in pySim.esim.saip.templates),
Es2PlusApiFunction (class in pySim.esim.es2p), 90 110
Es9PlusApiFunction (class in pySim.esim.es9p), 91 FilesDfSnpn (class in pySim.esim.saip.templates), 110
expand_default_value_pattern() FilesEap (class in pySim.esim.saip.templates), 110
(pySim.esim.saip.templates.FileTemplate FilesIsimMandatory (class in
method), 110 pySim.esim.saip.templates), 110
expand_fill_pattern() (pySim.esim.saip.File FilesIsimOptional (class in
method), 94 pySim.esim.saip.templates), 110
expand_hex() (in module pySim.utils), 85 FilesIsimOptionalv2 (class in
export() (pySim.filesystem.BerTlvEF static method), 63 pySim.esim.saip.templates), 110
export() (pySim.filesystem.CardADF static method), 63 FilesTelecom (class in pySim.esim.saip.templates), 110

134 Index
 osmopysim-usermanual

FilesTelecomV2 (class in pySim.esim.saip.templates), from_string() (pySim.esim.ActivationCode class

111 method), 89
FilesUsimDf5GS (class in pySim.esim.saip.templates), from_template() (pySim.esim.saip.File method), 95
111 from_tlv() (pySim.utils.DataObject method), 83
FilesUsimDf5GSv2 (class in from_tuples() (pySim.esim.saip.File method), 95
pySim.esim.saip.templates), 111 from_upp() (pySim.esim.es8p.ProtectedProfilePackage
FilesUsimDf5GSv3 (class in class method), 90
pySim.esim.saip.templates), 111 FsNode (class in pySim.esim.saip), 95
FilesUsimDf5GSv4 (class in FsNodeADF (class in pySim.esim.saip), 95
pySim.esim.saip.templates), 111 FsNodeDF (class in pySim.esim.saip), 95
FilesUsimDfGsmAccess (class in FsNodeEF (class in pySim.esim.saip), 96
pySim.esim.saip.templates), 111 FsNodeMF (class in pySim.esim.saip), 96
FilesUsimDfPhonebook (class in FsProfileElement (class in pySim.esim.saip), 96
pySim.esim.saip.templates), 111 fully_qualified_path() (pySim.filesystem.CardFile
FilesUsimDfSaip (class in pySim.esim.saip.templates), method), 65
111 fully_qualified_path_fobj()
FilesUsimMandatory (class in (pySim.filesystem.CardFile method), 66
pySim.esim.saip.templates), 111 fully_qualified_path_str()
FilesUsimMandatoryV2 (class in (pySim.filesystem.CardFile method), 66
pySim.esim.saip.templates), 111
FilesUsimOptional (class in G
pySim.esim.saip.templates), 111 gen_init_sec_chan_signed_part() (in module
FilesUsimOptionalV2 (class in pySim.esim.es8p), 91
pySim.esim.saip.templates), 111 gen_initialiseSecureChannel() (in module
FilesUsimOptionalV3 (class in pySim.esim.es8p), 91
pySim.esim.saip.templates), 112 gen_replace_session_keys() (in module
FileTemplate (class in pySim.esim.saip.templates), 109 pySim.esim.es8p), 91
find_key() (pySim.esim.saip.ProfileElementSD gen_store_metadata_request()
method), 104 (pySim.esim.es8p.ProfileMetadata method), 90
for_version() (pySim.esim.saip.templates.SaipSpecVersionget() (pySim.card_handler.CardHandlerBase method),
static method), 112 87
fork_lchan() (pySim.commands.SimCardCommands get() (pySim.card_key_provider.CardKeyProvider
method), 74 method), 87
from_bitstring() (pySim.esim.PMO class method), 89 get() (pySim.card_key_provider.CardKeyProviderCsv
from_bytes() (pySim.utils.DataObject method), 83 method), 87
from_bytes() (pySim.utils.TL0_DataObject method), get_addr_type() (in module pySim.utils), 85
84 get_app_names() (pySim.filesystem.CardMF method),
from_der() (pySim.esim.es8p.UnprotectedProfilePackage 67
class method), 91 get_app_selectables() (pySim.filesystem.CardMF
from_der() (pySim.esim.saip.ProfileElement class method), 67
method), 97 get_atr() (pySim.commands.SimCardCommands
from_der() (pySim.esim.saip.ProfileElementSequence method), 74
class method), 105 get_atr() (pySim.transport.calypso.CalypsoSimLink
from_file() (pySim.esim.saip.ProfileElementApplication method), 80
class method), 98 get_atr() (pySim.transport.LinkBase method), 79
from_fileDescriptor() (pySim.esim.saip.File get_atr() (pySim.transport.modem_atcmd.ModemATCommandLink
method), 95 method), 81
from_int() (pySim.esim.PMO class method), 89 get_atr() (pySim.transport.pcsc.PcscSimLink method),
from_kdf() (pySim.esim.bsp.BspInstance class method), 81
92 get_atr() (pySim.transport.serial.SerialSimLink
from_saip_dict() (pySim.esim.saip.SecurityDomainKey method), 82
class method), 106 get_authority_key_identifier()
from_saip_dict() (pySim.esim.saip.SecurityDomainKeyComponent(pySim.esim.x509_cert.CertAndPrivkey
class method), 106 method), 93

Index 135
osmopysim-usermanual

I
get_by_oid() (pySim.esim.saip.templates.ProfileTemplateRegistry
class method), 112 Iccid (class in pySim.esim.saip.personalization), 107
get_cert_as_der() (pySim.esim.x509_cert.CertAndPrivkey iccid (pySim.esim.saip.ProfileElementSequence prop-
method), 94 erty), 105
get_closest_prev_pe_for_templateID() identification (pySim.esim.saip.ProfileElement prop-
(pySim.esim.saip.ProfileElementSequence erty), 97
method), 105 Imsi (class in pySim.esim.saip.personalization), 107
get_field() (pySim.card_key_provider.CardKeyProvider init_reader() (in module pySim.transport), 80
method), 87 InitiateAuthentication (class in pySim.esim.es9p),
get_file_by_path() (pySim.esim.saip.templates.FileTemplate 91
method), 110 insert_after_pe() (pySim.esim.saip.ProfileElementSequence
get_index_by_pe() (pySim.esim.saip.ProfileElementSequence method), 105
method), 105 insert_at_index() (pySim.esim.saip.ProfileElementSequence
get_index_by_type() method), 105
(pySim.esim.saip.ProfileElementSequence interpret_sw() (in module pySim.filesystem), 72
method), 105 interpret_sw() (pySim.filesystem.CardApplication
get_mf() (pySim.filesystem.CardFile method), 66 method), 63
get_pe_for_type() (pySim.esim.saip.ProfileElementSequence
is_parent() (pySim.filesystem.Path method), 69
method), 105
get_pes_for_templateID() J
(pySim.esim.saip.ProfileElementSequence
JsonHttpApiFunction (class in
method), 105
pySim.esim.http_json_api), 93
get_pes_for_type() (pySim.esim.saip.ProfileElementSequence
JsonResponseHeader (class in
method), 105
pySim.esim.http_json_api), 93
get_profile() (pySim.filesystem.CardFile method), 66
get_selectable_names() (pySim.filesystem.CardFile
method), 66
K
get_selectables() (pySim.filesystem.CardDF K (class in pySim.esim.saip.personalization), 108
method), 64
get_selectables() (pySim.filesystem.CardEF L
method), 65 lchan_nr_to_cla() (in module pySim.commands), 78
get_selectables() (pySim.filesystem.CardFile LinFixedEF (class in pySim.filesystem), 67
method), 66 LinFixedEF.ShellCommands (class in
get_selectables() (pySim.filesystem.CardMF pySim.filesystem), 68
method), 67 LinkBase (class in pySim.transport), 79
get_subject_alt_name() LinkBaseTpdu (class in pySim.transport), 79
(pySim.esim.x509_cert.CertAndPrivkey lookup() (pySim.utils.CardCommandSet method), 82
method), 94 lookup_by_fidpath() (pySim.esim.saip.FsNodeDF
get_tuplelist_item() (pySim.esim.saip.File static method), 96
method), 95 lookup_by_path() (pySim.esim.saip.FsNodeDF
GetBoundProfilePackage (class in pySim.esim.es9p), method), 96
91 lookup_file_by_fid() (pySim.filesystem.CardDF
method), 64
H lookup_file_by_name() (pySim.filesystem.CardDF
HandleDownloadProgressInfo (class in method), 64
pySim.esim.es2p), 90 lookup_file_by_sfid() (pySim.filesystem.CardDF
HandleNotification (class in pySim.esim.es9p), 91 method), 64
has_scp() (pySim.esim.saip.ProfileElementSD method),
104 M
header (pySim.esim.saip.ProfileElement property), 97 mac_only_one() (pySim.esim.bsp.BspInstance method),
header_name (pySim.esim.saip.ProfileElement prop- 92
erty), 97 manage_channel() (pySim.commands.SimCardCommands
HttpHeaderError, 93 method), 74
HttpStatusError, 93 match() (pySim.filesystem.CardModel class method), 67

136 Index
 osmopysim-usermanual

match_cla() (pySim.utils.CardCommand method), 82 parent (pySim.esim.saip.templates.FilesDfSnpn at-

max_cmd_len (pySim.commands.SimCardCommands tribute), 110
property), 74 parent (pySim.esim.saip.templates.FilesUsimDf5GS at-
mcc_from_imsi() (in module pySim.utils), 85 tribute), 111
mf (pySim.esim.saip.FsNode property), 95 parent (pySim.esim.saip.templates.FilesUsimDf5GSv2
mnc_from_imsi() (in module pySim.utils), 85 attribute), 111
ModemATCommandLink (class in parent (pySim.esim.saip.templates.FilesUsimDf5GSv3
pySim.transport.modem_atcmd), 81 attribute), 111
module parent (pySim.esim.saip.templates.FilesUsimDf5GSv4
pySim.card_handler, 86 attribute), 111
pySim.card_key_provider, 87 parent (pySim.esim.saip.templates.FilesUsimDfGsmAccess
pySim.commands, 73 attribute), 111
pySim.esim, 88 parent (pySim.esim.saip.templates.FilesUsimDfSaip at-
pySim.esim.bsp, 91 tribute), 111
pySim.esim.es2p, 89 parse_command_apdu() (in module pySim.utils), 85
pySim.esim.es8p, 90 parse_der() (pySim.esim.saip.ProfileElementSequence
pySim.esim.es9p, 91 method), 105
pySim.esim.http_json_api, 92 Path (class in pySim.filesystem), 69
pySim.esim.rsp, 89 path (pySim.esim.saip.templates.FileTemplate property),
pySim.esim.saip, 94 110
pySim.esim.saip.oid, 107 path_from_gfm() (pySim.esim.saip.File static method),
pySim.esim.saip.personalization, 107 95
pySim.esim.saip.templates, 109 path_to_gfm() (pySim.esim.saip.File static method), 95
pySim.esim.saip.validation, 113 PcscSimLink (class in pySim.transport.pcsc), 81
pySim.esim.x509_cert, 93 pe2files() (pySim.esim.saip.FsProfileElement
pySim.exceptions, 86 method), 97
pySim.filesystem, 62 pe2files() (pySim.esim.saip.ProfileElementGFM
pySim.transport, 79 method), 101
pySim.transport.calypso, 80 pe_for_path() (pySim.esim.saip.ProfileElementSequence
pySim.transport.modem_atcmd, 81 method), 105
pySim.transport.pcsc, 81 peclass_for_path() (pySim.esim.saip.ProfileElementSequence
pySim.transport.serial, 82 static method), 105
pySim.utils, 82 Pin (class in pySim.esim.saip.personalization), 108
Pin1 (class in pySim.esim.saip.personalization), 108
N Pin2 (class in pySim.esim.saip.personalization), 108
Naa (class in pySim.esim.saip), 97 PMO (class in pySim.esim), 89
naa_for_path() (pySim.esim.saip.ProfileElementSequenceprint_tree() (pySim.esim.saip.templates.FileTemplate
static method), 105 method), 110
NaaCsim (class in pySim.esim.saip), 97 ProactiveHandler (class in pySim.transport), 80
NaaIsim (class in pySim.esim.saip), 97 process_transport_keys()
NaaUsim (class in pySim.esim.saip), 97 (pySim.card_key_provider.CardKeyProviderCsv
name_path (pySim.esim.saip.FsNode property), 95 static method), 88
nested_collection_cls ProfileConstraintChecker (class in
(pySim.esim.saip.ProfileElementSD.C9 at- pySim.esim.saip.validation), 113
tribute), 103 ProfileElement (class in pySim.esim.saip), 97
NoCardError, 86 ProfileElementAKA (class in pySim.esim.saip), 98
ProfileElementApplication (class in
O pySim.esim.saip), 98
Opc (class in pySim.esim.saip.personalization), 108 ProfileElementCD (class in pySim.esim.saip), 99
ProfileElementDf5GProSe (class in pySim.esim.saip),
P 99
ProfileElementDf5GS (class in pySim.esim.saip), 99
parent (pySim.esim.saip.templates.FilesDf5GProSe at-
ProfileElementDfSAIP (class in pySim.esim.saip), 99
tribute), 110
ProfileElementDfSNPN (class in pySim.esim.saip), 100

Index 137
osmopysim-usermanual

ProfileElementEAP (class in pySim.esim.saip), 100 module, 92

ProfileElementEnd (class in pySim.esim.saip), 100 pySim.esim.rsp
ProfileElementGFM (class in pySim.esim.saip), 100 module, 89
ProfileElementGsmAccess (class in pySim.esim.saip), pySim.esim.saip
101 module, 94
ProfileElementHeader (class in pySim.esim.saip), 101 pySim.esim.saip.oid
ProfileElementISIM (class in pySim.esim.saip), 101 module, 107
ProfileElementMF (class in pySim.esim.saip), 101 pySim.esim.saip.personalization
ProfileElementOptISIM (class in pySim.esim.saip), module, 107
102 pySim.esim.saip.templates
ProfileElementOptUSIM (class in pySim.esim.saip), module, 109
102 pySim.esim.saip.validation
ProfileElementPhonebook (class in pySim.esim.saip), module, 113
102 pySim.esim.x509_cert
ProfileElementPin (class in pySim.esim.saip), 102 module, 93
ProfileElementPuk (class in pySim.esim.saip), 103 pySim.exceptions
ProfileElementRFM (class in pySim.esim.saip), 103 module, 86
ProfileElementSD (class in pySim.esim.saip), 103 pySim.filesystem
ProfileElementSD.C9 (class in pySim.esim.saip), 103 module, 62
ProfileElementSequence (class in pySim.esim.saip), pySim.transport
104 module, 79
ProfileElementSSD (class in pySim.esim.saip), 104 pySim.transport.calypso
ProfileElementTelecom (class in pySim.esim.saip), module, 80
106 pySim.transport.modem_atcmd
ProfileElementUSIM (class in pySim.esim.saip), 106 module, 81
ProfileError, 113 pySim.transport.pcsc
ProfileMetadata (class in pySim.esim.es8p), 90 module, 81
ProfileTemplate (class in pySim.esim.saip.templates), pySim.transport.serial
112 module, 82
ProfileTemplateRegistry (class in pySim.utils
pySim.esim.saip.templates), 112 module, 82
ProtectedProfilePackage (class in pySim.esim.es8p),
90 R
ProtocolError, 86 read_binary() (pySim.commands.SimCardCommands
Puk (class in pySim.esim.saip.personalization), 108 method), 74
Puk1 (class in pySim.esim.saip.personalization), 108 read_record() (pySim.commands.SimCardCommands
Puk2 (class in pySim.esim.saip.personalization), 108 method), 74
pySim.card_handler ReaderError, 86
module, 86 rebuild_mandatory_gfstelist()
pySim.card_key_provider (pySim.esim.saip.ProfileElementSequence
module, 87 method), 105
pySim.commands rebuild_mandatory_services()
module, 73 (pySim.esim.saip.ProfileElementSequence
pySim.esim method), 105
module, 88 receive_fetch() (pySim.transport.ProactiveHandler
pySim.esim.bsp method), 80
module, 91 record_count() (pySim.commands.SimCardCommands
pySim.esim.es2p method), 75
module, 89 record_size() (pySim.commands.SimCardCommands
pySim.esim.es8p method), 75
module, 90 relative_to_mf() (pySim.filesystem.Path method), 69
pySim.esim.es9p ReleaseProfile (class in pySim.esim.es2p), 90
module, 91 remove_instance() (pySim.esim.saip.ProfileElementApplication
pySim.esim.http_json_api method), 99

138 Index
 osmopysim-usermanual

remove_naas_of_type() SdKeyScp02_20Mac (class in

(pySim.esim.saip.ProfileElementSequence pySim.esim.saip.personalization), 108
method), 105 SdKeyScp03_30 (class in
remove_scp() (pySim.esim.saip.ProfileElementSD pySim.esim.saip.personalization), 108
method), 104 SdKeyScp03_30Dek (class in
remove_unwanted_tuples_from_list() (in module pySim.esim.saip.personalization), 108
pySim.esim.saip.personalization), 109 SdKeyScp03_30Enc (class in
renumber_identification() pySim.esim.saip.personalization), 108
(pySim.esim.saip.ProfileElementSequence SdKeyScp03_30Mac (class in
method), 106 pySim.esim.saip.personalization), 108
reset_card() (pySim.commands.SimCardCommands SdKeyScp03_31 (class in
method), 75 pySim.esim.saip.personalization), 108
reset_card() (pySim.transport.LinkBase method), 79 SdKeyScp03_31Dek (class in
resize_file() (pySim.commands.SimCardCommands pySim.esim.saip.personalization), 108
method), 75 SdKeyScp03_31Enc (class in
resume_uicc() (pySim.commands.SimCardCommands pySim.esim.saip.personalization), 108
method), 75 SdKeyScp03_31Mac (class in
retrieve_data() (pySim.commands.SimCardCommands pySim.esim.saip.personalization), 108
method), 75 SdKeyScp03_32 (class in
RspSessionState (class in pySim.esim.rsp), 89 pySim.esim.saip.personalization), 109
RspSessionStore (class in pySim.esim.rsp), 89 SdKeyScp03_32Dek (class in
run_gsm() (pySim.commands.SimCardCommands pySim.esim.saip.personalization), 109
method), 75 SdKeyScp03_32Enc (class in
pySim.esim.saip.personalization), 109
S SdKeyScp03_32Mac (class in
SaipSpecVersion (class in pySim.esim.saip.templates), pySim.esim.saip.personalization), 109
112 SdKeyScp80_01 (class in
SaipSpecVersion101 (class in pySim.esim.saip.personalization), 109
pySim.esim.saip.templates), 112 SdKeyScp80_01Kic (class in
SaipSpecVersion20 (class in pySim.esim.saip.personalization), 109
pySim.esim.saip.templates), 112 SdKeyScp80_01Kid (class in
SaipSpecVersion21 (class in pySim.esim.saip.personalization), 109
pySim.esim.saip.templates), 112 SdKeyScp80_01Kik (class in
SaipSpecVersion22 (class in pySim.esim.saip.personalization), 109
pySim.esim.saip.templates), 112 SdKeyScp81_01 (class in
SaipSpecVersion23 (class in pySim.esim.saip.personalization), 109
pySim.esim.saip.templates), 112 SdKeyScp81_01Dek (class in
SaipSpecVersion231 (class in pySim.esim.saip.personalization), 109
pySim.esim.saip.templates), 112 SdKeyScp81_01Psk (class in
SaipSpecVersion31 (class in pySim.esim.saip.personalization), 109
pySim.esim.saip.templates), 112 SecurityDomainKey (class in pySim.esim.saip), 106
SaipSpecVersion32 (class in SecurityDomainKeyComponent (class in
pySim.esim.saip.templates), 112 pySim.esim.saip), 106
SaipSpecVersion331 (class in select_adf() (pySim.commands.SimCardCommands
pySim.esim.saip.templates), 113 method), 75
sanitize_pin_adm() (in module pySim.utils), 85 select_file() (pySim.commands.SimCardCommands
SdKey (class in pySim.esim.saip.personalization), 108 method), 75
SdKeyScp02_20 (class in select_parent_df() (pySim.commands.SimCardCommands
pySim.esim.saip.personalization), 108 method), 75
SdKeyScp02_20Dek (class in select_path() (pySim.commands.SimCardCommands
pySim.esim.saip.personalization), 108 method), 75
SdKeyScp02_20Enc (class in send_apdu() (pySim.commands.SimCardCommands
pySim.esim.saip.personalization), 108 method), 75
send_apdu() (pySim.transport.LinkBase method), 79

Index 139
osmopysim-usermanual

send_apdu_checksw() method), 77
(pySim.commands.SimCardCommands sw_match() (in module pySim.utils), 85
method), 76 SwMatchError, 86
send_apdu_checksw() (pySim.transport.LinkBase
method), 79 T
send_apdu_constr() (pySim.commands.SimCardCommands tabulate_str_list() (in module pySim.utils), 85
method), 76 templateID (pySim.esim.saip.ProfileElement property),
send_apdu_constr_checksw() 98
(pySim.commands.SimCardCommands terminal_profile() (pySim.commands.SimCardCommands
method), 76 method), 77
send_tpdu() (pySim.transport.calypso.CalypsoSimLink terminate_card_usage()
method), 80 (pySim.commands.SimCardCommands
send_tpdu() (pySim.transport.LinkBaseTpdu method), method), 77
80 terminate_df() (pySim.commands.SimCardCommands
send_tpdu() (pySim.transport.modem_atcmd.ModemATCommandLink method), 77
method), 81 terminate_ef() (pySim.commands.SimCardCommands
send_tpdu() (pySim.transport.pcsc.PcscSimLink method), 77
method), 81 TL0_DataObject (class in pySim.utils), 84
send_tpdu() (pySim.transport.serial.SerialSimLink to_bitstring() (pySim.esim.PMO method), 89
method), 82 to_bytes() (pySim.utils.DataObject method), 83
SerialSimLink (class in pySim.transport.serial), 82 to_bytes() (pySim.utils.TL0_DataObject method), 84
set_data() (pySim.commands.SimCardCommands to_der() (pySim.esim.es8p.UnprotectedProfilePackage
method), 77 method), 91
set_icon() (pySim.esim.es8p.ProfileMetadata method), to_der() (pySim.esim.saip.ProfileElement method), 98
90 to_der() (pySim.esim.saip.ProfileElementSequence
set_mapping() (pySim.esim.saip.ProfileElementAKA method), 106
method), 98 to_dict() (pySim.utils.DataObject method), 83
set_milenage() (pySim.esim.saip.ProfileElementAKA to_file() (pySim.esim.saip.ProfileElementApplication
method), 98 method), 99
set_sw_interpreter() (pySim.transport.LinkBase to_fileDescriptor() (pySim.esim.saip.File method),
method), 79 95
set_tpdu_format() (pySim.transport.LinkBaseTpdu to_gfm() (pySim.esim.saip.File method), 95
method), 80 to_qrcode() (pySim.esim.ActivationCode method), 89
set_tuak() (pySim.esim.saip.ProfileElementAKA to_saip_dict() (pySim.esim.saip.SecurityDomainKey
method), 98 method), 106
set_xor3g() (pySim.esim.saip.ProfileElementAKA to_saip_dict() (pySim.esim.saip.SecurityDomainKeyComponent
method), 98 method), 106
should_exist_for_services() to_string() (pySim.esim.ActivationCode method), 89
(pySim.filesystem.CardFile method), 66 to_tlv() (pySim.utils.DataObject method), 83
SimCardCommands (class in pySim.commands), 73 to_tuples() (pySim.esim.saip.File method), 95
SmdpAddress (class in pySim.esim.http_json_api), 93 TransparentEF (class in pySim.filesystem), 71
status() (pySim.commands.SimCardCommands TransparentEF.ShellCommands (class in
method), 77 pySim.filesystem), 71
StdoutApduTracer (class in pySim.transport), 80 TransRecEF (class in pySim.filesystem), 70
suports_template_OID() try_select_path() (pySim.commands.SimCardCommands
(pySim.esim.saip.templates.SaipSpecVersion method), 77
class method), 112
supports_file_for_path() U
(pySim.esim.saip.FsProfileElement method), unblock_chv() (pySim.commands.SimCardCommands
97 method), 77
supports_file_for_path() UnprotectedProfilePackage (class in
(pySim.esim.saip.ProfileElementGFM method), pySim.esim.es8p), 91
101 update_binary() (pySim.commands.SimCardCommands
suspend_uicc() (pySim.commands.SimCardCommands method), 78

140 Index
 osmopysim-usermanual

update_record() (pySim.commands.SimCardCommands wait_for_card() (pySim.transport.serial.SerialSimLink

method), 78 method), 82
walk() (pySim.esim.saip.FsNode method), 95
V walk() (pySim.esim.saip.FsNodeDF method), 96
validate() (pySim.esim.saip.personalization.AlgoConfig wrap_as_der_tlv() (in module pySim.esim.es8p), 91
method), 107
validate() (pySim.esim.saip.personalization.AlgorithmID
method), 107
validate() (pySim.esim.saip.personalization.AppPin
method), 107
validate() (pySim.esim.saip.personalization.ConfigurableParameter
method), 107
validate() (pySim.esim.saip.personalization.Iccid
method), 107
validate() (pySim.esim.saip.personalization.Imsi
method), 107
validate() (pySim.esim.saip.personalization.Pin
method), 108
validate() (pySim.esim.saip.personalization.Puk
method), 108
validate() (pySim.esim.saip.personalization.SdKey
method), 108
verify_cert_chain()
(pySim.esim.x509_cert.CertificateSet method),
94
verify_chv() (pySim.commands.SimCardCommands
method), 78
verify_decoded() (pySim.esim.http_json_api.ApiParam
class method), 92
verify_decoded() (pySim.esim.http_json_api.ApiParamInteger
class method), 93
verify_decoded() (pySim.esim.http_json_api.JsonResponseHeader
class method), 93
verify_encoded() (pySim.esim.http_json_api.ApiParam
class method), 92
verify_encoded() (pySim.esim.http_json_api.ApiParamFqdn
class method), 93
verify_encoded() (pySim.esim.http_json_api.ApiParamInteger
class method), 93
verify_luhn() (in module pySim.utils), 86
VerifyError, 94
version_match() (pySim.esim.saip.templates.SaipSpecVersion
class method), 112

W
wait_for_card() (pySim.transport.calypso.CalypsoSimLink
method), 80
wait_for_card() (pySim.transport.LinkBase method),
79
wait_for_card() (pySim.transport.modem_atcmd.ModemATCommandLink
method), 81
wait_for_card() (pySim.transport.pcsc.PcscSimLink
method), 82

Index 141