WIP: Remote Card Procedure

Related: SYS#6959

.github/FUNDING.yml

@@ -0,0 +1 @@
+open_collective: osmocom

.gitignore

@@ -1,5 +1,17 @@
 *.pyc
-.*.swp
+.*.sw?
 
 /docs/_*
 /docs/generated
+/docs/filesystem.rst
+/.cache
+/.local
+/build
+/pySim.egg-info
+/smdpp-data/sm-dp-sessions*
+dist
+tags
+smdpp-data/certs/DPtls/CERT_S_SM_DP_TLS_NIST.pem
+smdpp-data/certs/DPtls/CERT_S_SM_DP_TLS_BRP.pem
+smdpp-data/generated
+smdpp-data/certs/dhparam2048.pem

README.md

@@ -1,16 +1,29 @@
-pySim - Read, Write and Browse Programmable SIM/USIM/ISIM/HPSIM Cards
-=====================================================================
+pySim - Tools for reading, decoding, browsing SIM/USIM/ISIM/HPSIM/eUICC Cards
+=============================================================================
 
-This repository contains a number of Python programs that can be used
-to read, program (write) and browse all fields/parameters/files on
-SIM/USIM/ISIM/HPSIM cards used in 3GPP cellular networks from 2G to 5G.
+This repository contains a number of Python programs related to working with
+subscriber identity modules of cellular networks, including but not limited
+to SIM, UICC, USIM, ISIM, HPSIMs and eUICCs.
+
+* `pySim-shell.py` can be used to interactively explore, read and decode contents
+  of any of the supported card models / card applications.  Furthermore, if
+  you have the credentials to your card (ADM PIN), you can also write to the card,
+  i.e. edit its contents.
+* `pySim-read.py` and `pySim-prog.py` are _legacy_ tools for batch programming
+  some very common parameters to an entire batch of programmable cards
+* `pySim-trace.py` is a tool to do an in-depth decode of SIM card protocol traces
+  such as those obtained by [Osmocom SIMtrace2](https://osmocom.org/projects/simtrace2/wiki)
+  or [osmo-qcdiag](https://osmocom.org/projects/osmo-qcdiag/wiki).
+* `osmo-smdpp.py` is a proof-of-concept GSMA SGP.22 Consumer eSIM SM-DP+ for lab/research
+* there are more related tools, particularly in the `contrib` directory.
 
 Note that the access control configuration of normal production cards
 issue by operators will restrict significantly which files a normal
 user can read, and particularly write to.
 
 The full functionality of pySim hence can only be used with on so-called
-programmable SIM/USIM/ISIM/HPSIM cards.
+programmable SIM/USIM/ISIM/HPSIM cards, such as the various
+[sysmocom programmable card products](https://shop.sysmocom.de/SIM/).
 
 Such SIM/USIM/ISIM/HPSIM cards are special cards, which - unlike those
 issued by regular commercial operators - come with the kind of keys that
@@ -49,9 +62,9 @@ pySim-shell vs. legacy tools
 ----------------------------
 
 While you will find a lot of online resources still describing the use of
-pySim-prog.py and pySim-read.py, those tools are considered legacy by
+`pySim-prog.py` and `pySim-read.py`, those tools are considered legacy by
 now and have by far been superseded by the much more capable
-pySim-shell.  We strongly encourage users to adopt pySim-shell, unless
+`pySim-shell.py`.  We strongly encourage users to adopt pySim-shell, unless
 they have very specific requirements like batch programming of large
 quantities of cards, which is about the only remaining use case for the
 legacy tools.
@@ -77,14 +90,14 @@ Please install the following dependencies:
  - cmd2 >= 1.5.0
  - colorlog
  - construct >= 2.9.51
- - gsm0338
+ - pyosmocom
  - jsonpath-ng
  - packaging
  - pycryptodomex
  - pyscard
  - pyserial
  - pytlv
- - pyyaml >= 5.1
+ - pyyaml >= 5.4
  - smpp.pdu (from `github.com/hologram-io/smpp.pdu`)
  - termcolor
 
@@ -123,19 +136,34 @@ sudo pacman -Rs python-pysim-git
 ```
 
 
+Forum
+-----
+
+We welcome any pySim related discussions in the
+[SIM Card Technology](https://discourse.osmocom.org/c/sim-card-technology/)
+section of the osmocom discourse (web based Forum).
+
+
 Mailing List
 ------------
 
 There is no separate mailing list for this project. However,
-discussions related to pysim-prog are happening on the
-<openbsc@lists.osmocom.org> mailing list, please see
-<https://lists.osmocom.org/mailman/listinfo/openbsc> for subscription
+discussions related to pySim are happening on the simtrace
+<simtrace@lists.osmocom.org> mailing list, please see
+<https://lists.osmocom.org/mailman/listinfo/simtrace> for subscription
 options and the list archive.
 
 Please observe the [Osmocom Mailing List
 Rules](https://osmocom.org/projects/cellular-infrastructure/wiki/Mailing_List_Rules)
 when posting.
 
+Issue Tracker
+-------------
+
+We use the [issue tracker of the pysim project on osmocom.org](https://osmocom.org/projects/pysim/issues) for
+tracking the state of bug reports and feature requests.  Feel free to submit any issues you may find, or help
+us out by resolving existing issues.
+
 
 Contributing
 ------------

contrib/analyze_simaResponse.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+
+# A tool to analyze the eUICC simaResponse (series of EUICCResponse)
+#
+# (C) 2025 by sysmocom - s.f.m.c. GmbH
+# All Rights Reserved
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+import argparse
+from osmocom.utils import h2b, b2h
+from osmocom.tlv import bertlv_parse_one, bertlv_encode_tag, bertlv_encode_len
+from pySim.esim.saip import *
+
+parser = argparse.ArgumentParser(description="""Utility program to analyze the contents of an eUICC simaResponse.""")
+parser.add_argument('SIMA_RESPONSE', help='Hexstring containing the simaResponse as received from the eUICC')
+
+def split_sima_response(sima_response):
+    """split an eUICC simaResponse field into a list of EUICCResponse fields"""
+
+    remainder = sima_response
+    result = []
+    while len(remainder):
+        tdict, l, v, next_remainder = bertlv_parse_one(remainder)
+        rawtag = bertlv_encode_tag(tdict)
+        rawlen = bertlv_encode_len(l)
+        result = result + [remainder[0:len(rawtag) + len(rawlen) + l]]
+        remainder = next_remainder
+    return result
+
+def analyze_status(status):
+    """
+    Convert a status code (integer) into a human readable string
+    (see eUICC Profile Package: Interoperable Format Technical Specification, section 8.11)
+    """
+
+    # SIMA status codes
+    string_values = {0 : 'ok',
+                     1 : 'pe-not-supported',
+                     2 : 'memory-failure',
+                     3 : 'bad-values',
+                     4 : 'not-enough-memory',
+                     5 : 'invalid-request-format',
+                     6 : 'invalid-parameter',
+                     7 : 'runtime-not-supported',
+                     8 : 'lib-not-supported',
+                     9 : 'template-not-supported ',
+                     10 : 'feature-not-supported',
+                     11 : 'pin-code-missing',
+                     31 : 'unsupported-profile-version'}
+
+    string_value = string_values.get(status, None)
+    if string_value is not None:
+        return "%d = %s (SIMA status code)" % (status, string_value)
+
+    # ISO 7816 status words
+    if status >= 24576 and status <= 28671:
+        return "%d = %04x (ISO7816 status word)" % (status, status)
+    elif status >= 36864 and status <= 40959:
+        return "%d = %04x (ISO7816 status word)" % (status, status)
+
+    # Proprietary status codes
+    elif status >= 40960 and status <= 65535:
+        return "%d = %04x (proprietary)" % (status, status)
+
+    # Unknown status codes
+    return "%d (unknown, proprietary?)" % status
+
+def analyze_euicc_response(euicc_response):
+    """Analyze and display the contents of an EUICCResponse"""
+
+    print(" EUICCResponse: %s" % b2h(euicc_response))
+    euicc_response_decoded = asn1.decode('EUICCResponse', euicc_response)
+
+    pe_status = euicc_response_decoded.get('peStatus')
+    print("  peStatus:")
+    for s in pe_status:
+        print("   status: %s" % analyze_status(s.get('status')))
+        print("   identification: %s" % str(s.get('identification', None)))
+        print("   additional-information: %s" % str(s.get('additional-information', None)))
+        print("   offset: %s" % str(s.get('offset', None)))
+
+    if euicc_response_decoded.get('profileInstallationAborted', False) is None:
+        # This type is defined as profileInstallationAborted NULL OPTIONAL, so when it is present it
+        # will have the value None, otherwise it is simply not present.
+        print("  profileInstallationAborted: True")
+    else:
+        print("  profileInstallationAborted: False")
+
+    status_message = euicc_response_decoded.get('statusMessage', None)
+    print("  statusMessage: %s" % str(status_message))
+
+if __name__ == '__main__':
+    opts = parser.parse_args()
+    sima_response = h2b(opts.SIMA_RESPONSE);
+
+    print("simaResponse: %s" % b2h(sima_response))
+    euicc_response_list = split_sima_response(sima_response)
+
+    for euicc_response in euicc_response_list:
+        analyze_euicc_response(euicc_response)

contrib/csv-encrypt-columns.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+
+# Utility program to perform column-based encryption of a CSV file holding SIM/UICC
+# related key materials.
+#
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import sys
+import csv
+import argparse
+from Cryptodome.Cipher import AES
+from osmocom.utils import h2b, b2h, Hexstr
+
+from pySim.card_key_provider import CardKeyFieldCryptor
+
+class CsvColumnEncryptor(CardKeyFieldCryptor):
+    def __init__(self, filename: str, transport_keys: dict):
+        self.filename = filename
+        self.crypt = CardKeyFieldCryptor(transport_keys)
+
+    def encrypt(self) -> None:
+        with open(self.filename, 'r') as infile:
+            cr = csv.DictReader(infile)
+            cr.fieldnames = [field.upper() for field in cr.fieldnames]
+
+            with open(self.filename + '.encr', 'w') as outfile:
+                cw = csv.DictWriter(outfile, dialect=csv.unix_dialect, fieldnames=cr.fieldnames)
+                cw.writeheader()
+
+                for row in cr:
+                    for fieldname in cr.fieldnames:
+                            row[fieldname] = self.crypt.encrypt_field(fieldname, row[fieldname])
+                    cw.writerow(row)
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument('CSVFILE', help="CSV file name")
+    parser.add_argument('--csv-column-key', action='append', required=True,
+                        help='per-CSV-column AES transport key')
+
+    opts = parser.parse_args()
+
+    csv_column_keys = {}
+    for par in opts.csv_column_key:
+        name, key = par.split(':')
+        csv_column_keys[name] = key
+
+    if len(csv_column_keys) == 0:
+        print("You must specify at least one key!")
+        sys.exit(1)
+
+    cce = CsvColumnEncryptor(opts.CSVFILE, csv_column_keys)
+    cce.encrypt()

contrib/csv-to-pgsql.py

@@ -0,0 +1,301 @@
+#!/usr/bin/env python3
+
+# (C) 2025 by sysmocom - s.f.m.c. GmbH
+# All Rights Reserved
+#
+# Author: Philipp Maier
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import argparse
+import logging
+import csv
+import sys
+import os
+import yaml
+import psycopg2
+from psycopg2.sql import Identifier, SQL
+from pathlib import Path
+from pySim.log import PySimLogger
+from packaging import version
+
+log = PySimLogger.get(Path(__file__).stem)
+
+class CardKeyDatabase:
+    def __init__(self, config_filename: str, table_name: str, create_table: bool = False, admin: bool = False):
+        """
+        Initialize database connection and set the table which shall be used as storage for the card key data.
+        In case the specified table does not exist yet it can be created using the create_table_type parameter.
+
+        New tables are always minimal tables which follow a pre-defined table scheme. The user may extend the table
+        with additional columns using the add_cols() later.
+
+        Args:
+                tablename : name of the database table to create.
+                create_table_type : type of the table to create ('UICC' or 'EUICC')
+        """
+
+        def user_from_config_file(config, role: str) -> tuple[str, str]:
+            db_users = config.get('db_users')
+            user = db_users.get(role)
+            if user is None:
+                raise ValueError("user for role '%s' not set up in config file." % role)
+            return user.get('name'), user.get('pass')
+
+        self.table = table_name.lower()
+        self.cols = None
+
+        # Depending on the table type, the table name must contain either the substring "uicc_keys" or "euicc_keys".
+        # This convention will allow us to deduct the table type from the table name.
+        if "euicc_keys" not in table_name and "uicc_keys" not in table_name:
+            raise ValueError("Table name (%s) should contain the substring \"uicc_keys\" or \"euicc_keys\"" % table_name)
+
+        # Read config file
+        log.info("Using config file: %s", config_filename)
+        with open(config_filename, "r") as cfg:
+            config = yaml.load(cfg, Loader=yaml.FullLoader)
+        host = config.get('host')
+        log.info("Database host: %s", host)
+        db_name = config.get('db_name')
+        log.info("Database name: %s", db_name)
+        table_names = config.get('table_names')
+        username_admin, password_admin = user_from_config_file(config, 'admin')
+        username_importer, password_importer = user_from_config_file(config, 'importer')
+        username_reader, _ = user_from_config_file(config, 'reader')
+
+        # Switch between admin and importer user
+        if admin:
+            username, password = username_admin, password_admin
+        else:
+            username, password = username_importer, password_importer
+
+        # Create database connection
+        log.info("Database user: %s", username)
+        self.conn = psycopg2.connect(dbname=db_name, user=username, password=password, host=host)
+        self.cur = self.conn.cursor()
+
+        # In the context of this tool it is not relevant if the table name is present in the config file. However,
+        # pySim-shell.py will require the table name to be configured properly to access the database table.
+        if self.table not in table_names:
+            log.warning("Specified table name (%s) is not yet present in config file (required for access from pySim-shell.py)",
+                        self.table)
+
+        # Create a new minimal database table of the specified table type.
+        if create_table:
+            if not admin:
+                raise ValueError("creation of new table refused, use option --admin and try again.")
+            if "euicc_keys" in self.table:
+                self.__create_table(username_reader, username_importer, ['EID'])
+            elif "uicc_keys" in self.table:
+                self.__create_table(username_reader, username_importer, ['ICCID', 'IMSI'])
+
+        # Ensure a table with the specified name exists
+        log.info("Database table: %s", self.table)
+        if self.get_cols() == []:
+            raise ValueError("Table name (%s) does not exist yet" % self.table)
+        log.info("Database table columns: %s", str(self.get_cols()))
+
+    def __create_table(self, user_reader:str, user_importer:str, cols:list[str]):
+        """
+        Initialize a new table. New tables are always minimal tables with one primary key and additional index columns.
+        Non index-columns may be added later using method _update_cols().
+        """
+
+        # Create table columns with primary key
+        query = SQL("CREATE TABLE {} ({} VARCHAR PRIMARY KEY").format(Identifier(self.table),
+                                                                      Identifier(cols[0].lower()))
+        for c in cols[1:]:
+            query += SQL(", {} VARCHAR").format(Identifier(c.lower()))
+        query += SQL(");")
+        self.cur.execute(query)
+
+        # Create indexes for all other columns
+        for c in cols[1:]:
+            self.cur.execute(query = SQL("CREATE INDEX {} ON {}({});").format(Identifier(c.lower()),
+                                                                              Identifier(self.table),
+                                                                              Identifier(c.lower())))
+
+        # Set permissions
+        self.cur.execute(SQL("GRANT INSERT ON {} TO {};").format(Identifier(self.table),
+                                                                 Identifier(user_importer)))
+        self.cur.execute(SQL("GRANT SELECT ON {} TO {};").format(Identifier(self.table),
+                                                                 Identifier(user_reader)))
+
+        log.info("New database table created: %s", self.table)
+
+    def get_cols(self) -> list[str]:
+        """
+        Get a list of all columns available in the current table scheme.
+
+        Returns:
+                list with column names (in uppercase) of the database table
+        """
+
+        # Return cached col list if present
+        if self.cols:
+            return self.cols
+
+        # Request a list of current cols from the database
+        self.cur.execute("SELECT column_name FROM information_schema.columns where table_name = %s;", (self.table,))
+
+        cols_result = self.cur.fetchall()
+        cols = []
+        for c in cols_result:
+            cols.append(c[0].upper())
+        self.cols = cols
+        return cols
+
+    def get_missing_cols(self, cols_expected:list[str]) -> list[str]:
+        """
+        Check if the current table scheme lacks any of the given expected columns.
+
+        Returns:
+                list with the missing columns.
+        """
+
+        cols_present = self.get_cols()
+        return list(set(cols_expected) - set(cols_present))
+
+    def add_cols(self, cols:list[str]):
+        """
+        Update the current table scheme with additional columns. In case the updated columns are already exist, the
+        table schema is not changed.
+
+        Args:
+                table : name of the database table to alter
+                cols : list with updated colum names to add
+        """
+
+        cols_missing = self.get_missing_cols(cols)
+
+        # Depending on the table type (see constructor), we either have a primary key 'ICCID' (for UICC data), or 'EID'
+        # (for eUICC data). Both table formats different types of data and have rather differen columns also. Let's
+        # prevent the excidentally mixing of both types.
+        if 'ICCID' in cols_missing:
+            raise ValueError("Table %s stores eUCCC key material, refusing to add UICC specific column 'ICCID'" % self.table)
+        if 'EID' in cols_missing:
+            raise ValueError("Table %s stores UCCC key material, refusing to add eUICC specific column 'EID'" % self.table)
+
+        # Add the missing columns to the table
+        self.cols = None
+        for c in cols_missing:
+            self.cur.execute(query = SQL("ALTER TABLE {} ADD {} VARCHAR;").format(Identifier(self.table),
+                                                                                  Identifier(c.lower())))
+
+    def insert_row(self, row:dict[str, str]):
+        """
+        Insert a new row into the database table.
+
+        Args:
+                row : dictionary with the colum names and their designated values
+        """
+
+        # Check if the row is compatible with the current table scheme
+        cols_expected = list(row.keys())
+        cols_missing = self.get_missing_cols(cols_expected)
+        if cols_missing != []:
+            raise ValueError("table %s has incompatible format, the row %s contains unknown cols %s" %
+                             (self.table, str(row), str(cols_missing)))
+
+        # Insert row into datbase table
+        row_keys = list(row.keys())
+        row_values = list(row.values())
+        query = SQL("INSERT INTO {} ").format(Identifier(self.table))
+        query += SQL("({} ").format(Identifier(row_keys[0].lower()))
+        for k in row_keys[1:]:
+            query += SQL(", {}").format(Identifier(k.lower()))
+        query += SQL(") VALUES (%s")
+        for v in row_values[1:]:
+            query += SQL(", %s")
+        query += SQL(");")
+        self.cur.execute(query, row_values)
+
+    def commit(self):
+        self.conn.commit()
+        log.info("Changes to table %s committed!", self.table)
+
+def open_csv(opts: argparse.Namespace):
+    log.info("CSV file: %s", opts.csv)
+    csv_file = open(opts.csv, 'r')
+    cr = csv.DictReader(csv_file)
+    if not cr:
+        raise RuntimeError("could not open DictReader for CSV-File '%s'" % opts.csv)
+    cr.fieldnames = [field.upper() for field in cr.fieldnames]
+    log.info("CSV file columns: %s", str(cr.fieldnames))
+    return cr
+
+def open_db(cr: csv.DictReader, opts: argparse.Namespace) -> CardKeyDatabase:
+    try:
+        db = CardKeyDatabase(os.path.expanduser(opts.pgsql), opts.table_name, opts.create_table, opts.admin)
+
+        # Check CSV format against table schema, add missing columns
+        cols_missing = db.get_missing_cols(cr.fieldnames)
+        if cols_missing != [] and (opts.update_columns or opts.create_table):
+            log.info("Adding missing columns: %s", str(cols_missing))
+            db.add_cols(cols_missing)
+            cols_missing = db.get_missing_cols(cr.fieldnames)
+
+        # Make sure the table schema has no missing columns
+        if cols_missing != []:
+            log.error("Database table lacks CSV file columns: %s -- import aborted!", cols_missing)
+            sys.exit(2)
+    except Exception as e:
+        log.error(str(e).strip())
+        log.error("Database initialization aborted due to error!")
+        sys.exit(2)
+
+    return db
+
+def import_from_csv(db: CardKeyDatabase, cr: csv.DictReader):
+    count = 0
+    for row in cr:
+        try:
+            db.insert_row(row)
+            count+=1
+            if count % 100 == 0:
+                log.info("CSV file import in progress, %d rows imported...", count)
+        except Exception as e:
+            log.error(str(e).strip())
+            log.error("CSV file import aborted due to error, no datasets committed!")
+            sys.exit(2)
+    log.info("CSV file import done, %d rows imported", count)
+
+if __name__ == '__main__':
+    option_parser = argparse.ArgumentParser(description='CSV importer for pySim-shell\'s PostgreSQL Card Key Provider',
+                                            formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+    option_parser.add_argument("--verbose", help="Enable verbose logging", action='store_true', default=False)
+    option_parser.add_argument('--pgsql', metavar='FILE',
+                               default="~/.osmocom/pysim/card_data_pgsql.cfg",
+                               help='Read card data from PostgreSQL database (config file)')
+    option_parser.add_argument('--csv', metavar='FILE', help='input CSV file with card data', required=True)
+    option_parser.add_argument("--table-name", help="name of the card key table", type=str, required=True)
+    option_parser.add_argument("--update-columns", help="add missing table columns", action='store_true', default=False)
+    option_parser.add_argument("--create-table", action='store_true', help="create new card key table", default=False)
+    option_parser.add_argument("--admin", action='store_true', help="perform action as admin", default=False)
+    opts = option_parser.parse_args()
+
+    PySimLogger.setup(print, {logging.WARN: "\033[33m"}, opts.verbose)
+
+    # Open CSV file
+    cr = open_csv(opts)
+
+    # Open database, create initial table, update column scheme
+    db = open_db(cr, opts)
+
+    # Progress with import
+    if not opts.admin:
+        import_from_csv(db, cr)
+
+    # Commit changes to the database
+    db.commit()

contrib/es2p_client.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import copy
+import argparse
+from pySim.esim import es2p, ActivationCode
+
+EID_HELP='EID of the eUICC for which eSIM shall be made available'
+ICCID_HELP='The ICCID of the eSIM that shall be made available'
+MATCHID_HELP='MatchingID that shall be used by profile download'
+
+parser = argparse.ArgumentParser(description="""
+Utility to manually issue requests against the ES2+ API of an SM-DP+ according to GSMA SGP.22.""")
+parser.add_argument('--url', required=True, help='Base URL of ES2+ API endpoint')
+parser.add_argument('--id', required=True, help='Entity identifier passed to SM-DP+')
+parser.add_argument('--client-cert', help='X.509 client certificate used to authenticate to server')
+parser.add_argument('--server-ca-cert', help="""X.509 CA certificates acceptable for the server side. In
+                    production use cases, this would be the GSMA Root CA (CI) certificate.""")
+subparsers = parser.add_subparsers(dest='command',help="The command (API function) to call")
+
+parser_dlo = subparsers.add_parser('download-order', help="ES2+ DownloadOrder function")
+parser_dlo.add_argument('--eid', help=EID_HELP)
+parser_dlo.add_argument('--iccid', help=ICCID_HELP)
+parser_dlo.add_argument('--profileType', help='The profile type of which one eSIM shall be made available')
+
+parser_cfo = subparsers.add_parser('confirm-order', help="ES2+ ConfirmOrder function")
+parser_cfo.add_argument('--iccid', required=True, help=ICCID_HELP)
+parser_cfo.add_argument('--eid', help=EID_HELP)
+parser_cfo.add_argument('--matchingId', help=MATCHID_HELP)
+parser_cfo.add_argument('--confirmationCode', help='Confirmation code that shall be used by profile download')
+parser_cfo.add_argument('--smdsAddress', help='SM-DS Address')
+parser_cfo.add_argument('--releaseFlag', action='store_true', help='Shall the profile be immediately released?')
+
+parser_co = subparsers.add_parser('cancel-order', help="ES2+ CancelOrder function")
+parser_co.add_argument('--iccid', required=True, help=ICCID_HELP)
+parser_co.add_argument('--eid', help=EID_HELP)
+parser_co.add_argument('--matchingId', help=MATCHID_HELP)
+parser_co.add_argument('--finalProfileStatusIndicator', required=True, choices=['Available','Unavailable'])
+
+parser_rp = subparsers.add_parser('release-profile', help='ES2+ ReleaseProfile function')
+parser_rp.add_argument('--iccid', required=True, help=ICCID_HELP)
+
+if __name__ == '__main__':
+    opts = parser.parse_args()
+    #print(opts)
+
+    peer = es2p.Es2pApiClient(opts.url, opts.id, server_cert_verify=opts.server_ca_cert, client_cert=opts.client_cert)
+
+    data = {}
+    for k, v in vars(opts).items():
+        if k in ['url', 'id', 'client_cert', 'server_ca_cert', 'command']:
+            # remove keys from dict that should not end up in JSON...
+            continue
+        if v is not None:
+            data[k] = v
+
+    print(data)
+    if opts.command == 'download-order':
+        res = peer.call_downloadOrder(data)
+    elif opts.command == 'confirm-order':
+        res = peer.call_confirmOrder(data)
+        matchingId = res.get('matchingId', None)
+        smdpAddress = res.get('smdpAddress', None)
+        if matchingId:
+            ac = ActivationCode(smdpAddress, matchingId, cc_required=bool(opts.confirmationCode))
+            print("Activation Code: '%s'" % ac.to_string())
+    elif opts.command == 'cancel-order':
+        res = peer.call_cancelOrder(data)
+    elif opts.command == 'release-profile':
+        res = peer.call_releaseProfile(data)

contrib/es2p_server.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+
+# (C) 2026 by sysmocom - s.f.m.c. GmbH
+# All Rights Reserved
+#
+# Author: Philipp Maier
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import sys
+import argparse
+import logging
+import json
+import asn1tools
+import asn1tools.codecs.ber
+import asn1tools.codecs.der
+import pySim.esim.rsp as rsp
+import pySim.esim.saip as saip
+from pySim.esim.es2p import param, Es2pApiServerMno, Es2pApiServerHandlerMno
+from osmocom.utils import b2h
+from datetime import datetime
+from analyze_simaResponse import split_sima_response
+from pathlib import Path
+
+logger = logging.getLogger(Path(__file__).stem)
+
+parser = argparse.ArgumentParser(description="""
+Utility to receive and log requests against the ES2+ API of an SM-DP+ according to GSMA SGP.22.""")
+parser.add_argument("--host", help="Host/IP to bind HTTP(S) to", default="localhost")
+parser.add_argument("--port", help="TCP port to bind HTTP(S) to", default=443, type=int)
+parser.add_argument('--server-cert', help='X.509 server certificate used to provide the ES2+ HTTPs service')
+parser.add_argument('--client-ca-cert', help='X.509 CA certificates to authenticate the requesting client(s)')
+parser.add_argument("-v", "--verbose", help="enable debug output", action='store_true', default=False)
+
+def decode_sima_response(sima_response):
+    decoded = []
+    euicc_response_list = split_sima_response(sima_response)
+    for euicc_response in euicc_response_list:
+        decoded.append(saip.asn1.decode('EUICCResponse', euicc_response))
+    return decoded
+
+def decode_result_data(result_data):
+    return rsp.asn1.decode('PendingNotification', result_data)
+
+def decode(data, path="/"):
+    if data is None:
+        return 'none'
+    elif type(data) is datetime:
+        return data.isoformat()
+    elif type(data) is tuple:
+        return {str(data[0]) : decode(data[1], path + str(data[0]) + "/")}
+    elif type(data) is list:
+        new_data = []
+        for item in data:
+            new_data.append(decode(item, path))
+        return new_data
+    elif type(data) is bytes:
+        return b2h(data)
+    elif type(data) is dict:
+        new_data = {}
+        for key, item in data.items():
+            new_key = str(key)
+            if path == '/' and new_key == 'resultData':
+                new_item = decode_result_data(item)
+            elif (path == '/resultData/profileInstallationResult/profileInstallationResultData/finalResult/successResult/' \
+                  or path == '/resultData/profileInstallationResult/profileInstallationResultData/finalResult/errorResult/') \
+                  and new_key == 'simaResponse':
+                new_item = decode_sima_response(item)
+            else:
+                new_item = item
+            new_data[new_key] = decode(new_item, path + new_key + "/")
+        return new_data
+    else:
+        return data
+
+class Es2pApiServerHandlerForLogging(Es2pApiServerHandlerMno):
+    def call_handleDownloadProgressInfo(self, data: dict) -> (dict, str):
+        logging.info("ES2+:handleDownloadProgressInfo: %s" % json.dumps(decode(data)))
+        return {}, None
+
+if __name__ == "__main__":
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.WARNING,
+                        format='%(asctime)s %(levelname)s %(message)s',
+                        datefmt='%Y-%m-%d %H:%M:%S')
+
+    Es2pApiServerMno(args.port, args.host, Es2pApiServerHandlerForLogging(), args.server_cert, args.client_ca_cert)
+

contrib/es9p_client.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import os
+import sys
+import argparse
+import logging
+import hashlib
+
+from typing import List
+from urllib.parse import urlparse
+
+from cryptography import x509
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from osmocom.utils import h2b, b2h, swap_nibbles, is_hexstr
+from osmocom.tlv import bertlv_parse_one_rawtag, bertlv_return_one_rawtlv
+
+import pySim.esim.rsp as rsp
+from pySim.esim import es9p, PMO
+from pySim.esim.x509_cert import CertAndPrivkey
+from pySim.esim.es8p import BoundProfilePackage
+
+logging.basicConfig(level=logging.DEBUG)
+
+parser = argparse.ArgumentParser(description="""
+Utility to manually issue requests against the ES9+ API of an SM-DP+ according to GSMA SGP.22.""")
+parser.add_argument('--url', required=True, help='Base URL of ES9+ API endpoint')
+parser.add_argument('--server-ca-cert', help="""X.509 CA certificates acceptable for the server side. In
+                    production use cases, this would be the GSMA Root CA (CI) certificate.""")
+parser.add_argument('--certificate-path', default='.',
+                    help="Path in which to look for certificate and key files.")
+parser.add_argument('--euicc-certificate', default='CERT_EUICC_ECDSA_NIST.der',
+                    help="File name of DER-encoded eUICC certificate file.")
+parser.add_argument('--euicc-private-key', default='SK_EUICC_ECDSA_NIST.pem',
+                    help="File name of PEM-format eUICC secret key file.")
+parser.add_argument('--eum-certificate', default='CERT_EUM_ECDSA_NIST.der',
+                    help="File name of DER-encoded EUM certificate file.")
+parser.add_argument('--ci-certificate', default='CERT_CI_ECDSA_NIST.der',
+                    help="File name of DER-encoded CI certificate file.")
+
+subparsers = parser.add_subparsers(dest='command',help="The command (API function) to call", required=True)
+
+# download
+parser_dl = subparsers.add_parser('download', help="ES9+ download")
+parser_dl.add_argument('--matchingId', required=True,
+                       help='MatchingID that shall be used by profile download')
+parser_dl.add_argument('--output-path', default='.',
+                       help="Path to which the output files will be written.")
+parser_dl.add_argument('--confirmation-code',
+                       help="Confirmation Code for the eSIM download")
+
+# notification
+parser_ntf = subparsers.add_parser('notification', help='ES9+ (other) notification')
+parser_ntf.add_argument('operation', choices=['enable','disable','delete'],
+                        help='Profile Management Operation whoise occurrence shall be notififed')
+parser_ntf.add_argument('--sequence-nr', type=int, required=True,
+                        help='eUICC global notification sequence number')
+parser_ntf.add_argument('--notification-address', help='notificationAddress, if different from URL')
+parser_ntf.add_argument('--iccid', type=is_hexstr, help='ICCID to which the notification relates')
+
+# notification-install
+parser_ntfi = subparsers.add_parser('notification-install', help='ES9+ installation notification')
+parser_ntfi.add_argument('--sequence-nr', type=int, required=True,
+                         help='eUICC global notification sequence number')
+parser_ntfi.add_argument('--transaction-id', required=True,
+                         help='transactionId of previous ES9+ download')
+parser_ntfi.add_argument('--notification-address', help='notificationAddress, if different from URL')
+parser_ntfi.add_argument('--iccid', type=is_hexstr, help='ICCID to which the notification relates')
+parser_ntfi.add_argument('--smdpp-oid', required=True, help='SM-DP+ OID (as in CERT.DPpb.ECDSA)')
+parser_ntfi.add_argument('--isdp-aid', type=is_hexstr, required=True,
+                         help='AID of the ISD-P of the installed profile')
+parser_ntfi.add_argument('--sima-response', type=is_hexstr, required=True,
+                         help='hex digits of BER-encoded SAIP EUICCResponse')
+
+class Es9pClient:
+    def __init__(self, opts):
+        self.opts = opts
+        self.cert_and_key = CertAndPrivkey()
+        self.cert_and_key.cert_from_der_file(os.path.join(opts.certificate_path, opts.euicc_certificate))
+        self.cert_and_key.privkey_from_pem_file(os.path.join(opts.certificate_path, opts.euicc_private_key))
+
+        with open(os.path.join(opts.certificate_path, opts.eum_certificate), 'rb') as f:
+            self.eum_cert = x509.load_der_x509_certificate(f.read())
+
+        with open(os.path.join(opts.certificate_path, opts.ci_certificate), 'rb') as f:
+            self.ci_cert = x509.load_der_x509_certificate(f.read())
+            subject_exts = list(filter(lambda x: isinstance(x.value, x509.SubjectKeyIdentifier), self.ci_cert.extensions))
+            subject_pkid = subject_exts[0].value
+            self.ci_pkid = subject_pkid.key_identifier
+
+        print("EUICC: %s" % self.cert_and_key.cert.subject)
+        print("EUM: %s" % self.eum_cert.subject)
+        print("CI: %s" % self.ci_cert.subject)
+
+        self.eid = self.cert_and_key.cert.subject.get_attributes_for_oid(x509.oid.NameOID.SERIAL_NUMBER)[0].value
+        print("EID: %s" % self.eid)
+        print("CI PKID: %s" % b2h(self.ci_pkid))
+        print()
+
+        self.peer = es9p.Es9pApiClient(opts.url, server_cert_verify=opts.server_ca_cert)
+
+
+    def do_notification(self):
+
+        ntf_metadata = {
+            'seqNumber': self.opts.sequence_nr,
+            'profileManagementOperation': PMO(self.opts.operation).to_bitstring(),
+            'notificationAddress': self.opts.notification_address or urlparse(self.opts.url).netloc,
+        }
+        if self.opts.iccid:
+            ntf_metadata['iccid'] = h2b(swap_nibbles(self.opts.iccid))
+
+        if self.opts.operation == 'install':
+            pird = {
+                'transactionId': h2b(self.opts.transaction_id),
+                'notificationMetadata': ntf_metadata,
+                'smdpOid': self.opts.smdpp_oid,
+                'finalResult': ('successResult', {
+                    'aid': h2b(self.opts.isdp_aid),
+                    'simaResponse': h2b(self.opts.sima_response),
+                    }),
+            }
+            pird_bin = rsp.asn1.encode('ProfileInstallationResultData', pird)
+            signature = self.cert_and_key.ecdsa_sign(pird_bin)
+            pn_dict = ('profileInstallationResult', {
+                'profileInstallationResultData': pird,
+                'euiccSignPIR': signature,
+            })
+        else:
+            ntf_bin = rsp.asn1.encode('NotificationMetadata', ntf_metadata)
+            signature = self.cert_and_key.ecdsa_sign(ntf_bin)
+            pn_dict = ('otherSignedNotification', {
+                'tbsOtherNotification': ntf_metadata,
+                'euiccNotificationSignature': signature,
+                'euiccCertificate': rsp.asn1.decode('Certificate', self.cert_and_key.get_cert_as_der()),
+                'eumCertificate': rsp.asn1.decode('Certificate', self.eum_cert.public_bytes(Encoding.DER)),
+            })
+
+        data = {
+            'pendingNotification': pn_dict,
+            }
+        #print(data)
+        res = self.peer.call_handleNotification(data)
+
+
+    def do_download(self):
+
+        print("Step 1: InitiateAuthentication...")
+
+        euiccInfo1 = {
+                'svn': b'\x02\x04\x00',
+                'euiccCiPKIdListForVerification': [
+                    self.ci_pkid,
+                ],
+                'euiccCiPKIdListForSigning': [
+                    self.ci_pkid,
+                ],
+          }
+
+        data = {
+            'euiccChallenge': os.urandom(16),
+            'euiccInfo1': euiccInfo1,
+            'smdpAddress': urlparse(self.opts.url).netloc,
+          }
+        init_auth_res = self.peer.call_initiateAuthentication(data)
+        print(init_auth_res)
+
+        print("Step 2: AuthenticateClient...")
+
+        #res['serverSigned1']
+        #res['serverSignature1']
+        print("TODO: verify serverSignature1 over serverSigned1")
+        #res['transactionId']
+        print("TODO: verify transactionId matches the signed one in serverSigned1")
+        #res['euiccCiPKIdToBeUsed']
+        # TODO: select eUICC certificate based on CI
+        #res['serverCertificate']
+        # TODO: verify server certificate against CI
+
+        euiccInfo2 = {
+            'profileVersion': b'\x02\x03\x01',
+            'svn': euiccInfo1['svn'],
+            'euiccFirmwareVer': b'\x23\x42\x00',
+            'extCardResource': b'\x81\x01\x00\x82\x04\x00\x04\x9ch\x83\x02"#',
+            'uiccCapability': (b'k6\xd3\xc3', 32),
+            'javacardVersion': b'\x11\x02\x00',
+            'globalplatformVersion': b'\x02\x03\x00',
+            'rspCapability': (b'\x9c', 6),
+            'euiccCiPKIdListForVerification': euiccInfo1['euiccCiPKIdListForVerification'],
+            'euiccCiPKIdListForSigning': euiccInfo1['euiccCiPKIdListForSigning'],
+            #'euiccCategory':
+            #'forbiddenProfilePolicyRules':
+            'ppVersion': b'\x01\x00\x00',
+            'sasAcreditationNumber': 'OSMOCOM-TEST-1', #TODO: make configurable
+            #'certificationDataObject':
+        }
+
+        euiccSigned1 = {
+            'transactionId': h2b(init_auth_res['transactionId']),
+            'serverAddress': init_auth_res['serverSigned1']['serverAddress'],
+            'serverChallenge': init_auth_res['serverSigned1']['serverChallenge'],
+            'euiccInfo2': euiccInfo2,
+            'ctxParams1':
+                ('ctxParamsForCommonAuthentication', {
+                    'matchingId': self.opts.matchingId,
+                    'deviceInfo': {
+                        'tac': b'\x35\x23\x01\x45', # same as lpac
+                        'deviceCapabilities': {},
+                        #imei:
+                    }
+                }),
+        }
+        euiccSigned1_bin = rsp.asn1.encode('EuiccSigned1', euiccSigned1)
+        euiccSignature1 = self.cert_and_key.ecdsa_sign(euiccSigned1_bin)
+        auth_clnt_req = {
+            'transactionId': init_auth_res['transactionId'],
+            'authenticateServerResponse':
+                ('authenticateResponseOk', {
+                    'euiccSigned1': euiccSigned1,
+                    'euiccSignature1': euiccSignature1,
+                    'euiccCertificate': rsp.asn1.decode('Certificate', self.cert_and_key.get_cert_as_der()),
+                    'eumCertificate': rsp.asn1.decode('Certificate', self.eum_cert.public_bytes(Encoding.DER))
+                 })
+        }
+        auth_clnt_res = self.peer.call_authenticateClient(auth_clnt_req)
+        print(auth_clnt_res)
+        #auth_clnt_res['transactionId']
+        print("TODO: verify transactionId matches previous ones")
+        #auth_clnt_res['profileMetadata']
+        # TODO: what's in here?
+        #auth_clnt_res['smdpSigned2']['bppEuiccOtpk']
+        #auth_clnt_res['smdpSignature2']
+        print("TODO: verify serverSignature2 over smdpSigned2")
+
+        smdp_cert = x509.load_der_x509_certificate(auth_clnt_res['smdpCertificate'])
+
+        print("Step 3: GetBoundProfilePackage...")
+        # Generate a one-time ECKA key pair (ot{PK,SK}.DP.ECKA) using the curve indicated by the Key Parameter
+        # Reference value of CERT.DPpb.ECDSA
+        euicc_ot = ec.generate_private_key(smdp_cert.public_key().public_numbers().curve)
+
+        # extract the public key in (hopefully) the right format for the ES8+ interface
+        euicc_otpk = euicc_ot.public_key().public_bytes(Encoding.X962, PublicFormat.UncompressedPoint)
+
+        euiccSigned2 = {
+            'transactionId': h2b(auth_clnt_res['transactionId']),
+            'euiccOtpk': euicc_otpk,
+            #hashCC
+        }
+        # check for smdpSigned2 ccRequiredFlag, and send it in PrepareDownloadRequest hashCc
+        if auth_clnt_res['smdpSigned2']['ccRequiredFlag']:
+            if not self.opts.confirmation_code:
+                raise ValueError('Confirmation Code required but not provided')
+            cc_hash = hashlib.sha256(self.opts.confirmation_code.encode('ascii')).digest()
+            euiccSigned2['hashCc'] = hashlib.sha256(cc_hash + euiccSigned2['transactionId']).digest()
+        euiccSigned2_bin = rsp.asn1.encode('EUICCSigned2', euiccSigned2)
+        euiccSignature2 = self.cert_and_key.ecdsa_sign(euiccSigned2_bin + auth_clnt_res['smdpSignature2'])
+        gbp_req = {
+            'transactionId': auth_clnt_res['transactionId'],
+            'prepareDownloadResponse':
+                ('downloadResponseOk', {
+                    'euiccSigned2': euiccSigned2,
+                    'euiccSignature2': euiccSignature2,
+                 })
+        }
+        gbp_res = self.peer.call_getBoundProfilePackage(gbp_req)
+        print(gbp_res)
+        #gbp_res['transactionId']
+        # TODO: verify transactionId
+        print("TODO: verify transactionId matches previous ones")
+        bpp_bin = gbp_res['boundProfilePackage']
+        print("TODO: verify boundProfilePackage smdpSignature")
+
+        bpp = BoundProfilePackage()
+        upp_bin = bpp.decode(euicc_ot, self.eid, bpp_bin)
+
+        iccid = swap_nibbles(b2h(bpp.storeMetadataRequest['iccid']))
+        base_name = os.path.join(self.opts.output_path, '%s' % iccid)
+
+        print("SUCCESS: Storing files as %s.*.der" % base_name)
+
+        # write various output files
+        with open(base_name+'.upp.der', 'wb') as f:
+            f.write(bpp.upp)
+        with open(base_name+'.isdp.der', 'wb') as f:
+            f.write(bpp.encoded_configureISDPRequest)
+        with open(base_name+'.smr.der', 'wb') as f:
+            f.write(bpp.encoded_storeMetadataRequest)
+
+
+if __name__ == '__main__':
+    opts = parser.parse_args()
+
+    c = Es9pClient(opts)
+
+    if opts.command == 'download':
+        c.do_download()
+    elif opts.command == 'notification':
+        c.do_notification()
+    elif opts.command == 'notification-install':
+        opts.operation = 'install'
+        c.do_notification()

contrib/esim-qrcode-gen.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+
+# Small command line utility program to encode eSIM QR-Codes
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import sys
+import argparse
+
+from pySim.esim import ActivationCode
+
+
+option_parser = argparse.ArgumentParser(description="""
+eSIM QR code generator. Will encode the given hostname + activation code
+into the eSIM RSP String format as specified in SGP.22 Section 4.1.  If
+a PNG output file is specified, it will also generate a QR code.""")
+option_parser.add_argument('hostname', help='FQDN of SM-DP+')
+option_parser.add_argument('token', help='MatchingID / Token')
+option_parser.add_argument('--oid', help='SM-DP+ OID in CERT.DPauth.ECDSA')
+option_parser.add_argument('--confirmation-code-required', action='store_true',
+                           help='Whether a Confirmation Code is required')
+option_parser.add_argument('--png', help='Output PNG file name (no PNG is written if omitted)')
+
+
+
+if __name__ == '__main__':
+    opts = option_parser.parse_args()
+
+    ac = ActivationCode(opts.hostname, opts.token, opts.oid, opts.confirmation_code_required)
+    print(ac.to_string())
+    if opts.png:
+        with open(opts.png, 'wb') as f:
+            img = ac.to_qrcode()
+            img.save(f)
+            print("# generated QR code stored to '%s'" % (opts.png))

contrib/esim_gen_metadata.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+
+# (C) 2025 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import argparse
+from osmocom.utils import h2b, swap_nibbles
+from pySim.esim.es8p import ProfileMetadata
+
+parser = argparse.ArgumentParser(description="""Utility program to generate profile metadata in the
+StoreMetadataRequest format based on input values from the command line.""")
+parser.add_argument('--iccid', required=True, help="ICCID of eSIM profile");
+parser.add_argument('--spn', required=True, help="Service Provider Name");
+parser.add_argument('--profile-name', required=True, help="eSIM Profile Name");
+parser.add_argument('--profile-class', choices=['test', 'operational', 'provisioning'],
+                    default='operational', help="Profile Class");
+parser.add_argument('--outfile', required=True, help="Output File Name");
+
+if __name__ == '__main__':
+    opts = parser.parse_args()
+
+    iccid_bin = h2b(swap_nibbles(opts.iccid))
+    pmd = ProfileMetadata(iccid_bin, spn=opts.spn, profile_name=opts.profile_name,
+                          profile_class=opts.profile_class)
+
+    with open(opts.outfile, 'wb') as f:
+        f.write(pmd.gen_store_metadata_request())
+    print("Written StoreMetadataRequest to '%s'" % opts.outfile)

contrib/fsdump-diff-apply.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+
+# The purpose of this script is to
+# * load two SIM card 'fsdump' files
+# * determine which file contents in "B" differs from that of "A"
+# * create a pySim-shell script to update the contents of "A" to match that of "B"
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import json
+import argparse
+
+# Files that we should not update
+FILES_TO_SKIP = [
+    "MF/EF.ICCID",
+    #"MF/DF.GSM/EF.IMSI",
+    #"MF/ADF.USIM/EF.IMSI",
+    ]
+
+# Files that need zero-padding at the end, not ff-padding
+FILES_PAD_ZERO = [
+    "DF.GSM/EF.SST",
+    "MF/ADF.USIM/EF.UST",
+    "MF/ADF.USIM/EF.EST",
+    "MF/ADF.ISIM/EF.IST",
+    ]
+
+def pad_file(path, instr, byte_len):
+    if path in FILES_PAD_ZERO:
+        pad = '0'
+    else:
+        pad = 'f'
+    return pad_hexstr(instr, byte_len, pad)
+
+def pad_hexstr(instr, byte_len:int, pad='f'):
+    """Pad given hex-string to the number of bytes given in byte_len, using ff as padding."""
+    if len(instr) == byte_len*2:
+        return instr
+    elif len(instr) > byte_len*2:
+        raise ValueError('Cannot pad string of length %u to smaller length %u' % (len(instr)/2, byte_len))
+    else:
+        return instr + pad * (byte_len*2 - len(instr))
+
+def is_all_ff(instr):
+    """Determine if the entire input hex-string consists of f-digits."""
+    if all([x == 'f' for x in instr.lower()]):
+        return True
+    else:
+        return False
+
+parser = argparse.ArgumentParser()
+parser.add_argument('file_a')
+parser.add_argument('file_b')
+
+
+if __name__ == '__main__':
+    opts = parser.parse_args()
+
+    with open(opts.file_a, 'r') as file_a:
+        json_a = json.loads(file_a.read())
+    with open(opts.file_b, 'r') as file_b:
+        json_b = json.loads(file_b.read())
+
+    for path in json_b.keys():
+        print()
+        print("# %s" % path)
+
+        if not path in json_a:
+            raise ValueError("%s doesn't exist in file_a!" % path)
+
+        if path in FILES_TO_SKIP:
+            print("# skipped explicitly as it is in FILES_TO_SKIP")
+            continue
+
+        if not 'body' in json_b[path]:
+            print("# file doesn't exist in B so we cannot possibly need to modify A")
+            continue
+
+        if not 'body' in json_a[path]:
+            # file was not readable in original (permissions? deactivated?)
+            print("# ERROR: %s not readable in A; please fix that" % path)
+            continue
+
+        body_a = json_a[path]['body']
+        body_b = json_b[path]['body']
+        if body_a == body_b:
+            print("# file body is identical")
+            continue
+
+        file_size_a = json_a[path]['fcp']['file_size']
+        file_size_b = json_b[path]['fcp']['file_size']
+
+        cmds = []
+        structure = json_b[path]['fcp']['file_descriptor']['file_descriptor_byte']['structure']
+        if structure == 'transparent':
+            val_a = body_a
+            val_b = body_b
+            if file_size_a < file_size_b:
+                if not is_all_ff(val_b[2*file_size_a:]):
+                    print("# ERROR: file_size_a (%u) < file_size_b (%u); please fix!" % (file_size_a, file_size_b))
+                    continue
+                else:
+                    print("# WARN: file_size_a (%u) < file_size_b (%u); please fix!" % (file_size_a, file_size_b))
+                    # truncate val_b to fit in A
+                    val_b = val_b[:file_size_a*2]
+
+            elif file_size_a != file_size_b:
+                print("# NOTE: file_size_a (%u) != file_size_b (%u)" % (file_size_a, file_size_b))
+
+            # Pad to file_size_a
+            val_b = pad_file(path, val_b, file_size_a)
+            if val_b != val_a:
+                cmds.append("update_binary %s" % val_b)
+            else:
+                print("# padded file body is identical")
+        elif structure in ['linear_fixed', 'cyclic']:
+            record_len_a = json_a[path]['fcp']['file_descriptor']['record_len']
+            record_len_b = json_b[path]['fcp']['file_descriptor']['record_len']
+            if record_len_a < record_len_b:
+                print("# ERROR: record_len_a (%u) < record_len_b (%u); please fix!" % (file_size_a, file_size_b))
+                continue
+            elif record_len_a != record_len_b:
+                print("# NOTE: record_len_a (%u) != record_len_b (%u)" % (record_len_a, record_len_b))
+
+            num_rec_a = file_size_a // record_len_a
+            num_rec_b = file_size_b // record_len_b
+            if num_rec_a < num_rec_b:
+                if not all([is_all_ff(x) for x in body_b[num_rec_a:]]):
+                    print("# ERROR: num_rec_a (%u) < num_rec_b (%u); please fix!" % (num_rec_a, num_rec_b))
+                    continue
+                else:
+                    print("# WARN: num_rec_a (%u) < num_rec_b (%u); but they're empty" % (num_rec_a, num_rec_b))
+            elif num_rec_a != num_rec_b:
+                print("# NOTE: num_rec_a (%u) != num_rec_b (%u)" % (num_rec_a, num_rec_b))
+
+            i = 0
+            for r in body_b:
+                if i < len(body_a):
+                    break
+                val_a = body_a[i]
+                # Pad to record_len_a
+                val_b = pad_file(path, body_b[i], record_len_a)
+                if val_a != val_b:
+                    cmds.append("update_record %u %s" % (i+1, val_b))
+                i = i + 1
+            if len(cmds) == 0:
+                print("# padded file body is identical")
+        elif structure == 'ber_tlv':
+            print("# FIXME: Implement BER-TLV")
+        else:
+            raise ValueError('Unsupported structure %s' % structure)
+
+        if len(cmds):
+            print("select %s" % path)
+            for cmd in cmds:
+                print(cmd)

contrib/generate_smdpp_certs.py

@@ -0,0 +1,661 @@
+#!/usr/bin/env python3
+
+"""
+Faithfully reproduces the smdpp certs contained in SGP.26_v1.5_Certificates_18_07_2024.zip
+available at https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-26-test-certificate-definition-v1-5/
+Only usable for testing, it obviously uses a different CI key.
+"""
+
+import os
+import binascii
+from datetime import datetime
+from cryptography import x509
+from cryptography.x509.oid import NameOID, ExtensionOID
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.backends import default_backend
+
+# Custom OIDs used in certificates
+OID_CERTIFICATE_POLICIES_CI = "2.23.146.1.2.1.0"  # CI cert policy
+OID_CERTIFICATE_POLICIES_TLS = "2.23.146.1.2.1.3"  # DPtls cert policy
+OID_CERTIFICATE_POLICIES_AUTH = "2.23.146.1.2.1.4"  # DPauth cert policy
+OID_CERTIFICATE_POLICIES_PB = "2.23.146.1.2.1.5"  # DPpb cert policy
+
+# Subject Alternative Name OIDs
+OID_CI_RID = "2.999.1"  # CI Registered ID
+OID_DP_RID = "2.999.10"  # DP+ Registered ID
+OID_DP2_RID = "2.999.12"  # DP+2 Registered ID
+OID_DP4_RID = "2.999.14"  # DP+4 Registered ID
+OID_DP8_RID = "2.999.18"  # DP+8 Registered ID
+
+
+class SimplifiedCertificateGenerator:
+    def __init__(self):
+        self.backend = default_backend()
+        # Store generated CI keys to sign other certs
+        self.ci_certs = {}  # {"BRP": cert, "NIST": cert}
+        self.ci_keys = {}   # {"BRP": key, "NIST": key}
+
+    def get_curve(self, curve_type):
+        """Get the appropriate curve object."""
+        if curve_type == "BRP":
+            return ec.BrainpoolP256R1()
+        else:
+            return ec.SECP256R1()
+
+    def generate_key_pair(self, curve):
+        """Generate a new EC key pair."""
+        private_key = ec.generate_private_key(curve, self.backend)
+        return private_key
+
+    def load_private_key_from_hex(self, hex_key, curve):
+        """Load EC private key from hex string."""
+        key_bytes = binascii.unhexlify(hex_key.replace(":", "").replace(" ", "").replace("\n", ""))
+        key_int = int.from_bytes(key_bytes, 'big')
+        return ec.derive_private_key(key_int, curve, self.backend)
+
+    def generate_ci_cert(self, curve_type):
+        """Generate CI certificate for either BRP or NIST curve."""
+        curve = self.get_curve(curve_type)
+        private_key = self.generate_key_pair(curve)
+
+        # Build subject and issuer (self-signed) - same for both
+        subject = issuer = x509.Name([
+            x509.NameAttribute(NameOID.COMMON_NAME, "Test CI"),
+            x509.NameAttribute(NameOID.ORGANIZATIONAL_UNIT_NAME, "TESTCERT"),
+            x509.NameAttribute(NameOID.ORGANIZATION_NAME, "RSPTEST"),
+            x509.NameAttribute(NameOID.COUNTRY_NAME, "IT"),
+        ])
+
+        # Build certificate - all parameters same for both
+        builder = x509.CertificateBuilder()
+        builder = builder.subject_name(subject)
+        builder = builder.issuer_name(issuer)
+        builder = builder.not_valid_before(datetime(2020, 4, 1, 8, 27, 51))
+        builder = builder.not_valid_after(datetime(2055, 4, 1, 8, 27, 51))
+        builder = builder.serial_number(0xb874f3abfa6c44d3)
+        builder = builder.public_key(private_key.public_key())
+
+        # Add extensions - all same for both
+        builder = builder.add_extension(
+            x509.SubjectKeyIdentifier.from_public_key(private_key.public_key()),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.BasicConstraints(ca=True, path_length=None),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.CertificatePolicies([
+                x509.PolicyInformation(
+                    x509.ObjectIdentifier(OID_CERTIFICATE_POLICIES_CI),
+                    policy_qualifiers=None
+                )
+            ]),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.KeyUsage(
+                digital_signature=False,
+                content_commitment=False,
+                key_encipherment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                key_cert_sign=True,
+                crl_sign=True,
+                encipher_only=False,
+                decipher_only=False
+            ),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.SubjectAlternativeName([
+                x509.RegisteredID(x509.ObjectIdentifier(OID_CI_RID))
+            ]),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.CRLDistributionPoints([
+                x509.DistributionPoint(
+                    full_name=[x509.UniformResourceIdentifier("http://ci.test.example.com/CRL-A.crl")],
+                    relative_name=None,
+                    reasons=None,
+                    crl_issuer=None
+                ),
+                x509.DistributionPoint(
+                    full_name=[x509.UniformResourceIdentifier("http://ci.test.example.com/CRL-B.crl")],
+                    relative_name=None,
+                    reasons=None,
+                    crl_issuer=None
+                )
+            ]),
+            critical=False
+        )
+
+        certificate = builder.sign(private_key, hashes.SHA256(), self.backend)
+
+        self.ci_keys[curve_type] = private_key
+        self.ci_certs[curve_type] = certificate
+
+        return certificate, private_key
+
+    def generate_dp_cert(self, curve_type, subject_cn, serial, key_hex,
+                        cert_policy_oid, rid_oid, validity_start, validity_end):
+        """Generate a DP certificate signed by CI - works for both BRP and NIST."""
+        curve = self.get_curve(curve_type)
+        private_key = self.load_private_key_from_hex(key_hex, curve)
+
+        ci_cert = self.ci_certs[curve_type]
+        ci_key = self.ci_keys[curve_type]
+
+        subject = x509.Name([
+            x509.NameAttribute(NameOID.ORGANIZATION_NAME, "ACME"),
+            x509.NameAttribute(NameOID.COMMON_NAME, subject_cn),
+        ])
+
+        builder = x509.CertificateBuilder()
+        builder = builder.subject_name(subject)
+        builder = builder.issuer_name(ci_cert.subject)
+        builder = builder.not_valid_before(validity_start)
+        builder = builder.not_valid_after(validity_end)
+        builder = builder.serial_number(serial)
+        builder = builder.public_key(private_key.public_key())
+
+        builder = builder.add_extension(
+            x509.AuthorityKeyIdentifier.from_issuer_public_key(ci_key.public_key()),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.SubjectKeyIdentifier.from_public_key(private_key.public_key()),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.SubjectAlternativeName([
+                x509.RegisteredID(x509.ObjectIdentifier(rid_oid))
+            ]),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.KeyUsage(
+                digital_signature=True,
+                content_commitment=False,
+                key_encipherment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                key_cert_sign=False,
+                crl_sign=False,
+                encipher_only=False,
+                decipher_only=False
+            ),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.CertificatePolicies([
+                x509.PolicyInformation(
+                    x509.ObjectIdentifier(cert_policy_oid),
+                    policy_qualifiers=None
+                )
+            ]),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.CRLDistributionPoints([
+                x509.DistributionPoint(
+                    full_name=[x509.UniformResourceIdentifier("http://ci.test.example.com/CRL-A.crl")],
+                    relative_name=None,
+                    reasons=None,
+                    crl_issuer=None
+                ),
+                x509.DistributionPoint(
+                    full_name=[x509.UniformResourceIdentifier("http://ci.test.example.com/CRL-B.crl")],
+                    relative_name=None,
+                    reasons=None,
+                    crl_issuer=None
+                )
+            ]),
+            critical=False
+        )
+
+        certificate = builder.sign(ci_key, hashes.SHA256(), self.backend)
+
+        return certificate, private_key
+
+    def generate_tls_cert(self, curve_type, subject_cn, dns_name, serial, key_hex,
+                         rid_oid, validity_start, validity_end):
+        """Generate a TLS certificate signed by CI."""
+        curve = self.get_curve(curve_type)
+        private_key = self.load_private_key_from_hex(key_hex, curve)
+
+        ci_cert = self.ci_certs[curve_type]
+        ci_key = self.ci_keys[curve_type]
+
+        subject = x509.Name([
+            x509.NameAttribute(NameOID.ORGANIZATION_NAME, "ACME"),
+            x509.NameAttribute(NameOID.COMMON_NAME, subject_cn),
+        ])
+
+        builder = x509.CertificateBuilder()
+        builder = builder.subject_name(subject)
+        builder = builder.issuer_name(ci_cert.subject)
+        builder = builder.not_valid_before(validity_start)
+        builder = builder.not_valid_after(validity_end)
+        builder = builder.serial_number(serial)
+        builder = builder.public_key(private_key.public_key())
+
+        builder = builder.add_extension(
+            x509.KeyUsage(
+                digital_signature=True,
+                content_commitment=False,
+                key_encipherment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                key_cert_sign=False,
+                crl_sign=False,
+                encipher_only=False,
+                decipher_only=False
+            ),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.ExtendedKeyUsage([
+                x509.oid.ExtendedKeyUsageOID.SERVER_AUTH,
+                x509.oid.ExtendedKeyUsageOID.CLIENT_AUTH
+            ]),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.CertificatePolicies([
+                x509.PolicyInformation(
+                    x509.ObjectIdentifier(OID_CERTIFICATE_POLICIES_TLS),
+                    policy_qualifiers=None
+                )
+            ]),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.SubjectKeyIdentifier.from_public_key(private_key.public_key()),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.AuthorityKeyIdentifier.from_issuer_public_key(ci_key.public_key()),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.SubjectAlternativeName([
+                x509.DNSName(dns_name),
+                x509.RegisteredID(x509.ObjectIdentifier(rid_oid))
+            ]),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.CRLDistributionPoints([
+                x509.DistributionPoint(
+                    full_name=[x509.UniformResourceIdentifier("http://ci.test.example.com/CRL-A.crl")],
+                    relative_name=None,
+                    reasons=None,
+                    crl_issuer=None
+                ),
+                x509.DistributionPoint(
+                    full_name=[x509.UniformResourceIdentifier("http://ci.test.example.com/CRL-B.crl")],
+                    relative_name=None,
+                    reasons=None,
+                    crl_issuer=None
+                )
+            ]),
+            critical=False
+        )
+
+        certificate = builder.sign(ci_key, hashes.SHA256(), self.backend)
+
+        return certificate, private_key
+
+    def generate_eum_cert(self, curve_type, key_hex):
+        """Generate EUM certificate signed by CI."""
+        curve = self.get_curve(curve_type)
+        private_key = self.load_private_key_from_hex(key_hex, curve)
+
+        ci_cert = self.ci_certs[curve_type]
+        ci_key = self.ci_keys[curve_type]
+
+        subject = x509.Name([
+            x509.NameAttribute(NameOID.COUNTRY_NAME, "ES"),
+            x509.NameAttribute(NameOID.ORGANIZATION_NAME, "RSP Test EUM"),
+            x509.NameAttribute(NameOID.COMMON_NAME, "EUM Test"),
+        ])
+
+        builder = x509.CertificateBuilder()
+        builder = builder.subject_name(subject)
+        builder = builder.issuer_name(ci_cert.subject)
+        builder = builder.not_valid_before(datetime(2020, 4, 1, 9, 28, 37))
+        builder = builder.not_valid_after(datetime(2054, 3, 24, 9, 28, 37))
+        builder = builder.serial_number(0x12345678)
+        builder = builder.public_key(private_key.public_key())
+
+        builder = builder.add_extension(
+            x509.AuthorityKeyIdentifier.from_issuer_public_key(ci_key.public_key()),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.SubjectKeyIdentifier.from_public_key(private_key.public_key()),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.KeyUsage(
+                digital_signature=False,
+                content_commitment=False,
+                key_encipherment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                key_cert_sign=True,
+                crl_sign=False,
+                encipher_only=False,
+                decipher_only=False
+            ),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.CertificatePolicies([
+                x509.PolicyInformation(
+                    x509.ObjectIdentifier("2.23.146.1.2.1.2"),  # EUM policy
+                    policy_qualifiers=None
+                )
+            ]),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.SubjectAlternativeName([
+                x509.RegisteredID(x509.ObjectIdentifier("2.999.5"))
+            ]),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.BasicConstraints(ca=True, path_length=0),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.CRLDistributionPoints([
+                x509.DistributionPoint(
+                    full_name=[x509.UniformResourceIdentifier("http://ci.test.example.com/CRL-B.crl")],
+                    relative_name=None,
+                    reasons=None,
+                    crl_issuer=None
+                )
+            ]),
+            critical=False
+        )
+
+        # Name Constraints
+        constrained_name = x509.Name([
+            x509.NameAttribute(NameOID.ORGANIZATION_NAME, "RSP Test EUM"),
+            x509.NameAttribute(NameOID.SERIAL_NUMBER, "89049032"),
+        ])
+
+        name_constraints = x509.NameConstraints(
+            permitted_subtrees=[
+                x509.DirectoryName(constrained_name)
+            ],
+            excluded_subtrees=None
+        )
+
+        builder = builder.add_extension(
+            name_constraints,
+            critical=True
+        )
+
+        certificate = builder.sign(ci_key, hashes.SHA256(), self.backend)
+
+        return certificate, private_key
+
+    def generate_euicc_cert(self, curve_type, eum_cert, eum_key, key_hex):
+        """Generate eUICC certificate signed by EUM."""
+        curve = self.get_curve(curve_type)
+        private_key = self.load_private_key_from_hex(key_hex, curve)
+
+        subject = x509.Name([
+            x509.NameAttribute(NameOID.COUNTRY_NAME, "ES"),
+            x509.NameAttribute(NameOID.ORGANIZATION_NAME, "RSP Test EUM"),
+            x509.NameAttribute(NameOID.SERIAL_NUMBER, "89049032123451234512345678901235"),
+            x509.NameAttribute(NameOID.COMMON_NAME, "Test eUICC"),
+        ])
+
+        builder = x509.CertificateBuilder()
+        builder = builder.subject_name(subject)
+        builder = builder.issuer_name(eum_cert.subject)
+        builder = builder.not_valid_before(datetime(2020, 4, 1, 9, 48, 58))
+        builder = builder.not_valid_after(datetime(7496, 1, 24, 9, 48, 58))
+        builder = builder.serial_number(0x0200000000000001)
+        builder = builder.public_key(private_key.public_key())
+
+        builder = builder.add_extension(
+            x509.AuthorityKeyIdentifier.from_issuer_public_key(eum_key.public_key()),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.SubjectKeyIdentifier.from_public_key(private_key.public_key()),
+            critical=False
+        )
+
+        builder = builder.add_extension(
+            x509.KeyUsage(
+                digital_signature=True,
+                content_commitment=False,
+                key_encipherment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                key_cert_sign=False,
+                crl_sign=False,
+                encipher_only=False,
+                decipher_only=False
+            ),
+            critical=True
+        )
+
+        builder = builder.add_extension(
+            x509.CertificatePolicies([
+                x509.PolicyInformation(
+                    x509.ObjectIdentifier("2.23.146.1.2.1.1"),  # eUICC policy
+                    policy_qualifiers=None
+                )
+            ]),
+            critical=True
+        )
+
+        certificate = builder.sign(eum_key, hashes.SHA256(), self.backend)
+
+        return certificate, private_key
+
+    def save_cert_and_key(self, cert, key, cert_path_der, cert_path_pem, key_path_sk, key_path_pk):
+        """Save certificate and key in various formats."""
+        # Create directories if needed
+        os.makedirs(os.path.dirname(cert_path_der), exist_ok=True)
+
+        with open(cert_path_der, "wb") as f:
+            f.write(cert.public_bytes(serialization.Encoding.DER))
+
+        if cert_path_pem:
+            with open(cert_path_pem, "wb") as f:
+                f.write(cert.public_bytes(serialization.Encoding.PEM))
+
+        if key and key_path_sk:
+            with open(key_path_sk, "wb") as f:
+                f.write(key.private_bytes(
+                    encoding=serialization.Encoding.PEM,
+                    format=serialization.PrivateFormat.TraditionalOpenSSL,
+                    encryption_algorithm=serialization.NoEncryption()
+                ))
+
+        if key and key_path_pk:
+            with open(key_path_pk, "wb") as f:
+                f.write(key.public_key().public_bytes(
+                    encoding=serialization.Encoding.PEM,
+                    format=serialization.PublicFormat.SubjectPublicKeyInfo
+                ))
+
+
+def main():
+    gen = SimplifiedCertificateGenerator()
+
+    output_dir = "smdpp-data/generated"
+    os.makedirs(output_dir, exist_ok=True)
+
+    print("=== Generating CI Certificates ===")
+
+    for curve_type in ["BRP", "NIST"]:
+        ci_cert, ci_key = gen.generate_ci_cert(curve_type)
+        suffix = "_ECDSA_BRP" if curve_type == "BRP" else "_ECDSA_NIST"
+        gen.save_cert_and_key(
+            ci_cert, ci_key,
+            f"{output_dir}/CertificateIssuer/CERT_CI{suffix}.der",
+            f"{output_dir}/CertificateIssuer/CERT_CI{suffix}.pem",
+            None, None
+        )
+        print(f"Generated CI {curve_type} certificate")
+
+    print("\n=== Generating DPauth Certificates ===")
+
+    dpauth_configs = [
+        ("BRP", "TEST SM-DP+", 256, "93:fb:33:d0:58:4f:34:9b:07:f8:b5:d2:af:93:d7:c3:e3:54:b3:49:a3:b9:13:50:2e:6a:bc:07:0e:4d:49:29", OID_DP_RID, "DPauth"),
+        ("NIST", "TEST SM-DP+", 256, "0a:7c:c1:c2:44:e6:0c:52:cd:5b:78:07:ab:8c:36:0c:26:52:46:01:50:7d:ca:bc:5d:d5:98:b5:a6:16:d5:d5", OID_DP_RID, "DPauth"),
+        ("BRP", "TEST SM-DP+2", 512, "0c:17:35:5c:01:1d:0f:e8:d7:da:dd:63:f1:97:85:cf:6c:51:cb:cd:46:6a:e8:8b:e8:f8:1b:c1:05:88:46:f6", OID_DP2_RID, "DP2auth"),
+        ("NIST", "TEST SM-DP+2", 512, "9c:32:a0:95:d4:88:42:d9:ff:a4:04:f7:12:51:2a:a2:c5:42:5a:1a:26:38:6a:b6:a1:45:d5:81:1e:03:91:41", OID_DP2_RID, "DP2auth"),
+    ]
+
+    for curve_type, cn, serial, key_hex, rid_oid, name_prefix in dpauth_configs:
+        cert, key = gen.generate_dp_cert(
+            curve_type, cn, serial, key_hex,
+            OID_CERTIFICATE_POLICIES_AUTH, rid_oid,
+            datetime(2020, 4, 1, 8, 31, 30),
+            datetime(2030, 3, 30, 8, 31, 30)
+        )
+        suffix = "_ECDSA_BRP" if curve_type == "BRP" else "_ECDSA_NIST"
+        gen.save_cert_and_key(
+            cert, key,
+            f"{output_dir}/DPauth/CERT_S_SM_{name_prefix}{suffix}.der",
+            None,
+            f"{output_dir}/DPauth/SK_S_SM_{name_prefix}{suffix}.pem",
+            f"{output_dir}/DPauth/PK_S_SM_{name_prefix}{suffix}.pem"
+        )
+        print(f"Generated {name_prefix} {curve_type} certificate")
+
+    print("\n=== Generating DPpb Certificates ===")
+
+    dppb_configs = [
+        ("BRP", "TEST SM-DP+", 257, "75:ff:32:2f:41:66:16:da:e1:a4:84:ef:71:d4:87:4f:b0:df:32:95:fd:35:c2:cb:a4:89:fb:b2:bb:9c:7b:f6", OID_DP_RID, "DPpb"),
+        ("NIST", "TEST SM-DP+", 257, "dc:d6:94:b7:78:95:7e:8e:9a:dd:bd:d9:44:33:e9:ef:8f:73:d1:1e:49:1c:48:d4:25:a3:8a:94:91:bd:3b:ed", OID_DP_RID, "DPpb"),
+        ("BRP", "TEST SM-DP+2", 513, "9c:ae:2e:1a:56:07:a9:d5:78:38:2e:ee:93:2e:25:1f:52:30:4f:86:ee:b1:f1:70:8c:db:d3:c0:7b:e2:cd:3d", OID_DP2_RID, "DP2pb"),
+        ("NIST", "TEST SM-DP+2", 513, "66:93:11:49:63:9d:ba:ac:1d:c3:d3:06:c5:8b:d2:df:d2:2f:73:bf:63:ac:86:31:98:32:90:b5:7f:90:93:45", OID_DP2_RID, "DP2pb"),
+    ]
+
+    for curve_type, cn, serial, key_hex, rid_oid, name_prefix in dppb_configs:
+        cert, key = gen.generate_dp_cert(
+            curve_type, cn, serial, key_hex,
+            OID_CERTIFICATE_POLICIES_PB, rid_oid,
+            datetime(2020, 4, 1, 8, 34, 46),
+            datetime(2030, 3, 30, 8, 34, 46)
+        )
+        suffix = "_ECDSA_BRP" if curve_type == "BRP" else "_ECDSA_NIST"
+        gen.save_cert_and_key(
+            cert, key,
+            f"{output_dir}/DPpb/CERT_S_SM_{name_prefix}{suffix}.der",
+            None,
+            f"{output_dir}/DPpb/SK_S_SM_{name_prefix}{suffix}.pem",
+            f"{output_dir}/DPpb/PK_S_SM_{name_prefix}{suffix}.pem"
+        )
+        print(f"Generated {name_prefix} {curve_type} certificate")
+
+    print("\n=== Generating DPtls Certificates ===")
+
+    dptls_configs = [
+        ("BRP", "testsmdpplus1.example.com", "testsmdpplus1.example.com", 9, "3f:67:15:28:02:b3:f4:c7:fa:e6:79:58:55:f6:82:54:1e:45:e3:5e:ff:f4:e8:a0:55:65:a0:f1:91:2a:78:2e", OID_DP_RID, "DP_TLS_BRP"),
+        ("NIST", "testsmdpplus1.example.com", "testsmdpplus1.example.com", 9, "a0:3e:7c:e4:55:04:74:be:a4:b7:a8:73:99:ce:5a:8c:9f:66:1b:68:0f:94:01:39:ff:f8:4e:9d:ec:6a:4d:8c", OID_DP_RID, "DP_TLS_NIST"),
+        ("NIST", "testsmdpplus2.example.com", "testsmdpplus2.example.com", 12, "4e:65:61:c6:40:88:f6:69:90:7a:db:e3:94:b1:1a:84:24:2e:03:3a:82:a8:84:02:31:63:6d:c9:1b:4e:e3:f5", OID_DP2_RID, "DP2_TLS"),
+        ("NIST", "testsmdpplus4.example.com", "testsmdpplus4.example.com", 14, "f2:65:9d:2f:52:8f:4b:11:37:40:d5:8a:0d:2a:f3:eb:2b:48:e1:22:c2:b6:0a:6a:f6:fc:96:ad:86:be:6f:a4", OID_DP4_RID, "DP4_TLS"),
+        ("NIST", "testsmdpplus8.example.com", "testsmdpplus8.example.com", 18, "ff:6e:4a:50:9b:ad:db:38:10:88:31:c2:3c:cc:2d:44:30:7a:f2:81:e9:25:96:7f:8c:df:1d:95:54:a0:28:8d", OID_DP8_RID, "DP8_TLS"),
+    ]
+
+    for curve_type, cn, dns, serial, key_hex, rid_oid, name_prefix in dptls_configs:
+        cert, key = gen.generate_tls_cert(
+            curve_type, cn, dns, serial, key_hex, rid_oid,
+            datetime(2024, 7, 9, 15, 29, 36),
+            datetime(2025, 8, 11, 15, 29, 36)
+        )
+        gen.save_cert_and_key(
+            cert, key,
+            f"{output_dir}/DPtls/CERT_S_SM_{name_prefix}.der",
+            None,
+            f"{output_dir}/DPtls/SK_S_SM_{name_prefix.replace('_BRP', '_BRP').replace('_NIST', '_NIST')}.pem",
+            f"{output_dir}/DPtls/PK_S_SM_{name_prefix.replace('_BRP', '_BRP').replace('_NIST', '_NIST')}.pem"
+        )
+        print(f"Generated {name_prefix} certificate")
+
+    print("\n=== Generating EUM Certificates ===")
+
+    eum_configs = [
+        ("BRP", "12:9b:0a:b1:3f:17:e1:4a:40:b6:fa:4e:d8:23:e0:cf:46:5b:7b:3d:73:24:05:e6:29:5d:3b:23:b0:45:c9:9a"),
+        ("NIST", "25:e6:75:77:28:e1:e9:51:13:51:9c:dc:34:55:5c:29:ba:ed:23:77:3a:c5:af:dd:dc:da:d9:84:89:8a:52:f0"),
+    ]
+
+    eum_certs = {}
+    eum_keys = {}
+
+    for curve_type, key_hex in eum_configs:
+        cert, key = gen.generate_eum_cert(curve_type, key_hex)
+        eum_certs[curve_type] = cert
+        eum_keys[curve_type] = key
+        suffix = "_ECDSA_BRP" if curve_type == "BRP" else "_ECDSA_NIST"
+        gen.save_cert_and_key(
+            cert, key,
+            f"{output_dir}/EUM/CERT_EUM{suffix}.der",
+            None,
+            f"{output_dir}/EUM/SK_EUM{suffix}.pem",
+            f"{output_dir}/EUM/PK_EUM{suffix}.pem"
+        )
+        print(f"Generated EUM {curve_type} certificate")
+
+    print("\n=== Generating eUICC Certificates ===")
+
+    euicc_configs = [
+        ("BRP", "8d:c3:47:a7:6d:b7:bd:d6:22:2d:d7:5e:a1:a1:68:8a:ca:81:1e:4c:bc:6a:7f:6a:ef:a4:b2:64:19:62:0b:90"),
+        ("NIST", "11:e1:54:67:dc:19:4f:33:71:83:e4:60:c9:f6:32:60:09:1e:12:e8:10:26:cd:65:61:e1:7c:6d:85:39:cc:9c"),
+    ]
+
+    for curve_type, key_hex in euicc_configs:
+        cert, key = gen.generate_euicc_cert(curve_type, eum_certs[curve_type], eum_keys[curve_type], key_hex)
+        suffix = "_ECDSA_BRP" if curve_type == "BRP" else "_ECDSA_NIST"
+        gen.save_cert_and_key(
+            cert, key,
+            f"{output_dir}/eUICC/CERT_EUICC{suffix}.der",
+            None,
+            f"{output_dir}/eUICC/SK_EUICC{suffix}.pem",
+            f"{output_dir}/eUICC/PK_EUICC{suffix}.pem"
+        )
+        print(f"Generated eUICC {curve_type} certificate")
+
+    print("\n=== Certificate generation complete! ===")
+    print(f"All certificates saved to: {output_dir}/")
+
+if __name__ == "__main__":
+    main()

contrib/jenkins.sh

@@ -4,37 +4,75 @@
 # environment variables:
 # * WITH_MANUALS: build manual PDFs if set to "1"
 # * PUBLISH: upload manuals after building if set to "1" (ignored without WITH_MANUALS = "1")
-# * JOB_TYPE: one of 'test', 'pylint', 'docs'
+# * JOB_TYPE: one of 'test', 'distcheck', 'pylint', 'docs'
+# * SKIP_CLEAN_WORKSPACE: don't run osmo-clean-workspace.sh (for pyosmocom CI)
 #
 
 export PYTHONUNBUFFERED=1
 
-if [ ! -d "./pysim-testdata/" ] ; then
+setup_venv() {
+	virtualenv -p python3 venv --system-site-packages
+	. venv/bin/activate
+}
+
+if [ ! -d "./tests/" ] ; then
 	echo "###############################################"
 	echo "Please call from pySim-prog top directory"
 	echo "###############################################"
 	exit 1
 fi
 
+if [ -z "$SKIP_CLEAN_WORKSPACE" ]; then
+	osmo-clean-workspace.sh
+fi
+
 case "$JOB_TYPE" in
 "test")
-	virtualenv -p python3 venv --system-site-packages
-	. venv/bin/activate
+	setup_venv
 
 	pip install -r requirements.txt
 	pip install pyshark
 
 	# Execute automatically discovered unit tests first
-	python -m unittest discover -v -s tests/
+	python -m unittest discover -v -s tests/unittests
 
-	# Run the test with physical cards
-	cd pysim-testdata
-	../tests/pySim-prog_test.sh
-	../tests/pySim-trace_test.sh
+	# Run pySim-trace test
+	tests/pySim-trace_test/pySim-trace_test.sh
+	;;
+"card-test") # tests requiring physical cards
+	setup_venv
+
+	pip install -r requirements.txt
+
+	# Run pySim-prog integration tests
+	cd tests/pySim-prog_test/
+	./pySim-prog_test.sh
+	cd ../../
+
+	# Run pySim-shell integration tests
+	python3 -m unittest discover -v -s ./tests/pySim-shell_test/
+
+	# Run pySim-smpp2sim test
+	tests/pySim-smpp2sim_test/pySim-smpp2sim_test.sh
+	;;
+"distcheck")
+	setup_venv
+
+	pip install .
+	pip install pyshark
+
+	for prog in venv/bin/pySim-*.py; do
+		$prog --help > /dev/null
+	done
 	;;
 "pylint")
 	# Print pylint version
 	pip3 freeze | grep pylint
+
+	setup_venv
+
+	pip install .
+
 	# Run pylint to find potential errors
 	# Ignore E1102: not-callable
 	#   pySim/filesystem.py: E1102: method is not callable (not-callable)
@@ -45,9 +83,14 @@ case "$JOB_TYPE" in
 		--disable E1102 \
 		--disable E0401 \
 		--enable W0301 \
-		pySim *.py
+		pySim tests/unittests/*.py *.py \
+		contrib/*.py
 	;;
 "docs")
+	setup_venv
+
+	pip install -r requirements.txt
+
 	rm -rf docs/_build
 	make -C "docs" html latexpdf
 
@@ -60,3 +103,5 @@ case "$JOB_TYPE" in
 	echo "ERROR: JOB_TYPE has unexpected value '$JOB_TYPE'."
 	exit 1
 esac
+
+osmo-clean-workspace.sh

contrib/rcp/rcp_client.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+
+# (C) 2026 by sysmocom - s.f.m.c. GmbH
+# All Rights Reserved
+#
+# Author: Philipp Maier
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import sys
+import websockets
+import asyncio
+import argparse
+import logging
+from copy import deepcopy
+from pathlib import Path
+from pySim.log import PySimLogger
+from rcp_utils import CltConnHdlr, backtrace, pytype_to_type, load_ca_cert
+from pySim.transport import init_reader, argparse_add_reader_args, LinkBase
+
+SERVER_TIMEOUT = 10
+
+log = PySimLogger.get(Path(__file__).stem)
+option_parser = argparse.ArgumentParser(description='RCP Client',
+                                        formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+argparse_add_reader_args(option_parser)
+option_parser.add_argument("--verbose", help="Enable verbose logging",
+                           action='store_true', default=False)
+option_parser.add_argument("--uri", help="URI of the RCP-Server")
+option_parser.add_argument("--ca-cert", help="SSL/TLS CA-Certificate of the RCP-Server")
+
+class RcpcCltConnHdlr(CltConnHdlr):
+    def __init__(self, sl, *args, **kwargs):
+        self.sl = sl
+        super().__init__(*args, **kwargs)
+
+    async def describe(self, suitable_for:dict) -> list:
+        log.info("Requesting module descriptions from RCP Server ...")
+        tx_json = {'rcpc_hello': {'suitable_for' : suitable_for}}
+        rx_json = await self._transact(tx_json)
+        module_descr = rx_json['rcpc_welcome']['module_descr']
+        if not module_descr:
+            raise ValueError("No RCP module available for this card")
+        return module_descr
+
+    async def run(self, cmd:str, cmd_argv) -> int:
+        log.info("Executing command with RCP Server ...")
+        tx_json = {'rcpc_command': {'cmd' : cmd, 'cmd_argv' : cmd_argv}}
+        while(True):
+            rx_json = await self._transact(tx_json)
+            tx_json = None
+            if 'rcpc_instr' in rx_json:
+                rcpc_instr = rx_json['rcpc_instr']
+                if 'c_apdu' in rcpc_instr:
+                    c_apdu = rx_json['rcpc_instr']['c_apdu']
+                    data, sw = sl.send_apdu(c_apdu)
+                    tx_json = {'rcpc_result': {'r_apdu' : {'data': data.upper(), 'sw': sw.upper()}}}
+                elif 'reset' in rcpc_instr:
+                    sl.reset_card()
+                    atr = sl.get_atr()
+                    tx_json = {'rcpc_result': {'atr' : atr.upper()}}
+                elif 'print' in rcpc_instr:
+                    log.info(str(self) + " -- %s", rx_json['rcpc_instr']['print'])
+                    tx_json = {'rcpc_result': {'empty' : None}}
+            elif 'rcpc_goodbye' in rx_json:
+                rc = rx_json['rcpc_goodbye']
+                log.info("Command execution done, rc: %d", rc)
+                return rc
+
+def check_if_user_needs_basic_help(argv):
+    """
+    The '--uri' argument is the minimum requirement to connect to the RCP Server to retrieve the information about the
+    dynamic commandline arguments. In case this argument is missing while '--help' or '-h' arguments are present. Then
+    we will fall back to display only a basic help that contains only the static commandline arguments (see above).
+    """
+
+    if '--help' in argv or '-h' in argv:
+        if '--uri' not in argv:
+            option_parser.parse_args()
+            sys.exit(1)
+
+def parse_known_arguemnts(argv):
+    """
+    Parse the commandline arguments we know so far. Ignore unknown arguments and filter out '--help' and '-h'
+    arguments, in case those are present.
+    """
+
+    argv_filtered = deepcopy(argv)
+    if '--help' in argv_filtered:
+        argv_filtered.remove('--help')
+    if '-h' in argv_filtered:
+        argv_filtered.remove('-h')
+    opts, unknown = option_parser.parse_known_args(argv_filtered)
+    return opts
+
+async def run_rcp_session(opts, sl, ssl_context) -> int:
+    """
+    Connect to the RCP Server, retrieve the module description, use the module description to complete the commandline
+    argument parser, execute the command that the user has selected.
+    """
+
+    # Request ATR from card
+    card_atr = sl.get_atr().upper()
+    log.info("Detected Card with ATR: %s" % card_atr)
+
+    # Connect to RCP server
+    log.info("RCP Server URI: %s" % opts.uri)
+    async with websockets.connect(opts.uri, ssl=ssl_context) as websocket:
+        client = RcpcCltConnHdlr(sl, websocket, SERVER_TIMEOUT)
+
+        # Retrieve module description
+        module_descrs = await client.describe({"atr" : card_atr})
+
+        # Complete the commandlie parser and set up a dict that we can use as filter
+        # TODO: Maybe it makes sense to integrate this as a method into the RcpcCltConnHdlr class?
+        option_subparsers = option_parser.add_subparsers(dest='command', help="RCP command to use", required=True)
+        sys_argv_filter = {}
+        for module_descr in module_descrs:
+            cmd_descr = module_descr['cmd_descr']
+            for cmd in cmd_descr:
+                command_name = module_descr['name'] + "_" + cmd['name']
+                option_parser_cmd = option_subparsers.add_parser(command_name, help=cmd['help'])
+                sys_argv_filter[command_name] = []
+                for arg in cmd['args']:
+                    arg['spec'] = pytype_to_type(arg['spec'])
+                    option_parser_cmd.add_argument(arg['name'], **arg['spec'])
+                    sys_argv_filter[command_name].append(arg['name'])
+
+        # Re-Parse commandline options with the completed commandline parser. In case commandline help is
+        # requested. The program is able to display the full helpscreen and exists.
+        opts = option_parser.parse_args()
+
+        # Filter the relevant command arguments from sys.argv
+        cmd_argv = []
+        next_is_value=False
+        for arg in sys.argv:
+            if arg in sys_argv_filter[opts.command]:
+                cmd_argv.append(arg)
+                next_is_value=True
+            elif next_is_value is True:
+                next_is_value=False
+                cmd_argv.append(arg)
+
+        # Run the command and close the connection
+        rc = await client.run(opts.command, cmd_argv)
+        await client.close()
+        return rc
+
+if __name__ == '__main__':
+
+    # Setup logging
+    PySimLogger.setup(print, {logging.WARN: "\033[33m", logging.DEBUG: "\033[90m"}, '--verbose' in sys.argv)
+
+    # Since parts of the commandline arguments are retrieved dynamically, we have to resolve a chicken-egg-problem.
+    # We cannot call option_parser.parse_args() at the beginning, since we haven't received all information to
+    # complete the option_parser yet. However in order to retrieve the arguments correctly we need to get the
+    # URI and the parameters for the smartcard reader before we make the connection. The situation is even further
+    # complicated in case the user requests commandline help.
+
+    # To resolve the problem we first check if the user needs basic help (no '--uri' parameter present). If this is the
+    # case, the program will exit with a basic helpscreen.
+    check_if_user_needs_basic_help(sys.argv)
+
+    # In all other cases we parse the arguments we know so far. In case the user requests commandline help, we will
+    # ignore this request and continue. The full help is then displayed later when the option_parser is completed
+    # afer we have requested the commandline argument descriptions from the RCP Server. (see below)
+    opts = parse_known_arguemnts(sys.argv)
+
+    # Load SSL/TLS CA certificate from file
+    if opts.ca_cert:
+        ssl_context = load_ca_cert("RCP Server CA", opts.ca_cert)
+    else:
+        ssl_context = None
+
+    # Initialize card reader
+    try:
+        sl = init_reader(opts)
+        sl.connect()
+    except Exception as e:
+        backtrace("Card reader initialization")
+        sys.exit(1)
+
+    # Run the RCP session
+    try:
+        rc = asyncio.run(run_rcp_session(opts, sl, ssl_context))
+        sys.exit(rc)
+    except SystemExit as rc:
+        sys.exit(rc)
+    except:
+        backtrace("RCP session")
+        sys.exit(1)
+
+

contrib/rcp/rcp_module_utils.py

@@ -0,0 +1,387 @@
+#!/usr/bin/env python3
+
+# (C) 2026 by sysmocom - s.f.m.c. GmbH
+# All Rights Reserved
+#
+# Author: Philipp Maier
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+import abc
+import os
+import argparse
+import logging
+import threading
+import asyncio
+import websockets
+from argparse import Namespace
+from copy import deepcopy
+from pathlib import Path
+from typing import Optional
+from osmocom.utils import Hexstr, is_hexstr
+from pySim.utils import ResTuple
+from pySim.transport import LinkBase
+from pySim.commands import SimCardCommands
+from pySim.log import PySimLogger
+from rcp_utils import SrvSyncConnHdlr, CltConnHdlr, backtrace, pytype_to_type, load_server_cert, load_ca_cert
+from rcp_utils import dict_from_key_value_pairs
+from websockets.sync.server import serve, ServerConnection
+
+# Response timeout towards the RCP Server (includes RCP Client latency)
+RCP_SERVER_TIMEOUT = 30 # sec.
+
+log = PySimLogger.get(Path(__file__).stem)
+
+class RcpsSimLink(LinkBase):
+    """
+    pySim: Transport Link for RCPM (Remote Card Procedure Module)
+    This is a 'headless' transport link implementation that can only be used from an RCPM module. It merely serves as
+    an adapter between the pySim transport API and the RCPM command server connection handler.
+    """
+
+    name = 'RCPM'
+
+    def __init__(self, conn_hdlr: SrvSyncConnHdlr, **kwargs):
+        self.conn_hdlr = conn_hdlr
+        self._atr = None
+        super().__init__(**kwargs)
+
+    def __str__(self) -> str:
+        return "rcpm:" + str(self.conn_hdlr)
+
+    def _send_apdu(self, apdu: Hexstr) -> ResTuple:
+        tx_json = {'rcpc_instr': {'c_apdu' : apdu.upper()}}
+        rx_json = self.conn_hdlr._transact(tx_json)
+        data = rx_json['rcpc_result']['r_apdu']['data']
+        sw = rx_json['rcpc_result']['r_apdu']['sw']
+        return data, sw
+
+    def wait_for_card(self, timeout: Optional[int] = None, newcardonly: bool = False):
+        # In this setting, we do not have/cannot to wait for a card since we are not the entity that handles the
+        # direct connection to the card. When the procedure begins, we assume that the remote end already has set up
+        # a connection to the card and made it ready to perform operations on it.
+        pass
+
+    def connect(self):
+        # In this setting, we do not have/cannot to connect because we are not the entity that handles the direct
+        # connection to the card. The connection is established by the remote end.
+        pass
+
+    def get_atr(self) -> Hexstr:
+        return self._atr
+
+    def disconnect(self):
+        # In this setting, we do not have/cannot disconnect because we are not the enitity that handles the direct
+        # connection to the card. The disconnect is eventually done by the remote end when the procedure has finished.
+        pass
+
+    def _reset_card(self):
+        tx_json = {'rcpc_instr': {'reset' : None}}
+        rx_json = self.conn_hdlr._transact(tx_json)
+        self._atr = rx_json['rcpc_result']['atr']
+        return 1
+
+class RcpsCltConnHdlr(CltConnHdlr):
+    """
+    The RCP Server client handler is used to connect to the RCP Server when RCP Module is started. The connection is
+    kept alive until the RCP Module is terminated. This connection is used to exchange management data with the RCP
+    Server.
+    """
+
+    def __init__(self, cmd_srv_addr: str, cmd_srv_port: int, module, *args, **kwargs):
+        self.cmd_srv_addr = cmd_srv_addr
+        self.cmd_srv_port = cmd_srv_port
+        self.module = module
+        super().__init__(*args, **kwargs)
+
+    async def describe(self):
+        """
+        Send a detailed description about this RCP Module to the RCP Server. This is also the initial message that
+        the RCP Server expects when an RCP Module connects.
+        """
+
+        # The rules (dict) in suitable_for (array of dict) may contain hexstrings. Here we go through those rules
+        # and convert those hexstrings to uppercase, since this is the standard we have set for the JSON messages.
+        suitable_for = []
+        for rule in self.module.suitable_for:
+            rule_filtered = {}
+            for k in rule:
+                if is_hexstr(rule[k]):
+                    rule_filtered[k] = rule[k].upper()
+                else:
+                    rule_filtered[k] = rule[k]
+            suitable_for.append(rule_filtered)
+
+        # Publish RCP Module description on the RCP server
+        tx_json = {'rcpm_hello':
+                   {'name' : self.module.name,
+                    'cmd_descr' : self.module.cmd_descr,
+                    'suitable_for' : suitable_for,
+                    'retrieve_keys' : {
+                        'euicc' : self.module.retrieve_euicc_keys,
+                        'uicc' : self.module.retrieve_uicc_keys
+                    },
+                    'addr' : self.cmd_srv_addr,
+                    'port' : self.cmd_srv_port
+                    }
+                   }
+        rx_json = await self._transact(tx_json)
+        if 'rcpm_welcome' not in rx_json:
+            raise ValueError("description not accepted by RCP Server")
+
+class RcpModule(abc.ABC):
+    """
+    Base class to implement to derive a concrete RCPM module class
+    """
+
+    # Module name used to identify the module in logs and user output. This module name should be short and concise.
+    name = "RCPM"
+
+    # Command description of this module. The command description consists of a short and concise command name, a
+    # helpstring and an argument specification in the form of a python dict. This specificaton dict is directly
+    # passed to agparse on the client side.
+    #
+    # Example:
+    # [{"name" : "reset",
+    #  "help": "reset the card",
+    #  "args" : []},
+    # {"name" : "read_binary",
+    #  "help": "read binary data from a transparent file.",
+    #  "args" : [ { "name" : "--fid",
+    #               "spec" : {"required" : True,
+    #                         "help" : "File identifier to of the file to read",
+    #                         "action" : "append"},
+    #              }
+    #            ]}
+    # ]
+    cmd_descr = []
+
+    # List with UICC (or eSIM) keys (columns) that the RCP Server shall retrieve before a command is executed.
+    # Execution will not continue in case any of the requested keys is not found.
+    # (see also: pySim.card_key_provider)
+    #
+    # Example: ['kic1', 'kid1', 'kik1']
+    retrieve_uicc_keys = []
+
+    # Same as retrieve_uicc_keys (see above), but only applicable with eUICCs
+    #
+    # Example: ['isdr_kic1', 'isdr_kid1', 'isdr_kik1']
+    retrieve_euicc_keys = []
+
+    # Card properties to determine if this module is suitable for a specific card type or card types. The RCP Server
+    # will match those properties against user requests to determine which module provides useful services to the
+    # user's card.
+    #
+    # Example: [{"atr" : "3b9f96803f87828031e073fe211f574543753130136502"}]
+    suitable_for = []
+
+    # In addition the above, the derived class must implement command methods for each command that is defined in the
+    # command description (see above). Each command method must begin with the prefix "cmd_" followed by the command
+    # name used in the command description. A command method must have the form as shown in the example shown below.
+    # Each method should return an integer value which will become the final return code of the RCP client program.
+    #
+    # Args:
+    #     hdlr:     RcpModuleHdlr object, this object is provided by the RcpmCmdSrvConnHdlr object, which calls
+    #               the command method of the module. Through the RcpModuleHdlr object, the API user gets access
+    #               to special service methods (e.g. print) and other required properties (e.g. the SimCardCommands
+    #               objects, key material and others (see above).
+    #
+    # Example:
+    # def cmd_reset(self, hdlr: RcpModuleHdlr) -> int: ...
+    # def cmd_read_binary(self, hdlr: RcpModuleHdlr) -> int: ...
+
+class RcpmCmdSrvConnHdlr(SrvSyncConnHdlr):
+    """
+    The RCP Module command server connection handler is used to handle dedicated connections from the RCP Server. Those
+    dedicated connections are technically transparent connections between the RCP Client and the RCP Module (this). The
+    RCP Server merely acts as a proxy at that point.
+    """
+
+    def __init__(self, module: RcpModule, *args, **kwargs):
+        SrvSyncConnHdlr.__init__(self, *args, *kwargs)
+        self.module = module
+
+    def _parse_cmd_argv(self, cmd_suffix: str, cmd_argv: list[str]) -> Namespace:
+        """ Parse (and validate) the received argument vector """
+        # Use the cmd_descr of the module to create a (temporary) argument parser for the received argument vector
+        cmd_parser = argparse.ArgumentParser()
+        for cmd in self.module.cmd_descr:
+            if cmd['name'] == cmd_suffix:
+                args = deepcopy(cmd['args'])
+                for arg in args:
+                    arg['spec'] = pytype_to_type(arg['spec'])
+                    cmd_parser.add_argument(arg['name'], **arg['spec'])
+
+        # Parse the arguments and return the parsed Namespace object.
+        try:
+            return cmd_parser.parse_args(cmd_argv)
+        except SystemExit:
+            raise ValueError("unable to parse arguments: %s", str(cmd_argv), )
+
+    def print(self, message: str):
+        """ Print a message on the client side """
+        log.info(str(self) + " -- %s" % message)
+        tx_json = {'rcpc_instr': {'print' : message}}
+        rx_json = self._transact(tx_json)
+        if rx_json != {'rcpc_result': {'empty' : None}}:
+            raise ValueError("unexpected response from RCP Client: %s", rx_json)
+
+    def procedure(self):
+        """ Receive and process a command from the RCP Client (via RCP Server) """
+
+        # Receive the command request
+        rx_json = self._recv()
+        cmd = rx_json['rcpc_command']['cmd']
+        cmd_argv = rx_json['rcpc_command']['cmd_argv']
+        keys = rx_json['rcpc_command']['keys']
+        keys_uicc = dict_from_key_value_pairs(keys['uicc'], keylabel='key', valuelabel='value')
+        keys_euicc = dict_from_key_value_pairs(keys['euicc'], keylabel='key', valuelabel='value')
+
+        log.info(str(self) + " -- executing command: %s %s", cmd, " ".join(cmd_argv))
+
+        try:
+            # Make sure the command actually addresses this module
+            cmd_prefix = self.module.name + "_"
+            if not cmd.startswith(cmd_prefix):
+                raise ValueError("invalid command: %s" % cmd)
+
+            # Make sure the module actually provides a command method for the requested command
+            cmd_suffix = cmd[len(cmd_prefix):]
+            cmd_method = "cmd_" + cmd_suffix
+            if not hasattr(self.module, cmd_method):
+                raise ValueError("missing command method: %s" % cmd_method)
+
+            # Parse and validate command arguments
+            cmd_args = self._parse_cmd_argv(cmd_suffix, cmd_argv)
+
+            # TODO: Perform a proper setup, similar to the one we have in pySim-shell, so that we have proper
+            # runtime states and full access to the pySim API
+            self.scc = SimCardCommands(transport=RcpsSimLink(self))
+            self.scc.cla_byte = "00"
+            self.scc.sel_ctrl = "0004"
+
+            # Hand over control to the command method provided by the specific module implementation
+            try:
+                rcp_module_hdlr = RcpModuleHdlr(self, cmd_args, keys_uicc, keys_euicc)
+                rc = getattr(self.module, cmd_method)(rcp_module_hdlr)
+            except Exception as e:
+                backtrace("command method")
+                rc = 1 # general error
+
+        except Exception as e:
+            backtrace("command parsing")
+            rc = 126 # cannot execute
+
+        # The prodedure is done, send "goodbye" message
+        log.info(str(self) + " -- command execution done, rc: %d" % rc)
+        tx_json = {'rcpc_goodbye': rc}
+        self._send(tx_json)
+
+class RcpModuleHdlr():
+    """
+    RCP Module handler class. This class is used by the RcpmCmdSrvConnHdlr to create the handler RcpModuleHdlr object
+    (hdlr), which is is passed to the command method. The RcpModuleHdlr gives the API user access to resources he can
+    use carry out the command.
+    """
+
+    # The scc property contains the SimCardCommands object may be used to send APDUs, retrieve the ATR, or even more
+    # complex tasks like selecting a file (see also pysim.commands)
+    scc = None
+
+    # The cmd_args property contains the parsed command arguments which were passed by the end-user to the RCP Client.
+    # The arguments are already parsed and validated against the cmd_dscr property of the RcpModule. The arguments are
+    # in the form of a Namespace object and can be accessed like any argparse output. However, since the arguments
+    # contain user input, some caution is required.
+    cmd_args = None
+
+    # In case the retrieve_uicc_keys property of the RcpModule is used retrieve UICC key material, this property will
+    # contain the key material in the form of a dictionary. The format is similar to the return value of
+    # card_key_provider_get() (see also pySim.card_key_provider)
+    keys_uicc = {}
+
+    # Same as self.keys_uicc, but contains eUICC related key material in case requested using retrieve_uicc_keys
+    keys_euicc = {}
+
+    def __init__(self, hdlr: RcpmCmdSrvConnHdlr, cmd_args: Namespace, keys_uicc: dict, keys_euicc: dict):
+        # The command method (API user) must not access the related RcpmCmdSrvConnHdlr (see below) directly. Only
+        # the resources below may be accessed.
+        self.__hdlr = hdlr
+
+        # Assign properties intended to be used by the command method (API user)
+        self.scc = self.__hdlr.scc
+        self.cmd_args = cmd_args
+        self.keys_uicc = keys_uicc
+        self.keys_euicc = keys_euicc
+
+    def print(self, message: str):
+        """ Print a message on the client side """
+        self.__hdlr.print(message)
+
+def rcpm_setup_argparse(description: str):
+    """Create argument parser and add the basic arguments all RCP Modules should have"""
+
+    option_parser = argparse.ArgumentParser(description='RCP Module: ' + description,
+                                            formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+    option_parser.add_argument("--verbose", help="Enable verbose logging", action='store_true', default=False)
+    option_parser.add_argument("--uri", help="URI of the RCP-Server", required=True)
+    option_parser.add_argument("--rcps-ca-cert", help="SSL/TLS CA-Certificate of the RCP-Server", required=True)
+    option_parser.add_argument("--rcpm-cmd-server-addr", help="Local Host/IP to bind RCP-Module-Command-Server to",
+                               required=True)
+    option_parser.add_argument("--rcpm-cmd-server-port", help="Local TCP port to bind RCP-Module-Command-Server to",
+                               required=True, type=int)
+    option_parser.add_argument("--rcpm-cmd-server-cert", help="SSL/TLS Certificate of the RCP-Module-Command-Server",
+                               required=True)
+    return option_parser
+
+def rcpm_run_module(opts: Namespace, module: RcpModule, *args, **kwargs):
+
+    PySimLogger.setup(print, {logging.WARN: "\033[33m", logging.DEBUG: "\033[90m"}, opts.verbose)
+    log.info("RCP Module startup: %s", module.name)
+    log.debug("Main process ID: %d", os.getpid())
+
+    # Load SSL/TLS certificates
+    rcpm_cmd_ssl_context = load_server_cert("RCPM Command Server", opts.rcpm_cmd_server_cert)
+    ssl_context = load_ca_cert("RCPM Server Client", opts.rcps_ca_cert)
+
+    # Start local RCP Client Command Server
+    log.info("RCPC command server at: %s:%d" % (opts.rcpm_cmd_server_addr, opts.rcpm_cmd_server_port))
+    def rcpm_cmd_conn_hdlr(websocket: ServerConnection):
+        hdlr = RcpmCmdSrvConnHdlr(module(*args, *kwargs), websocket, RCP_SERVER_TIMEOUT)
+        hdlr.procedure()
+        hdlr.close()
+
+    server = serve(rcpm_cmd_conn_hdlr, opts.rcpm_cmd_server_addr, opts.rcpm_cmd_server_port, ssl=rcpm_cmd_ssl_context)
+    def rcpm_cmd_server():
+        log.debug("RCPC command server thread ID: %d", threading.get_native_id())
+        server.serve_forever()
+    rcpm_cmd_server_thread = threading.Thread(target = rcpm_cmd_server)
+    rcpm_cmd_server_thread.start()
+
+    # Connect to RCP Server and publish module description
+    async def rcps_client():
+        async with websockets.connect(opts.uri, ping_timeout=10.0, ping_interval=1.0, ssl=ssl_context) as websocket:
+            client = RcpsCltConnHdlr(opts.rcpm_cmd_server_addr, opts.rcpm_cmd_server_port, module, websocket,
+                                     RCP_SERVER_TIMEOUT)
+            await client.describe()
+            await client.wait_close()
+    try:
+        asyncio.run(rcps_client())
+    except Exception as e:
+        backtrace("RCPS client")
+
+    # Shutdown
+    server.shutdown()
+    rcpm_cmd_server_thread.join()
+    log.info("RCP Module shutdown: %s", module.name)

contrib/rcp/rcp_server.py

@@ -0,0 +1,361 @@
+#!/usr/bin/env python3
+
+# (C) 2026 by sysmocom - s.f.m.c. GmbH
+# All Rights Reserved
+#
+# Author: Philipp Maier
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import os
+import sys
+import argparse
+import asyncio
+import logging
+from osmocom.utils import Hexstr
+from pySim.utils import ResTuple
+from copy import deepcopy
+from pathlib import Path
+from pySim.log import PySimLogger
+from pySim.utils import dec_iccid
+import websockets
+from websockets.asyncio.server import serve, ServerConnection
+from rcp_utils import SrvConnHdlr, CltConnHdlr, JsonValidator
+from rcp_utils import load_json_schema, backtrace, pytype_to_type, load_server_cert, load_ca_cert
+from rcp_utils import key_value_pairs_from_dict
+from pySim.card_key_provider import argparse_add_card_key_provider_args, init_card_key_provider
+from pySim.card_key_provider import card_key_provider_get_field, card_key_provider_get
+
+# TODO: Logging is fine, however it may also be a good idea to log some higher level events to some sort of journal.
+# We could use OpenObserve for that.
+
+CLIENT_TIMEOUT = 10
+
+log = PySimLogger.get(Path(__file__).stem)
+runtime_state = None
+option_parser = argparse.ArgumentParser(description='RCP Server',
+                                        formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+option_parser.add_argument("--verbose", help="Enable verbose logging",
+                           action='store_true', default=False)
+option_parser.add_argument("--rcpc-server-addr", help="Local Host/IP to bind RCP-Client-Server to",
+                           required=True)
+option_parser.add_argument("--rcpc-server-port", help="Local TCP port to bind RCP-Client-Server to",
+                           required=True, type=int)
+option_parser.add_argument("--rcpc-server-cert", help="SSL/TLS Certificate of the RCP-Client-Server",
+                           required=True)
+option_parser.add_argument("--rcpm-server-addr", help="Local Host/IP to bind RCP-Module-Server to",
+                           required=True)
+option_parser.add_argument("--rcpm-server-port", help="Local TCP port to bind RCP-Module-Server to",
+                           required=True, type=int)
+option_parser.add_argument("--rcpm-server-cert", help="SSL/TLS Certificate of the RCP-Module-Server",
+                           required=True)
+option_parser.add_argument("--rcpm-module-ca-cert", help="SSL/TLS CA-Certificate of the RCP-Module-Command-Server",
+                           required=True)
+argparse_add_card_key_provider_args(option_parser)
+
+# TODO move those into the RuntimeState?
+rcpc_rx_schema = None
+rcpc_tx_schema = None
+rcpm_ca_ssl_contextssl_context = None
+
+class ModuleRuntimeState:
+    def __init__(self, websocket:ServerConnection, name:str, cmd_descr:list, suitable_for:list, retrieve_keys:dict,
+                 addr:str, port:int):
+        self.name = name
+        self.websocket = websocket
+
+        # Run the cmd_descr through argparse to catch malformed arguments early
+        for cmd in cmd_descr:
+            args = deepcopy(cmd['args'])
+            cmd_parser = argparse.ArgumentParser()
+            for arg in args:
+                # TODO: wrap this into a try/catch block and log broken arguments?
+                arg['spec'] = pytype_to_type(arg['spec'])
+                cmd_parser.add_argument(arg['name'], **arg['spec'])
+
+        self.cmd_descr = cmd_descr
+        self.suitable_for = suitable_for
+        self.retrieve_keys = retrieve_keys
+        self.addr = addr
+        self.port = port
+        log.debug("new RCP module context created: '%s'", name)
+
+    def is_suitable(self, suitable_for:dict) -> bool:
+        if suitable_for in self.suitable_for:
+            return True
+        return False
+
+    def describe(self) -> dict:
+        return {'name': self.name,
+                'cmd_descr': self.cmd_descr}
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __del__(self):
+        log.debug("RCP module context destroyed: '%s'", self.name)
+
+class RuntimeState:
+    def __init__(self):
+        self.module_runtime_states = []
+        log.debug("new runtime context created.")
+
+    def __log_modules_available(self) -> str:
+        if self.module_runtime_states:
+            modules_str = ""
+            for module in self.module_runtime_states:
+                modules_str += "'" + str(module) + "', "
+            return "RCP modules available: %s" % modules_str[:-2]
+        else:
+            return "RCP modules available: none"
+
+    def module_add(self, module: ModuleRuntimeState):
+        self.module_runtime_states.append(module)
+        log.info("new RCP module, %s", self.__log_modules_available())
+
+    def module_remove(self, websocket:ServerConnection):
+        for module in self.module_runtime_states:
+            if module.websocket == websocket:
+                self.module_runtime_states.remove(module)
+                log.info("RCP module removed, %s", self.__log_modules_available())
+                return
+        log.warning("cannot remove RCP module, no RCP module associated with RCPC connection: %s:%d, %s" %
+                    (*websocket.remote_address, self.__log_modules_available()))
+
+    def modules_find(self, suitable_for:dict) -> list[dict]:
+        modules = []
+        for module in self.module_runtime_states:
+            if module.is_suitable(suitable_for):
+                modules.append(module.describe())
+        if modules:
+            return modules
+        # It is absolutely tolerable if no suitable RCP module can be found. If this is the case, the client should
+        # display an empty help screen and exit normally.
+        log.warning("no suitable RCP module found, %s", self.__log_modules_available())
+        return []
+
+    def module_find(self, suitable_for:dict, cmd:str) -> ModuleRuntimeState:
+        modules = self.modules_find(suitable_for)
+        for m in modules:
+            module_name = m['name']
+            cmd_descr = m['cmd_descr']
+            for c in cmd_descr:
+                cmd_name = c['name']
+                if module_name + "_" + cmd_name == cmd:
+                    break
+        for module_runtime_state in self.module_runtime_states:
+            if module_runtime_state.name == module_name:
+                return module_runtime_state
+        # Normally we should find the RCP module. When this method is called, we have already called modules_find
+        # before because we had to return the command descriptions to the client. If we cannot find the RCP module
+        # now, the module have been disconnected or the client somehow called a command that does not exist. In any
+        # case, ending up here means we cannot continue.
+        raise ValueError("RCP module not found for command: %s, ", cmd, self.__log_modules_available())
+
+class RcpmCltConnHdlr(CltConnHdlr):
+    """
+    The RCP Module client connection handler is the dedicated client that is used by the RCP Client connection handler
+    to handle the dedicated connection towards the RCP Module (see below)
+    """
+
+class RcpcSrvConnHdlr(SrvConnHdlr):
+    """
+    The RCP Client connection handler takes care of the handling of client requests. Througout the lifetime of a
+    connection, the client will request a description of the available commands and then request the execution of a
+    procedure. To execute the procedure, the handler will make a dedicated connection to the RCP Module and then
+    transparently pass the messages from the RCP Client to the RCP Module and vice versa.
+    """
+
+    async def describe(self):
+        """
+        Collect the command/argument description of suitable modules and forward that definition to the RCP client. The
+        RCP client will then build an argument parser (commmandlien help, argument validation) from this information.
+        """
+        rx_json = await self._recv()
+        self.suitable_for = rx_json['rcpc_hello']['suitable_for']
+        modules = runtime_state.modules_find(self.suitable_for)
+        tx_json = {'rcpc_welcome':
+                   {'module_descr' : modules}
+                   }
+        await self._send(tx_json)
+
+    async def _transact_apdu(self, apdu: Hexstr) -> ResTuple:
+        """Private low level method to exchange an APDU"""
+        tx_json = {'rcpc_instr': {'c_apdu' : apdu.upper()}}
+        rx_json = await self._transact(tx_json)
+        data = rx_json['rcpc_result']['r_apdu']['data']
+        sw = rx_json['rcpc_result']['r_apdu']['sw']
+        return data, sw
+
+    async def _reset(self) -> Hexstr:
+        """Private low level method to reset the UICC/eUICC"""
+        tx_json = {'rcpc_instr': {'reset' : None}}
+        rx_json = await self._transact(tx_json)
+        return rx_json['rcpc_result']['atr']
+
+    async def _read_iccid(self) -> Hexstr:
+        """Private low level method to read the EID from an UICC (or eSIM)"""
+        data, sw = await self._transact_apdu("00A40000022FE200")
+        if sw != "9000":
+            raise ValueError("Unable to select EF.ICCID, sw: %s, " % sw)
+        data, sw = await self._transact_apdu("00B000000A")
+        if sw != "9000":
+            raise ValueError("Unable to read EF.ICCID, sw: %s, " % sw)
+        return dec_iccid(data)
+
+    async def _read_eid(self) -> Hexstr:
+        """Private low level method to read the EID from an eUICC"""
+        data, sw = await self._transact_apdu("00A4040410A0000005591010FFFFFFFF890000010000")
+        if sw != "9000":
+            raise ValueError("Unable to select ISD-R, sw: %s, " % sw)
+        data, sw = await self._transact_apdu("80E2910006BF3E035C015A00")
+        if sw != "9000":
+            raise ValueError("Unable to retrieve EID, sw: %s, " % sw)
+        return data[10:]
+
+    async def print(self, message: str):
+        """ Print a message on the client side """
+        tx_json = {'rcpc_instr': {'print' : message}}
+        rx_json = await self._transact(tx_json)
+        if rx_json != {'rcpc_result': {'empty' : None}}:
+            raise ValueError("unexpected response from RCP Client: %s", rx_json)
+
+    async def procedure(self):
+        """
+        Receive a command from the client, pick a matching module, make a decdicated connection to that module and
+        forward instruction/response messages between RCP Client and RCP Module until the procedure is done.
+        """
+
+        # Expect a command from the client
+        rx_json = await self._recv()
+        if rx_json is None:
+            log.debug(str(self) + " -- RCP client has closed the connection, no procedure executed")
+            return
+        command = rx_json['rcpc_command']
+
+        # Pick the matching RCP Module
+        module = runtime_state.module_find(self.suitable_for, command['cmd'])
+
+        # Retrieve keys (if module requires them)
+        keys = {}
+        if module.retrieve_keys['uicc']:
+            iccid = await self._read_iccid()
+            keys_uicc = card_key_provider_get(module.retrieve_keys['uicc'], 'ICCID', iccid)
+            keys['uicc'] = key_value_pairs_from_dict(keys_uicc, keylabel='key', valuelabel='value')
+        else:
+            keys['uicc'] = []
+        if module.retrieve_keys['euicc']:
+            eid = await self._read_eid()
+            keys_euicc = card_key_provider_get(module.retrieve_keys['euicc'], 'EID', eid)
+            keys['euicc'] = key_value_pairs_from_dict(keys_euicc, keylabel='key', valuelabel='value')
+        else:
+            keys['euicc'] = []
+        command['keys'] = keys
+
+        # Resetting card to ensure the card is in a defined state
+        await self._reset()
+
+        # Transparently forward messages between RCP Client and RCP Module
+        module_uri = "wss://%s:%d" % (module.addr, module.port)
+        log.info(str(self) + " -- executing procedure for command \"%s\" on module \"%s\" at: %s" %
+                 (command['cmd'], module.name, module_uri))
+        async with websockets.connect(module_uri, ssl=rcpm_ca_ssl_context) as websocket:
+            module_client = RcpmCltConnHdlr(websocket, CLIENT_TIMEOUT)
+            rx_json = {'rcpc_command' : command}
+            while(True):
+                module_rx_json = await module_client._transact(rx_json)
+                await self._send(module_rx_json)
+                if 'rcpc_goodbye' in module_rx_json:
+                    log.info(str(self) + " -- command execution done, rc: %d" % module_rx_json['rcpc_goodbye'])
+                    break
+                rx_json = await self._recv()
+            await module_client.close()
+
+class RcpmSrvConnHdlr(SrvConnHdlr):
+    """
+    The RCP Module connection handler is responsible to handle connect and disconnect events of RCP Modules. This
+    connection between the RCP Module and the RCP Server is used for management purposes only.
+    """
+
+    async def describe(self):
+        """
+        Receive the module description from an RCP Module. This description will be stored in an internal list until
+        the module is disconnected from the server.
+        """
+        rx_json = await self._recv()
+        runtime_state.module_add(module = ModuleRuntimeState(self.websocket, **rx_json['rcpm_hello']))
+        tx_json = {'rcpm_welcome': {}}
+        await self._send(tx_json)
+
+    def __del__(self):
+        """
+        Remove RCPM from internal list when the connection is closed (and the handler is deleted)
+        """
+        runtime_state.module_remove(self.websocket)
+        super().__del__()
+
+async def rcpc_conn_hdlr(websocket: ServerConnection):
+    # TODO: Implement some sort of rate limit to protect against DoS. We may count the requests for each requesting
+    # IP address and reject the connection once a certain threshold is reached. (we plan to use the CardKeyProvider
+    # together with a database)
+    try:
+        json_validator = JsonValidator(rcpc_rx_schema, rcpc_tx_schema)
+        hdlr = RcpcSrvConnHdlr(websocket, CLIENT_TIMEOUT, json_validator)
+        await hdlr.describe()
+        await hdlr.procedure()
+        await hdlr.close()
+    except:
+        backtrace("RCPC connection handler")
+
+async def rcpm_conn_hdlr(websocket: ServerConnection):
+    try:
+        hdlr = RcpmSrvConnHdlr(websocket, CLIENT_TIMEOUT)
+        await hdlr.describe()
+        await hdlr.close()
+    except:
+        backtrace("RCPM connection handler")
+
+if __name__ == '__main__':
+    opts = option_parser.parse_args()
+
+    PySimLogger.setup(print, {logging.WARN: "\033[33m", logging.DEBUG: "\033[90m"}, opts.verbose)
+    runtime_state = RuntimeState()
+
+    # TODO: Modularize the JSON schemas. We already repeat ourselves with multiple definitions of the ATR fields.
+    rcpc_rx_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(), "rcpc_rx_schema.json"))
+    rcpc_tx_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(), "rcpc_tx_schema.json"))
+
+    # Load SSL/TLS certificates
+    rcpc_ssl_context = load_server_cert("RCP Client Server", opts.rcpc_server_cert)
+    rcpm_ssl_context = load_server_cert("RCP Module Server", opts.rcpm_server_cert)
+    rcpm_ca_ssl_context = load_ca_cert("RCP Module Command Server Client", opts.rcpm_module_ca_cert)
+
+    # Init card key provider for automatic card key retrieval
+    init_card_key_provider(opts)
+
+    # Start RCP server
+    async def rcp_server():
+        log.info("RCP Client Server at: %s:%d" % (opts.rcpc_server_addr, opts.rcpc_server_port))
+        log.info("RCP Module server at: %s:%d" % (opts.rcpm_server_addr, opts.rcpm_server_port))
+        async with serve(rcpc_conn_hdlr, opts.rcpc_server_addr, opts.rcpc_server_port, ssl=rcpc_ssl_context), \
+                   serve(rcpm_conn_hdlr, opts.rcpm_server_addr, opts.rcpm_server_port, ssl=rcpm_ssl_context):
+            await asyncio.get_running_loop().create_future()
+    try:
+        asyncio.run(rcp_server())
+    except SystemExit:
+        pass
+    except:
+        backtrace("RCP Server")
+        sys.exit(1)
+

contrib/rcp/rcp_utils.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+
+# (C) 2026 by sysmocom - s.f.m.c. GmbH
+# All Rights Reserved
+#
+# Author: Philipp Maier
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import sys
+import ssl
+import json
+import abc
+import asyncio
+import websockets
+import traceback
+import threading
+from copy import deepcopy
+from websockets.asyncio.server import ServerConnection
+from websockets.asyncio.client import ClientConnection
+from pathlib import Path
+from jsonschema import validate
+from pySim.log import PySimLogger
+from ssl import SSLContext
+
+log = PySimLogger.get(Path(__file__).stem)
+
+# TODO: Might be helpful for others as well, move this to pySim.utils?
+def backtrace(what: str):
+    log.error("%s failed with an exception:", what)
+    log.error("---------------------8<---------------------")
+    traceback_lines = traceback.format_exc()
+    for line in traceback_lines.split("\n"):
+        if line:
+            log.error(line)
+    log.error("---------------------8<---------------------")
+
+# TODO: Might be helpful for others as well, move this to pySim.utils?
+def key_value_pairs_from_dict(keys: dict, keylabel: str='key', valuelabel: str='value') -> list:
+    key_list = []
+    for key in keys:
+        key_list.append({keylabel : key, valuelabel : keys[key]})
+    return key_list
+
+# TODO: Might be helpful for others as well, move this to pySim.utils?
+def dict_from_key_value_pairs(keys: list, keylabel: str='key', valuelabel: str='value') -> dict:
+    key_dict = {}
+    for key in keys:
+        key_dict[key[keylabel]] = key[valuelabel]
+    return key_dict
+
+def pytype_to_type(dict_in: dict) -> dict:
+    """
+    There is no way to properly express python types in JSON. This function can be used to replace
+    each ocurrence of "pytype", with "type", where the string type name is replaced with an actual
+    python type.
+    """
+    dict_out = deepcopy(dict_in)
+    if dict_out.get('pytype'):
+        if dict_out['pytype'] == "str":
+            dict_out.pop('pytype')
+            dict_out['type'] = str
+        elif dict_out['pytype'] == "int":
+            dict_out.pop('pytype')
+            dict_out['type'] = int
+        else:
+            raise ValueError("invalid type in command argument specification: %s" % arg['spec']['type'])
+    return dict_out
+
+def load_json_schema(filename: str) -> dict:
+    """Load a JSON schema from file"""
+    log.info("loading JSON schema: %s", filename)
+    try:
+        with open(filename) as schema_file:
+            return json.load(schema_file)
+    except Exception as e:
+        backtrace("JSON schema load")
+        sys.exit(1)
+
+def load_server_cert(what: str, filename: str) -> SSLContext:
+    """Load an SSL/TLS server certificate"""
+    log.info("loading SSL/TLS server certificate (%s): %s", what, filename)
+    ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    ssl_context.load_cert_chain(filename)
+    return ssl_context
+
+def load_ca_cert(what: str, filename: str) -> SSLContext:
+    """Load an SSL/TLS CA certificate"""
+    log.info("loading SSL/TLS CA certificate (%s): %s", what, filename)
+    ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    ssl_context.load_verify_locations(filename)
+    return ssl_context
+
+class JsonValidator():
+    """
+    JSON validator class, can be passed to any ConnHdlr object to automatically validate the JSON messages which are
+    sent and and received.
+    """
+
+    def __init__(self, rx_schema: dict, tx_schema: dict = None):
+        self.rx_schema = rx_schema
+        if tx_schema:
+            self.tx_schema = tx_schema
+        else:
+            self.tx_schema = None
+
+    def valid_rx_json(self, rx_json: dict):
+        validate(instance = rx_json, schema = self.rx_schema)
+
+    def valid_tx_json(self, tx_json: dict):
+        if self.tx_schema:
+            # We intentionally do not prevent the sending of an invalid JSON message. It is the responsibility of the
+            # receiving end to detect an invalid message and react accordingly. The purpose of this validation is to
+            # make developers/users aware of the problem.
+            try:
+                validate(instance = tx_json, schema = self.tx_schema)
+            except Exception as e:
+                backtrace("JSON schema validation (TX)")
+
+class ConnHdlr(abc.ABC):
+    """Base class that can be used to create a connection handler"""
+
+    def __init__(self, websocket: ServerConnection | ClientConnection, timeout: int,
+                 json_validator: JsonValidator = None):
+        self.websocket = websocket
+        self.timeout = timeout
+        self.json_validator = json_validator
+        log.debug(str(self) + " -- new handler, timeout: %d sec.", self.timeout)
+
+    def _log_recv_peer(self, rx_json_str: str):
+        peer = "%s:%d<-%s:%d" % (self.websocket.local_address[0],
+                           self.websocket.local_address[1],
+                           self.websocket.remote_address[0],
+                           self.websocket.remote_address[1])
+        log.debug(str(self) + " -- RX(%s): %s", peer, rx_json_str)
+
+    def _log_send_peer(self, tx_json_str: str):
+        peer = "%s:%d->%s:%d" % (self.websocket.local_address[0],
+                           self.websocket.local_address[1],
+                           self.websocket.remote_address[0],
+                           self.websocket.remote_address[1])
+        log.debug(str(self) + " -- TX(%s): %s", peer, tx_json_str)
+
+    def __str__(self) -> str:
+        return "%s(%d)" % (type(self).__name__, id(self))
+
+    def __del__(self):
+        log.debug(str(self) + " -- closed handler")
+
+class SrvConnHdlr(ConnHdlr):
+    """Base class that can be used to create a connection handler for a server"""
+
+    async def _recv(self) -> dict:
+        """Receive JSON message from client"""
+        async with asyncio.timeout(self.timeout):
+            try:
+                rx_json_str = await self.websocket.recv()
+            except websockets.exceptions.ConnectionClosedOK:
+                log.debug(str(self) + " -- no data received, connection is closed")
+                return None
+        self._log_recv_peer(rx_json_str)
+        rx_json = json.loads(rx_json_str)
+        if self.json_validator:
+            self.json_validator.valid_rx_json(rx_json)
+        return rx_json
+
+    async def _send(self, tx_json: dict):
+        """Send JSON message to client"""
+        if self.json_validator:
+            self.json_validator.valid_tx_json(tx_json)
+        tx_json_str = json.dumps(tx_json)
+        self._log_send_peer(tx_json_str)
+        await self.websocket.send(tx_json_str)
+
+    async def _transact(self, tx_json: dict) -> dict:
+        """Exchange JSON message with client"""
+        await self._send(tx_json)
+        return await self._recv()
+
+    async def close(self):
+        """Wait for a connecion to close normally"""
+        await self.websocket.wait_closed()
+        log.debug(str(self) + " -- closed connection")
+
+class SrvSyncConnHdlr(ConnHdlr):
+    """Base class that can be used to create a synchronous connection handler for a server"""
+
+    def _recv(self) -> dict:
+        """Receive JSON message from client"""
+        # TODO: we do not have a timeout here (the self.timeout is currently useless). Check if we can do something
+        # about this or if we have to implement some watchdog functionality elsewhere.
+        rx_json_str = self.websocket.recv()
+        self._log_recv_peer(rx_json_str)
+        rx_json = json.loads(rx_json_str)
+        if self.json_validator:
+            self.json_validator.valid_rx_json(rx_json)
+        return rx_json
+
+    def _send(self, tx_json: dict):
+        """Send JSON message to client"""
+        if self.json_validator:
+            self.json_validator.valid_tx_json(tx_json)
+        tx_json_str = json.dumps(tx_json)
+        self._log_send_peer(tx_json_str)
+        self.websocket.send(tx_json_str)
+
+    def _transact(self, tx_json: dict) -> dict:
+        """Exchange JSON message with client"""
+        self._send(tx_json)
+        return self._recv()
+
+    def close(self):
+        """Close connection normally"""
+        self.websocket.close()
+        log.debug(str(self) + " -- closed connection")
+
+class CltConnHdlr(ConnHdlr):
+    """Base class that can be used to create a connection handler for a client"""
+
+    async def _transact(self, tx_json: dict) -> dict:
+        """Exchange JSON message with server"""
+        if self.json_validator:
+            self.json_validator.valid_tx_json(tx_json)
+        tx_json_str = json.dumps(tx_json)
+        self._log_send_peer(tx_json_str)
+        async with asyncio.timeout(self.timeout):
+            await self.websocket.send(tx_json_str)
+            rx_json_str = await self.websocket.recv()
+        self._log_recv_peer(rx_json_str)
+        rx_json = json.loads(rx_json_str);
+        if self.json_validator:
+            self.json_validator.valid_rx_json(rx_json)
+        return rx_json
+
+    async def close(self):
+        """Close connection normally"""
+        await self.websocket.close()
+        log.debug(str(self) + " -- closed connection")
+
+    async def wait_close(self):
+        """Wait for a connecion to close normally"""
+        await self.websocket.wait_closed()
+        log.debug(str(self) + " -- closed connection")

contrib/rcp/rcpc_rx_schema.json

@@ -0,0 +1,69 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "RCP Client RX",
+    "type": "object",
+    "properties": {
+	"rcpc_hello": {
+	    "type": "object",
+	    "properties": {
+		"suitable_for": {
+		    "type": "object",
+		    "properties": {
+			"atr": {
+			    "type": "string",
+			    "pattern": "^[0-9,A-F]{0,66}$"
+			}
+		    },
+		    "additionalProperties": false
+		}
+	    },
+	    "additionalProperties": false
+	},
+	"rcpc_command": {
+	    "type": "object",
+	    "properties": {
+		"cmd": {
+		    "type": "string",
+		    "pattern": "^[0-9,A-Z,a-z,_]{0,40}$"
+		},
+		"cmd_argv": {
+		    "type": "array",
+		    "items": {
+			"type": "string",
+			"pattern": "^.{0,512}$"
+		    },
+		    "maxItems": 255
+		}
+	    },
+	    "additionalProperties": false
+	},
+	"rcpc_result": {
+	    "type": "object",
+	    "properties": {
+		"r_apdu": {
+		    "type": "object",
+		    "properties": {
+			"data": {
+			    "type": "string",
+			    "pattern": "^[0-9,A-F]{0,512}$"
+			},
+			"sw": {
+			    "type": "string",
+			    "pattern": "^[0-9,A-F]{0,4}$"
+			}
+		    },
+		    "additionalProperties": false
+		},
+		"atr": {
+		    "type": "string",
+		    "pattern": "^[0-9,A-F]{0,66}$"
+		},
+		"empty": {
+		    "type": "null"
+		}
+	    },
+	    "additionalProperties": false
+	}
+    },
+    "additionalProperties": false
+}

contrib/rcp/rcpc_tx_schema.json

@@ -0,0 +1,89 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "RCP Client TX",
+    "type": "object",
+    "properties": {
+	"rcpc_welcome": {
+	    "type": "object",
+	    "properties": {
+		"module_descr": {
+		    "type": "array",
+		    "items": {
+			"type": "object",
+			"properties": {
+			    "name": {
+				"type": "string"
+			    },
+			    "cmd_descr": {
+				"type": "array",
+				"items": {
+				    "type": "object",
+				    "properties": {
+					"name": {
+					    "type": "string"
+					},
+					"help": {
+					    "type": "string"
+					},
+					"args": {
+					    "type": "array",
+					    "items": {
+						"name": {
+						    "type": "string"
+						},
+						"spec": {
+						    "type": "object",
+						    "properties": {
+							"required" : {
+							    "type": "boolean"
+							},
+							"help": {
+							    "type": "string"
+							},
+							"action": {
+							    "type": "string"
+							},
+							"pytype": {
+							    "type": "string"
+							},
+							"default" : {
+							    "type": ["string", "integer"]
+							}
+						    },
+						    "additionalProperties": false
+						}
+					    }
+					}
+				    },
+				    "additionalProperties": false
+				}
+			    }
+			},
+			"additionalProperties": false
+		    }
+		}
+	    },
+	    "additionalProperties": false
+	},
+	"rcpc_instr": {
+	    "type": "object",
+	    "properties": {
+		"print": {
+		    "type": "string"
+		},
+		"reset": {
+		    "type": "null"
+		},
+		"c_apdu": {
+		    "type": "string",
+		    "pattern": "^[0-9,A-F]{0,512}$"
+		}
+	    },
+	    "additionalProperties": false
+	},
+	"rcpc_goodbye": {
+	    "type": "integer"
+	}
+    },
+    "additionalProperties": false
+}

contrib/rcp/usage_example/certs/example_ssl_rcp_ca_cert.crt

@@ -0,0 +1,20 @@
+-----BEGIN CERTIFICATE-----
+MIIDSzCCAjOgAwIBAgIUEv1f0yjVtkr+RNYLItZ33eTJwHMwDQYJKoZIhvcNAQEL
+BQAwFjEUMBIGA1UEAwwLRWFzeS1SU0EgQ0EwHhcNMjYwNDI5MTIwOTM0WhcNMzYw
+NDI2MTIwOTM0WjAWMRQwEgYDVQQDDAtFYXN5LVJTQSBDQTCCASIwDQYJKoZIhvcN
+AQEBBQADggEPADCCAQoCggEBANXdkSyQlDzuo2cJmnBmFiZpc0V9tYBcNkpZd3Ac
+R0WljazKKgXDWNmOcSO7891bi+1HZzz+nDfV0mJY776ScGkTqF43Hzpg9eZakMAx
+yC24mT4h+uyRcPWZrBwaQhpiQrvZy4MRyuUB+BEgBSmhoDiuXP44kWiuEJHuzpOq
+X6Q2dW8RIeQPDGGK6XPZIQLqx+krxkaqphd/vHgT1/yd7Ol5xxMc4x2UuPaVCj0D
+OzslFsbb0Zu77ffCtHOVVnzSCzeEGGx1MPQm6hDVW+KUXXTwke1K55fmFZhu0gKO
+HYSEjgPj6X8muDb+GvOAQX3fHmS6KvFS4fwWd2InZ3v2f3cCAwEAAaOBkDCBjTAM
+BgNVHRMEBTADAQH/MB0GA1UdDgQWBBS6zY4Dd0pJFrvWLmyjn0vDTFqVqzBRBgNV
+HSMESjBIgBS6zY4Dd0pJFrvWLmyjn0vDTFqVq6EapBgwFjEUMBIGA1UEAwwLRWFz
+eS1SU0EgQ0GCFBL9X9Mo1bZK/kTWCyLWd93kycBzMAsGA1UdDwQEAwIBBjANBgkq
+hkiG9w0BAQsFAAOCAQEAGJUXlbnVhh+xL+pyTyjwtd8nxhUcHzYZl+OT0bkGY9zT
+S3NjHkKBbdnEftuYDYqp0uBuGFQ1WIOKiM3rp4IePKe84lSivZMVh9ObtNalcEQr
+sqxBziNOMJM2mh5V2NdxiK2E1gCZ959wOQ8yzM6gGC+wW8w4zwULhv4JimQDjk+G
+kAdiGL7+WAxrNWUulvm8khFt2nOlucJg4IAYVt2SI1AFMt/YSXoA4wMwM9QcHGj0
+1A069IxX93WVhUpIL1Avwz+KJK0BPY6SM8LYUy6V50Hojp76BB7VD6SxQrSoceUo
+6cRNDtCmofOlltfeUJLr1mI4S2tM50bQVsHD92EJBA==
+-----END CERTIFICATE-----

contrib/rcp/usage_example/certs/example_ssl_rcpc_rcps_cert.pem

@@ -0,0 +1,115 @@
+Certificate:
+    Data:
+        Version: 3 (0x2)
+        Serial Number:
+            42:38:a5:6f:70:53:40:e4:a4:1a:2c:0f:fc:81:13:42
+        Signature Algorithm: sha256WithRSAEncryption
+        Issuer: CN=Easy-RSA CA
+        Validity
+            Not Before: Apr 29 12:09:35 2026 GMT
+            Not After : Aug  1 12:09:35 2028 GMT
+        Subject: CN=example_ssl_rcpc_rcps_cert
+        Subject Public Key Info:
+            Public Key Algorithm: rsaEncryption
+                Public-Key: (2048 bit)
+                Modulus:
+                    00:ae:0f:e1:ee:fc:f6:db:75:45:c0:f4:49:72:46:
+                    3d:e3:db:0c:c4:34:d2:9e:49:d4:86:4f:19:0d:55:
+                    70:50:81:e4:e6:64:56:a8:58:e8:e6:54:0a:16:bc:
+                    f4:4b:84:cd:1d:b9:2e:ed:62:b6:cd:62:35:8b:81:
+                    18:ab:ff:63:f5:c1:dc:16:3e:a8:dc:ac:11:dd:43:
+                    12:f8:ef:f2:f1:af:84:fd:83:fe:a8:d3:46:7d:77:
+                    e6:ae:95:61:a6:c9:99:6b:40:61:8d:6e:7e:66:1e:
+                    97:77:b0:e8:b7:3d:3a:d5:d7:d3:ee:66:95:62:83:
+                    14:cc:5e:32:ff:9e:bd:f1:06:e6:8d:6a:7c:0a:27:
+                    22:19:b9:06:09:cf:ef:c7:dc:e8:8f:04:4b:83:0d:
+                    cc:8d:b1:c2:cf:ab:40:25:6e:f2:bf:b7:c6:1d:8f:
+                    d2:fc:3d:c8:a1:be:4a:09:b9:91:e3:76:4f:c7:9b:
+                    fc:2f:de:d9:bb:eb:df:d3:d8:8c:72:79:bd:bf:10:
+                    8b:01:e6:0f:7f:bb:f6:75:31:5a:40:ad:df:e1:07:
+                    e6:12:12:b2:d3:99:d0:bd:24:5a:9a:ce:62:4f:da:
+                    fe:0d:df:09:ae:da:04:83:54:e8:cb:68:c0:57:78:
+                    c2:f4:68:42:d7:f4:81:4a:a3:b4:4e:0b:49:95:26:
+                    1d:15
+                Exponent: 65537 (0x10001)
+        X509v3 extensions:
+            X509v3 Basic Constraints: 
+                CA:FALSE
+            X509v3 Subject Key Identifier: 
+                8E:99:9D:C0:70:98:57:16:08:8E:DF:6E:51:78:A6:86:18:FF:06:52
+            X509v3 Authority Key Identifier: 
+                keyid:BA:CD:8E:03:77:4A:49:16:BB:D6:2E:6C:A3:9F:4B:C3:4C:5A:95:AB
+                DirName:/CN=Easy-RSA CA
+                serial:12:FD:5F:D3:28:D5:B6:4A:FE:44:D6:0B:22:D6:77:DD:E4:C9:C0:73
+            X509v3 Extended Key Usage: 
+                TLS Web Server Authentication
+            X509v3 Key Usage: 
+                Digital Signature, Key Encipherment
+            X509v3 Subject Alternative Name: 
+                DNS:127.0.0.1, IP Address:127.0.0.1
+    Signature Algorithm: sha256WithRSAEncryption
+    Signature Value:
+        3e:56:20:f9:3b:fa:13:6e:7e:a9:80:a6:15:18:01:82:f1:b8:
+        4d:1b:f1:ee:da:ed:50:f7:3b:13:01:a5:14:f9:4c:0e:34:57:
+        dc:e6:d1:7e:02:30:af:3b:fd:c9:ae:18:16:c9:3b:0a:4e:20:
+        da:cd:e8:cc:05:0c:b3:7d:6f:e5:15:ff:66:59:6b:fe:ff:1a:
+        ef:ca:b5:3a:1a:ad:dd:f6:19:43:d9:2b:61:18:29:95:b4:0c:
+        1e:b2:4a:ce:80:d3:1b:59:dc:62:ec:50:21:37:9c:2f:7a:4d:
+        c2:ac:de:1b:1d:a3:25:e0:e8:33:42:cf:77:31:2a:f2:44:36:
+        ef:59:89:da:6c:3e:9a:e8:d7:06:39:17:d5:78:82:6d:b6:63:
+        3f:9a:40:3b:e6:12:58:52:3d:63:4e:85:0b:02:cb:40:d2:8a:
+        59:8d:8f:ee:4a:c8:97:91:51:a9:2f:1b:15:81:9c:20:dd:94:
+        08:6f:ac:fa:c6:28:90:6c:17:5a:23:87:9a:5b:e5:c6:2e:f3:
+        09:66:de:76:1b:60:42:c1:5c:71:88:87:f6:7b:cb:e3:7e:14:
+        67:c9:a0:15:98:b6:7b:75:40:9a:08:fc:77:39:3a:23:cb:e3:
+        78:7d:57:f9:a7:66:36:b4:b5:07:de:61:3a:dd:07:58:b3:4f:
+        41:f6:f4:d9
+-----BEGIN CERTIFICATE-----
+MIIDhDCCAmygAwIBAgIQQjilb3BTQOSkGiwP/IETQjANBgkqhkiG9w0BAQsFADAW
+MRQwEgYDVQQDDAtFYXN5LVJTQSBDQTAeFw0yNjA0MjkxMjA5MzVaFw0yODA4MDEx
+MjA5MzVaMCUxIzAhBgNVBAMMGmV4YW1wbGVfc3NsX3JjcGNfcmNwc19jZXJ0MIIB
+IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArg/h7vz223VFwPRJckY949sM
+xDTSnknUhk8ZDVVwUIHk5mRWqFjo5lQKFrz0S4TNHbku7WK2zWI1i4EYq/9j9cHc
+Fj6o3KwR3UMS+O/y8a+E/YP+qNNGfXfmrpVhpsmZa0BhjW5+Zh6Xd7Dotz061dfT
+7maVYoMUzF4y/5698QbmjWp8CiciGbkGCc/vx9zojwRLgw3MjbHCz6tAJW7yv7fG
+HY/S/D3Iob5KCbmR43ZPx5v8L97Zu+vf09iMcnm9vxCLAeYPf7v2dTFaQK3f4Qfm
+EhKy05nQvSRams5iT9r+Dd8JrtoEg1Toy2jAV3jC9GhC1/SBSqO0TgtJlSYdFQID
+AQABo4G+MIG7MAkGA1UdEwQCMAAwHQYDVR0OBBYEFI6ZncBwmFcWCI7fblF4poYY
+/wZSMFEGA1UdIwRKMEiAFLrNjgN3SkkWu9YubKOfS8NMWpWroRqkGDAWMRQwEgYD
+VQQDDAtFYXN5LVJTQSBDQYIUEv1f0yjVtkr+RNYLItZ33eTJwHMwEwYDVR0lBAww
+CgYIKwYBBQUHAwEwCwYDVR0PBAQDAgWgMBoGA1UdEQQTMBGCCTEyNy4wLjAuMYcE
+fwAAATANBgkqhkiG9w0BAQsFAAOCAQEAPlYg+Tv6E25+qYCmFRgBgvG4TRvx7trt
+UPc7EwGlFPlMDjRX3ObRfgIwrzv9ya4YFsk7Ck4g2s3ozAUMs31v5RX/Zllr/v8a
+78q1Ohqt3fYZQ9krYRgplbQMHrJKzoDTG1ncYuxQITecL3pNwqzeGx2jJeDoM0LP
+dzEq8kQ271mJ2mw+mujXBjkX1XiCbbZjP5pAO+YSWFI9Y06FCwLLQNKKWY2P7krI
+l5FRqS8bFYGcIN2UCG+s+sYokGwXWiOHmlvlxi7zCWbedhtgQsFccYiH9nvL434U
+Z8mgFZi2e3VAmgj8dzk6I8vjeH1X+admNrS1B95hOt0HWLNPQfb02Q==
+-----END CERTIFICATE-----
+-----BEGIN PRIVATE KEY-----
+MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCuD+Hu/PbbdUXA
+9ElyRj3j2wzENNKeSdSGTxkNVXBQgeTmZFaoWOjmVAoWvPRLhM0duS7tYrbNYjWL
+gRir/2P1wdwWPqjcrBHdQxL47/Lxr4T9g/6o00Z9d+aulWGmyZlrQGGNbn5mHpd3
+sOi3PTrV19PuZpVigxTMXjL/nr3xBuaNanwKJyIZuQYJz+/H3OiPBEuDDcyNscLP
+q0AlbvK/t8Ydj9L8PcihvkoJuZHjdk/Hm/wv3tm769/T2Ixyeb2/EIsB5g9/u/Z1
+MVpArd/hB+YSErLTmdC9JFqazmJP2v4N3wmu2gSDVOjLaMBXeML0aELX9IFKo7RO
+C0mVJh0VAgMBAAECggEAGBhmQhdeE+Cu1Ihsn2dWW3PAF2wpiNR3GVWbRfOBHf/x
+QCx9K4ZNTU8ua1niZo7edyIiuyVaYWGaQHLRR8QNoiBhN2oapZujSHInzvKmeqr9
+ubt7NgMzQ5ykwB+5OiW3uXda2cGFOV08QgspF+6ftakQMzUbslyrdSQIIscmi5Ya
+uTDvE6+lBFinxy3RHFKVCZ3UrsDwfHR4eTUmgCHRB27joB7DFXL32amv0M8HjoGz
+EZKGJgTwmRf9U4z4D4wCnOfVAPlsuthKUqMuTlBg0ZEstMZrzlP4suT2ieku0Usv
+0XbJ38VozPYYFdR7nApVVvrJgHzI9cpoUbGto4BLOQKBgQDbXjFVLffOec8hv9dN
+2VGZQmK61S9OrbvTnEOlxJd+kRid71X1pV5TuPKJJQtUJXf429bQOs40YbLeOmJt
+BiRSR5yIBH7hDDC/c0ynqunstwDlgz+QX2Oh2B4alvVaWy0rZYF6NpBiI0+R5r5V
+C2fHRS4LLPoflg83+CMubyLS6QKBgQDLIOXxlp1JQTzXhJkrkytLkafmEHAafovt
+wbRD50/s+dl16BRX12sK0gXj2vwu0FleUD6Z7afDfspmvQdg3fyDxYw9Q+vw5LYQ
+7BvoVU99o1m468yXwX/v36peCt4nOpwkJZKJfjgxjnMJByyeSUgL9uW4K+0D0LBV
+a5Iv7QklTQKBgH30BkVPIHKIE/rfyIJlXemuaTu2/fOh4y9sEJdUWluMeeLssaFa
+ct+FWJSQFYIaBVl4+E0VBqKi2e2o/ix1E1O+1ExwsF0M/8xdKk024BtPNA+TnWKK
+so0Rpq9Dr9pScYvyOzZtr9b5SU2PfAcehlavDPHTwEV0hoZvTdvyab9JAoGADMBJ
+7vp3cSvJN/Y470VTyHCiS4zonKEpA4nPWRviJowgnIgvDryVGZ7Jg94xSncFxSfg
+ZiVHDLye1Ag1uFz3BwaVoRrsarjQvQs1TUZdsRNaBIO42iXpdBNkTHb+LxQ8zQAW
+zM7BlErO6dgrctxCy416Ki+Ht1+YUiRojt2gX1kCgYBqytUy+XkPi5j3Ga29xcvP
+WI3Uc8RI2GmoAmrw5QFiSG6lNXAzfo2ZNQbFnxgxeMOG9fV9yzBdIjXWNWr0E/KH
+Fsb65R8iIrXQB9BZjuQqjz9nDm7eZZUBNGGbQ4DgSepnp194gXC5DoAElzuwOXbE
+pY/kM1KwlpUR3J3LeF3i+Q==
+-----END PRIVATE KEY-----

contrib/rcp/usage_example/certs/example_ssl_rcpm_rcps_cert.pem

@@ -0,0 +1,115 @@
+Certificate:
+    Data:
+        Version: 3 (0x2)
+        Serial Number:
+            e7:09:ab:70:b5:dc:1f:11:d9:2a:23:04:39:87:34:f3
+        Signature Algorithm: sha256WithRSAEncryption
+        Issuer: CN=Easy-RSA CA
+        Validity
+            Not Before: Apr 29 12:09:35 2026 GMT
+            Not After : Aug  1 12:09:35 2028 GMT
+        Subject: CN=example_ssl_rcpm_rcps_cert
+        Subject Public Key Info:
+            Public Key Algorithm: rsaEncryption
+                Public-Key: (2048 bit)
+                Modulus:
+                    00:cc:79:9b:d3:f3:1f:41:9f:00:48:cd:47:0b:ae:
+                    b9:1c:4e:3e:55:e2:4e:5f:a8:cc:13:d5:dd:bd:f0:
+                    01:4c:19:ae:e3:a9:09:06:89:92:49:f7:bb:90:28:
+                    fb:8c:22:69:b5:f5:a0:50:3d:97:0f:1e:1d:b1:a8:
+                    57:9b:d7:e2:0d:99:67:7f:02:82:0c:9c:8e:dd:13:
+                    03:28:93:b5:cb:7e:b5:78:06:10:bf:7b:55:c3:f7:
+                    10:8b:20:4a:1c:f9:f1:b2:fa:f1:c7:44:9d:0a:ce:
+                    ef:8d:f9:e8:ff:d1:c1:69:ec:8e:5f:11:cc:c9:98:
+                    d5:1c:33:e2:5b:7a:4d:34:dc:76:c3:cd:db:4c:93:
+                    d1:08:78:6f:3c:9a:ee:74:39:1e:cd:65:1e:c9:35:
+                    cc:3b:2b:9e:d7:49:10:8e:58:85:b0:10:5b:90:1e:
+                    f1:5e:d5:92:04:93:f9:33:c6:9d:77:63:d1:33:46:
+                    5b:98:ff:9a:a8:f5:df:f7:84:21:e2:88:28:7a:a4:
+                    c6:0d:9f:25:7e:0d:73:5b:d5:53:4a:90:79:94:37:
+                    14:f3:c8:75:76:d4:1c:32:51:bf:58:16:74:d5:8d:
+                    18:b6:53:f4:ab:cb:91:a8:8c:a3:ca:3c:5c:35:b6:
+                    5f:62:57:37:5a:75:28:b7:4d:26:aa:ea:50:da:a4:
+                    1c:55
+                Exponent: 65537 (0x10001)
+        X509v3 extensions:
+            X509v3 Basic Constraints: 
+                CA:FALSE
+            X509v3 Subject Key Identifier: 
+                47:92:B5:81:8B:5C:14:98:B3:83:B6:EB:06:9F:43:F3:3A:7E:ED:24
+            X509v3 Authority Key Identifier: 
+                keyid:BA:CD:8E:03:77:4A:49:16:BB:D6:2E:6C:A3:9F:4B:C3:4C:5A:95:AB
+                DirName:/CN=Easy-RSA CA
+                serial:12:FD:5F:D3:28:D5:B6:4A:FE:44:D6:0B:22:D6:77:DD:E4:C9:C0:73
+            X509v3 Extended Key Usage: 
+                TLS Web Server Authentication
+            X509v3 Key Usage: 
+                Digital Signature, Key Encipherment
+            X509v3 Subject Alternative Name: 
+                DNS:127.0.0.1, IP Address:127.0.0.1
+    Signature Algorithm: sha256WithRSAEncryption
+    Signature Value:
+        6d:31:e6:29:d2:3b:a8:90:5c:4b:ac:61:15:95:5d:70:66:a5:
+        77:9d:88:47:49:73:75:be:70:69:d8:2f:62:82:5e:83:86:3b:
+        a8:48:3f:f1:5f:22:ae:81:23:64:c4:f2:2b:dd:4d:be:e5:6a:
+        26:a5:ea:c7:ba:1b:3e:6a:34:03:5a:f1:49:28:5f:56:4a:a6:
+        0e:1b:7a:07:48:76:95:b6:4b:f5:3f:b9:67:2e:e0:33:06:80:
+        d4:d6:01:a5:76:01:c0:a5:18:e5:38:8b:52:73:6e:6d:45:50:
+        b7:9a:ab:86:5d:e3:65:b4:b8:c7:ee:b2:dc:bf:e3:d5:bb:e4:
+        91:eb:f5:0c:38:22:5e:37:54:9e:ba:96:25:10:04:18:23:f7:
+        ae:73:4d:d0:aa:03:81:b4:89:36:97:15:da:1a:60:a0:98:5f:
+        03:f8:1b:22:83:57:41:4b:12:28:7d:8d:ea:88:74:24:28:5c:
+        53:41:89:5e:9a:da:fd:7b:bf:60:dc:de:9b:49:ce:5c:a3:b2:
+        01:7d:1d:cb:28:8c:ba:f4:7b:5d:2b:cb:15:5b:2a:97:1a:d1:
+        f9:e7:12:e3:43:b9:f4:2a:88:dd:6d:b6:a0:72:d3:bd:63:23:
+        e9:d7:f0:ac:b5:6d:0d:f2:d9:8b:2c:c4:35:5b:4d:83:dc:e8:
+        7d:0b:3d:a3
+-----BEGIN CERTIFICATE-----
+MIIDhTCCAm2gAwIBAgIRAOcJq3C13B8R2SojBDmHNPMwDQYJKoZIhvcNAQELBQAw
+FjEUMBIGA1UEAwwLRWFzeS1SU0EgQ0EwHhcNMjYwNDI5MTIwOTM1WhcNMjgwODAx
+MTIwOTM1WjAlMSMwIQYDVQQDDBpleGFtcGxlX3NzbF9yY3BtX3JjcHNfY2VydDCC
+ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMx5m9PzH0GfAEjNRwuuuRxO
+PlXiTl+ozBPV3b3wAUwZruOpCQaJkkn3u5Ao+4wiabX1oFA9lw8eHbGoV5vX4g2Z
+Z38Cggycjt0TAyiTtct+tXgGEL97VcP3EIsgShz58bL68cdEnQrO74356P/RwWns
+jl8RzMmY1Rwz4lt6TTTcdsPN20yT0Qh4bzya7nQ5Hs1lHsk1zDsrntdJEI5YhbAQ
+W5Ae8V7VkgST+TPGnXdj0TNGW5j/mqj13/eEIeKIKHqkxg2fJX4Nc1vVU0qQeZQ3
+FPPIdXbUHDJRv1gWdNWNGLZT9KvLkaiMo8o8XDW2X2JXN1p1KLdNJqrqUNqkHFUC
+AwEAAaOBvjCBuzAJBgNVHRMEAjAAMB0GA1UdDgQWBBRHkrWBi1wUmLODtusGn0Pz
+On7tJDBRBgNVHSMESjBIgBS6zY4Dd0pJFrvWLmyjn0vDTFqVq6EapBgwFjEUMBIG
+A1UEAwwLRWFzeS1SU0EgQ0GCFBL9X9Mo1bZK/kTWCyLWd93kycBzMBMGA1UdJQQM
+MAoGCCsGAQUFBwMBMAsGA1UdDwQEAwIFoDAaBgNVHREEEzARggkxMjcuMC4wLjGH
+BH8AAAEwDQYJKoZIhvcNAQELBQADggEBAG0x5inSO6iQXEusYRWVXXBmpXediEdJ
+c3W+cGnYL2KCXoOGO6hIP/FfIq6BI2TE8ivdTb7laial6se6Gz5qNANa8UkoX1ZK
+pg4begdIdpW2S/U/uWcu4DMGgNTWAaV2AcClGOU4i1Jzbm1FULeaq4Zd42W0uMfu
+sty/49W75JHr9Qw4Il43VJ66liUQBBgj965zTdCqA4G0iTaXFdoaYKCYXwP4GyKD
+V0FLEih9jeqIdCQoXFNBiV6a2v17v2Dc3ptJzlyjsgF9HcsojLr0e10ryxVbKpca
+0fnnEuNDufQqiN1ttqBy071jI+nX8Ky1bQ3y2YssxDVbTYPc6H0LPaM=
+-----END CERTIFICATE-----
+-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDMeZvT8x9BnwBI
+zUcLrrkcTj5V4k5fqMwT1d298AFMGa7jqQkGiZJJ97uQKPuMImm19aBQPZcPHh2x
+qFeb1+INmWd/AoIMnI7dEwMok7XLfrV4BhC/e1XD9xCLIEoc+fGy+vHHRJ0Kzu+N
++ej/0cFp7I5fEczJmNUcM+Jbek003HbDzdtMk9EIeG88mu50OR7NZR7JNcw7K57X
+SRCOWIWwEFuQHvFe1ZIEk/kzxp13Y9EzRluY/5qo9d/3hCHiiCh6pMYNnyV+DXNb
+1VNKkHmUNxTzyHV21BwyUb9YFnTVjRi2U/Sry5GojKPKPFw1tl9iVzdadSi3TSaq
+6lDapBxVAgMBAAECggEADJFN6K9OWhYX1PcEWUgOLxqdCLd95Iccsfxot7ekcMUP
+A4WnHRyACLqor9c2V3o2//IpU2fnB2IXu6ISmRd3WKl3hm4vnZmoIJeTpQm9Iv/g
++fqkyrbIgktcHDJUySal+n+jiYFNW2B1h1xXUT/scMz+FthNJg1Azfi0vorMFjCk
+SBOSo7BQ2hiQ83FneVJU1TsxD4S4IBLx9fF6AW05norRmvm17Ip2pKk4QYzKiOI3
+NIoSwbOgU0Vp1X3MMlilM5ZZdN3a9lI6lfBZE682WOxBmH67mKMQnR8aC+nwynQ+
+45pUQIn8Fjx2hQHehbD7ZNw9Nob9AyGWqWGKFV74IQKBgQDox/j7dCHNm1mz1QRm
+Q2YyN4OGXJI97t9Gd8UdNCv5bAkdx2cR2lmP3tRc6iAzrfNIpPCGaXo1vwJx477X
+wO95W2b4hfm3j6v0cqRbsFzzVIHZUB77pXfAJfZeICpoqu0vxn5nb+yPgzgmToLX
+pbIDdqWafzzrDLTmLCfwfKDI9QKBgQDg3tgpAXo8WCL4phNuW44XQ172lPTijpn+
+wj1Z0rBrS806gL/+QvZZLS1WCym/QBV7TgGlxIJbmAfghcGyin3NliskSHAiccxG
+/9eCSQes8czfsVj6qmBMwyff5r+wmk662qV0u07UHmuykYk3Dgs/zYdwq2SsTlL4
+Y9eRjutp4QKBgQCONg0wYcR8/hmROeRULXzz1OJvZYKaf6K8RFOSAduTp6LyJG4d
+hA4PTQzkLsy5hd4JVWr0UuAskaMGvSJMYTxsIaEI16C1ufpNfvRWZ6qBpfEmOEKV
+boN4Sjj3TCNcioAZHeT/gGs/SeU10eUxpbLZVtTZTD6FQuAJdpR34UvBOQKBgFNM
+mXxPLM2vxHyhYK9PwQoDDel/8lr+gjMqFvnwHyQP911FllmEyqbsIlAuYG+VOJ/t
+nJSgf72YSsq0IbWWsdV3XFHbd5Z62zYtzdJYZTx+cesnUhPBC11EKcA6RSYRczqq
+hgIA5MmU30ZNvSukyyv+Yb6t7uQZO4kByzgDXldhAoGBALgRkAHxgbKUXp5XyCDJ
+e8dwVx0g9tfDM/DEZtU/Si5oUaunBaPV/Byov7OXOT02V8JLnA5ChUYgwUFI030x
+QL/3eK12Qh5Gb9VabvYCicDRk4GzmqZU9Wcvm1zgbUr5jY8Lou44nFjol/Y1m70n
+51WZbVkkWmBZO5m3NqN66SkJ
+-----END PRIVATE KEY-----

contrib/rcp/usage_example/certs/example_ssl_rcps_rcpm_cert.pem

@@ -0,0 +1,115 @@
+Certificate:
+    Data:
+        Version: 3 (0x2)
+        Serial Number:
+            28:96:2e:a1:40:e0:7e:f1:fb:63:1a:f4:53:6f:ce:fb
+        Signature Algorithm: sha256WithRSAEncryption
+        Issuer: CN=Easy-RSA CA
+        Validity
+            Not Before: Apr 29 12:09:35 2026 GMT
+            Not After : Aug  1 12:09:35 2028 GMT
+        Subject: CN=example_ssl_rcps_rcpm_cert
+        Subject Public Key Info:
+            Public Key Algorithm: rsaEncryption
+                Public-Key: (2048 bit)
+                Modulus:
+                    00:ae:11:46:ef:d1:81:34:dd:23:5d:54:40:f3:9c:
+                    85:35:95:a6:91:57:92:5c:bf:eb:40:34:69:eb:db:
+                    c0:86:3c:7b:ff:9c:d7:ba:0e:41:57:84:15:cd:94:
+                    f1:48:63:50:9c:34:97:ee:be:be:b0:27:d8:fd:cd:
+                    8a:cf:85:ff:08:1f:07:d8:28:96:0e:e4:2d:d0:8b:
+                    df:a8:fa:41:47:a0:a2:80:2e:2e:58:01:cc:6f:43:
+                    5c:c2:fb:84:a7:ff:9e:97:bb:b3:a3:1f:63:64:73:
+                    8d:73:dd:f4:7e:96:d7:6b:b3:cb:e2:35:59:55:e0:
+                    e7:e3:c0:41:f8:b6:0f:c5:46:4c:cd:0e:91:80:ef:
+                    e3:43:f0:72:26:12:10:be:83:a2:db:23:2d:b4:b1:
+                    07:5a:b1:b3:10:9c:09:69:98:42:79:81:77:5e:22:
+                    e4:71:47:70:27:15:2c:a7:13:c2:6d:44:59:b4:73:
+                    c9:bb:27:7f:d6:e8:3d:85:bb:36:f6:cb:71:36:11:
+                    b1:99:1a:1d:1a:15:dd:cd:65:7f:cd:cc:10:00:49:
+                    ed:07:2d:7b:15:88:be:73:ba:1d:15:69:bc:d3:02:
+                    55:ea:dc:2c:3f:0b:cd:18:57:59:7a:e3:09:b2:89:
+                    cd:d6:e7:f6:95:c4:2e:8a:53:2b:a8:96:82:94:53:
+                    00:77
+                Exponent: 65537 (0x10001)
+        X509v3 extensions:
+            X509v3 Basic Constraints: 
+                CA:FALSE
+            X509v3 Subject Key Identifier: 
+                60:BD:48:06:68:15:D4:DC:ED:EE:E4:C7:B1:9F:C4:93:6D:50:3A:77
+            X509v3 Authority Key Identifier: 
+                keyid:BA:CD:8E:03:77:4A:49:16:BB:D6:2E:6C:A3:9F:4B:C3:4C:5A:95:AB
+                DirName:/CN=Easy-RSA CA
+                serial:12:FD:5F:D3:28:D5:B6:4A:FE:44:D6:0B:22:D6:77:DD:E4:C9:C0:73
+            X509v3 Extended Key Usage: 
+                TLS Web Server Authentication
+            X509v3 Key Usage: 
+                Digital Signature, Key Encipherment
+            X509v3 Subject Alternative Name: 
+                DNS:127.0.0.1, IP Address:127.0.0.1
+    Signature Algorithm: sha256WithRSAEncryption
+    Signature Value:
+        c5:35:61:58:23:e2:69:da:6c:d5:41:ab:a8:70:f4:dd:cc:a0:
+        a3:3d:84:89:93:b6:7f:69:7d:10:35:9d:c5:d1:0d:db:d2:d7:
+        36:af:d4:54:30:14:a7:5d:31:ca:5c:13:92:d5:60:50:f8:56:
+        4a:cb:16:b1:b3:b1:03:bf:96:53:77:1f:4a:0f:9c:29:2b:bf:
+        a4:e0:da:6f:ad:13:c7:2d:8e:18:c4:72:50:17:ed:1f:36:51:
+        7a:12:9f:fc:a6:d6:c8:55:e0:db:ea:16:d6:22:0d:a2:cb:eb:
+        b2:ba:07:92:2f:db:33:d6:a2:0c:ec:89:29:f1:96:40:e5:0b:
+        e6:1f:08:50:d6:29:87:a8:20:b2:e2:17:50:25:ff:53:36:ee:
+        7f:ce:e6:1d:ed:b3:16:61:18:42:a9:17:9e:a6:86:0d:a5:fc:
+        f9:42:c8:50:48:74:72:35:eb:8c:ff:4d:e8:98:88:a0:b4:b3:
+        d0:82:b3:2f:ea:19:d7:d5:ac:47:35:96:24:37:34:0c:7a:a2:
+        e0:4d:99:a7:55:61:85:1e:7e:6a:23:77:f5:07:13:e6:50:5c:
+        65:00:13:f6:b5:4b:5b:8c:11:c3:5d:af:ba:41:e9:84:1d:f1:
+        a4:70:16:28:c2:be:6e:d8:67:38:c5:a0:ba:8a:64:6f:27:ce:
+        63:a0:92:9b
+-----BEGIN CERTIFICATE-----
+MIIDhDCCAmygAwIBAgIQKJYuoUDgfvH7Yxr0U2/O+zANBgkqhkiG9w0BAQsFADAW
+MRQwEgYDVQQDDAtFYXN5LVJTQSBDQTAeFw0yNjA0MjkxMjA5MzVaFw0yODA4MDEx
+MjA5MzVaMCUxIzAhBgNVBAMMGmV4YW1wbGVfc3NsX3JjcHNfcmNwbV9jZXJ0MIIB
+IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArhFG79GBNN0jXVRA85yFNZWm
+kVeSXL/rQDRp69vAhjx7/5zXug5BV4QVzZTxSGNQnDSX7r6+sCfY/c2Kz4X/CB8H
+2CiWDuQt0IvfqPpBR6CigC4uWAHMb0NcwvuEp/+el7uzox9jZHONc930fpbXa7PL
+4jVZVeDn48BB+LYPxUZMzQ6RgO/jQ/ByJhIQvoOi2yMttLEHWrGzEJwJaZhCeYF3
+XiLkcUdwJxUspxPCbURZtHPJuyd/1ug9hbs29stxNhGxmRodGhXdzWV/zcwQAEnt
+By17FYi+c7odFWm80wJV6twsPwvNGFdZeuMJsonN1uf2lcQuilMrqJaClFMAdwID
+AQABo4G+MIG7MAkGA1UdEwQCMAAwHQYDVR0OBBYEFGC9SAZoFdTc7e7kx7GfxJNt
+UDp3MFEGA1UdIwRKMEiAFLrNjgN3SkkWu9YubKOfS8NMWpWroRqkGDAWMRQwEgYD
+VQQDDAtFYXN5LVJTQSBDQYIUEv1f0yjVtkr+RNYLItZ33eTJwHMwEwYDVR0lBAww
+CgYIKwYBBQUHAwEwCwYDVR0PBAQDAgWgMBoGA1UdEQQTMBGCCTEyNy4wLjAuMYcE
+fwAAATANBgkqhkiG9w0BAQsFAAOCAQEAxTVhWCPiadps1UGrqHD03cygoz2EiZO2
+f2l9EDWdxdEN29LXNq/UVDAUp10xylwTktVgUPhWSssWsbOxA7+WU3cfSg+cKSu/
+pODab60Txy2OGMRyUBftHzZRehKf/KbWyFXg2+oW1iINosvrsroHki/bM9aiDOyJ
+KfGWQOUL5h8IUNYph6ggsuIXUCX/Uzbuf87mHe2zFmEYQqkXnqaGDaX8+ULIUEh0
+cjXrjP9N6JiIoLSz0IKzL+oZ19WsRzWWJDc0DHqi4E2Zp1VhhR5+aiN39QcT5lBc
+ZQAT9rVLW4wRw12vukHphB3xpHAWKMK+bthnOMWguopkbyfOY6CSmw==
+-----END CERTIFICATE-----
+-----BEGIN PRIVATE KEY-----
+MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCuEUbv0YE03SNd
+VEDznIU1laaRV5Jcv+tANGnr28CGPHv/nNe6DkFXhBXNlPFIY1CcNJfuvr6wJ9j9
+zYrPhf8IHwfYKJYO5C3Qi9+o+kFHoKKALi5YAcxvQ1zC+4Sn/56Xu7OjH2Nkc41z
+3fR+ltdrs8viNVlV4OfjwEH4tg/FRkzNDpGA7+ND8HImEhC+g6LbIy20sQdasbMQ
+nAlpmEJ5gXdeIuRxR3AnFSynE8JtRFm0c8m7J3/W6D2Fuzb2y3E2EbGZGh0aFd3N
+ZX/NzBAASe0HLXsViL5zuh0VabzTAlXq3Cw/C80YV1l64wmyic3W5/aVxC6KUyuo
+loKUUwB3AgMBAAECggEABGfLiSZJmYeUmDgZrLtkDlx16sJx9zGkR+u2V+cn6D3U
++uiCoo2EedfjSrYKT/AI35Xf19sGrc6ptJgPJfwY3aEWFxJv5HtB7ZVHWS98QiPT
++QqHgb1fPzGlQgoQ7Bo8GVBW1joPz0Bdbsv0ntTn1CyowauNUe8Z71mzpxJ0iQ7u
+Z8LNoD7INEAZDBjHVov6pLGDHS9KFxGy20WG549mE37I4QxyxetJEgmuyhJkZOQ4
+noEWiCMQjGsSg4YuSc1GS1jAVf3p2g3/TiheD/31r1jleY/T5s2qYC6MJ4vY+7yA
+5sl7m8A47i0lHSKBdR3nWz+vXEsxB0nXK3Sulyt9AQKBgQDYRZ1nEe32CCZcWn/7
+nG+9e6XNOe9E25skuvY/uEpikt92kdnyZOgHFfwM9Nv+w2IWGLZ8MmDDJ6/4hGvj
+fJjcOUb3d/SJiivPvdRC9GYMrDUZe5AJ3p6fPqi4IeZOw7bMTcVB6aHAr9KoO//J
+2t0WNvwzkOyl6KlhaQEIDK8bOQKBgQDOCvWvUEg8nHaKcmN0uQaKuPvCorhnyqUT
+VFqLlSrYC79ffHCwp2y8nkFUnxpeHXENrtHtcrdnKBNkgGEn2l4xs63CjhKrBuIG
+bDjrtp3vKlHRhQjX6HkrEEuUk52wYzuX7CfU8nTZnrtV74MocOEewJVW+84Rtwiw
+vIUcgfgJLwKBgAbgj9TLOSntsGqXZiJ2Iwd/exI/mWAzK4fLejEkhxkDWp/Gm4ud
+sdMn28/9qVE8nU3ek073uyP5ixr3+wZM2/+EwsDzy47kGeiNPMa0Rtp4T2f0CeyG
+a7zcnTjduxkeGB3/CxrBdydNcAFxhvzAPO+L6BErtpq//0Ldt+6tmJPhAoGAFxEh
+Cjx5qdd2ae9+dO3V7qfg/5xJ+sy0CGL0NBZCEqfWB/GdiBlmUgOBmuCpCgpPwtFk
+jSm/oJva9/BrcBPBYd0Uweg37M+7dC6ffLwYGFNrj4JOSCWtkwWjAII6MCob3NlC
+aFOwg0CDBo7m5xskCNZUocVU/6S3I1onqNZgF18CgYAczBf1NS4VPZvebrutTBEH
+zyUX3XU9mR+dy0ncCGNVS8zYMtz7cweZInzNB2cTOfisIHzzdOnazm7D9uzPsREi
+pKgaL+ErWYDlGiDTxMtGSRPTWGocYBYdU6y/0bobhZb0qyvyRhpGvPK0ReMUuvqu
+FkNgoQ1lo0n6vawvxWW8Mw==
+-----END PRIVATE KEY-----

contrib/rcp/usage_example/certs/make_certs.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+EASYRSA=/usr/share/easy-rsa/easyrsa
+CA_NAME="example_ssl_rcp_ca_cert"
+
+export EASYRSA_PASSIN=pass:test
+export EASYRSA_PASSOUT=pass:test
+
+echo "Cleaning up..."
+rm -rf ./ca
+rm -rf ./*.pem
+rm -rf ./*.key
+rm -rf ./*.crt
+
+echo "Creating CA cert..."
+mkdir -p ./ca
+cd ./ca
+$EASYRSA init-pki
+cp ../vars ./pki/
+$EASYRSA --batch build-ca
+cp ./pki/ca.crt  ../$CA_NAME.crt
+
+echo "Creating server certs..."
+# Secures connection between RCP-Client and RCP-Server:
+$EASYRSA --batch --subject-alt-name="DNS:127.0.0.1,IP:127.0.0.1" build-server-full example_ssl_rcpc_rcps_cert nopass
+
+# Secures connection between RCP-Module and RCP-Server (module description):
+$EASYRSA --batch --subject-alt-name="DNS:127.0.0.1,IP:127.0.0.1" build-server-full example_ssl_rcpm_rcps_cert nopass
+
+# Secures connection between RCP-Server and RCP-Module (command execution):
+$EASYRSA --batch --subject-alt-name="DNS:127.0.0.1,IP:127.0.0.1" build-server-full example_ssl_rcps_rcpm_cert nopass
+
+echo "Collecting server certs..."
+cp ./pki/issued/* ../
+cp ./pki/private/* ../
+cd ..
+rm ./ca.key
+
+echo "Merging server certs..."
+for CRT in ./*.crt; do
+    CRT_NAME=`basename ${CRT%.*}`
+    if [ -f $CRT_NAME.key ]; then
+	cat $CRT_NAME.crt $CRT_NAME.key > $CRT_NAME.pem
+	rm $CRT_NAME.key
+	rm $CRT_NAME.crt
+    fi
+done
+
+echo "Finalizing..."
+rm -rf ./ca

contrib/rcp/usage_example/params.cfg

@@ -0,0 +1,36 @@
+# PYSIM_DIR passed to all components
+PYSIM_DIR=../../../ # Points to the psyim top directory
+
+# Verbosity switch passed to all components (comment-out to disable verbode mode)
+#VERBOSE="--verbose"
+
+# PCSC reader that the RCP Client shall use
+PCSC_READER=0
+
+# Since RCP Modules are custom implementations, they will most likely reside
+# in a dedicated directory. This directory is passed together with PYSIM_DIR
+# via PYTHONPATH to the module.
+RCP_DIR=../
+
+# CA of the certificates used in this example
+CA_CERT="./certs/example_ssl_rcp_ca_cert.crt"
+
+# Network interface where RCP Clients connect
+RCPC_SERVER_PORT=8000
+RCPC_SERVER_ADDR="127.0.0.1"
+RCPC_SERVER_CERT="./certs/example_ssl_rcpc_rcps_cert.pem"
+RCPC_SERVER_URI="wss://$RCPC_SERVER_ADDR:$RCPC_SERVER_PORT"
+
+# Network interface where RCP Modules connect
+RCPM_SERVER_PORT=8010
+RCPM_SERVER_ADDR="127.0.0.1"
+RCPM_SERVER_CERT="./certs/example_ssl_rcpm_rcps_cert.pem"
+RCPM_SERVER_URI="wss://$RCPM_SERVER_ADDR:$RCPM_SERVER_PORT"
+
+# Network interface where the (example) RCP Module binds its Command Server to.
+# The command server is used by the RCP Server to run the command requested
+# by the user. Each module needs a dedicated port. The address and port is
+# automatically forwarded to the RCP Server.
+RCPM_CMD_SERVER_PORT=8020
+RCPM_CMD_SERVER_ADDR="127.0.0.1"
+RCPM_CMD_SERVER_CERT="./certs/example_ssl_rcps_rcpm_cert.pem"

contrib/rcp/usage_example/rcp_module.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+
+# (C) 2026 by sysmocom - s.f.m.c. GmbH
+# All Rights Reserved
+#
+# Author: Philipp Maier
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import logging
+from pathlib import Path
+from pySim.log import PySimLogger
+from argparse import Namespace
+from rcp_module_utils import rcpm_setup_argparse, rcpm_run_module, RcpModule, RcpmCmdSrvConnHdlr
+
+log = PySimLogger.get(Path(__file__).stem)
+
+class ExmpleModule(RcpModule):
+
+    name = Path(__file__).stem
+    cmd_descr = [{"name" : "reset",
+                  "help": "reset the card",
+                  "args" : []},
+                 {"name" : "read_binary",
+                  "help": "read binary data from a transparent file.",
+                  "args" : [{ "name" : "--fid",
+                               "spec" : {"required" : True,
+                                         "help" : "File identifier to of the file to read",
+                                         "action" : "append",
+                                         "pytype" : "str"},
+                             }
+                            ]},
+                 {"name" : "read_record",
+                  "help": "read binary data from a transparent file.",
+                  "args" : [{ "name" : "--fid",
+                               "spec" : {"required" : True,
+                                         "help" : "File identifier to of the file to read",
+                                         "action" : "append",
+                                         "pytype" : "str"},
+                             },
+                            { "name" : "--record",
+                               "spec" : {"required" : True,
+                                         "help" : "File record to read",
+                                         "default" : 1,
+                                         "pytype" : "int"},
+                              }
+                            ]}
+                 ]
+    suitable_for = [{"atr" : "3b9f96803f87828031e073fe211f574543753130136502"}]
+
+    def cmd_reset(self, hdlr: RcpmCmdSrvConnHdlr) -> int:
+        hdlr.print("resetting UICC/eUICC")
+        hdlr.scc.reset_card()
+        hdlr.print("ATR is: %s" % hdlr.scc.get_atr())
+        return 0
+
+    def cmd_read_binary(self, hdlr: RcpmCmdSrvConnHdlr) -> int:
+        fid = hdlr.cmd_args.fid
+        hdlr.print("reading transparent file: %s" % fid)
+        (res, _) = hdlr.scc.read_binary(fid)
+        hdlr.print("file content is: %s" % res)
+        return 0
+
+    def cmd_read_record(self, hdlr: RcpmCmdSrvConnHdlr) -> int:
+        fid = hdlr.cmd_args.fid
+        record = hdlr.cmd_args.record
+        hdlr.print("reading linear-fixed file: %s" % fid)
+        (res, _) = hdlr.scc.read_record(fid, record)
+        hdlr.print("file content is: %s" % res)
+        return 0
+
+if __name__ == '__main__':
+    option_parser = rcpm_setup_argparse("Example Module")
+    opts = option_parser.parse_args()
+    rcpm_run_module(opts, ExmpleModule)

contrib/rcp/usage_example/readme.txt

@@ -0,0 +1,14 @@
+How to try:
+
+Go to the directory that contains the usage example:
+cd pysim/contrib/rcp/usage_example
+
+Start the RCP Server:
+./start_rcp_server.sh
+
+Start the RCP Module:
+ ./start_rcp_module.sh
+
+Run the exmple scripts:
+./run_rcp_client.sh
+(it is also possible to call the run_rcp_client_*.sh scripts individually)

contrib/rcp/usage_example/run_rcp_client.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+echo "basic help"
+echo "===================================================================================="
+./run_rcp_client_help.sh
+echo "===================================================================================="
+echo ""
+echo ""
+
+echo "help for which commands are available"
+echo "===================================================================================="
+./run_rcp_client_help_cmd.sh
+echo "===================================================================================="
+echo ""
+echo ""
+
+echo "help for specific commands"
+echo "===================================================================================="
+./run_rcp_client_help_cmd_specific.sh
+echo "===================================================================================="
+echo ""
+echo ""
+
+echo "run specific RCP commands"
+echo "===================================================================================="
+./run_rcp_client_cmd.sh
+echo "===================================================================================="
+echo ""
+echo ""

contrib/rcp/usage_example/run_rcp_client_cmd.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+
+PYTHONPATH=$PYSIM_DIR ../rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI\
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_reset
+
+PYTHONPATH=$PYSIM_DIR ../rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_read_binary --fid 3f00 --fid 2fe2
+
+PYTHONPATH=$PYSIM_DIR ../rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_read_record --fid 3f00 --fid 2f00 --record 1

contrib/rcp/usage_example/run_rcp_client_help.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+PYTHONPATH=$PYSIM_DIR ../rcp_client.py $VERBOSE \
+		      -h

contrib/rcp/usage_example/run_rcp_client_help_cmd.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+PYTHONPATH=$PYSIM_DIR ../rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      -h

contrib/rcp/usage_example/run_rcp_client_help_cmd_specific.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+
+PYTHONPATH=$PYSIM_DIR ../rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_reset --help
+
+PYTHONPATH=$PYSIM_DIR ../rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_read_binary --help
+
+PYTHONPATH=$PYSIM_DIR ../rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_read_record --help

contrib/rcp/usage_example/start_rcp_module.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+PYTHONPATH=$PYSIM_DIR:$RCP_DIR ./rcp_module.py $VERBOSE \
+			       --uri $RCPM_SERVER_URI \
+			       --rcps-ca-cert $CA_CERT \
+			       --rcpm-cmd-server-addr $RCPM_CMD_SERVER_ADDR \
+			       --rcpm-cmd-server-port $RCPM_CMD_SERVER_PORT \
+			       --rcpm-cmd-server-cert $RCPM_CMD_SERVER_CERT
+

contrib/rcp/usage_example/start_rcp_server.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+PYTHONPATH=$PYSIM_DIR ../rcp_server.py $VERBOSE \
+		      --rcpc-server-addr $RCPC_SERVER_ADDR \
+		      --rcpc-server-port $RCPC_SERVER_PORT \
+		      --rcpc-server-cert $RCPC_SERVER_CERT \
+		      --rcpm-server-addr $RCPM_SERVER_ADDR \
+		      --rcpm-server-port $RCPM_SERVER_PORT \
+		      --rcpm-server-cert $RCPM_SERVER_CERT \
+		      --rcpm-module-ca-cert $CA_CERT
+

contrib/saip-tool.py

@@ -0,0 +1,489 @@
+#!/usr/bin/env python3
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import os
+import sys
+import argparse
+import logging
+from pathlib import Path as PlPath
+from typing import List
+from osmocom.utils import h2b, b2h, swap_nibbles
+from osmocom.construct import GreedyBytes, StripHeaderAdapter
+
+from pySim.esim.saip import *
+from pySim.esim.saip.validation import CheckBasicStructure
+from pySim.pprint import HexBytesPrettyPrinter
+
+pp = HexBytesPrettyPrinter(indent=4,width=500)
+
+parser = argparse.ArgumentParser(description="""
+Utility program to work with eSIM SAIP (SimAlliance Interoperable Profile) files.""")
+parser.add_argument('INPUT_UPP', help='Unprotected Profile Package Input file')
+parser.add_argument("--loglevel", dest="loglevel", choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'],
+                    default='INFO', help="Set the logging level")
+parser.add_argument('--debug', action='store_true', help='Enable DEBUG logging')
+subparsers = parser.add_subparsers(dest='command', help="The command to perform", required=True)
+
+parser_split = subparsers.add_parser('split', help='Split PE-Sequence into individual PEs')
+parser_split.add_argument('--output-prefix', default='.', help='Prefix path/filename for output files')
+
+parser_dump = subparsers.add_parser('dump', help='Dump information on PE-Sequence')
+parser_dump.add_argument('mode', choices=['all_pe', 'all_pe_by_type', 'all_pe_by_naa'])
+parser_dump.add_argument('--dump-decoded', action='store_true', help='Dump decoded PEs')
+
+parser_check = subparsers.add_parser('check', help='Run constraint checkers on PE-Sequence')
+
+parser_rpe = subparsers.add_parser('extract-pe', help='Extract specified PE to (DER encoded) file')
+parser_rpe.add_argument('--pe-file', required=True, help='PE file name')
+parser_rpe.add_argument('--identification', type=int, help='Extract PE matching specified identification')
+
+parser_rpe = subparsers.add_parser('remove-pe', help='Remove specified PEs from PE-Sequence')
+parser_rpe.add_argument('--output-file', required=True, help='Output file name')
+parser_rpe.add_argument('--identification', default=[], type=int, action='append', help='Remove PEs matching specified identification')
+parser_rpe.add_argument('--type', default=[], action='append', help='Remove PEs matching specified type')
+
+parser_rn = subparsers.add_parser('remove-naa', help='Remove specified NAAs from PE-Sequence')
+parser_rn.add_argument('--output-file', required=True, help='Output file name')
+parser_rn.add_argument('--naa-type', required=True, choices=NAAs.keys(), help='Network Access Application type to remove')
+# TODO: add an --naa-index or the like, so only one given instance can be removed
+
+parser_info = subparsers.add_parser('info', help='Display information about the profile')
+parser_info.add_argument('--apps', action='store_true', help='List applications and their related instances')
+
+parser_eapp = subparsers.add_parser('extract-apps', help='Extract applications as loadblock file')
+parser_eapp.add_argument('--output-dir', default='.', help='Output directory (where to store files)')
+parser_eapp.add_argument('--format', default='cap', choices=['ijc', 'cap'], help='Data format of output files')
+
+parser_aapp = subparsers.add_parser('add-app', help='Add application to PE-Sequence')
+parser_aapp.add_argument('--output-file', required=True, help='Output file name')
+parser_aapp.add_argument('--applet-file', required=True, help='Applet file name')
+parser_aapp.add_argument('--aid', required=True, help='Load package AID')
+parser_aapp.add_argument('--sd-aid', default=None, help='Security Domain AID')
+parser_aapp.add_argument('--non-volatile-code-limit', default=None, type=int, help='Non volatile code limit (C6)')
+parser_aapp.add_argument('--volatile-data-limit', default=None, type=int, help='Volatile data limit (C7)')
+parser_aapp.add_argument('--non-volatile-data-limit', default=None, type=int, help='Non volatile data limit (C8)')
+parser_aapp.add_argument('--hash-value', default=None, help='Hash value')
+
+parser_rapp = subparsers.add_parser('remove-app', help='Remove application from PE-Sequence')
+parser_rapp.add_argument('--output-file', required=True, help='Output file name')
+parser_rapp.add_argument('--aid', required=True, help='Load package AID')
+
+parser_aappi = subparsers.add_parser('add-app-inst', help='Add application instance to Application PE')
+parser_aappi.add_argument('--output-file', required=True, help='Output file name')
+parser_aappi.add_argument('--aid', required=True, help='Load package AID')
+parser_aappi.add_argument('--class-aid', required=True, help='Class AID')
+parser_aappi.add_argument('--inst-aid', required=True, help='Instance AID (must match Load package AID)')
+parser_aappi.add_argument('--app-privileges', default='000000', help='Application privileges')
+parser_aappi.add_argument('--volatile-memory-quota', default=None, type=int, help='Volatile memory quota (C7)')
+parser_aappi.add_argument('--non-volatile-memory-quota', default=None, type=int, help='Non volatile memory quota (C8)')
+parser_aappi.add_argument('--app-spec-pars', default='00', help='Application specific parameters (C9)')
+parser_aappi.add_argument('--uicc-toolkit-app-spec-pars', help='UICC toolkit application specific parameters field')
+parser_aappi.add_argument('--uicc-access-app-spec-pars', help='UICC Access application specific parameters field')
+parser_aappi.add_argument('--uicc-adm-access-app-spec-pars', help='UICC Administrative access application specific parameters field')
+parser_aappi.add_argument('--process-data', default=[], action='append', help='Process personalization APDUs')
+
+parser_rappi = subparsers.add_parser('remove-app-inst', help='Remove application instance from Application PE')
+parser_rappi.add_argument('--output-file', required=True, help='Output file name')
+parser_rappi.add_argument('--aid', required=True, help='Load package AID')
+parser_rappi.add_argument('--inst-aid', required=True, help='Instance AID')
+
+esrv_flag_choices = [t.name for t in asn1.types['ServicesList'].type.root_members]
+parser_esrv = subparsers.add_parser('edit-mand-srv-list', help='Add/Remove service flag from/to mandatory services list')
+parser_esrv.add_argument('--output-file', required=True, help='Output file name')
+parser_esrv.add_argument('--add-flag', default=[], choices=esrv_flag_choices, action='append', help='Add flag to mandatory services list')
+parser_esrv.add_argument('--remove-flag', default=[], choices=esrv_flag_choices, action='append', help='Remove flag from mandatory services list')
+
+parser_tree = subparsers.add_parser('tree', help='Display the filesystem tree')
+
+def write_pes(pes: ProfileElementSequence, output_file:str):
+    """write the PE sequence to a file"""
+    print("Writing %u PEs to file '%s'..." % (len(pes.pe_list), output_file))
+    with open(output_file, 'wb') as f:
+        f.write(pes.to_der())
+
+def do_split(pes: ProfileElementSequence, opts):
+    i = 0
+    for pe in pes.pe_list:
+        basename = PlPath(opts.INPUT_UPP).stem
+        if not pe.identification:
+            fname = '%s-%02u-%s.der' % (basename, i, pe.type)
+        else:
+            fname = '%s-%02u-%05u-%s.der' % (basename, i, pe.identification, pe.type)
+        print("writing single PE to file '%s'" % fname)
+        with open(os.path.join(opts.output_prefix, fname), 'wb') as outf:
+            outf.write(pe.to_der())
+        i += 1
+
+def do_dump(pes: ProfileElementSequence, opts):
+    def print_all_pe(pes: ProfileElementSequence, dump_decoded:bool = False):
+        # iterate over each pe in the pes (using its __iter__ method)
+        for pe in pes:
+            print("="*70 + " " + pe.type)
+            if dump_decoded:
+                pp.pprint(pe.decoded)
+
+    def print_all_pe_by_type(pes: ProfileElementSequence, dump_decoded:bool = False):
+        # sort by PE type and show all PE within that type
+        for pe_type in pes.pe_by_type.keys():
+            print("="*70 + " " + pe_type)
+            for pe in pes.pe_by_type[pe_type]:
+                pp.pprint(pe)
+                if dump_decoded:
+                    pp.pprint(pe.decoded)
+
+    def print_all_pe_by_naa(pes: ProfileElementSequence, dump_decoded:bool = False):
+        for naa in pes.pes_by_naa:
+            i = 0
+            for naa_instance in pes.pes_by_naa[naa]:
+                print("="*70 + " " + naa + str(i))
+                i += 1
+                for pe in naa_instance:
+                    pp.pprint(pe.type)
+                    if dump_decoded:
+                        for d in pe.decoded:
+                            print("    %s" % d)
+
+    if opts.mode == 'all_pe':
+        print_all_pe(pes, opts.dump_decoded)
+    elif opts.mode == 'all_pe_by_type':
+        print_all_pe_by_type(pes, opts.dump_decoded)
+    elif opts.mode == 'all_pe_by_naa':
+        print_all_pe_by_naa(pes, opts.dump_decoded)
+
+def do_check(pes: ProfileElementSequence, opts):
+    print("Checking PE-Sequence structure...")
+    checker = CheckBasicStructure()
+    checker.check(pes)
+    print("All good!")
+
+def do_extract_pe(pes: ProfileElementSequence, opts):
+    new_pe_list = []
+    for pe in pes.pe_list:
+        if pe.identification == opts.identification:
+            print("Extracting PE %s (id=%u) to file %s..." % (pe, pe.identification, opts.pe_file))
+            with open(opts.pe_file, 'wb') as f:
+                f.write(pe.to_der())
+
+def do_remove_pe(pes: ProfileElementSequence, opts):
+    new_pe_list = []
+    for pe in pes.pe_list:
+        identification = pe.identification
+        if identification:
+            if identification in opts.identification:
+                print("Removing PE %s (id=%u) from Sequence..." % (pe, identification))
+                continue
+        if pe.type in opts.type:
+            print("Removing PE %s (type=%s) from Sequence..." % (pe, pe.type))
+            continue
+        new_pe_list.append(pe)
+
+    pes.pe_list = new_pe_list
+    pes._process_pelist()
+    write_pes(pes, opts.output_file)
+
+def do_remove_naa(pes: ProfileElementSequence, opts):
+    if not opts.naa_type in NAAs:
+        raise ValueError('unsupported NAA type %s' % opts.naa_type)
+    naa = NAAs[opts.naa_type]
+    print("Removing NAAs of type '%s' from Sequence..." % opts.naa_type)
+    pes.remove_naas_of_type(naa)
+    write_pes(pes, opts.output_file)
+
+def info_apps(pes:ProfileElementSequence):
+    def show_member(dictionary:Optional[dict], member:str, indent:str="\t", mandatory:bool = False, limit:bool = False):
+        if dictionary is None:
+            return
+        value = dictionary.get(member, None)
+        if value is None and mandatory == True:
+            print("%s%s: (missing!)" % (indent, member))
+            return
+        elif value is None:
+            return
+
+        if limit and len(value) > 40:
+            print("%s%s: '%s...%s' (%u bytes)" % (indent, member, b2h(value[:20]), b2h(value[-20:]), len(value)))
+        else:
+            print("%s%s: '%s' (%u bytes)" % (indent, member, b2h(value), len(value)))
+
+    apps = pes.pe_by_type.get('application', [])
+    if len(apps) == 0:
+        print("No Application PE present!")
+        return;
+
+    for app_pe in enumerate(apps):
+        print("Application #%u:" % app_pe[0])
+        print("\tloadBlock:")
+        load_block = app_pe[1].decoded['loadBlock']
+        show_member(load_block, 'loadPackageAID', "\t\t", True)
+        show_member(load_block, 'securityDomainAID', "\t\t")
+        show_member(load_block, 'nonVolatileCodeLimitC6', "\t\t")
+        show_member(load_block, 'volatileDataLimitC7', "\t\t")
+        show_member(load_block, 'nonVolatileDataLimitC8', "\t\t")
+        show_member(load_block, 'hashValue', "\t\t")
+        show_member(load_block, 'loadBlockObject', "\t\t", True, True)
+        for inst in enumerate(app_pe[1].decoded.get('instanceList', [])):
+            print("\tinstanceList[%u]:" % inst[0])
+            show_member(inst[1], 'applicationLoadPackageAID', "\t\t", True)
+            if inst[1].get('applicationLoadPackageAID', None) != load_block.get('loadPackageAID', None):
+                print("\t\t(applicationLoadPackageAID should be the same as loadPackageAID!)")
+            show_member(inst[1], 'classAID', "\t\t", True)
+            show_member(inst[1], 'instanceAID', "\t\t", True)
+            show_member(inst[1], 'extraditeSecurityDomainAID', "\t\t")
+            show_member(inst[1], 'applicationPrivileges', "\t\t", True)
+            show_member(inst[1], 'lifeCycleState', "\t\t", True)
+            show_member(inst[1], 'applicationSpecificParametersC9', "\t\t", True)
+            sys_specific_pars = inst[1].get('systemSpecificParameters', None)
+            if sys_specific_pars:
+                print("\t\tsystemSpecificParameters:")
+                show_member(sys_specific_pars, 'volatileMemoryQuotaC7', "\t\t\t")
+                show_member(sys_specific_pars, 'nonVolatileMemoryQuotaC8', "\t\t\t")
+                show_member(sys_specific_pars, 'globalServiceParameters', "\t\t\t")
+                show_member(sys_specific_pars, 'implicitSelectionParameter', "\t\t\t")
+                show_member(sys_specific_pars, 'volatileReservedMemory', "\t\t\t")
+                show_member(sys_specific_pars, 'nonVolatileReservedMemory', "\t\t\t")
+                show_member(sys_specific_pars, 'ts102226SIMFileAccessToolkitParameter', "\t\t\t")
+                additional_cl_pars = inst.get('ts102226AdditionalContactlessParameters', None)
+                if additional_cl_pars:
+                    print("\t\t\tts102226AdditionalContactlessParameters:")
+                    show_member(additional_cl_pars, 'protocolParameterData', "\t\t\t\t")
+                show_member(sys_specific_pars, 'userInteractionContactlessParameters', "\t\t\t")
+                show_member(sys_specific_pars, 'cumulativeGrantedVolatileMemory', "\t\t\t")
+                show_member(sys_specific_pars, 'cumulativeGrantedNonVolatileMemory', "\t\t\t")
+            app_pars = inst[1].get('applicationParameters', None)
+            if app_pars:
+                print("\t\tapplicationParameters:")
+                show_member(app_pars, 'uiccToolkitApplicationSpecificParametersField', "\t\t\t")
+                show_member(app_pars, 'uiccAccessApplicationSpecificParametersField', "\t\t\t")
+                show_member(app_pars, 'uiccAdministrativeAccessApplicationSpecificParametersField', "\t\t\t")
+            ctrl_ref_tp = inst[1].get('controlReferenceTemplate', None)
+            if ctrl_ref_tp:
+                print("\t\tcontrolReferenceTemplate:")
+                show_member(ctrl_ref_tp, 'applicationProviderIdentifier', "\t\t\t", True)
+            process_data = inst[1].get('processData', None)
+            if process_data:
+                print("\t\tprocessData:")
+                for proc in process_data:
+                    print("\t\t\t" + b2h(proc))
+
+def do_info(pes: ProfileElementSequence, opts):
+    def get_naa_count(pes: ProfileElementSequence) -> dict:
+        """return a dict with naa-type (usim, isim) as key and the count of NAA instances as value."""
+        ret = {}
+        for naa_type in pes.pes_by_naa:
+            ret[naa_type] = len(pes.pes_by_naa[naa_type])
+        return ret
+
+    if opts.apps:
+        info_apps(pes)
+        return;
+
+    pe_hdr_dec = pes.pe_by_type['header'][0].decoded
+    print()
+    print("SAIP Profile Version: %u.%u" % (pe_hdr_dec['major-version'], pe_hdr_dec['minor-version']))
+    print("Profile Type: '%s'" % pe_hdr_dec['profileType'])
+    print("ICCID: %s" % b2h(pe_hdr_dec['iccid']))
+    print("Mandatory Services: %s" % ', '.join(pe_hdr_dec['eUICC-Mandatory-services'].keys()))
+    print()
+    naa_strs = ["%s[%u]" % (k, v) for k, v in get_naa_count(pes).items()]
+    print("NAAs: %s" % ', '.join(naa_strs))
+    for naa_type in pes.pes_by_naa:
+        for naa_inst in pes.pes_by_naa[naa_type]:
+            first_pe = naa_inst[0]
+            adf_name = ''
+            if hasattr(first_pe, 'adf_name'):
+                adf_name = '(' + first_pe.adf_name + ')'
+            print("NAA %s %s" % (first_pe.type, adf_name))
+            if hasattr(first_pe, 'imsi'):
+                print("\tIMSI: %s" % first_pe.imsi)
+
+    # applications
+    print()
+    apps = pes.pe_by_type.get('application', [])
+    print("Number of applications: %u" % len(apps))
+    for app_pe in apps:
+        print("App Load Package AID: %s" % b2h(app_pe.decoded['loadBlock']['loadPackageAID']))
+        print("\tMandated: %s" % ('mandated' in app_pe.decoded['app-Header']))
+        print("\tLoad Block Size: %s" % len(app_pe.decoded['loadBlock']['loadBlockObject']))
+        for inst in app_pe.decoded.get('instanceList', []):
+            print("\tInstance AID: %s" % b2h(inst['instanceAID']))
+
+    # security domains
+    print()
+    sds = pes.pe_by_type.get('securityDomain', [])
+    print("Number of security domains: %u" % len(sds))
+    for sd in sds:
+        print("Security domain Instance AID: %s" % b2h(sd.decoded['instance']['instanceAID']))
+        # FIXME: 'applicationSpecificParametersC9' parsing to figure out enabled SCP
+        for key in sd.keys:
+            print("\t%s" % repr(key))
+
+    # RFM
+    print()
+    rfms = pes.pe_by_type.get('rfm', [])
+    print("Number of RFM instances: %u" % len(rfms))
+    for rfm in rfms:
+        inst_aid = rfm.decoded['instanceAID']
+        print("RFM instanceAID: %s" % b2h(inst_aid))
+        print("\tMSL: 0x%02x" % rfm.decoded['minimumSecurityLevel'][0])
+        adf = rfm.decoded.get('adfRFMAccess', None)
+        if adf:
+            print("\tADF AID: %s" % b2h(adf['adfAID']))
+        tar_list = rfm.decoded.get('tarList', [inst_aid[-3:]])
+        for tar in tar_list:
+            print("\tTAR: %s" % b2h(tar))
+
+def do_extract_apps(pes:ProfileElementSequence, opts):
+    apps = pes.pe_by_type.get('application', [])
+    for app_pe in apps:
+        package_aid = b2h(app_pe.decoded['loadBlock']['loadPackageAID'])
+        fname = os.path.join(opts.output_dir, '%s-%s.%s' % (pes.iccid, package_aid, opts.format))
+        print("Writing Load Package AID: %s to file %s" % (package_aid, fname))
+        app_pe.to_file(fname)
+
+def do_add_app(pes:ProfileElementSequence, opts):
+    print("Applying applet file: '%s'..." % opts.applet_file)
+    app_pe = ProfileElementApplication.from_file(opts.applet_file,
+                                                 opts.aid,
+                                                 opts.sd_aid,
+                                                 opts.non_volatile_code_limit,
+                                                 opts.volatile_data_limit,
+                                                 opts.non_volatile_data_limit,
+                                                 opts.hash_value)
+
+    security_domain = pes.pe_by_type.get('securityDomain', [])
+    if len(security_domain) == 0:
+        print("profile package does not contain a securityDomain, please add a securityDomain PE first!")
+    elif len(security_domain) > 1:
+        print("adding an application PE to profiles with multiple securityDomain is not supported yet!")
+    else:
+        pes.insert_after_pe(security_domain[0], app_pe)
+        print("application PE inserted into PE Sequence after securityDomain PE AID: %s" %
+              b2h(security_domain[0].decoded['instance']['instanceAID']))
+        write_pes(pes, opts.output_file)
+
+def do_remove_app(pes:ProfileElementSequence, opts):
+    apps = pes.pe_by_type.get('application', [])
+    for app_pe in apps:
+        package_aid = b2h(app_pe.decoded['loadBlock']['loadPackageAID'])
+        if opts.aid == package_aid:
+            identification = app_pe.identification
+            opts_remove_pe = argparse.Namespace()
+            opts_remove_pe.identification = [app_pe.identification]
+            opts_remove_pe.type = []
+            opts_remove_pe.output_file = opts.output_file
+            print("Found Load Package AID: %s, removing related PE (id=%u) from Sequence..." %
+                  (package_aid, identification))
+            do_remove_pe(pes, opts_remove_pe)
+            return
+    print("Load Package AID: %s not found in PE Sequence" % opts.aid)
+
+def do_add_app_inst(pes:ProfileElementSequence, opts):
+    apps = pes.pe_by_type.get('application', [])
+    for app_pe in apps:
+        package_aid = b2h(app_pe.decoded['loadBlock']['loadPackageAID'])
+        if opts.aid == package_aid:
+            print("Found Load Package AID: %s, adding new instance AID: %s to Application PE..." %
+                  (opts.aid, opts.inst_aid))
+            app_pe.add_instance(opts.aid,
+                                opts.class_aid,
+                                opts.inst_aid,
+                                opts.app_privileges,
+                                opts.app_spec_pars,
+                                opts.uicc_toolkit_app_spec_pars,
+                                opts.uicc_access_app_spec_pars,
+                                opts.uicc_adm_access_app_spec_pars,
+                                opts.volatile_memory_quota,
+                                opts.non_volatile_memory_quota,
+                                opts.process_data)
+            write_pes(pes, opts.output_file)
+            return
+    print("Load Package AID: %s not found in PE Sequence" % opts.aid)
+
+def do_remove_app_inst(pes:ProfileElementSequence, opts):
+    apps = pes.pe_by_type.get('application', [])
+    for app_pe in apps:
+        if opts.aid == b2h(app_pe.decoded['loadBlock']['loadPackageAID']):
+            print("Found Load Package AID: %s, removing instance AID: %s from Application PE..." %
+                  (opts.aid, opts.inst_aid))
+            app_pe.remove_instance(opts.inst_aid)
+            write_pes(pes, opts.output_file)
+            return
+    print("Load Package AID: %s not found in PE Sequence" % opts.aid)
+
+def do_edit_mand_srv_list(pes: ProfileElementSequence, opts):
+    header = pes.pe_by_type.get('header', [])[0]
+
+    for s in opts.add_flag:
+        print("Adding service '%s' to mandatory services list..." % s)
+        header.mandatory_service_add(s)
+    for s in opts.remove_flag:
+        if s in header.decoded['eUICC-Mandatory-services'].keys():
+            print("Removing service '%s' from mandatory services list..." % s)
+            header.mandatory_service_remove(s)
+        else:
+            print("Service '%s' not present in mandatory services list, cannot remove!" % s)
+
+    print("The following services are now set mandatory:")
+    for s in header.decoded['eUICC-Mandatory-services'].keys():
+        print("\t%s" % s)
+
+    write_pes(pes, opts.output_file)
+
+def do_tree(pes:ProfileElementSequence, opts):
+    pes.mf.print_tree()
+
+if __name__ == '__main__':
+    opts = parser.parse_args()
+
+    if opts.debug:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.getLevelName(opts.loglevel))
+
+    with open(opts.INPUT_UPP, 'rb') as f:
+        pes = ProfileElementSequence.from_der(f.read())
+
+    print("Read %u PEs from file '%s'" % (len(pes.pe_list), opts.INPUT_UPP))
+
+    if opts.command == 'split':
+        do_split(pes, opts)
+    elif opts.command == 'dump':
+        do_dump(pes, opts)
+    elif opts.command == 'check':
+        do_check(pes, opts)
+    elif opts.command == 'extract-pe':
+        do_extract_pe(pes, opts)
+    elif opts.command == 'remove-pe':
+        do_remove_pe(pes, opts)
+    elif opts.command == 'remove-naa':
+        do_remove_naa(pes, opts)
+    elif opts.command == 'info':
+        do_info(pes, opts)
+    elif opts.command == 'extract-apps':
+        do_extract_apps(pes, opts)
+    elif opts.command == 'add-app':
+        do_add_app(pes, opts)
+    elif opts.command == 'remove-app':
+        do_remove_app(pes, opts)
+    elif opts.command == 'add-app-inst':
+        do_add_app_inst(pes, opts)
+    elif opts.command == 'remove-app-inst':
+        do_remove_app_inst(pes, opts)
+    elif opts.command == 'edit-mand-srv-list':
+        do_edit_mand_srv_list(pes, opts)
+    elif opts.command == 'tree':
+        do_tree(pes, opts)

contrib/saip-tool_example_add-app.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# This is an example script to illustrate how to add JAVA card applets to an existing eUICC profile package.
+
+PYSIMPATH=../
+INPATH=../smdpp-data/upp/TS48V1-A-UNIQUE.der
+OUTPATH=../smdpp-data/upp/TS48V1-A-UNIQUE-hello.der
+APPPATH=./HelloSTK_09122024.cap
+
+# Download example applet (see also https://gitea.osmocom.org/sim-card/hello-stk):
+if ! [ -f $APPPATH ]; then
+    wget https://osmocom.org/attachments/download/8931/HelloSTK_09122024.cap
+fi
+
+# Step #1: Create the application PE and load the ijc contents from the .cap file:
+PYTHONPATH=$PYSIMPATH python3 $PYSIMPATH/contrib/saip-tool.py $INPATH add-app \
+		      --output-file $OUTPATH --applet-file $APPPATH --aid 'D07002CA44'
+
+# Step #2: Create the application instance inside the application PE created in step #1:
+PYTHONPATH=$PYSIMPATH python3 $PYSIMPATH/contrib/saip-tool.py $OUTPATH add-app-inst --output-file $OUTPATH \
+		      --aid 'D07002CA44' \
+		      --class-aid 'D07002CA44900101' \
+		      --inst-aid 'D07002CA44900101' \
+		      --app-privileges '00' \
+		      --app-spec-pars '00' \
+		      --uicc-toolkit-app-spec-pars '01001505000000000000000000000000'
+
+# Display the contents of the resulting application PE:
+PYTHONPATH=$PYSIMPATH python3 $PYSIMPATH/contrib/saip-tool.py $OUTPATH info --apps
+
+# For an explanation of --uicc-toolkit-app-spec-pars, see:
+# ETSI TS 102 226, section 8.2.1.3.2.2.1

contrib/saip-tool_example_extract-apps.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# This is an example script to illustrate how to extract JAVA card applets from an existing eUICC profile package.
+
+PYSIMPATH=../
+INPATH=../smdpp-data/upp/TS48V1-A-UNIQUE-hello.der
+OUTPATH=./
+
+PYTHONPATH=$PYSIMPATH python3 $PYSIMPATH/contrib/saip-tool.py $INPATH extract-apps --output-dir ./ --format ijc

contrib/saip-tool_example_remove-app-inst.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# This is an example script to illustrate how to remove a JAVA card applet instance from an application PE inside an
+# existing eUICC profile package.
+
+PYSIMPATH=../
+INPATH=../smdpp-data/upp/TS48V1-A-UNIQUE-hello.der
+OUTPATH=../smdpp-data/upp/TS48V1-A-UNIQUE-hello-no-inst.der
+
+# Remove application PE entirely
+PYTHONPATH=$PYSIMPATH python3 $PYSIMPATH/contrib/saip-tool.py $INPATH remove-app-inst \
+		      --output-file $OUTPATH --aid 'd07002ca44' --inst-aid 'd07002ca44900101'
+
+# Display the contents of the resulting application PE:
+PYTHONPATH=$PYSIMPATH python3 $PYSIMPATH/contrib/saip-tool.py $OUTPATH info --apps

contrib/saip-tool_example_remove-app.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# This is an example script to illustrate how to remove a JAVA card applet from an existing eUICC profile package.
+
+PYSIMPATH=../
+INPATH=../smdpp-data/upp/TS48V1-A-UNIQUE-hello.der
+OUTPATH=../smdpp-data/upp/TS48V1-A-UNIQUE-no-hello.der
+
+# Remove application PE entirely
+PYTHONPATH=$PYSIMPATH python3 $PYSIMPATH/contrib/saip-tool.py $INPATH remove-app \
+		      --output-file $OUTPATH --aid 'D07002CA44'
+
+# Display the contents of the resulting application PE:
+PYTHONPATH=$PYSIMPATH python3 $PYSIMPATH/contrib/saip-tool.py $OUTPATH info --apps

contrib/sim-rest-client.py

@@ -162,6 +162,7 @@ def main(argv):
     parser.add_argument("-v", "--verbose", help="increase output verbosity", action='count', default=0)
     parser.add_argument("-n", "--slot-nr", help="SIM slot number", type=int, default=0)
     subp = parser.add_subparsers()
+    subp.required = True
 
     auth_p = subp.add_parser('auth', help='UMTS AKA Authentication')
     auth_p.add_argument("-c", "--count", help="Auth count", type=int, default=10)

contrib/smpp-ota-tool.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+
+# (C) 2026 by sysmocom - s.f.m.c. GmbH
+# All Rights Reserved
+#
+# Author: Harald Welte, Philipp Maier
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import argparse
+import logging
+import smpplib.gsm
+import smpplib.client
+import smpplib.consts
+import time
+from pySim.ota import OtaKeyset, OtaDialectSms, OtaAlgoCrypt, OtaAlgoAuth, CNTR_REQ, RC_CC_DS, POR_REQ
+from pySim.utils import b2h, h2b, is_hexstr
+from pathlib import Path
+
+logger = logging.getLogger(Path(__file__).stem)
+
+option_parser = argparse.ArgumentParser(description='Tool to send OTA SMS RFM/RAM messages via SMPP',
+                                        formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+option_parser.add_argument("--host", help="Host/IP of the SMPP server", default="localhost")
+option_parser.add_argument("--port", help="TCP port of the SMPP server", default=2775, type=int)
+option_parser.add_argument("--system-id", help="System ID to use to bind to the SMPP server", default="test")
+option_parser.add_argument("--password", help="Password to use to bind to the SMPP server", default="test")
+option_parser.add_argument("--verbose", help="Enable verbose logging", action='store_true', default=False)
+algo_crypt_choices = []
+algo_crypt_classes = OtaAlgoCrypt.__subclasses__()
+for cls in algo_crypt_classes:
+    algo_crypt_choices.append(cls.enum_name)
+option_parser.add_argument("--algo-crypt", choices=algo_crypt_choices, default='triple_des_cbc2',
+                           help="OTA crypt algorithm")
+algo_auth_choices = []
+algo_auth_classes = OtaAlgoAuth.__subclasses__()
+for cls in algo_auth_classes:
+    algo_auth_choices.append(cls.enum_name)
+option_parser.add_argument("--algo-auth", choices=algo_auth_choices, default='triple_des_cbc2',
+                           help="OTA auth algorithm")
+option_parser.add_argument('--kic', required=True, type=is_hexstr, help='OTA key (KIC)')
+option_parser.add_argument('--kic-idx', default=1, type=int, help='OTA key index (KIC)')
+option_parser.add_argument('--kid', required=True, type=is_hexstr, help='OTA key (KID)')
+option_parser.add_argument('--kid-idx', default=1, type=int, help='OTA key index (KID)')
+option_parser.add_argument('--cntr', default=0, type=int, help='replay protection counter')
+option_parser.add_argument('--tar', required=True, type=is_hexstr, help='Toolkit Application Reference')
+option_parser.add_argument("--cntr-req", choices=CNTR_REQ.decmapping.values(), default='no_counter',
+                           help="Counter requirement")
+option_parser.add_argument('--no-ciphering', action='store_true', default=False, help='Disable ciphering')
+option_parser.add_argument("--rc-cc-ds", choices=RC_CC_DS.decmapping.values(), default='cc',
+                           help="message check (rc=redundency check, cc=crypt. checksum, ds=digital signature)")
+option_parser.add_argument('--por-in-submit', action='store_true', default=False,
+                           help='require PoR to be sent via SMS-SUBMIT')
+option_parser.add_argument('--por-no-ciphering', action='store_true', default=False, help='Disable ciphering (PoR)')
+option_parser.add_argument("--por-rc-cc-ds", choices=RC_CC_DS.decmapping.values(), default='cc',
+                           help="PoR check (rc=redundency check, cc=crypt. checksum, ds=digital signature)")
+option_parser.add_argument("--por-req", choices=POR_REQ.decmapping.values(), default='por_required',
+                           help="Proof of Receipt requirements")
+option_parser.add_argument('--src-addr', default='12', type=str, help='SMS source address (MSISDN)')
+option_parser.add_argument('--dest-addr', default='23', type=str, help='SMS destination address (MSISDN)')
+option_parser.add_argument('--timeout', default=10, type=int, help='Maximum response waiting time')
+option_parser.add_argument('-a', '--apdu', action='append', required=True, type=is_hexstr, help='C-APDU to send')
+
+class SmppHandler:
+    client = None
+
+    def __init__(self, host: str, port: int,
+                 system_id: str, password: str,
+                 ota_keyset: OtaKeyset, spi: dict, tar: bytes):
+        """
+        Initialize connection to SMPP server and set static OTA SMS-TPDU ciphering parameters
+        Args:
+                host : Hostname or IPv4/IPv6 address of the SMPP server
+                port : TCP Port of the SMPP server
+                system_id: SMPP System-ID used by ESME (client) to bind
+                password: SMPP Password used by ESME (client) to bind
+                ota_keyset: OTA keyset to be used for SMS-TPDU ciphering
+                spi: Security Parameter Indicator (SPI) to be used for SMS-TPDU ciphering
+                tar: Toolkit Application Reference (TAR) of the targeted card application
+        """
+
+        # Create and connect SMPP client
+        client = smpplib.client.Client(host, port, allow_unknown_opt_params=True)
+        client.set_message_sent_handler(self.message_sent_handler)
+        client.set_message_received_handler(self.message_received_handler)
+        client.connect()
+        client.bind_transceiver(system_id=system_id, password=password)
+        self.client = client
+
+        # Setup static OTA parameters
+        self.ota_dialect = OtaDialectSms()
+        self.ota_keyset = ota_keyset
+        self.tar = tar
+        self.spi = spi
+
+    def __del__(self):
+        if self.client:
+            self.client.unbind()
+            self.client.disconnect()
+
+    def message_received_handler(self, pdu):
+        if pdu.short_message:
+            logger.info("SMS-TPDU received: %s", b2h(pdu.short_message))
+            try:
+                dec = self.ota_dialect.decode_resp(self.ota_keyset, self.spi, pdu.short_message)
+            except ValueError:
+                # Retry to decoding with ciphering disabled (in case the card has problems to decode the SMS-TDPU
+                # we have sent, the response will contain an unencrypted error message)
+                spi = self.spi.copy()
+                spi['por_shall_be_ciphered'] = False
+                spi['por_rc_cc_ds'] = 'no_rc_cc_ds'
+                dec = self.ota_dialect.decode_resp(self.ota_keyset, spi, pdu.short_message)
+            logger.info("SMS-TPDU decoded: %s", dec)
+            self.response = dec
+        return None
+
+    def message_sent_handler(self, pdu):
+            logger.debug("SMS-TPDU sent: pdu_sequence=%s pdu_message_id=%s", pdu.sequence, pdu.message_id)
+
+    def transceive_sms_tpdu(self, tpdu: bytes, src_addr: str, dest_addr: str, timeout: int) -> tuple:
+        """
+        Transceive SMS-TPDU. This method sends the SMS-TPDU to the SMPP server, and waits for a response. The method
+        returns when the response is received.
+
+        Args:
+                tpdu : short message content (plaintext)
+                src_addr : short message source address
+                dest_addr : short message destination address
+                timeout : timeout after which this method should give up waiting for a response
+        Returns:
+                tuple containing the response (plaintext)
+        """
+
+        logger.info("SMS-TPDU sending: %s...", b2h(tpdu))
+
+        self.client.send_message(
+            # TODO: add parameters to switch source_addr_ton and dest_addr_ton between SMPP_TON_INTL and SMPP_NPI_ISDN
+            source_addr_ton=smpplib.consts.SMPP_TON_INTL,
+            source_addr=src_addr,
+            dest_addr_ton=smpplib.consts.SMPP_TON_INTL,
+            destination_addr=dest_addr,
+            short_message=tpdu,
+            # TODO: add parameters to set data_coding and esm_class
+            data_coding=smpplib.consts.SMPP_ENCODING_BINARY,
+            esm_class=smpplib.consts.SMPP_GSMFEAT_UDHI,
+            protocol_id=0x7f,
+            # TODO: add parameter to use registered delivery
+            # registered_delivery=True,
+        )
+
+        logger.info("SMS-TPDU sent, waiting for response...")
+        timestamp_sent=int(time.time())
+        self.response = None
+        while self.response is None:
+            self.client.poll()
+            if int(time.time()) - timestamp_sent > timeout:
+                raise ValueError("Timeout reached, no response SMS-TPDU received!")
+        return self.response
+
+    def transceive_apdu(self, apdu: bytes, src_addr: str, dest_addr: str, timeout: int) -> tuple[bytes, bytes]:
+        """
+        Transceive APDU. This method wraps the given APDU into an SMS-TPDU, sends it to the SMPP server and waits for
+        the response. When the response is received, the last response data and the last status word is extracted from
+        the response and returned to the caller.
+
+        Args:
+                apdu : one or more concatenated APDUs
+                src_addr : short message source address
+                dest_addr : short message destination address
+                timeout : timeout after which this method should give up waiting for a response
+        Returns:
+                tuple containing the last response data and the last status word as byte strings
+        """
+
+        logger.info("C-APDU sending: %s...", b2h(apdu))
+
+        # translate to Secured OTA RFM
+        secured = self.ota_dialect.encode_cmd(self.ota_keyset, self.tar, self.spi, apdu=apdu)
+        # add user data header
+        tpdu = b'\x02\x70\x00' + secured
+        # send via SMPP
+        response =  self.transceive_sms_tpdu(tpdu, src_addr, dest_addr, timeout)
+
+        # Extract last_response_data and last_status_word from the response
+        sw = None
+        resp = None
+        for container in response:
+            if container:
+                container_dict = dict(container)
+                resp = container_dict.get('last_response_data')
+                sw = container_dict.get('last_status_word')
+        if resp is None:
+            raise ValueError("Response does not contain any last_response_data, no R-APDU received!")
+        if sw is None:
+            raise ValueError("Response does not contain any last_status_word, no R-APDU received!")
+
+        logger.info("R-APDU received: %s %s", resp, sw)
+        return h2b(resp), h2b(sw)
+
+if __name__ == '__main__':
+    opts = option_parser.parse_args()
+
+    logging.basicConfig(level=logging.DEBUG if opts.verbose else logging.INFO,
+                        format='%(asctime)s %(levelname)s %(message)s',
+                        datefmt='%Y-%m-%d %H:%M:%S')
+
+    if opts.kic_idx != opts.kid_idx:
+        logger.warning("KIC index (%s) and KID index (%s) are different (security violation, card should reject message)",
+                       opts.kic_idx, opts.kid_idx)
+
+    ota_keyset = OtaKeyset(algo_crypt=opts.algo_crypt,
+                           kic_idx=opts.kic_idx,
+                           kic=h2b(opts.kic),
+                           algo_auth=opts.algo_auth,
+                           kid_idx=opts.kid_idx,
+                           kid=h2b(opts.kid),
+                           cntr=opts.cntr)
+    spi = {'counter' : opts.cntr_req,
+           'ciphering' : not opts.no_ciphering,
+           'rc_cc_ds': opts.rc_cc_ds,
+           'por_in_submit': opts.por_in_submit,
+           'por_shall_be_ciphered': not opts.por_no_ciphering,
+           'por_rc_cc_ds': opts.por_rc_cc_ds,
+           'por': opts.por_req}
+    apdu = h2b("".join(opts.apdu))
+
+    smpp_handler = SmppHandler(opts.host, opts.port, opts.system_id, opts.password, ota_keyset, spi, h2b(opts.tar))
+    resp, sw = smpp_handler.transceive_apdu(apdu, opts.src_addr, opts.dest_addr, opts.timeout)
+    print("%s %s" % (b2h(resp), b2h(sw)))

contrib/suci-keytool.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+
+# small utility program to deal with 5G SUCI key material, at least for the ECIES Protection Scheme
+# Profile A (curve25519) and B (secp256r1)
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+# SPDX-License-Identifier: GPL-2.0+
+
+import argparse
+
+from osmocom.utils import b2h
+from Cryptodome.PublicKey import ECC
+# if used with pycryptodome < v3.21.0 you will get the following error when using curve25519:
+# "Cryptodome.PublicKey.ECC.UnsupportedEccFeature: Unsupported ECC purpose (OID: 1.3.101.110)"
+
+def gen_key(opts):
+    # FIXME: avoid overwriting key files
+    mykey = ECC.generate(curve=opts.curve)
+    data = mykey.export_key(format='PEM')
+    with open(opts.key_file, "wt") as f:
+        f.write(data)
+
+def dump_pkey(opts):
+
+    #with open("curve25519-1.key", "r") as f:
+
+    with open(opts.key_file, "r") as f:
+        data = f.read()
+        mykey = ECC.import_key(data)
+
+        der = mykey.public_key().export_key(format='raw', compress=opts.compressed)
+        print(b2h(der))
+
+arg_parser = argparse.ArgumentParser(description="""Generate or export SUCI keys for 5G SA networks""")
+arg_parser.add_argument('--key-file', help='The key file to use', required=True)
+
+subparsers = arg_parser.add_subparsers(dest='command', help="The command to perform", required=True)
+
+parser_genkey = subparsers.add_parser('generate-key', help='Generate a new key pair')
+parser_genkey.add_argument('--curve', help='The ECC curve to use', choices=['secp256r1','curve25519'], required=True)
+
+parser_dump_pkey = subparsers.add_parser('dump-pub-key', help='Dump the public key')
+parser_dump_pkey.add_argument('--compressed', help='Use point compression', action='store_true')
+
+if __name__ == '__main__':
+
+    opts = arg_parser.parse_args()
+
+    if opts.command == 'generate-key':
+        gen_key(opts)
+    elif opts.command == 'dump-pub-key':
+        dump_pkey(opts)

contrib/unber.py

@@ -1,12 +1,13 @@
 #!/usr/bin/env python3
 
-# A more useful verion of the 'unber' tool provided with asn1c:
+# A more useful version of the 'unber' tool provided with asn1c:
 # Give a hierarchical decode of BER/DER-encoded ASN.1 TLVs
 
 import sys
 import argparse
 
-from pySim.utils import bertlv_parse_one, bertlv_encode_tag, b2h, h2b
+from osmocom.utils import b2h, h2b
+from osmocom.tlv import bertlv_parse_one, bertlv_encode_tag
 
 def process_one_level(content: bytes, indent: int):
     remainder = content
@@ -35,5 +36,8 @@ if __name__ == '__main__':
             content = f.read()
     elif opts.hex:
         content = h2b(opts.hex)
+    else:
+        # avoid pylint "(possibly-used-before-assignment)" below
+        sys.exit(2)
 
     process_one_level(content, 0)

docs/Makefile

@@ -4,7 +4,7 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
+SPHINXBUILD   ?= python3 -m sphinx.cmd.build
 SOURCEDIR     = .
 BUILDDIR      = _build
 

docs/cap-tutorial.rst

@@ -0,0 +1,103 @@
+
+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 process.
+(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 parameters. Those
+parameters are supplied in the form of a hexstring and should be provided by the applet manufacturer. 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 |
++---------+----------------------------------+
+
+[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.
+
+
+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.
+
+

docs/card-key-provider.rst

@@ -0,0 +1,342 @@
+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.
+
+pySim already includes two CardKeyProvider implementations. One to retrieve
+key material from a CSV file (`CardKeyProviderCsv`) and a second one that allows
+to retrieve the key material from a PostgreSQL database (`CardKeyProviderPgsql`).
+Both implementations equally implement a column encryption scheme that allows
+to protect sensitive columns using a *transport key*
+
+
+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.
+
+The `CardKeyProviderCsv` is suitable to manage small amounts of key material
+locally. However, if your card inventory is very large and the key material
+must be made available on multiple sites, the `CardKeyProviderPgsql` is the
+better option.
+
+
+The CardKeyProviderPgsql
+------------------------
+
+With the `CardKeyProviderPgsql` you can use a PostgreSQL database as storage
+medium. The implementation comes with a CSV importer tool that consumes the
+same CSV files you would normally use with the `CardKeyProviderCsv`, so you
+can just use your existing CSV files and import them into the database.
+
+
+Requirements
+^^^^^^^^^^^^
+
+The `CardKeyProviderPgsql` uses the `Psycopg` PostgreSQL database adapter
+(https://www.psycopg.org). `Psycopg` is not part of the default requirements
+of pySim-shell and must be installed separately. `Psycopg` is available as
+Python package under the name `psycopg2-binary`.
+
+
+Setting up the database
+^^^^^^^^^^^^^^^^^^^^^^^
+
+From the perspective of the database, the `CardKeyProviderPgsql` has only
+minimal requirements. You do not have to create any tables in advance. An empty
+database and at least one user that may create, alter and insert into tables is
+sufficient. However, for increased reliability and as a protection against
+incorrect operation, the `CardKeyProviderPgsql` supports a hierarchical model
+with three users (or roles):
+
+* **admin**:
+  This should be the owner of the database. It is intended to be used for
+  administrative tasks like adding new tables or adding new columns to existing
+  tables. This user should not be used to insert new data into tables or to access
+  data from within pySim-shell using the `CardKeyProviderPgsql`
+
+* **importer**:
+  This user is used when feeding new data into an existing table. It should only
+  be able to insert new rows into existing tables. It should not be used for
+  administrative tasks or to access data from within pySim-shell using the
+  `CardKeyProviderPgsql`
+
+* **reader**:
+  To access data from within pySim shell using the `CardKeyProviderPgsql` the
+  reader user is the correct one to use. This user should have no write access
+  to the database or any of the tables.
+
+
+Creating a config file
+^^^^^^^^^^^^^^^^^^^^^^
+
+The default location for the config file is `~/.osmocom/pysim/card_data_pgsql.cfg`
+The file uses `yaml` syntax and should look like the example below:
+
+::
+
+   host: "127.0.0.1"
+   db_name: "my_database"
+   table_names:
+   - "uicc_keys"
+   - "euicc_keys"
+   db_users:
+      admin:
+         name: "my_admin_user"
+         pass: "my_admin_password"
+      importer:
+         name: "my_importer_user"
+         pass: "my_importer_password"
+      reader:
+         name: "my_reader_user"
+         pass: "my_reader_password"
+
+This file is used by pySim-shell and by the importer tool. Both expect the file
+in the aforementioned location. In case you want to store the file in a
+different location you may use the `--pgsql` commandline option to provide a
+custom config file path.
+
+The hostname and the database name for the PostgreSQL database is set with the
+`host` and `db_name` fields. The field `db_users` sets the user names and
+passwords for each of the aforementioned users (or roles). In case only a single
+admin user is used, all three entries may be populated with the same user name
+and password (not recommended)
+
+The field `table_names` sets the tables that the `CardKeyProviderPgsql` shall
+use to query to locate card key data. You can set up as many tables as you
+want, `CardKeyProviderPgsql` will query them in order, one by one until a
+matching entry is found.
+
+NOTE: In case you do not want to disclose the admin and the importer credentials
+to pySim-shell you may remove those lines. pySim-shell will only require the
+`reader` entry under `db_users`.
+
+
+Using the Importer
+^^^^^^^^^^^^^^^^^^
+
+Before data can be imported, you must first create a database table. Tables
+are created with the provided importer tool, which can be found under
+`contrib/csv-to-pgsql.py`. This tool is used to create the database table and
+read the data from the provided CSV file into the database.
+
+As mentioned before, all CSV file formats that work with `CardKeyProviderCsv`
+may be used. To demonstrate how the import process works, let's assume you want
+to import a CSV file format that looks like the following example. Let's also
+assume that you didn't get the Global Platform keys from your card vendor for
+this batch of UICC cards, so your CSV file lacks the columns for those fields.
+
+::
+
+   "id","imsi","iccid","acc","pin1","puk1","pin2","puk2","ki","opc","adm1"
+   "card1","999700000000001","8900000000000000001","0001","1111","11111111","0101","01010101","11111111111111111111111111111111","11111111111111111111111111111111","11111111"
+   "card2","999700000000002","8900000000000000002","0002","2222","22222222","0202","02020202","22222222222222222222222222222222","22222222222222222222222222222222","22222222"
+   "card3","999700000000003","8900000000000000003","0003","3333","22222222","0303","03030303","33333333333333333333333333333333","33333333333333333333333333333333","33333333"
+
+Since this is your first import, the database still lacks the table. To
+instruct the importer to create a new table, you may use the `--create-table`
+option. You also have to pick an appropriate name for the table. Any name may
+be chosen as long as it contains the string `uicc_keys` or `euicc_keys`,
+depending on the type of data (`UICC` or `eUICC`) you intend to store in the
+table. The creation of the table is an administrative task and can only be done
+with the `admin` user. The `admin` user is selected using the `--admin` switch.
+
+::
+
+   $ PYTHONPATH=../ ./csv-to-pgsql.py --csv ./csv-to-pgsql_example_01.csv --table-name uicc_keys --create-table --admin
+   INFO: CSV file: ./csv-to-pgsql_example_01.csv
+   INFO: CSV file columns: ['ID', 'IMSI', 'ICCID', 'ACC', 'PIN1', 'PUK1', 'PIN2', 'PUK2', 'KI', 'OPC', 'ADM1']
+   INFO: Using config file: /home/user/.osmocom/pysim/card_data_pgsql.cfg
+   INFO: Database host: 127.0.0.1
+   INFO: Database name: my_database
+   INFO: Database user: my_admin_user
+   INFO: New database table created: uicc_keys
+   INFO: Database table: uicc_keys
+   INFO: Database table columns: ['ICCID', 'IMSI']
+   INFO: Adding missing columns: ['PIN2', 'PUK1', 'PUK2', 'ACC', 'ID', 'PIN1', 'ADM1', 'KI', 'OPC']
+   INFO: Changes to table uicc_keys committed!
+
+The importer has created a new table with the name `uicc_keys`. The table is
+now ready to be filled with data.
+
+::
+
+   $ PYTHONPATH=../ ./csv-to-pgsql.py --csv ./csv-to-pgsql_example_01.csv --table-name uicc_keys
+   INFO: CSV file: ./csv-to-pgsql_example_01.csv
+   INFO: CSV file columns: ['ID', 'IMSI', 'ICCID', 'ACC', 'PIN1', 'PUK1', 'PIN2', 'PUK2', 'KI', 'OPC', 'ADM1']
+   INFO: Using config file: /home/user/.osmocom/pysim/card_data_pgsql.cfg
+   INFO: Database host: 127.0.0.1
+   INFO: Database name: my_database
+   INFO: Database user: my_importer_user
+   INFO: Database table: uicc_keys
+   INFO: Database table columns: ['ICCID', 'IMSI', 'PIN2', 'PUK1', 'PUK2', 'ACC', 'ID', 'PIN1', 'ADM1', 'KI', 'OPC']
+   INFO: CSV file import done, 3 rows imported
+   INFO: Changes to table uicc_keys committed!
+
+A quick `SELECT * FROM uicc_keys;` at the PostgreSQL console should now display
+the contents of the CSV file you have fed into the importer.
+
+Let's now assume that with your next batch of UICC cards your vendor includes
+the Global Platform keys so your CSV format changes. It may now look like this:
+
+::
+
+   "id","imsi","iccid","acc","pin1","puk1","pin2","puk2","ki","opc","adm1","scp02_dek_1","scp02_enc_1","scp02_mac_1"
+   "card4","999700000000004","8900000000000000004","0004","4444","44444444","0404","04040404","44444444444444444444444444444444","44444444444444444444444444444444","44444444","44444444444444444444444444444444","44444444444444444444444444444444","44444444444444444444444444444444"
+   "card5","999700000000005","8900000000000000005","0005","4444","55555555","0505","05050505","55555555555555555555555555555555","55555555555555555555555555555555","55555555","55555555555555555555555555555555","55555555555555555555555555555555","55555555555555555555555555555555"
+   "card6","999700000000006","8900000000000000006","0006","4444","66666666","0606","06060606","66666666666666666666666666666666","66666666666666666666666666666666","66666666","66666666666666666666666666666666","66666666666666666666666666666666","66666666666666666666666666666666"
+
+When importing data from an updated CSV format the database table also has
+to be updated. This is done using the `--update-columns` switch. Like when
+creating new tables, this operation also requires admin privileges, so the
+`--admin` switch is required again.
+
+::
+
+   $ PYTHONPATH=../ ./csv-to-pgsql.py --csv ./csv-to-pgsql_example_02.csv --table-name uicc_keys --update-columns --admin
+   INFO: CSV file: ./csv-to-pgsql_example_02.csv
+   INFO: CSV file columns: ['ID', 'IMSI', 'ICCID', 'ACC', 'PIN1', 'PUK1', 'PIN2', 'PUK2', 'KI', 'OPC', 'ADM1', 'SCP02_DEK_1', 'SCP02_ENC_1', 'SCP02_MAC_1']
+   INFO: Using config file: /home/user/.osmocom/pysim/card_data_pgsql.cfg
+   INFO: Database host: 127.0.0.1
+   INFO: Database name: my_database
+   INFO: Database user: my_admin_user
+   INFO: Database table: uicc_keys
+   INFO: Database table columns: ['ICCID', 'IMSI', 'PIN2', 'PUK1', 'PUK2', 'ACC', 'ID', 'PIN1', 'ADM1', 'KI', 'OPC']
+   INFO: Adding missing columns: ['SCP02_ENC_1', 'SCP02_MAC_1', 'SCP02_DEK_1']
+   INFO: Changes to table uicc_keys committed!
+
+When the new table columns are added, the import may be continued like the
+first one:
+
+::
+
+   $ PYTHONPATH=../ ./csv-to-pgsql.py --csv ./csv-to-pgsql_example_02.csv --table-name uicc_keys
+   INFO: CSV file: ./csv-to-pgsql_example_02.csv
+   INFO: CSV file columns: ['ID', 'IMSI', 'ICCID', 'ACC', 'PIN1', 'PUK1', 'PIN2', 'PUK2', 'KI', 'OPC', 'ADM1', 'SCP02_DEK_1', 'SCP02_ENC_1', 'SCP02_MAC_1']
+   INFO: Using config file: /home/user/.osmocom/pysim/card_data_pgsql.cfg
+   INFO: Database host: 127.0.0.1
+   INFO: Database name: my_database
+   INFO: Database user: my_importer_user
+   INFO: Database table: uicc_keys
+   INFO: Database table columns: ['ICCID', 'IMSI', 'PIN2', 'PUK1', 'PUK2', 'ACC', 'ID', 'PIN1', 'ADM1', 'KI', 'OPC', 'SCP02_ENC_1', 'SCP02_MAC_1', 'SCP02_DEK_1']
+   INFO: CSV file import done, 3 rows imported
+   INFO: Changes to table uicc_keys committed!
+
+On the PostgreSQL console a `SELECT * FROM uicc_keys;` should now show the
+imported data with the added columns. All important data should now also be
+available from within pySim-shell via the `CardKeyProviderPgsql`.
+
+
+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 (or
+database).
+
+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`
+
+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`
+
+NOTE: When using `CardKeyProviderPqsl`, the input CSV files must be encrypted
+before import.
+
+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 CardKeyProvider finds a line (row) in your CSV file
+(or database) 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 of 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.

docs/conf.py

@@ -13,14 +13,23 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('.'))   # for local extensions (pysim_fs_sphinx, ...)
 
 
 # -- Project information -----------------------------------------------------
 
 project = 'osmopysim-usermanual'
-copyright = '2009-2023 by Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle, Merlin Chlosta'
+copyright = '2009-2025 by Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle, Merlin Chlosta'
 author = 'Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle, Merlin Chlosta'
 
+# PDF: Avoid that the authors list exceeds the page by inserting '\and'
+# manually as line break (https://github.com/sphinx-doc/sphinx/issues/6875)
+latex_elements = {
+    "maketitle":
+        r"""\author{Sylvain Munaut, Harald Welte, Philipp Maier, \and Supreeth Herle, Merlin Chlosta}
+\sphinxmaketitle
+"""
+}
 
 # -- General configuration ---------------------------------------------------
 
@@ -31,7 +40,8 @@ extensions = [
         "sphinx.ext.autodoc",
         "sphinxarg.ext",
         "sphinx.ext.autosectionlabel",
-        "sphinx.ext.napoleon"
+        "sphinx.ext.napoleon",
+        "pysim_fs_sphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -56,3 +66,25 @@ html_theme = 'alabaster'
 html_static_path = ['_static']
 
 autoclass_content = 'both'
+
+# Mock optional server-side deps of es2p and http_json_api/es9p,
+# so that autodoc can import and document those modules.
+autodoc_mock_imports = ['klein', 'twisted']
+
+# Workaround for duplicate label warnings:
+# https://github.com/sphinx-doc/sphinx-argparse/issues/14
+#
+# sphinxarg.ext generates generic sub-headings ("Named arguments",
+# "Positional arguments", "Sub-commands", "General options", ...) for every
+# argparse command/tool.  These repeat across many files and trigger tons
+# of autosectionlabel duplicate-label warnings - suppress them.
+autosectionlabel_maxdepth = 3
+suppress_warnings = [
+    'autosectionlabel.filesystem',
+    'autosectionlabel.saip-tool',
+    'autosectionlabel.shell',
+    'autosectionlabel.smpp2sim',
+    'autosectionlabel.smpp-ota-tool',
+    'autosectionlabel.suci-keytool',
+    'autosectionlabel.trace',
+]

docs/index.rst

@@ -39,10 +39,17 @@ pySim consists of several parts:
    :caption: Contents:
 
    shell
+   filesystem
    trace
    legacy
+   smpp2sim
    library
+   library-esim
    osmo-smdpp
+   sim-rest
+   suci-keytool
+   saip-tool
+   smpp-ota-tool
 
 
 Indices and tables

docs/legacy.rst

@@ -1,20 +1,20 @@
-Legacy tools
+Legacy tools
 ============
 
 *legacy tools* are the classic ``pySim-prog`` and ``pySim-read`` programs that
 existed long before ``pySim-shell``.
 
-These days, you should primarily use ``pySim-shell`` instead of these
+These days, it is highly recommended to use ``pySim-shell`` instead of these
 legacy tools.
 
 pySim-prog
 ----------
 
-``pySim-prog`` was the first part of the pySim software suite.  It started as
-a tool to write ICCID, IMSI, MSISDN and Ki to very simplistic SIM cards, and
-was later extended to a variety of other cards.  As the number of features supported
-became no longer bearable to express with command-line arguments, `pySim-shell` was
-created.
+``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`.
 
@@ -22,36 +22,180 @@ Program customizable SIMs
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 Two modes are possible:
 
-  - one where you specify every parameter manually :
+  - one where the user specifies every parameter manually:
 
-``./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -i <IMSI> -s <ICCID>``
+    This is the most common way to use ``pySim-prog``. The user will specify all relevant parameters directly via the
+    commandline. A typical commandline would look like this:
+
+    ``pySim-prog.py -p <pcsc_reader> --ki <ki_value> --opc <opc_value> --mcc <mcc_value> --mnc <mnc_value>
+    --country <country_code> --imsi <imsi_value> --iccid <iccid_value> --pin-adm <adm_pin>``
+
+    Please note, that this already lengthy commandline still only contains the most common card parameters. For a full
+    list of all possible parameters, use the ``--help`` option of ``pySim-prog``. It is also important to mention
+    that not all parameters are supported by all card types. In particular, very simple programmable SIM cards will only
+    support a very basic set of parameters, such as MCC, MNC, IMSI and KI values.
+
+  - one where the parameters are generated from a minimal set:
+
+    It is also possible to leave the generation of certain parameters to ``pySim-prog``. This is in particular helpful
+    when a large number of cards should be initialized with randomly generated key material.
+
+    ``pySim-prog.py -p <pcsc_reader> --mcc <mcc_value> --mnc <mnc_value> --secret <random_secret> --num <card_number> --pin-adm <adm_pin>``
+
+    The parameter ``--secret`` specifies a random seed that is used to generate the card individual parameters. (IMSI).
+    The secret should contain enough randomness to avoid conflicts. It is also recommended to store the secret safely,
+    in case cards have to be re-generated or the current card batch has to be extended later. For security reasons, the
+    key material, which is also card individual, will not be derived from the random seed. Instead a new random set of
+    Ki and OPc will be generated during each programming cycle. This means fresh keys are generated, even when the
+    ``--num`` remains unchanged.
+
+    The parameter ``--num`` specifies a card individual number. This number will be managed 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 with 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.
 
 
-  - one where they are generated from some minimal set :
+Card programming using CSV files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``./pySim-prog.py -n 26C3 -c 49 -x 262 -y 42 -z <random_string_of_choice> -j <card_num>``
+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.
 
-    With <random_string_of_choice> and <card_num>, the soft will generate
-    'predictable' IMSI and ICCID, so make sure you choose them so as not to
-    conflict with anyone. (for eg. your name as <random_string_of_choice> and
-    0 1 2 ... for <card num>).
+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.
 
-  You also need to enter some parameters to select the device :
-   -t TYPE : type of card (supersim, magicsim, fakemagicsim or try 'auto')
-   -d DEV  : Serial port device (default /dev/ttyUSB0)
-   -b BAUD : Baudrate (default 9600)
+The CSV file format is a flexible format with mandatory and optional columns,
+here the same rules as for the commandline parameters apply. The column names
+match the command line options. The CSV file may also contain columns that are
+unknown to pySim-prog, such as inventory numbers, nicknames or parameters that
+are unrelated to the card programming process. ``pySim-prog`` will silently
+ignore all unknown columns.
+
+A CSV file may contain the following columns:
+
+* name
+* iccid (typically used as key)
+* mcc
+* mnc
+* imsi (may be used as key, but not recommended)
+* smsp
+* ki
+* opc
+* acc
+* pin_adm, adm1 or pin_adm_hex (must be present)
+* msisdn
+* epdgid
+* epdgSelection
+* pcscf
+* ims_hdomain
+* impi
+* impu
+* opmode
+* fplmn
+
+Due to historical reasons, and to maintain the compatibility between multiple different CSV file formats, the ADM pin
+may be stored in three different columns. Only one of the three columns must be available.
+
+* adm1: This column contains the ADM pin in numeric ASCII digit format. This format is the most common.
+* pin_adm: Same as adm1, only the column name is different
+* pin_adm_hex: If the ADM pin consists of raw HEX digits, rather then of numerical ASCII digits, then the ADM pin
+  can also be provided as HEX string using this column.
+
+The following example shows a typical minimal example
+::
+
+   "imsi","iccid","acc","ki","opc","adm1"
+   "999700000053010","8988211000000530108","0001","51ACE8BD6313C230F0BFE1A458928DF0","E5A00E8DE427E21B206526B5D1B902DF","65942330"
+   "999700000053011","8988211000000530116","0002","746AAFD7F13CFED3AE626B770E53E860","38F7CE8322D2A7417E0BBD1D7B1190EC","13445792"
+   "999700123053012","8988211000000530124","0004","D0DA4B7B150026ADC966DC637B26429C","144FD3AEAC208DFFF4E2140859BAE8EC","53540383"
+   "999700000053013","8988211000000530132","0008","52E59240ABAC6F53FF5778715C5CE70E","D9C988550DC70B95F40342298EB84C5E","26151368"
+   "999700000053014","8988211000000530140","0010","3B4B83CB9C5F3A0B41EBD17E7D96F324","D61DCC160E3B91F284979552CC5B4D9F","64088605"
+   "999700000053015","8988211000000530157","0020","D673DAB320D81039B025263610C2BBB3","4BCE1458936B338067989A06E5327139","94108841"
+   "999700000053016","8988211000000530165","0040","89DE5ACB76E06D14B0F5D5CD3594E2B1","411C4B8273FD7607E1885E59F0831906","55184287"
+   "999700000053017","8988211000000530173","0080","977852F7CEE83233F02E69E211626DE1","2EC35D48DBF2A99C07D4361F19EF338F","70284674"
+
+The following commandline will instruct ``pySim-prog`` to use the provided CSV file as parameter source and the
+ICCID (read from the card before programming) as a key to identify the card. To use the IMSI as a key, the parameter
+``--read-imsi`` can be used instead of ``--read-iccid``. However, this option is only recommended to be used in very
+specific corner cases.
+
+``pySim-prog.py -p <pcsc_reader> --read-csv <path_to_csv_file> --source csv --read-iccid``
+
+It is also possible to pick a row from the CSV file by manually providing an ICCID (option ``--iccid``) or an IMSI
+(option ``--imsi``) that is then used as a key to find the matching row in the CSV file.
+
+``pySim-prog.py -p <pcsc_reader> --read-csv <path_to_csv_file> --source csv --iccid <iccid_value>``
+
+
+Writing CSV files
+~~~~~~~~~~~~~~~~~
+``pySim-prog`` is also able to generate CSV files that contain a subset of the parameters it has generated or received
+from some other source (commandline, CSV-File). The generated file will be header-less and contain the following
+columns:
+
+* name
+* iccid
+* mcc
+* mnc
+* imsi
+* smsp
+* ki
+* opc
+
+A commandline that makes use of the CSV write feature would look like this:
+
+``pySim-prog.py -p <pcsc_reader> --read-csv <path_to_input_csv_file> --read-iccid --source csv --write-csv <path_to_output_csv_file>``
+
+
+Batch programming
+~~~~~~~~~~~~~~~~~
+
+In case larger card batches need to be programmed, it is possible to use the ``--batch`` parameter to run ``pySim-prog`` in batch mode.
+
+The batch mode will prompt the user to insert a card. Once a card is detected in the reader, the programming is carried out. The user may then remove the card again and the process starts over. This allows for a quick and efficient card programming without permanent commandline interaction.
 
 
 pySim-read
 ----------
 
-``pySim-read`` allows you to read some data from a SIM card.  It will only some files
-of the card, and will only read files accessible to a normal user (without any special authentication)
+``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, you should 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``.
+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:
 
@@ -61,7 +205,7 @@ Specifically, pySim-read will dump the following:
 
 * DF.GSM
 
- * EF,IMSI
+ * EF.IMSI
  * EF.GID1
  * EF.GID2
  * EF.SMSP

docs/library-esim.rst

@@ -0,0 +1,95 @@
+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.
+
+.. automodule:: pySim.esim
+   :members:
+
+
+GSMA SGP.21/22 Remote SIM Provisioning (RSP) - High Level
+---------------------------------------------------------
+
+pySim.esim.rsp
+~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.rsp
+   :members:
+
+pySim.esim.es2p
+~~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.es2p
+   :members:
+
+
+pySim.esim.es8p
+~~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.es8p
+   :members:
+
+
+pySim.esim.es9p
+~~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.es9p
+   :members:
+
+
+GSMA SGP.21/22 Remote SIM Provisioning (RSP) - Low Level
+--------------------------------------------------------
+
+pySim.esim.bsp
+~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.bsp
+   :members:
+
+pySim.esim.http_json_api
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.http_json_api
+   :members:
+
+pySim.esim.x509_cert
+~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.x509_cert
+   :members:
+
+SIMalliance / TCA Interoperable Profile
+---------------------------------------
+
+
+pySim.esim.saip
+~~~~~~~~~~~~~~~
+.. automodule:: pySim.esim.saip
+   :members:
+
+
+pySim.esim.saip.oid
+~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.saip.oid
+   :members:
+
+pySim.esim.saip.personalization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.saip.personalization
+   :members:
+
+pySim.esim.saip.templates
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.saip.templates
+   :members:
+
+pySim.esim.saip.validation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pySim.esim.saip.validation
+   :members:

docs/library.rst

@@ -74,18 +74,6 @@ at 9600 bps.  These readers are sometimes called `Phoenix`.
    :members:
 
 
-pySim construct utilities
--------------------------
-
-.. automodule:: pySim.construct
-   :members:
-
-pySim TLV utilities
--------------------
-
-.. automodule:: pySim.tlv
-   :members:
-
 pySim utility functions
 -----------------------
 

docs/osmo-smdpp.rst

@@ -19,32 +19,42 @@ support for profile personalization yet.
 
 osmo-smdpp currently
 
-* uses test certificates copied from GSMA SGP.26 into `./smdpp-data/certs`, assuming that your osmo-smdppp
-  would be running at the host name `testsmdpplus1.example.com`
+* [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
+  certificates with your own, whether SGP.26 derived or part of a *private root CA* setup with matching 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
-* doesn't perform any personalization, so the IMSI/ICCID etc. are always identical
+  of the EID or whether it was downloaded 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 any certificate verification
- * does not evaluate/consider any *Matching ID* or *Confirmation Code*
- * stores the sessions in an unencrypted _python shelve_ and is hence leaking one-time key materials
+ * 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.
 
 
 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.
+osmo-smdpp comes with built-in TLS support which is enabled by default. However, it is always possible to
+disable the built-in TLS support if needed.
+
+In order to use osmo-smdpp without the built-in TLS support, it has to be put behind a TLS reverse proxy,
+which terminates the ES9+ HTTPS traffic from the LPA, and then forwards it as plain HTTP to osmo-smdpp.
+
+NOTE: The built in TLS support in osmo-smdpp makes use of the python *twisted* framework. Older versions
+of this framework appear 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::
+If you chose to use `nginx` as TLS reverse proxy, you can use the following configuration snippet::
 
   upstream smdpp {
           server localhost:8000;
@@ -74,31 +84,56 @@ If you use `nginx` as web server, you can use the following configuration snippe
 You can of course achieve a similar functionality with apache, lighttpd or many other web server
 software.
 
+supplementary files
+~~~~~~~~~~~~~~~~~~~
 
-osmo-smdpp
-~~~~~~~~~~
-
-osmo-smdpp currently doesn't have any configuration file or command line options.  You just run it,
-and it will bind its plain-HTTP ES9+ interface to local TCP port 8000.
-
-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.
+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 osmo-smdpp without any arguments, and it will bind its built-in HTTPS ES9+ interface to
+`localhost` TCP port 443. In this case an external TLS reverse proxy is not needed.
+
+osmo-smdpp currently doesn't have any configuration file.
+
+There are command line options for binding:
+
+Bind the HTTPS ES9+ to a port other than 443::
+
+  ./osmo-smdpp.py -p 8443
+
+Disable the built-in TLS support and bind the plain-HTTP ES9+ to a port 8000::
+
+  ./osmo-smdpp.py -p 8000 --nossl
+
+Bind the HTTP ES9+ to a different local interface::
+
+  ./osmo-smdpp.py -H 127.0.0.2
 
 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.
+It must also accept the TLS certificates used by your TLS proxy. In case osmo-smdpp is used with built-in TLS support,
+it will use the certificates provided in smdpp-data.
+
+NOTE: The HTTPS ES9+ interface cannot be addressed by the LPA directly via its IP address. The reason for this is that
+the included SGP.26 (DPtls) test certificates explicitly restrict the hostname to `testsmdpplus1.example.com` in the
+`X509v3 Subject Alternative Name` extension. Using a bare IP address as hostname may cause the certificate to be
+rejected by the LPA.
+
 
 Supported eUICC
 ~~~~~~~~~~~~~~~
 
-If you run osmo-smdpp with the included SGP.26 certificates, you must use an eUICC with matching SGP.26
+If you run osmo-smdpp with the included SGP.26 (DPauth, DPpb) certificates, you must use an eUICC with matching SGP.26
 certificates, 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.
 

docs/put_key-tutorial.rst

@@ -0,0 +1,836 @@
+Guide: Managing GP Keys
+=======================
+
+Most of today's smartcards follow the GlobalPlatform Card Specification and the included Security Domain model.
+UICCs and eUCCCs are no exception here.
+
+The Security Domain acts as an on-card representative of a card authority or administrator. It is used to perform tasks
+like the installation of applications or the provisioning and rotation of secure channel keys. It also acts as a secure
+key storage and offers all kinds of cryptographic services to applications that are installed under a specific
+Security Domain (see also GlobalPlatform Card Specification, section 7).
+
+In this tutorial, we will show how to work with the key material (keysets) stored inside a Security Domain and how to
+rotate (replace) existing keys. We will also show how to provision new keys.
+
+.. warning:: Making changes to keysets requires extreme caution as misconfigured keysets may lock you out permanently.
+	     It's also strongly recommended to maintain at least one backup keyset that you can use as fallback in case
+	     the primary keyset becomes unusable for some reason.
+
+
+Selecting a Security Domain
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A typical smartcard, such as an UICC will have one primary Security Domain, called the Issuer Security Domain (ISD).
+When working with those cards, the ISD will show up in the UICC filesystem tree as `ADF.ISD` and can be selected like
+any other file.
+
+::
+
+   pySIM-shell (00:MF)> select ADF.ISD
+   {
+      "application_id": "a000000003000000",
+      "proprietary_data": {
+         "maximum_length_of_data_field_in_command_message": 255
+      }
+   }
+
+When working with eUICCs, multiple Security Domains are involved. The model is fundamentally different from the classic
+model with one primary Security Domain (ISD). In the case of eUICCs, an ISD-R (Issuer Security Domain - Root) and an
+ISD-P (Issuer Security Domain - Profile) exist (see also: GSMA SGP.02, section 2.2.1).
+
+The ISD-P is established by the ISD-R during the profile installation and serves as a secure container for an eSIM
+profile. Within the ISD-P the eSIM profile establishes a dedicated Security Domain called `MNO-SD` (see also GSMA
+SGP.02, section 2.2.4). This `MNO-SD` is comparable to the Issuer Security Domain (ISD) we find on UICCs. The AID of
+`MNO-SD` is either the default AID for the Issuer Security Domain (see also GlobalPlatform, section H.1.3) or a
+different value specified by the provider of the eSIM profile.
+
+Since the AID of the `MNO-SD` is not a fixed value, it is not known by `pySim-shell`. This means there will be no
+`ADF.ISD` file shown in the file system, but we can simply select the `ADF.ISD-R` first and then select the `MNO-SD`
+using a raw APDU. In the following example we assume that the default AID (``a000000151000000``) is used  The APDU
+would look like this: ``00a4040408`` + ``a000000151000000`` + ``00``
+
+::
+
+   pySIM-shell (00: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": "020300"
+       }
+   }
+   pySIM-shell (00:MF/ADF.ISD-R)> apdu 00a4040408a00000015100000000
+   SW: 9000, RESP: 6f108408a000000151000000a5049f6501ff
+
+After that, the prompt will still show the `ADF.ISD-R`, but we are actually in `ADF.ISD` and the standard GlobalPlatform
+operations like `establish_scpXX`, `get_data`, and `put_key` should work. By doing this, we simply have tricked
+`pySim-shell` into making the GlobalPlatform related commands available for some other Security Domain we are not
+interested in. With the raw APDU we then have swapped out the Security Domain under the hood. The same workaround can
+be applied to any Security Domain, provided that the AID is known to the user.
+
+
+Establishing a secure channel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before we can make changes to the keysets in the currently selected Security Domain we must first establish a secure
+channel with that Security Domain. In the following examples we will use `SCP02` (see also GlobalPlatform Card
+Specification, section E.1.1) and `SCP03` (see also GlobalPlatform Card Specification – Amendment D) to establish the
+secure channel. `SCP02` is slightly older than `SCP03`. The main difference between the two is that `SCP02` uses 3DES
+while `SCP03` is based on AES.
+
+.. warning:: Secure channel protocols like `SCP02` and `SCP03` may manage an error counter to count failed login
+	     attempts. This means attempting to establish a secure channel with a wrong keyset multiple times may lock
+	     you out permanently. Double check the applied keyset before attempting to establish a secure channel.
+
+.. warning:: The key values used in the following examples are random key values used for illustration purposes only.
+	     Each UICC or eSIM profile is shipped with individual keys, which means that the keys used below will not
+	     work with your UICC or eSIM profile. You must replace the key values with the values you have received
+	     from your UICC vendor or eSIM profile provider.
+
+
+Example: `SCP02`
+----------------
+
+In the following example, we assume that we want to establish a secure channel with the ISD of a `sysmoUSIM-SJA5` UICC.
+Along with the card we have received the following keyset:
+
++---------+----------------------------------+
+| Keyname | Keyvalue                         |
++=========+==================================+
+| ENC/KIC | F09C43EE1A0391665CC9F05AF4E0BD10 |
++---------+----------------------------------+
+| MAC/KID | 01981F4A20999F62AF99988007BAF6CA |
++---------+----------------------------------+
+| DEK/KIK | 8F8AEE5CDCC5D361368BC45673D99195 |
++---------+----------------------------------+
+
+This keyset is tied to the key version number KVN 122 and is configured as a DES keyset. We can use this keyset to
+establish a secure channel using the SCP02 Secure Channel Protocol.
+
+::
+
+    pySIM-shell (00:MF/ADF.ISD)> establish_scp02 --key-enc F09C43EE1A0391665CC9F05AF4E0BD10 --key-mac 01981F4A20999F62AF99988007BAF6CA --key-dek 8F8AEE5CDCC5D361368BC45673D99195  --key-ver 112 --security-level 3
+    Successfully established a SCP02[03] secure channel
+
+
+Example: `SCP03`
+----------------
+
+The establishment of a secure channel via SCP03 works just the same. In the following example we will establish a
+secure channel to the `MNO-SD` of an eSIM profile. The SCP03 keyset we use is tied to KVN 48 and looks like this:
+
++---------+------------------------------------------------------------------+
+| Keyname | Keyvalue                                                         |
++=========+==================================================================+
+| ENC/KIC | 63af517c29ad6ac6fcadfe6ac8a3c8a041d8141c7eb845ef1cba6112a325e430 |
++---------+------------------------------------------------------------------+
+| MAC/KID | 54b9ad6713ae922f54014ed762132e7b59bdcd2a2a6beba98fb9afe6b4df27e1 |
++---------+------------------------------------------------------------------+
+| DEK/KIK | cbb933ba2389da93c86c112739cd96389139f16c6f80f7d16bf3593e407ca893 |
++---------+------------------------------------------------------------------+
+
+We assume that the `MNO-SD` is already selected (see above). We may now establish the SCP03 secure channel:
+
+::
+
+   pySIM-shell (00:MF/ADF.ISD-R)> establish_scp03 --key-enc 63af517c29ad6ac6fcadfe6ac8a3c8a041d8141c7eb845ef1cba6112a325e430 --key-mac 54b9ad6713ae922f54014ed762132e7b59bdcd2a2a6beba98fb9afe6b4df27e1 --key-dek cbb933ba2389da93c86c112739cd96389139f16c6f80f7d16bf3593e407ca893 --key-ver 48 --security-level 3
+   Successfully established a SCP03[03] secure channel
+
+
+
+Understanding Keysets
+~~~~~~~~~~~~~~~~~~~~~
+
+Before making any changes to keysets, it is recommended to check the status of the currently installed keysets. To do
+so, we use the `get_data` command to retrieve the `key_information`. This command does not require the establishment of
+a secure channel. We also cannot read back the key values themselves, but we get a summary of the installed keys
+together with their KVN numbers, IDs, algorithm and key length values.
+
+Example: `key_information` from a `sysmoISIM-SJA5`:
+
+::
+
+    pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> get_data key_information
+    {
+        "key_information": [
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 112,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 112,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 3,
+                    "key_version_number": 112,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 1,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 1,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 3,
+                    "key_version_number": 1,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 2,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 2,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 3,
+                    "key_version_number": 2,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 47,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 47,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 3,
+                    "key_version_number": 47,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            }
+        ]
+    }
+
+Example: `key_information` from a `sysmoEUICC1-C2T`:
+
+::
+
+    pySIM-shell (SCP03[03]:00:MF/ADF.ISD-R)> get_data key_information
+    {
+        "key_information": [
+            {
+                "key_information_data": {
+                    "key_identifier": 3,
+                    "key_version_number": 50,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 32
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 50,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 32
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 50,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 32
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 64,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 64,
+                    "key_types": [
+                        {
+                            "type": "tls_psk",
+                            "length": 16
+                        }
+                    ]
+                }
+            }
+        ]
+    }
+
+The output from those two examples above may seem lengthy, but in order to move on and to provision own keys
+successfully, it is important to understand each aspect of it.
+
+Key Version Number (KVN)
+------------------------
+
+Each key is associated with a Key Version Number (KVN). Multiple keys that share the same KVN belong to the same
+keyset. In the first example above we can see that four keysets with KVN numbers 112, 1, 2 and 47 are provisioned.
+In the second example we see two keysets. One with KVN 50 and one with KVN 64.
+
+The term "Key Version Number" is misleading as this number is not really a version number. It's actually a unique
+identifier for a specific keyset that also defines with which Secure Channel Protocol a key can be used. This means
+that the KVN is not just an arbitrary number. The following (incomplete) table gives a hint which KVN numbers may be
+used with which Secure Channel Protocol.
+
++-----------+-------------------------------------------------------+
+| KVN range | Secure Channel Protocol                               |
++===========+=======================================================+
+| 1-15      | reserved for `SCP80` (OTA SMS)                        |
++-----------+-------------------------------------------------------+
+| 17        | reserved for DAP specified in ETSI TS 102 226         |
++-----------+-------------------------------------------------------+
+| 32-47     | reserved for `SCP02`                                  |
++-----------+-------------------------------------------------------+
+| 48-63     | reserved for `SCP03`                                  |
++-----------+-------------------------------------------------------+
+| 64-79     | reserved for `SCP81` (GSMA SGP.02, section 2.2.5.1)   |
++-----------+-------------------------------------------------------+
+| 112       | Token key (RSA public or DES, also used with `SCP02`) |
++-----------+-------------------------------------------------------+
+| 113       | Receipt key (DES)                                     |
++-----------+-------------------------------------------------------+
+| 115       | DAP verification key (RS public or DES)               |
++-----------+-------------------------------------------------------+
+| 116       | reserved for CASD                                     |
++-----------+-------------------------------------------------------+
+| 117       | 16-byte DES key for Ciphered Load File Data Block     |
++-----------+-------------------------------------------------------+
+| 255       | reserved for ISD with SCP02 without SCP80 support     |
++-----------+-------------------------------------------------------+
+
+With that we can now understand that in the first example, the first and the last keyset is intended to be used with
+`SCP02` and that the second and the third keyset is intended to be used with `SCP80` (OTA SMS). In the second example we
+can see that the first keyset is intended to be used with `SCP03`, wheres the second should be usable with `SCP81`.
+
+
+Key Identifier
+--------------
+
+Each keyset consists of a number of keys, where each key has a different Key Identifier. The Key Identifier is usually
+an incrementing number that starts counting at 1. The Key Identifier is used to distinguish the keys within the keyset.
+The exact number of keys and their attributes depends on the secure channel protocol for which the keyset is intended
+for. Each secure channel protocol may have its specific requirements on how many keys of which which type, length or
+Key Identifier have to be present.
+
+However, almost all of the classic secure channel protocols (including  `SCP02`, `SCP03` and `SCP81`) make use of the
+following three-key scheme:
+
++----------------+---------+---------------------------------------+
+| Key Identifier | Keyname | Purpose                               |
++================+=========+=======================================+
+| 1              | ENC/KIC | encryption/decryption                 |
++----------------+---------+---------------------------------------+
+| 2              | MAC/KID | cryptographic checksumming/signing    |
++----------------+---------+---------------------------------------+
+| 3              | DEK/KIK | encryption/decryption of key material |
++----------------+---------+---------------------------------------+
+
+In this case, all three keys share the same length and are used with the same algorithm. The key length is often used
+to implicitly select sub-types of an algorithm. (e.g. a 16 byte key of type `aes` is associated with `AES128`, where a 32
+byte key would be associated with `AES256`).
+
+The second example shows that different schemes are possible. The `SCP80` keyset from the second example uses a scheme
+that works with two keys:
+
++----------------+---------+---------------------------------------+
+| Key Identifier | Keyname | Purpose                               |
++================+=========+=======================================+
+| 1              | TLS-PSK | pre-shared key used for TLS           |
++----------------+---------+---------------------------------------+
+| 2              | DEK/KIK | encryption/decryption of key material |
++----------------+---------+---------------------------------------+
+
+It should also be noted that the order in which keysets and keys appear is an implementation detail of the UICC/eUICC
+O/S. The order has no influence on how a keyset is interpreted. Only the Key Version Number (KVN) and the Key Identifier
+matter.
+
+
+Rotating a keyset
+~~~~~~~~~~~~~~~~~
+
+Rotating keys is one of the most basic tasks one might want to perform on an UICC/eUICC before using it productively. In
+the following example we will illustrate how key rotation can be done. When rotating keys, only the key itself may
+change. For example it is not possible to change the key length or the algorithm used (see also GlobalPlatform Card
+Specification, section 11.8.2.3.3). Any key of the current Security Domain can be rotated, this also includes the key
+that was used to establish the secure channel.
+
+In the following example we assume that the Security Domain is selected and a secure channel is already established. We
+intend to rotate the keyset with KVN 112. Since this keyset uses triple DES keys with a key length of 16, we must
+replace it with a keyset with keys of the same nature.
+
+The new keyset shall look like this:
+
++----------------+---------+----------------------------------+
+| Key Identifier | Keyname | Keyvalue                         |
++================+=========+==================================+
+| 1              | ENC/KIC | 542C37A6043679F2F9F71116418B1CD5 |
++----------------+---------+----------------------------------+
+| 2              | MAC/KID | 34F11BAC8E5390B57F4E601372339E3C |
++----------------+---------+----------------------------------+
+| 3              | DEK/KIK | 5524F4BECFE96FB63FC29D6BAAC6058B |
++----------------+---------+----------------------------------+
+
+When passing the keys to the `put_key` commandline, we set the Key Identifier of the first key using the `--key-id`
+parameter. This Key Identifier will be valid for the first key (KIC) we pass. For all consecutive keys, the Key
+Identifier will be incremented automatically (see also GlobalPlatform Card Specification, section 11.8.2.2). To Ensure
+that the new KIC, KID and KIK keys get the correct Key Identifiers, it is crucial to maintain order when passing the
+keys in the `--key-data` arguments. It is also important that each `--key-data` argument is preceded by a `--key-type`
+argument that sets the algorithm correctly (`des` in this case).
+
+Finally we have to target the keyset we want to rotate by its KVN. The `--old-key-version-nr` argument is set to 112
+as this identifies the keyset we want to rotate. The `--key-version-nr` is also set to 112 as we do not want
+KVN to be changed in this example. Changing the KVN while rotating a keyset is possible. In case the KVN has to change
+for some reason, the new KVN must be selected carefully to keep the key usable with the associated Secure Channel
+Protocol.
+
+The commandline that matches the keyset we had laid out above looks like this:
+::
+
+   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> put_key --key-id 1 --key-type des --key-data 542C37A6043679F2F9F71116418B1CD5 --key-type des --key-data 34F11BAC8E5390B57F4E601372339E3C --key-type des --key-data 5524F4BECFE96FB63FC29D6BAAC6058B --old-key-version-nr 112 --key-version-nr 112
+
+After executing this put_key commandline, the keyset identified by KVN 122 is equipped with new keys. We can use
+`get_data key_information` to inspect the currently installed keysets. The output should appear unchanged as
+we only swapped out the keys. All other parameters, identifiers etc. should remain constant.
+
+.. warning:: It is technically possible to rotate a keyset in a `non atomic` way using one `put_key` commandline for
+	     each key. However, in case the targeted keyset is the one used to establish the current secure channel,
+	     this method should not be used since, depending on the UICC/eUICC model, half-written key material may
+	     interrupt the current secure channel.
+
+
+Removing a keyset
+~~~~~~~~~~~~~~~~~
+
+In some cases it is necessary to remove a keyset entirely. This can be done with the `delete_key` command. Here it is
+important to understand that `delete_key` only removes one specific key from a specific keyset. This means that you
+need to run a separate `delete_key` command for each key inside a keyset.
+
+In the following example we assume that the Security Domain is selected and a secure channel is already established. We
+intend to remove the keyset with KVN 112. This keyset consists of three keys.
+
+::
+
+   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> delete_key --key-ver 112 --key-id 1
+   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> delete_key --key-ver 112 --key-id 2
+   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> delete_key --key-ver 112 --key-id 3
+
+To verify that the keyset has been deleted properly, we can use the `get_data key_information` command to inspect the
+current status of the installed keysets. We should see that the key with KVN 112 is no longer present.
+
+
+Adding a keyset
+~~~~~~~~~~~~~~~
+
+In the following we will discuss how to add an entirely new keyset. The procedure is almost identical with the key
+rotation procedure we have already discussed and it is assumed that all details about the key rotation are understood.
+In this section we will go into more detail and illustrate how to provision new 3DES, `AES128` and `AES256` keysets.
+
+It is important to keep in mind that storage space on smartcard is a precious resource. In many cases the amount of
+keysets that a Security Domain can store is limited. In some situations you may be forced to sacrifice one of your
+existing keysets in favor of a new keyset.
+
+The main difference between key rotation and the adding of new keys is that we do not simply replace an existing key.
+Instead an entirely new key is programmed into the Security Domain. Therefore the `put_key` commandline will have no
+`--old-key-version-nr` parameter. From the commandline perspective, this is already the only visible difference from a
+commandline that simply rotates a keyset. Since we are writing an entirely new keyset, we are free to chose the
+algorithm and the key length within the parameter range permitted by the targeted secure channel protocol. Otherwise
+the same rules apply.
+
+For reference, it should be mentioned that it is also possible to add or rotate keyset using multiple `put_key`
+commandlines. In this case one `put_key` commandline for each key is used. Each commandline will specify `--key-id` and
+`--key-version-nr` and one `--key-type` and `--key-data` tuple. However, when rotating or adding a keyset step-by-step,
+the whole process happens in a `non-atomic` way, which is less reliable. Therefore we will favor the `atomic method`
+
+In the following examples we assume that the Security Domain is selected and a secure channel is already established.
+
+
+Example: `3DES` key for `SCP02`
+-------------------------------
+
+Let's assume we want to provision a new 3DES keyset that we can use for SCP02. The keyset shall look like this:
+
++----------------+---------+----------------------------------+
+| Key Identifier | Keyname | Keyvalue                         |
++================+=========+==================================+
+| 1              | ENC/KIC | 542C37A6043679F2F9F71116418B1CD5 |
++----------------+---------+----------------------------------+
+| 2              | MAC/KID | 34F11BAC8E5390B57F4E601372339E3C |
++----------------+---------+----------------------------------+
+| 3              | DEK/KIK | 5524F4BECFE96FB63FC29D6BAAC6058B |
++----------------+---------+----------------------------------+
+
+The keyset shall be a associated with the KVN 46. We have made sure before that KVN 46 is still unused and that this
+KVN number is actually suitable for SCP02 keys. As we are using 3DES, it is obvious that we have to pass 3 keys with 16
+byte length.
+
+To program the key, we may use the following commandline. As we can see, this commandline is almost the exact same as
+the one from the key rotation example where we were rotating a 3DES key. The only difference is that we didn't specify
+an old KVN number and that we have chosen a different KVN.
+
+::
+
+   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> put_key --key-id 1 --key-type des --key-data 542C37A6043679F2F9F71116418B1CD5 --key-type des --key-data 34F11BAC8E5390B57F4E601372339E3C --key-type des --key-data 5524F4BECFE96FB63FC29D6BAAC6058B --key-version-nr 46
+
+In case of success, the keyset should appear in the `key_information` among the other keysets that are already present.
+
+::
+
+    pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> get_data key_information
+    {
+        "key_information": [
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 46,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 46,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 3,
+                    "key_version_number": 46,
+                    "key_types": [
+                        {
+                            "type": "des",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            ...
+        ]
+    }
+
+
+Example: `AES128` key for `SCP80`
+---------------------------------
+
+In this example we intend to provision a new `AES128` keyset that we can use with SCP80 (OTA SMS). The keyset shall look
+like this:
+
++----------------+---------+----------------------------------+
+| Key Identifier | Keyname | Keyvalue                         |
++================+=========+==================================+
+| 1              | ENC/KIC | 542C37A6043679F2F9F71116418B1CD5 |
++----------------+---------+----------------------------------+
+| 2              | MAC/KID | 34F11BAC8E5390B57F4E601372339E3C |
++----------------+---------+----------------------------------+
+| 3              | DEK/KIK | 5524F4BECFE96FB63FC29D6BAAC6058B |
++----------------+---------+----------------------------------+
+
+In addition to that, we want to associate this key with KVN 3. We have inspected the currently installed keysets before
+and made sure that KVN 3 is still unused. We are also aware that for SCP80 we may only use KVN values from 1 to 15.
+
+For `AES128`, we specify the algorithm using the `--key-type aes` parameter. The selection between `AES128` and `AES256` is
+done implicitly using the key length. Since we want to use `AES128` in this case, all three keys have a length of 16 byte.
+
+::
+
+   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> put_key --key-id 1 --key-type aes --key-data 542C37A6043679F2F9F71116418B1CD5 --key-type aes --key-data 34F11BAC8E5390B57F4E601372339E3C --key-type aes --key-data 5524F4BECFE96FB63FC29D6BAAC6058B --key-version-nr 3
+
+In case of success, the keyset should appear in the `key_information` among the other keysets that are already present.
+
+::
+
+    pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> get_data key_information
+    {
+        "key_information": [
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 3,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 3,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 3,
+                    "key_version_number": 3,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            ...
+        ]
+    }
+
+
+Example: `AES256` key for `SCP03`
+---------------------------------
+
+Let's assume we want to provision a new `AES256` keyset that we can use for SCP03. The keyset shall look like this:
+
++----------------+---------+------------------------------------------------------------------+
+| Key Identifier | Keyname | Keyvalue                                                         |
++================+=========+==================================================================+
+| 1              | ENC/KIC | 542C37A6043679F2F9F71116418B1CD5542C37A6043679F2F9F71116418B1CD5 |
++----------------+---------+------------------------------------------------------------------+
+| 2              | MAC/KID | 34F11BAC8E5390B57F4E601372339E3C34F11BAC8E5390B57F4E601372339E3C |
++----------------+---------+------------------------------------------------------------------+
+| 3              | DEK/KIK | 5524F4BECFE96FB63FC29D6BAAC6058B5524F4BECFE96FB63FC29D6BAAC6058B |
++----------------+---------+------------------------------------------------------------------+
+
+In addition to that, we assume that we want to associate this key with KVN 51. This KVN number falls in the range of
+48 - 63 and is therefore suitable for a key that shall be usable with SCP03. We also made sure before that KVN 51 is
+still unused.
+
+With that we can go ahead and make up the following commandline:
+::
+
+   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> put_key --key-id 1 --key-type aes --key-data 542C37A6043679F2F9F71116418B1CD5542C37A6043679F2F9F71116418B1CD5 --key-type aes --key-data 34F11BAC8E5390B57F4E601372339E3C34F11BAC8E5390B57F4E601372339E3C --key-type aes --key-data 5524F4BECFE96FB63FC29D6BAAC6058B5524F4BECFE96FB63FC29D6BAAC6058B --key-version-nr 51
+
+In case of success, we should see the keyset in the `key_information`
+
+::
+
+    pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> get_data key_information
+    {
+        "key_information": [
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 51,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 32
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 51,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 32
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 3,
+                    "key_version_number": 51,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 32
+                        }
+                    ]
+                }
+            },
+            ...
+        ]
+    }
+
+
+Example: `AES128` key for `SCP81`
+---------------------------------
+
+In this example we will show how to provision a new `AES128` keyset for `SCP81`. We will provision this keyset under
+KVN 64. The keyset we intend to apply shall look like this:
+
++----------------+---------+----------------------------------+
+| Key Identifier | Keyname | Keyvalue                         |
++================+=========+==================================+
+| 1              | TLS-PSK | 000102030405060708090a0b0c0d0e0f |
++----------------+---------+----------------------------------+
+| 2              | DEK/KIK | 000102030405060708090a0b0c0d0e0f |
++----------------+---------+----------------------------------+
+
+With that we can put together the following command line:
+
+::
+
+    put_key --key-id 1 --key-type tls_psk --key-data 000102030405060708090a0b0c0d0e0f --key-type aes --key-data 000102030405060708090a0b0c0d0e0f --key-version-nr 64
+
+In case of success, the keyset should appear in the `key_information` as follows:
+
+::
+
+    pySIM-shell (SCP03[03]:00:MF/ADF.ISD-R)> get_data key_information
+    {
+        "key_information": [
+            ...,
+            {
+                "key_information_data": {
+                    "key_identifier": 2,
+                    "key_version_number": 64,
+                    "key_types": [
+                        {
+                            "type": "aes",
+                            "length": 16
+                        }
+                    ]
+                }
+            },
+            {
+                "key_information_data": {
+                    "key_identifier": 1,
+                    "key_version_number": 64,
+                    "key_types": [
+                        {
+                            "type": "tls_psk",
+                            "length": 16
+                        }
+                    ]
+                }
+            }
+        ]
+    }

docs/pysim_fs_sphinx.py

@@ -0,0 +1,267 @@
+"""
+Sphinx extension: auto-generate docs/filesystem.rst from the pySim EF class hierarchy.
+
+Hooked into Sphinx's ``builder-inited`` event so the file is always regenerated
+from the live Python classes before Sphinx reads any source files.
+
+The table of root objects to document is in SECTIONS near the top of this file.
+EXCLUDED lists CardProfile/CardApplication subclasses intentionally omitted from
+SECTIONS, with reasons.  Both tables are read by tests/unittests/test_fs_coverage.py
+to ensure every class with EF/DF content is accounted for.
+"""
+
+import importlib
+import inspect
+import json
+import os
+import sys
+import textwrap
+
+# Ensure pySim is importable when this module is loaded as a Sphinx extension
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+from pySim.filesystem import (CardApplication, CardDF, CardMF, CardEF, # noqa: E402
+                              TransparentEF, TransRecEF, LinFixedEF, CyclicEF, BerTlvEF)
+from pySim.profile import CardProfile # noqa: E402
+
+
+# Generic EF base classes whose docstrings describe the *type* of file
+# (Transparent, LinFixed, ...) rather than a specific file's content.
+# Suppress those boilerplate texts in the per-EF entries; they are only
+# useful once, at the top of the document or in a dedicated glossary.
+_EF_BASE_TYPES = frozenset([TransparentEF,
+                            TransRecEF,
+                            LinFixedEF,
+                            CyclicEF,
+                            BerTlvEF])
+
+
+# ---------------------------------------------------------------------------
+# Sections: (heading, module, class-name)
+# The class must be either a CardProfile (uses .files_in_mf) or a CardDF
+# subclass (uses .children).
+# ---------------------------------------------------------------------------
+SECTIONS = [
+    ('MF / TS 102 221 (UICC)',
+     'pySim.ts_102_221', 'CardProfileUICC'),
+    ('ADF.USIM / TS 31.102',
+     'pySim.ts_31_102',  'ADF_USIM'),
+    ('ADF.ISIM / TS 31.103',
+     'pySim.ts_31_103',  'ADF_ISIM'),
+    ('ADF.HPSIM / TS 31.104',
+     'pySim.ts_31_104',  'ADF_HPSIM'),
+    ('DF.GSM + DF.TELECOM / TS 51.011 (SIM)',
+     'pySim.ts_51_011',  'CardProfileSIM'),
+    ('CDMA / IS-820 (RUIM)',
+     'pySim.cdma_ruim',  'CardProfileRUIM'),
+    ('DF.EIRENE / GSM-R',
+     'pySim.gsm_r',      'DF_EIRENE'),
+    ('DF.SYSTEM / sysmocom SJA2+SJA5',
+     'pySim.sysmocom_sja2', 'DF_SYSTEM'),
+]
+
+# ---------------------------------------------------------------------------
+# Excluded: {(module, class-name)}
+# CardProfile and CardApplication subclasses that have EF/DF children but are
+# intentionally absent from SECTIONS.  Keeping this list explicit lets
+# test_fs_coverage.py detect newly added classes that the developer forgot to
+# add to either table.
+# ---------------------------------------------------------------------------
+EXCLUDED = {
+    # eUICC profiles inherit files_in_mf verbatim from CardProfileUICC; the
+    # eUICC-specific content lives in ISD-R / ISD-P applications, not in MF.
+    ('pySim.euicc', 'CardProfileEuiccSGP02'),
+    ('pySim.euicc', 'CardProfileEuiccSGP22'),
+    ('pySim.euicc', 'CardProfileEuiccSGP32'),
+    # CardApplication* classes are thin wrappers that embed an ADF_* instance.
+    # The ADF contents are already documented via the corresponding ADF_* entry
+    # in SECTIONS above.
+    ('pySim.ts_31_102', 'CardApplicationUSIM'),
+    ('pySim.ts_31_102', 'CardApplicationUSIMnonIMSI'),
+    ('pySim.ts_31_103', 'CardApplicationISIM'),
+    ('pySim.ts_31_104', 'CardApplicationHPSIM'),
+}
+
+# RST underline characters ordered by nesting depth
+_HEADING_CHARS = ['=', '=', '-', '~', '^', '"']
+# Level 0 uses '=' with overline (page title).
+# Level 1 uses '=' without overline (major sections).
+# Levels 2+ use the remaining characters for DFs.
+
+
+# ---------------------------------------------------------------------------
+# RST formatting helpers
+# ---------------------------------------------------------------------------
+
+def _heading(title: str, level: int) -> str:
+    """Return an RST heading string.  Level 0 gets an overline."""
+    char = _HEADING_CHARS[level]
+    rule = char * len(title)
+    if level == 0:
+        return f'{rule}\n{title}\n{rule}\n\n'
+    return f'{title}\n{rule}\n\n'
+
+
+def _json_default(obj):
+    """Fallback serialiser: bytes -> hex, anything else -> repr."""
+    if isinstance(obj, (bytes, bytearray)):
+        return obj.hex()
+    return repr(obj)
+
+
+def _examples_block(cls) -> str:
+    """Return RST code-block examples (one per vector), or '' if none exist.
+
+    Each example is rendered as a ``json5`` code-block with the hex-encoded
+    binary as a ``// comment`` on the first line, followed by the decoded JSON.
+    ``json5`` is used instead of ``json`` so that Pygments does not flag the
+    ``//`` comment as a syntax error.
+    """
+    vectors = []
+    for attr in ('_test_de_encode', '_test_decode'):
+        v = getattr(cls, attr, None)
+        if v:
+            vectors.extend(v)
+    if not vectors:
+        return ''
+
+    lines = ['**Examples**\n\n']
+
+    for t in vectors:
+        # 2-tuple: (encoded, decoded)
+        # 3-tuple: (encoded, record_nr, decoded)   — LinFixedEF / CyclicEF
+        if len(t) >= 3:
+            encoded, record_nr, decoded = t[0], t[1], t[2]
+            comment = f'record {record_nr}: {encoded.lower()}'
+        else:
+            encoded, decoded = t[0], t[1]
+            comment = f'file: {encoded.lower()}'
+
+        json_str = json.dumps(decoded, default=_json_default, indent=2)
+        json_indented = textwrap.indent(json_str, '   ')
+
+        lines.append('.. code-block:: json5\n\n')
+        lines.append(f'   // {comment}\n')
+        lines.append(json_indented + '\n')
+        lines.append('\n')
+
+    return ''.join(lines)
+
+
+def _document_ef(ef: CardEF) -> str:
+    """Return RST for a single EF.  Uses ``rubric`` to stay out of the TOC."""
+    cls = type(ef)
+
+    parts = [ef.fully_qualified_path_str()]
+    if ef.fid:
+        parts.append(f'({ef.fid.upper()})')
+    if ef.desc:
+        parts.append(f'\u2014 {ef.desc}')   # em-dash
+    title = ' '.join(parts)
+
+    lines = [f'.. rubric:: {title}\n\n']
+
+    # Only show a docstring if it is specific to this class.  EFs that are
+    # direct instances of a base type (TransparentEF, LinFixedEF, ...) carry
+    # only the generic "what is a TransparentEF" boilerplate; named subclasses
+    # without their own __doc__ have cls.__dict__['__doc__'] == None.  Either
+    # way, suppress the text here - it belongs at the document level, not
+    # repeated for every single EF entry.
+    doc = None if cls in _EF_BASE_TYPES else cls.__dict__.get('__doc__')
+    if doc:
+        lines.append(inspect.cleandoc(doc) + '\n\n')
+
+    examples = _examples_block(cls)
+    if examples:
+        lines.append(examples)
+
+    return ''.join(lines)
+
+
+def _document_df(df: CardDF, level: int) -> str:
+    """Return RST for a DF section and all its children, recursively."""
+    parts = [df.fully_qualified_path_str()]
+    if df.fid:
+        parts.append(f'({df.fid.upper()})')
+    if df.desc:
+        parts.append(f'\u2014 {df.desc}')   # em-dash
+    title = ' '.join(parts)
+
+    lines = [_heading(title, level)]
+
+    cls = type(df)
+    doc = None if cls in (CardDF, CardMF) else cls.__dict__.get('__doc__')
+    if doc:
+        lines.append(inspect.cleandoc(doc) + '\n\n')
+
+    for child in df.children.values():
+        if isinstance(child, CardDF):
+            lines.append(_document_df(child, level + 1))
+        elif isinstance(child, CardEF):
+            lines.append(_document_ef(child))
+
+    return ''.join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Top-level generator
+# ---------------------------------------------------------------------------
+
+def generate_filesystem_rst() -> str:
+    """Walk all registered sections and return the full RST document as a string."""
+    out = [
+        '.. This file is auto-generated by docs/pysim_fs_sphinx.py — do not edit.\n\n',
+        _heading('Card Filesystem Reference', 0),
+        'This page documents all Elementary Files (EFs) and Dedicated Files (DFs) '
+        'implemented in pySim, organised by their location in the card filesystem.\n\n',
+    ]
+
+    # Track already-documented classes so that DFs/EFs shared between profiles
+    # (e.g. DF.TELECOM / DF.GSM present in both CardProfileSIM and CardProfileRUIM)
+    # are only emitted once.
+    seen_types: set = set()
+
+    for section_title, module_path, class_name in SECTIONS:
+        module = importlib.import_module(module_path)
+        cls = getattr(module, class_name)
+        obj = cls()
+
+        if isinstance(obj, CardProfile):
+            files = obj.files_in_mf
+        elif isinstance(obj, CardApplication):
+            files = list(obj.adf.children.values())
+        elif isinstance(obj, CardDF):
+            files = list(obj.children.values())
+        else:
+            continue
+
+        # Filter out files whose class was already documented in an earlier section.
+        files = [f for f in files if type(f) not in seen_types]
+        if not files:
+            continue
+
+        out.append(_heading(section_title, 1))
+
+        for f in files:
+            seen_types.add(type(f))
+            if isinstance(f, CardDF):
+                out.append(_document_df(f, level=2))
+            elif isinstance(f, CardEF):
+                out.append(_document_ef(f))
+
+    return ''.join(out)
+
+
+# ---------------------------------------------------------------------------
+# Sphinx integration
+# ---------------------------------------------------------------------------
+
+def _on_builder_inited(app):
+    output_path = os.path.join(app.srcdir, 'filesystem.rst')
+    with open(output_path, 'w') as fh:
+        fh.write(generate_filesystem_rst())
+
+
+def setup(app):
+    app.connect('builder-inited', _on_builder_inited)
+    return {'version': '0.1', 'parallel_read_safe': True}

docs/remote-access.rst

@@ -0,0 +1,46 @@
+
+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

docs/saip-tool.rst

@@ -0,0 +1,137 @@
+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`
+
+
+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
+
+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
+::
+
+  # 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 application
+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 insertion 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, 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 parameter. 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 :ref:`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'...
+
+
+saip-tool syntax
+~~~~~~~~~~~~~~~~
+
+.. argparse::
+   :module: contrib.saip-tool
+   :func: parser
+   :prog: contrib/saip-tool.py

docs/shell.rst

@@ -1,4 +1,4 @@
-pySim-shell
+pySim-shell
 ===========
 
 pySim-shell is an interactive command line shell for all kind of interactions with SIM cards,
@@ -20,6 +20,9 @@ The pySim-shell interactive shell provides commands for
 
 * 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:
 
@@ -64,7 +67,17 @@ Usage Examples
    :caption: Tutorials for pySIM-shell:
 
    suci-tutorial
+   cap-tutorial
+   put_key-tutorial
 
+Advanced Topics
+---------------
+.. toctree::
+   :maxdepth: 1
+   :caption: Advanced pySIM-shell topics
+
+   card-key-provider
+   remote-access
 
 cmd2 basics
 -----------
@@ -133,6 +146,32 @@ optional files in some later 3GPP release) were not found on the card, or were i
 trying to SELECT them.
 
 
+fsdump
+~~~~~~
+.. argparse::
+   :module: pySim-shell
+   :func: PySimCommands.fsdump_parser
+
+Please note that `fsdump` works relative to the current working
+directory, so if you are in `MF`, then the dump will contain all known
+files on the card.  However, if you are in `ADF.ISIM`, only files below
+that ADF will be part of the dump.
+
+Furthermore, it is strongly advised to first enter the ADM1 pin
+(`verify_adm`) to maximize the chance of having permission to read
+all/most files.
+
+One use case for this is to systematically analyze the differences between the contents of two
+cards.  To do this, you can create fsdumps of the two cards, and then use some general-purpose JSON
+diffing tool like `jycm --show` (see https://github.com/eggachecat/jycm).
+
+Example:
+::
+
+  pySIM-shell (00:MF)> fsdump > /tmp/fsdump.json
+  pySIM-shell (00:MF)>
+
+
 tree
 ~~~~
 Display a tree of the card filesystem.  It is important to note that this displays a tree
@@ -473,7 +512,18 @@ sequence including the electrical power down.
    :module: pySim.ts_102_221
    :func: CardProfileUICC.AddlShellCommands.resume_uicc_parser
 
+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.
+
+.. argparse::
+   :module: pySim.ts_102_221
+   :func: CardProfileUICC.AddlShellCommands.term_cap_parser
 
 
 Linear Fixed EF commands
@@ -494,6 +544,9 @@ read_record_decoded
    :module: pySim.filesystem
    :func: LinFixedEF.ShellCommands.read_rec_dec_parser
 
+If this command fails, it means that the record is not decodable, and you should use the :ref:`read_record`
+command and proceed with manual decoding of the contents.
+
 
 read_records
 ~~~~~~~~~~~~
@@ -508,6 +561,9 @@ read_records_decoded
    :module: pySim.filesystem
    :func: LinFixedEF.ShellCommands.read_recs_dec_parser
 
+If this command fails, it means that the record[s] are not decodable, and you should use the :ref:`read_records`
+command and proceed with manual decoding of the contents.
+
 
 update_record
 ~~~~~~~~~~~~~
@@ -522,6 +578,9 @@ update_record_decoded
    :module: pySim.filesystem
    :func: LinFixedEF.ShellCommands.upd_rec_dec_parser
 
+If this command fails, it means that the record is not encodable; please check your input and/or use the raw
+:ref:`update_record` command.
+
 
 edit_record_decoded
 ~~~~~~~~~~~~~~~~~~~
@@ -540,6 +599,12 @@ 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 :ref:`update_record_decoded` or :ref:`update_record` command.
+
+If this command fails after making your modifications in the editor, it means that the new file contents is not
+encodable; please check your input and/or use the raw :ref:`update_record` command.
+
 
 decode_hex
 ~~~~~~~~~~
@@ -568,6 +633,8 @@ read_binary_decoded
    :module: pySim.filesystem
    :func: TransparentEF.ShellCommands.read_bin_dec_parser
 
+If this command fails, it means that the file is not decodable, and you should use the :ref:`read_binary`
+command and proceed with manual decoding of the contents.
 
 update_binary
 ~~~~~~~~~~~~~
@@ -621,6 +688,10 @@ The below example demonstrates this by modifying the ciphering indicator field w
       "extensions": "ff"
   }
 
+If this command fails, it means that the file is not encodable; please check your input and/or use the raw
+:ref:`update_binary` command.
+
+
 edit_binary_decoded
 ~~~~~~~~~~~~~~~~~~~
 This command will read the selected binary EF, decode it to its JSON representation, save
@@ -634,6 +705,12 @@ 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 :ref:`update_binary_decoded` or :ref:`update_binary` command.
+
+If this command fails after making your modifications in the editor, it means that the new file contents is not
+encodable; please check your input and/or use the raw :ref:`update_binary` command.
+
 
 decode_hex
 ~~~~~~~~~~
@@ -926,7 +1003,25 @@ 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`
+intended must be manually inserted again using :ref:`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.
 
 
 GlobalPlatform commands
@@ -947,6 +1042,12 @@ get_status
    :module: pySim.global_platform
    :func: ADF_SD.AddlShellCommands.get_status_parser
 
+set_status
+~~~~~~~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.set_status_parser
+
 store_data
 ~~~~~~~~~~
 .. argparse::
@@ -959,6 +1060,64 @@ put_key
    :module: pySim.global_platform
    :func: ADF_SD.AddlShellCommands.put_key_parser
 
+delete_key
+~~~~~~~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.del_key_parser
+
+load
+~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.load_parser
+
+install_cap
+~~~~~~~~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.install_cap_parser
+
+install_for_personalization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.inst_perso_parser
+
+install_for_install
+~~~~~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.inst_inst_parser
+
+install_for_load
+~~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.inst_load_parser
+
+delete_card_content
+~~~~~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.del_cc_parser
+
+establish_scp02
+~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.est_scp02_parser
+
+establish_scp03
+~~~~~~~~~~~~~~~
+.. argparse::
+   :module: pySim.global_platform
+   :func: ADF_SD.AddlShellCommands.est_scp03_parser
+
+release_scp
+~~~~~~~~~~~
+Release any previously established SCP (Secure Channel Protocol)
+
 
 eUICC ISD-R commands
 --------------------
@@ -996,7 +1155,7 @@ es10x_store_data
 
 .. argparse::
    :module: pySim.euicc
-   :func: ADF_ISDR.AddlShellCommands.es10x_store_data_parser
+   :func: CardApplicationISDR.AddlShellCommands.es10x_store_data_parser
 
 get_euicc_configured_addresses
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1015,7 +1174,7 @@ set_default_dp_address
 
 .. argparse::
    :module: pySim.euicc
-   :func: ADF_ISDR.AddlShellCommands.set_def_dp_addr_parser
+   :func: CardApplicationISDR.AddlShellCommands.set_def_dp_addr_parser
 
 get_euicc_challenge
 ~~~~~~~~~~~~~~~~~~~
@@ -1158,7 +1317,7 @@ remove_notification_from_list
 
 .. argparse::
    :module: pySim.euicc
-   :func: ADF_ISDR.AddlShellCommands.rem_notif_parser
+   :func: CardApplicationISDR.AddlShellCommands.rem_notif_parser
 
 Example::
 
@@ -1207,7 +1366,7 @@ enable_profile
 
 .. argparse::
    :module: pySim.euicc
-   :func: ADF_ISDR.AddlShellCommands.en_prof_parser
+   :func: CardApplicationISDR.AddlShellCommands.en_prof_parser
 
 Example (successful)::
 
@@ -1229,7 +1388,7 @@ disable_profile
 
 .. argparse::
    :module: pySim.euicc
-   :func: ADF_ISDR.AddlShellCommands.dis_prof_parser
+   :func: CardApplicationISDR.AddlShellCommands.dis_prof_parser
 
 Example (successful)::
 
@@ -1243,7 +1402,7 @@ delete_profile
 
 .. argparse::
    :module: pySim.euicc
-   :func: ADF_ISDR.AddlShellCommands.del_prof_parser
+   :func: CardApplicationISDR.AddlShellCommands.del_prof_parser
 
 Example::
 
@@ -1252,6 +1411,13 @@ Example::
       "delete_result": "ok"
   }
 
+euicc_memory_reset
+~~~~~~~~~~~~~~~~~~
+
+.. argparse::
+   :module: pySim.euicc
+   :func: CardApplicationISDR.AddlShellCommands.mem_res_parser
+
 
 get_eid
 ~~~~~~~
@@ -1270,7 +1436,7 @@ set_nickname
 
 .. argparse::
    :module: pySim.euicc
-   :func: ADF_ISDR.AddlShellCommands.set_nickname_parser
+   :func: CardApplicationISDR.AddlShellCommands.set_nickname_parser
 
 Example::
 

docs/sim-rest.rst

@@ -0,0 +1,118 @@
+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 approach 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.
+
+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
+
+#. a successful outcome; encoding RES, CK, IK as hex-encoded string
+#. a sync failure; encoding AUTS as hex-encoded string
+#. errors
+   #. authentication error (incorrect MAC)
+   #. authentication error (security context not supported)
+   #. key freshness failure
+   #. unspecified card error
+
+Example (success):
+::
+
+        {
+           "successful_3g_authentication": {
+                "res": "b15379540ec93985",
+                "ck": "713fde72c28cbd282a4cd4565f3d6381",
+                "ik": "2e641727c95781f1020d319a0594f31a",
+                "kc": "771a2c995172ac42"
+            }
+        }
+
+Example (re-sync case):
+::
+
+        {
+            "synchronisation_failure": {
+                "auts": "dc2a591fe072c92d7c46ecfe97e5"
+            }
+        }
+
+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'}}

docs/smpp-ota-tool.rst

@@ -0,0 +1,179 @@
+smpp-ota-tool
+=============
+
+The `smpp-ota-tool` allows users to send OTA SMS messages containing APDU scripts (RFM, RAM) via an SMPP server. The
+intended audience are developers who want to test/evaluate the OTA SMS interface of a SIM/UICC/eUICC. `smpp-ota-tool`
+is intended to be used as a companion tool for :ref:`pySim-smpp2sim`, however it should be usable on any other SMPP
+server (such as a production SMSC of a live cellular network) as well.
+
+From the technical perspective `smpp-ota-tool` takes the role of an SMPP ESME. It takes care of the encoding, encryption
+and checksumming (signing) of the RFM/RAM OTA SMS and eventually submits it to the SMPP server. The program then waits
+for a response. The response is automatically parsed and printed on stdout. This makes the program also suitable to be
+called from shell scripts.
+
+.. note:: In the following we will we will refer to `SIM` as one of the following: `SIM`, `USIM`, `ISIM`, `UICC`,
+	  `eUICC`, `eSIM`.
+
+Applying OTA keys
+~~~~~~~~~~~~~~~~~
+
+Depending on the `SIM` type you will receive one or more sets of keys which you can use to communicate with the `SIM`
+through a secure channel protocol. When using the OTA SMS method, the SCP80 protocol is used and it therefore crucial
+to use a keyset that is actually suitable for SCP80.
+
+A keyset usually consists of three keys:
+
+#. KIC: the key used for ciphering (encryption/decryption)
+#. KID: the key used to compute a cryptographic checksum (signing)
+#. KIK: the key used to encrypt/decrypt key material (key rotation, adding of new keys)
+
+From the transport security perspective, only KIC and KID are relevant. The KIK (also referenced as "Data Encryption
+Key", DEK) is only used when keys are rotated or new keys are added (see also ETSI TS 102 226, section 8.2.1.5).
+
+When the keyset is programmed into the security domain of the `SIM`, it is tied to a specific cryptographic algorithm
+(3DES, AES128 or AES256) and a so called Key Version Number (KVN). The term "Key Version Number" is misleading, since
+it is actually not a version number. It is a unique identifier of a certain keyset which also identifies for which
+secure channel protocol the keyset may be used. Keysets with a KVN from 1-15 (``0x01``-``0x0F``) are suitable for SCP80.
+This means that it is not only important to know just the KIC/KID/KIK keys. Also the related algorithms and the KVN
+numbers must be known.
+
+.. note:: SCP80 keysets typically start counting from 1 upwards. Typical configurations use a set of 3 keysets with
+	  KVN numbers 1-3.
+
+Addressing an Application
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When communicating with a specific application on a `SIM` via SCP80, it is important to address that application with
+the correct parameters. The following two parameters must be known in advance:
+
+#. TAR: The Toolkit Application Reference (TAR) number is a three byte value that uniquely addresses an application
+   on the `SIM`. The exact values may vary (see also ETSI TS 101 220, Table D.1).
+#. MSL: The Minimum Security Level (MSL) is a bit-field that dictates which of the security measures encoded in the
+   SPI are mandatory (see also ETSI TS 102 225, section 5.1.1).
+
+A practical example
+~~~~~~~~~~~~~~~~~~~
+
+.. note:: This tutorial assumes that pySim-smpp2sim is running on the local machine with its default parameters.
+	  See also :ref:`pySim-smpp2sim`.
+
+Let's assume that an OTA SMS shall be sent to the SIM RFM application of an sysmoISIM-SJA2. What we want to do is to
+select DF.GSM and to get the select response back.
+
+We have received the following key material from the `SIM` vendor:
+
+::
+
+   KIC1: F09C43EE1A0391665CC9F05AF4E0BD10
+   KID1: 01981F4A20999F62AF99988007BAF6CA
+   KIK1: 8F8AEE5CDCC5D361368BC45673D99195
+   KIC2: 01022916E945B656FDE03F806A105FA2
+   KID2: D326CB69F160333CC5BD1495D448EFD6
+   KIK2: 08037E0590DFE049D4975FFB8652F625
+   KIC3: 2B22824D0D27A3A1CEEC512B312082B4
+   KID3: F1697766925A11F4458295590137B672
+   KIK3: C7EE69B2C5A1C8E160DD36A38EB517B3
+
+Those are three keysets. The enumeration is directly equal to the KVN used. All three keysets are 3DES keys, which
+means triple_des_cbc2 is the correct algorithm to use.
+
+.. note:: The key set configuration can be confirmed by retrieving the key configuration using
+	  `get_data key_information` from within an SCP02 session on ADF.ISD.
+
+In this example we intend to address the SIM RFM application on the `SIM`. Which according to the manual has TAR ``B00010``
+and MSL ``0x06``. When we hold ``0x06`` = ``0b00000110`` against the SPI coding chart (see also ETSI TS 102 225,
+section 5.1.1). We can deduct that Ciphering and Cryptographic Checksum are mandatory.
+
+.. note:: The MSL (see also ETSI TS 102 226, section 6.1) is assigned to an application by the `SIM` issuer. It is a
+	  custom decision and may vary with different `SIM` types/profiles. In the case of sysmoISIM-SJS1/SJA2/SJA5 the
+	  counter requirement has been waived to simplify lab/research type use. In productive environments, `SIM`
+	  applications should ideally use an MSL that makes the counter mandatory.
+
+In order to select DF.GSM (``0x7F20``) and to retrieve the select response, two APDUs are needed. The first APDU is the
+select command ``A0A40000027F20`` and the second is the related get-response command ``A0C0000016``. Those APDUs will be
+concatenated and are sent in a single message. The message containing the concatenated APDUs works as a script that
+is received by the SIM RFM application and then executed. This method poses some limitations that have to be taken into
+account when making requests like this (see also ETSI TS 102 226, section 5).
+
+With this information we may now construct a commandline for `smpp-ota-tool.py`. We will pass the KVN as kid_idx and
+kic_idx (see also ETSI TS 102 225, Table 2, fields `KIc` and `KID`). Both index values should refer to the same
+keyset/KVN as keysets should not be mixed. (`smpp-ota-tool` still provides separate parameters anyway to allow testing
+with invalid keyset combinations)
+
+::
+
+   $ PYTHONPATH=./ ./contrib/smpp-ota-tool.py --kic F09C43EE1A0391665CC9F05AF4E0BD10 --kid 01981F4A20999F62AF99988107BAF6CA --kid_idx 1 --kic_idx 1 --algo-crypt triple_des_cbc2 --algo-auth triple_des_cbc2 --tar B00010 --apdu A0A40000027F20 --apdu A0C0000016
+   2026-02-26 17:13:56 INFO Connecting to localhost:2775...
+   2026-02-26 17:13:56 INFO C-APDU sending: a0a40000027f20a0c0000016...
+   2026-02-26 17:13:56 INFO SMS-TPDU sending: 02700000281506191515b00010da1d6cbbd0d11ce4330d844c7408340943e843f67a6d7b0674730881605fd62d...
+   2026-02-26 17:13:56 INFO SMS-TPDU sent, waiting for response...
+   2026-02-26 17:13:56 INFO SMS-TPDU received: 027100002c12b000107ddf58d1780f771638b3975759f4296cf5c31efc87a16a1b61921426baa16da1b5ba1a9951d59a39
+   2026-02-26 17:13:56 INFO SMS-TPDU decoded: (Container(rpl=44, rhl=18, tar=b'\xb0\x00\x10', cntr=b'\x00\x00\x00\x00\x00', pcntr=0, response_status=uEnumIntegerString.new(0, 'por_ok'), cc_rc=b'\x8f\xea\xf5.\xf4\x0e\xc2\x14', secured_data=b'\x02\x90\x00\x00\x00\xff\xff\x7f \x02\x00\x00\x00\x00\x00\t\xb1\x065\x04\x00\x83\x8a\x83\x8a'), Container(number_of_commands=2, last_status_word=u'9000', last_response_data=u'0000ffff7f2002000000000009b106350400838a838a'))
+   2026-02-26 17:13:56 INFO R-APDU received: 0000ffff7f2002000000000009b106350400838a838a 9000
+   0000ffff7f2002000000000009b106350400838a838a 9000
+   2026-02-26 17:13:56 INFO Disconnecting...
+
+The result we see is the select response of DF.GSM and a status word indicating that the last command has been
+processed normally.
+
+As we can see, this mechanism now allows us to perform small administrative tasks remotely. We can read the contents of
+files remotely or make changes to files. Depending on the changes we make, there may be security issues arising from
+replay attacks. With the commandline above, the communication is encrypted and protected by a cryptographic checksum,
+so an adversary can neither read, nor alter the message. However, an adversary could still replay an intercepted
+message and the `SIM` would happily execute the contained APDUs again.
+
+To prevent this, we may include a replay protection counter within the message. In this case, the MSL indicates that a
+replay protection counter is not required. However, to extended the security of our messages, we may chose to use a
+counter anyway. In the following example, we will encode a counter value of 100. We will instruct the `SIM` to make sure
+that the value we send is higher than the counter value that is currently stored in the `SIM`.
+
+To add a replay connection counter we add the commandline arguments `--cntr-req` to set the counter requirement and
+`--cntr` to pass the counter value.
+
+::
+
+   $ PYTHONPATH=./ ./contrib/smpp-ota-tool.py --kic F09C43EE1A0391665CC9F05AF4E0BD10 --kid 01981F4A20999F62AF99988107BAF6CA --kid_idx 1 --kic_idx 1 --algo-crypt triple_des_cbc2 --algo-auth triple_des_cbc2 --tar B00010 --apdu A0A40000027F20 --apdu A0C0000016 --cntr-req counter_must_be_higher --cntr 100
+   2026-02-26 17:16:39 INFO Connecting to localhost:2775...
+   2026-02-26 17:16:39 INFO C-APDU sending: a0a40000027f20a0c0000016...
+   2026-02-26 17:16:39 INFO SMS-TPDU sending: 02700000281516191515b000103a4f599e94f2b5dcfbbda984761b7977df6514c57a580fb4844787c436d2eade...
+   2026-02-26 17:16:39 INFO SMS-TPDU sent, waiting for response...
+   2026-02-26 17:16:39 INFO SMS-TPDU received: 027100002c12b0001049fb0315f6c6401b553867f412cefaf9355b38271178edb342a3bc9cc7e670cdc1f45eea6ffcbb39
+   2026-02-26 17:16:39 INFO SMS-TPDU decoded: (Container(rpl=44, rhl=18, tar=b'\xb0\x00\x10', cntr=b'\x00\x00\x00\x00d', pcntr=0, response_status=uEnumIntegerString.new(0, 'por_ok'), cc_rc=b'\xa9/\xc7\xc9\x00"\xab5', secured_data=b'\x02\x90\x00\x00\x00\xff\xff\x7f \x02\x00\x00\x00\x00\x00\t\xb1\x065\x04\x00\x83\x8a\x83\x8a'), Container(number_of_commands=2, last_status_word=u'9000', last_response_data=u'0000ffff7f2002000000000009b106350400838a838a'))
+   2026-02-26 17:16:39 INFO R-APDU received: 0000ffff7f2002000000000009b106350400838a838a 9000
+   0000ffff7f2002000000000009b106350400838a838a 9000
+   2026-02-26 17:16:39 INFO Disconnecting...
+
+The `SIM` has accepted the message. The message got processed and the `SIM` has set its internal to 100. As an experiment,
+we may try to re-use the counter value:
+
+::
+
+   $ PYTHONPATH=./ ./contrib/smpp-ota-tool.py --kic F09C43EE1A0391665CC9F05AF4E0BD10 --kid 01981F4A20999F62AF99988107BAF6CA --kid_idx 1 --kic_idx 1 --algo-crypt triple_des_cbc2 --algo-auth triple_des_cbc2 --tar B00010 --apdu A0A40000027F20 --apdu A0C0000016 --cntr-req counter_must_be_higher --cntr 100
+   2026-02-26 17:16:43 INFO Connecting to localhost:2775...
+   2026-02-26 17:16:43 INFO C-APDU sending: a0a40000027f20a0c0000016...
+   2026-02-26 17:16:43 INFO SMS-TPDU sending: 02700000281516191515b000103a4f599e94f2b5dcfbbda984761b7977df6514c57a580fb4844787c436d2eade...
+   2026-02-26 17:16:43 INFO SMS-TPDU sent, waiting for response...
+   2026-02-26 17:16:43 INFO SMS-TPDU received: 027100000b0ab0001000000000000006
+   2026-02-26 17:16:43 INFO SMS-TPDU decoded: (Container(rpl=11, rhl=10, tar=b'\xb0\x00\x10', cntr=b'\x00\x00\x00\x00\x00', pcntr=0, response_status=uEnumIntegerString.new(6, 'undefined_security_error'), cc_rc=b'', secured_data=b''), None)
+   Traceback (most recent call last):
+   File "/home/user/work/git_master/pysim/./contrib/smpp-ota-tool.py", line 238, in <module>
+    resp, sw = smpp_handler.transceive_apdu(apdu, opts.src_addr, opts.dest_addr, opts.timeout)
+               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   File "/home/user/work/git_master/pysim/./contrib/smpp-ota-tool.py", line 162, in transceive_apdu
+     raise ValueError("Response does not contain any last_response_data, no R-APDU received!")
+   ValueError: Response does not contain any last_response_data, no R-APDU received!
+   2026-02-26 17:16:43 INFO Disconnecting...
+
+As we can see, the `SIM` has rejected the message with an `undefined_security_error`. The replay-protection-counter
+ensures that a message can only be sent once.
+
+.. note:: The replay-protection-counter is implemented as a 5 byte integer value (see also ETSI TS 102 225, Table 3).
+	  When the counter has reached its maximum, it will not overflow nor can it be reset.
+
+smpp-ota-tool syntax
+~~~~~~~~~~~~~~~~~~~~
+
+.. argparse::
+   :module: contrib.smpp-ota-tool
+   :func: option_parser
+   :prog: contrib/smpp-ota-tool.py

docs/smpp2sim.rst

@@ -0,0 +1,59 @@
+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`
+
+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:
+
+.. argparse::
+   :module: pySim-smpp2sim
+   :func: option_parser
+   :prog: pySim-smpp2sim.py
+
+
+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:
+::
+
+  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': '400290217ff6227052000000002d02700000281516191212b0000127fa28a5bac69d3c5e9df2c7155dfdde449c826b236215566530787b30e8be5d'}))
+  INFO     root: ENVELOPE: d147820283818604001032548b3b400290217ff6227052000000002d02700000281516191212b0000127fa28a5bac69d3c5e9df2c7155dfdde449c826b236215566530787b30e8be5d
+  INFO     root: SW 9000: 027100002412b000019a551bb7c28183652de0ace6170d0e563c5e949a3ba56747fe4c1dbbef16642c
+
+.. note:: for sending OTA SMS messages :ref:`smpp-ota-tool` may be used.

docs/suci-keytool.rst

@@ -0,0 +1,58 @@
+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.
+
+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
+
+#. generate a ECC key pair of public + private key
+#. deploy the public key on your USIMs
+#. deploy the private key on your 5GC, specifically the UDM function
+
+pysim contains (in its `contrib` directory) a small utility program that can make it easy to generate
+such keys: `suci-keytool.py`
+
+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
+
+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
+        0473152f32523725f5175d255da2bd909de97b1d06449a9277bc629fe42112f8643e6b69aa6dce6c86714ccbe6f2e0f4f4898d102e2b3f0c18ce26626f052539bb
+
+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
+
+
+
+suci-keytool syntax
+~~~~~~~~~~~~~~~~~~~
+
+.. argparse::
+   :module: contrib.suci-keytool
+   :func: arg_parser
+   :prog: contrib/suci-keytool.py

docs/suci-tutorial.rst

@@ -1,40 +1,56 @@
 
 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 data from the SIM
+* 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 cards (or successor products).
+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.
 
-In short, you can enable SUCI with these steps:
+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).
 
-* activate USIM **Service 124**
-* make sure USIM **Service 125** is disabled
-* store the public keys in **SUCI_Calc_Info**
-* set the **Routing Indicator** (required)
+This document describes both methods.
 
-If you want to disable the feature, you can just disable USIM Service 124 (and 125).
 
 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: `TS 31.102 <https://www.etsi.org/deliver/etsi_ts/131100_131199/131102/16.06.00_60/ts_131102v160600p.pdf>`__
-* USIM tests (incl. file content examples) `TS 31.121 <https://www.etsi.org/deliver/etsi_ts/131100_131199/131121/16.01.00_60/ts_131121v160100p.pdf>`__
+* USIM files and structure: `3GPP TS 31.102 <https://www.etsi.org/deliver/etsi_ts/131100_131199/131102/16.06.00_60/ts_131102v160600p.pdf>`__
+* USIM tests (incl. file content examples): `3GPP TS 31.121 <https://www.etsi.org/deliver/etsi_ts/131100_131199/131121/16.01.00_60/ts_131121v160100p.pdf>`__
+* Test keys for SUCI calculation: `3GPP TS 33.501 <https://www.etsi.org/deliver/etsi_ts/133500_133599/133501/16.05.00_60/ts_133501v160500p.pdf>`__
 
-For specific information on sysmocom SIM cards, refer to Section 9.1 of the `sysmoUSIM User
-Manual <https://www.sysmocom.de/manuals/sysmousim-manual.pdf>`__.
+For specific information on sysmocom SIM cards, refer to
+
+* the `sysmoISIM-SJA5 User Manual <https://sysmocom.de/manuals/sysmoisim-sja5-manual.pdf>`__ for the current
+  sysmoISIM-SJA5 product
+* the `sysmoISIM-SJA2 User Manual <https://sysmocom.de/manuals/sysmousim-manual.pdf>`__ for the older
+  sysmoISIM-SJA2 product
 
 --------------
 
+
+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
 ---------
 
@@ -83,8 +99,8 @@ By default, the file is present but empty:
    missing Protection Scheme Identifier List data object tag
    9000: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff -> {}
 
-The following JSON config defines the testfile from `TS 31.121 <https://www.etsi.org/deliver/etsi_ts/131100_131199/131121/16.01.00_60/ts_131121v160100p.pdf>`__ Section 4.9.4 with
-test keys from `TS 33.501 <hhttps://www.etsi.org/deliver/etsi_ts/133500_133599/133501/16.05.00_60/ts_133501v160500p.pdf>`__ Annex C.4. Highest priority (``0``) has a
+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``.
 
@@ -97,7 +113,7 @@ with ``hnet_pubkey_identifier: 27``.
            {"priority": 2, "identifier": 0, "key_index": 0}],
         "hnet_pubkey_list": [
            {"hnet_pubkey_identifier": 27,
-            "hnet_pubkey": "0272DA71976234CE833A6907425867B82E074D44EF907DFB4B3E21C1C2256EBCD1"},
+            "hnet_pubkey": "0472DA71976234CE833A6907425867B82E074D44EF907DFB4B3E21C1C2256EBCD15A7DED52FCBB097A4ED250E036C7B9C8C7004C4EEDC4F068CD7BF8D3F900E3B4"},
            {"hnet_pubkey_identifier": 30,
             "hnet_pubkey": "5A8D38864820197C3394B92613B20B91633CBD897119273BF8E4A6F4EEC0A650"}]
    }
@@ -106,7 +122,7 @@ 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": "0272DA71976234CE833A6907425867B82E074D44EF907DFB4B3E21C1C2256EBCD1"}, {"hnet_pubkey_identifier": 30, "hnet_pubkey": "5A8D38864820197C3394B92613B20B91633CBD897119273BF8E4A6F4EEC0A650"}]}'
+   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": "0472DA71976234CE833A6907425867B82E074D44EF907DFB4B3E21C1C2256EBCD15A7DED52FCBB097A4ED250E036C7B9C8C7004C4EEDC4F068CD7BF8D3F900E3B4"}, {"hnet_pubkey_identifier": 30, "hnet_pubkey": "5A8D38864820197C3394B92613B20B91633CBD897119273BF8E4A6F4EEC0A650"}]}'
 
 WARNING: These are TEST KEYS with publicly known/specified private keys, and hence unsafe for live/secure
 deployments! For use in production networks, you need to generate your own set[s] of keys.
@@ -150,7 +166,7 @@ First, check out the USIM Service Table (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]
 
-.. list-table:: From TS31.102
+.. list-table:: From 3GPP TS 31.102
    :widths: 15 40
    :header-rows: 1
 
@@ -184,7 +200,7 @@ be disabled.
 USIM Error with 5G and sysmoISIM
 --------------------------------
 
-sysmoISIMs come 5GS-enabled. By default however, the configuration stored
+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).
@@ -193,3 +209,62 @@ 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`!).
+
+::
+
+   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: 0199f90717ff021b027a2c58ce1c6b89df088a9eb4d242596dd75746bb5f3503d2cf58a7461e4fd106e205c86f76544e9d732226a4e1

osmo-smdpp.py

@@ -17,27 +17,124 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-import json
-import sys
-import argparse
-import uuid
-import os
-import functools
-from typing import Optional, Dict, List
-from pprint import pprint as pp
-
-import base64
-from base64 import b64decode
-from klein import Klein
-from twisted.web.iweb import IRequest
+# asn1tools issue https://github.com/eerimoq/asn1tools/issues/194
+# must be first here
 import asn1tools
+import asn1tools.codecs.ber
+import asn1tools.codecs.der
+# do not move the code
+def fix_asn1_oid_decoding():
+    fix_asn1_schema = """
+    TestModule DEFINITIONS ::= BEGIN
+        TestOid ::= SEQUENCE {
+            oid OBJECT IDENTIFIER
+        }
+    END
+    """
 
-from pySim.utils import h2b, b2h, swap_nibbles
+    fix_asn1_asn1 = asn1tools.compile_string(fix_asn1_schema, codec='der')
+    fix_asn1_oid_string = '2.999.10'
+    fix_asn1_encoded = fix_asn1_asn1.encode('TestOid', {'oid': fix_asn1_oid_string})
+    fix_asn1_decoded = fix_asn1_asn1.decode('TestOid', fix_asn1_encoded)
 
-import pySim.esim.rsp as rsp
-from pySim.esim.es8p import *
-from pySim.esim.x509_cert import oid, cert_policy_has_oid, cert_get_auth_key_id
-from pySim.esim.x509_cert import CertAndPrivkey, CertificateSet, cert_get_subject_key_id, VerifyError
+    if (fix_asn1_decoded['oid'] != fix_asn1_oid_string):
+        # ASN.1 OBJECT IDENTIFIER Decoding Issue:
+        #
+        # In ASN.1 BER/DER encoding, the first two arcs of an OBJECT IDENTIFIER are
+        # combined into a single value: (40 * arc0) + arc1. This is encoded as a base-128
+        # variable-length quantity (and commonly known as VLQ or base-128 encoding)
+        # as specified in ITU-T X.690 §8.19, it can span multiple bytes if
+        # the value is large.
+        #
+        # For arc0 = 0 or 1, arc1 must be in [0, 39]. For arc0 = 2, arc1 can be any non-negative integer.
+        # All subsequent arcs (arc2, arc3, ...) are each encoded as a separate base-128 VLQ.
+        #
+        # The decoding bug occurs when the decoder does not properly split the first
+        # subidentifier for arc0 = 2 and arc1 >= 40. Instead of decoding:
+        #   - arc0 = 2
+        #   - arc1 = (first_subidentifier - 80)
+        # it may incorrectly interpret the first_subidentifier as arc0 = (first_subidentifier // 40),
+        # arc1 = (first_subidentifier % 40), which is only valid for arc1 < 40.
+        #
+        # This patch handles it properly for all valid OBJECT IDENTIFIERs
+        # with large second arcs, by applying the ASN.1 rules:
+        #   - if first_subidentifier < 40: arc0 = 0, arc1 = first_subidentifier
+        #   - elif first_subidentifier < 80: arc0 = 1, arc1 = first_subidentifier - 40
+        #   - else: arc0 = 2, arc1 = first_subidentifier - 80
+        #
+        # This problem is not uncommon, see for example https://github.com/randombit/botan/issues/4023
+
+        def fixed_decode_object_identifier(data, offset, end_offset):
+            """Decode ASN.1 OBJECT IDENTIFIER from bytes to dotted string, fixing large second arc handling."""
+            def read_subidentifier(data, offset):
+                value = 0
+                while True:
+                    b = data[offset]
+                    value = (value << 7) | (b & 0x7F)
+                    offset += 1
+                    if not (b & 0x80):
+                        break
+                return value, offset
+
+            subid, offset = read_subidentifier(data, offset)
+            if subid < 40:
+                first = 0
+                second = subid
+            elif subid < 80:
+                first = 1
+                second = subid - 40
+            else:
+                first = 2
+                second = subid - 80
+            arcs = [first, second]
+
+            while offset < end_offset:
+                subid, offset = read_subidentifier(data, offset)
+                arcs.append(subid)
+
+            return '.'.join(str(x) for x in arcs)
+
+        asn1tools.codecs.ber.decode_object_identifier = fixed_decode_object_identifier
+        asn1tools.codecs.der.decode_object_identifier = fixed_decode_object_identifier
+
+        # test our patch
+        asn1 = asn1tools.compile_string(fix_asn1_schema, codec='der')
+        decoded = asn1.decode('TestOid', fix_asn1_encoded)['oid']
+        assert fix_asn1_oid_string == str(decoded)
+
+fix_asn1_oid_decoding()
+
+from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature # noqa: E402
+from cryptography import x509 # noqa: E402
+from cryptography.exceptions import InvalidSignature # noqa: E402
+from cryptography.hazmat.primitives import hashes # noqa: E402
+from cryptography.hazmat.primitives.asymmetric import ec, dh # noqa: E402
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat, PrivateFormat, NoEncryption, ParameterFormat # noqa: E402
+from pathlib import Path # noqa: E402
+import json # noqa: E402
+import sys # noqa: E402
+import argparse # noqa: E402
+import uuid # noqa: E402
+import os # noqa: E402
+import functools # noqa: E402
+from typing import Optional, Dict, List # noqa: E402
+from pprint import pprint as pp # noqa: E402
+
+import base64 # noqa: E402
+from base64 import b64decode # noqa: E402
+from klein import Klein # noqa: E402
+from twisted.web.iweb import IRequest # noqa: E402
+
+from osmocom.utils import h2b, b2h, swap_nibbles # noqa: E402
+
+import pySim.esim.rsp as rsp # noqa: E402
+from pySim.esim import saip, PMO # noqa: E402
+from pySim.esim.es8p import ProfileMetadata,UnprotectedProfilePackage,ProtectedProfilePackage,BoundProfilePackage,BspInstance # noqa: E402
+from pySim.esim.x509_cert import oid, cert_policy_has_oid, cert_get_auth_key_id # noqa: E402
+from pySim.esim.x509_cert import CertAndPrivkey, CertificateSet, cert_get_subject_key_id, VerifyError # noqa: E402
+
+import logging # noqa: E402
+logger = logging.getLogger(__name__)
 
 # HACK: make this configurable
 DATA_DIR = './smdpp-data'
@@ -53,6 +150,173 @@ def set_headers(request: IRequest):
     request.setHeader('Content-Type', 'application/json;charset=UTF-8')
     request.setHeader('X-Admin-Protocol', 'gsma/rsp/v2.1.0')
 
+def validate_request_headers(request: IRequest):
+    """Validate mandatory HTTP headers according to SGP.22."""
+    content_type = request.getHeader('Content-Type')
+    if not content_type or not content_type.startswith('application/json'):
+        raise ApiError('1.2.1', '2.1', 'Invalid Content-Type header')
+
+    admin_protocol = request.getHeader('X-Admin-Protocol')
+    if admin_protocol and not admin_protocol.startswith('gsma/rsp/v'):
+        raise ApiError('1.2.2', '2.1', 'Unsupported X-Admin-Protocol version')
+
+def get_eum_certificate_variant(eum_cert) -> str:
+    """Determine EUM certificate variant by checking Certificate Policies extension.
+    Returns 'O' for old variant, or 'NEW' for Ov3/A/B/C variants."""
+
+    try:
+        cert_policies_ext = eum_cert.extensions.get_extension_for_oid(
+            x509.oid.ExtensionOID.CERTIFICATE_POLICIES
+        )
+
+        for policy in cert_policies_ext.value:
+            policy_oid = policy.policy_identifier.dotted_string
+            logger.debug(f"Found certificate policy: {policy_oid}")
+
+            if policy_oid == '2.23.146.1.2.1.2':
+                logger.debug("Detected EUM certificate variant: O (old)")
+                return 'O'
+            elif policy_oid == '2.23.146.1.2.1.0.0.0':
+                logger.debug("Detected EUM certificate variant: Ov3/A/B/C (new)")
+                return 'NEW'
+    except x509.ExtensionNotFound:
+        logger.debug("No Certificate Policies extension found")
+    except Exception as e:
+        logger.debug(f"Error checking certificate policies: {e}")
+
+def parse_permitted_eins_from_cert(eum_cert) -> List[str]:
+    """Extract permitted IINs from EUM certificate using the appropriate method
+    based on certificate variant (O vs Ov3/A/B/C).
+    Returns list of permitted IINs (basically prefixes that valid EIDs must start with)."""
+
+    # Determine certificate variant first
+    cert_variant = get_eum_certificate_variant(eum_cert)
+    permitted_iins = []
+
+    if cert_variant == 'O':
+        # Old variant - use nameConstraints extension
+        permitted_iins.extend(_parse_name_constraints_eins(eum_cert))
+
+    else:
+        # New variants (Ov3, A, B, C) - use GSMA permittedEins extension
+        permitted_iins.extend(_parse_gsma_permitted_eins(eum_cert))
+
+    unique_iins = list(set(permitted_iins))
+
+    logger.debug(f"Total unique permitted IINs found: {len(unique_iins)}")
+    return unique_iins
+
+def _parse_gsma_permitted_eins(eum_cert) -> List[str]:
+    """Parse the GSMA permittedEins extension using correct ASN.1 structure.
+    PermittedEins ::= SEQUENCE OF PrintableString
+    Each string contains an IIN (Issuer Identification Number) - a prefix of valid EIDs."""
+    permitted_iins = []
+
+    try:
+        permitted_eins_oid = x509.ObjectIdentifier('2.23.146.1.2.2.0')  # sgp26: 2.23.146.1.2.2.0 = ASN1:SEQUENCE:permittedEins
+
+        for ext in eum_cert.extensions:
+            if ext.oid == permitted_eins_oid:
+                logger.debug(f"Found GSMA permittedEins extension: {ext.oid}")
+
+                # Get the DER-encoded extension value
+                ext_der = ext.value.value if hasattr(ext.value, 'value') else ext.value
+
+                if isinstance(ext_der, bytes):
+                    try:
+                        permitted_eins_schema = """
+                        PermittedEins DEFINITIONS ::= BEGIN
+                            PermittedEins ::= SEQUENCE OF PrintableString
+                        END
+                        """
+                        decoder = asn1tools.compile_string(permitted_eins_schema)
+                        decoded_strings = decoder.decode('PermittedEins', ext_der)
+
+                        for iin_string in decoded_strings:
+                            # Each string contains an IIN -> prefix of euicc EID
+                            iin_clean = iin_string.strip().upper()
+
+                            # IINs is 8 chars per sgp22, var len according to sgp29, fortunately we don't care
+                            if (len(iin_clean) == 8 and
+                                all(c in '0123456789ABCDEF' for c in iin_clean) and
+                                    len(iin_clean) % 2 == 0):
+                                permitted_iins.append(iin_clean)
+                                logger.debug(f"Found permitted IIN (GSMA): {iin_clean}")
+                            else:
+                                logger.debug(f"Invalid IIN format: {iin_string} (cleaned: {iin_clean})")
+                    except Exception as e:
+                        logger.debug(f"Error parsing GSMA permittedEins extension: {e}")
+
+    except Exception as e:
+        logger.debug(f"Error accessing GSMA certificate extensions: {e}")
+
+    return permitted_iins
+
+
+def _parse_name_constraints_eins(eum_cert) -> List[str]:
+    """Parse permitted IINs from nameConstraints extension (variant O)."""
+    permitted_iins = []
+
+    try:
+        # Look for nameConstraints extension
+        name_constraints_ext = eum_cert.extensions.get_extension_for_oid(
+            x509.oid.ExtensionOID.NAME_CONSTRAINTS
+        )
+
+        name_constraints = name_constraints_ext.value
+
+        # Check permittedSubtrees for IIN constraints
+        if name_constraints.permitted_subtrees:
+            for subtree in name_constraints.permitted_subtrees:
+
+                if isinstance(subtree, x509.DirectoryName):
+                    for attribute in subtree.value:
+                        # IINs for O in serialNumber
+                        if attribute.oid == x509.oid.NameOID.SERIAL_NUMBER:
+                            serial_value = attribute.value.upper()
+                            # sgp22 8, sgp29 var len, fortunately we don't care
+                            if (len(serial_value) == 8 and
+                                all(c in '0123456789ABCDEF' for c in serial_value) and
+                                    len(serial_value) % 2 == 0):
+                                permitted_iins.append(serial_value)
+                                logger.debug(f"Found permitted IIN (nameConstraints/DN): {serial_value}")
+
+    except x509.ExtensionNotFound:
+        logger.debug("No nameConstraints extension found")
+    except Exception as e:
+        logger.debug(f"Error parsing nameConstraints: {e}")
+
+    return permitted_iins
+
+
+def validate_eid_range(eid: str, eum_cert) -> bool:
+    """Validate that EID is within the permitted EINs of the EUM certificate."""
+    if not eid or len(eid) != 32:
+        logger.debug(f"Invalid EID format: {eid}")
+        return False
+
+    try:
+        permitted_eins = parse_permitted_eins_from_cert(eum_cert)
+
+        if not permitted_eins:
+            logger.debug("Warning: No permitted EINs found in EUM certificate")
+            return False
+
+        eid_normalized = eid.upper()
+        logger.debug(f"Validating EID {eid_normalized} against {len(permitted_eins)} permitted EINs")
+
+        for permitted_ein in permitted_eins:
+                if eid_normalized.startswith(permitted_ein):
+                    logger.debug(f"EID {eid_normalized} matches permitted EIN {permitted_ein}")
+                    return True
+
+        logger.debug(f"EID {eid_normalized} is not in any permitted EIN list")
+        return False
+
+    except Exception as e:
+        logger.debug(f"Error validating EID: {e}")
+        return False
+
 def build_status_code(subject_code: str, reason_code: str, subject_id: Optional[str], message: Optional[str]) -> Dict:
     r = {'subjectCode': subject_code, 'reasonCode': reason_code }
     if subject_id:
@@ -71,12 +335,6 @@ def build_resp_header(js: dict, status: str = 'Executed-Success', status_code_da
     if status_code_data:
         js['header']['functionExecutionStatus']['statusCodeData'] = status_code_data
 
-from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature, encode_dss_signature
-from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat, PrivateFormat, NoEncryption
-from cryptography.hazmat.primitives.asymmetric import ec
-from cryptography.hazmat.primitives import hashes
-from cryptography.exceptions import InvalidSignature
-from cryptography import x509
 
 def ecdsa_tr03111_to_dss(sig: bytes) -> bytes:
     """convert an ECDSA signature from BSI TR-03111 format to DER: first get long integers; then encode those."""
@@ -124,22 +382,36 @@ class SmDppHttpServer:
     def ci_get_cert_for_pkid(self, ci_pkid: bytes) -> Optional[x509.Certificate]:
         """Find CI certificate for given key identifier."""
         for cert in self.ci_certs:
-            print("cert: %s" % cert)
+            logger.debug("cert: %s" % cert)
             subject_exts = list(filter(lambda x: isinstance(x.value, x509.SubjectKeyIdentifier), cert.extensions))
-            print(subject_exts)
+            logger.debug(subject_exts)
             subject_pkid = subject_exts[0].value
-            print(subject_pkid)
+            logger.debug(subject_pkid)
             if subject_pkid and subject_pkid.key_identifier == ci_pkid:
                 return cert
         return None
 
-    def __init__(self, server_hostname: str, ci_certs_path: str, use_brainpool: bool = False):
+    def validate_certificate_chain_for_verification(self, euicc_ci_pkid_list: List[bytes]) -> bool:
+        """Validate that SM-DP+ has valid certificate chains for the given CI PKIDs."""
+        for ci_pkid in euicc_ci_pkid_list:
+            ci_cert = self.ci_get_cert_for_pkid(ci_pkid)
+            if ci_cert:
+                # Check if our DPauth certificate chains to this CI
+                try:
+                    cs = CertificateSet(ci_cert)
+                    cs.verify_cert_chain(self.dp_auth.cert)
+                    return True
+                except VerifyError:
+                    continue
+        return False
+
+    def __init__(self, server_hostname: str, ci_certs_path: str, common_cert_path: str, use_brainpool: bool = False, in_memory: bool = False):
         self.server_hostname = server_hostname
         self.upp_dir = os.path.realpath(os.path.join(DATA_DIR, 'upp'))
         self.ci_certs = self.load_certs_from_path(ci_certs_path)
         # load DPauth cert + key
         self.dp_auth = CertAndPrivkey(oid.id_rspRole_dp_auth_v2)
-        cert_dir = os.path.join(DATA_DIR, 'certs')
+        cert_dir = common_cert_path
         if use_brainpool:
             self.dp_auth.cert_from_der_file(os.path.join(cert_dir, 'DPauth', 'CERT_S_SM_DPauth_ECDSA_BRP.der'))
             self.dp_auth.privkey_from_pem_file(os.path.join(cert_dir, 'DPauth', 'SK_S_SM_DPauth_ECDSA_BRP.pem'))
@@ -154,7 +426,15 @@ class SmDppHttpServer:
         else:
             self.dp_pb.cert_from_der_file(os.path.join(cert_dir, 'DPpb', 'CERT_S_SM_DPpb_ECDSA_NIST.der'))
             self.dp_pb.privkey_from_pem_file(os.path.join(cert_dir, 'DPpb', 'SK_S_SM_DPpb_ECDSA_NIST.pem'))
-        self.rss = rsp.RspSessionStore(os.path.join(DATA_DIR, "sm-dp-sessions"))
+        if in_memory:
+            self.rss = rsp.RspSessionStore(in_memory=True)
+            logger.info("Using in-memory session storage")
+        else:
+            # Use different session database files for BRP and NIST to avoid file locking during concurrent runs
+            session_db_suffix = "BRP" if use_brainpool else "NIST"
+            db_path = os.path.join(DATA_DIR, f"sm-dp-sessions-{session_db_suffix}")
+            self.rss = rsp.RspSessionStore(filename=db_path, in_memory=False)
+            logger.info(f"Using file-based session storage: {db_path}")
 
     @app.handle_errors(ApiError)
     def handle_apierror(self, request: IRequest, failure):
@@ -178,17 +458,18 @@ class SmDppHttpServer:
         functionality, such as JSON decoding/encoding and debug-printing."""
         @functools.wraps(func)
         def _api_wrapper(self, request: IRequest):
-            # TODO: evaluate User-Agent + X-Admin-Protocol header
-            # TODO: reject any non-JSON Content-type
+            validate_request_headers(request)
 
             content = json.loads(request.content.read())
-            print("Rx JSON: %s" % json.dumps(content))
+            logger.debug("Rx JSON: %s" % json.dumps(content))
             set_headers(request)
 
-            output = func(self, request, content) or {}
+            output = func(self, request, content)
+            if output == None:
+                return ''
 
             build_resp_header(output)
-            print("Tx JSON: %s" % json.dumps(output))
+            logger.debug("Tx JSON: %s" % json.dumps(output))
             return json.dumps(output)
         return _api_wrapper
 
@@ -207,7 +488,7 @@ class SmDppHttpServer:
 
         euiccInfo1_bin = b64decode(content['euiccInfo1'])
         euiccInfo1 = rsp.asn1.decode('EUICCInfo1', euiccInfo1_bin)
-        print("Rx euiccInfo1: %s" % euiccInfo1)
+        logger.debug("Rx euiccInfo1: %s" % euiccInfo1)
         #euiccInfo1['svn']
 
         # TODO: If euiccCiPKIdListForSigningV3 is present ...
@@ -215,6 +496,12 @@ class SmDppHttpServer:
         pkid_list = euiccInfo1['euiccCiPKIdListForSigning']
         if 'euiccCiPKIdListForSigningV3' in euiccInfo1:
             pkid_list = pkid_list + euiccInfo1['euiccCiPKIdListForSigningV3']
+
+        # Validate that SM-DP+ supports certificate chains for verification
+        verification_pkid_list = euiccInfo1.get('euiccCiPKIdListForVerification', [])
+        if verification_pkid_list and not self.validate_certificate_chain_for_verification(verification_pkid_list):
+            raise ApiError('8.8.4', '3.7', 'The SM-DP+ has no CERT.DPauth.SIG which chains to one of the eSIM CA Root CA Certificate with a Public Key supported by the eUICC')
+
         # verify it supports one of the keys indicated by euiccCiPKIdListForSigning
         ci_cert = None
         for x in pkid_list:
@@ -229,16 +516,9 @@ class SmDppHttpServer:
         if not ci_cert:
            raise ApiError('8.8.2', '3.1', 'None of the proposed Public Key Identifiers is supported by the SM-DP+')
 
-        # TODO: Determine the set of CERT.DPauth.SIG that satisfy the following criteria:
-        # * Part of a certificate chain ending at one of the eSIM CA RootCA Certificate, whose Public Keys is
-        #   supported by the eUICC (indicated by euiccCiPKIdListForVerification).
-        # * Using a certificate chain that the eUICC and the LPA both support:
-        #euiccInfo1['euiccCiPKIdListForVerification']
-        #   raise ApiError('8.8.4', '3.7', 'The SM-DP+ has no CERT.DPauth.SIG which chains to one of the eSIM CA Root CA CErtificate with a Public Key supported by the eUICC')
-
         # Generate a TransactionID which is used to identify the ongoing RSP session. The TransactionID
         # SHALL be unique within the scope and lifetime of each SM-DP+.
-        transactionId = uuid.uuid4().hex
+        transactionId = uuid.uuid4().hex.upper()
         assert not transactionId in self.rss
 
         # Generate a serverChallenge for eUICC authentication attached to the ongoing RSP session.
@@ -251,9 +531,9 @@ class SmDppHttpServer:
             'serverAddress': self.server_hostname,
             'serverChallenge': serverChallenge,
             }
-        print("Tx serverSigned1: %s" % serverSigned1)
+        logger.debug("Tx serverSigned1: %s" % serverSigned1)
         serverSigned1_bin = rsp.asn1.encode('ServerSigned1', serverSigned1)
-        print("Tx serverSigned1: %s" % rsp.asn1.decode('ServerSigned1', serverSigned1_bin))
+        logger.debug("Tx serverSigned1: %s" % rsp.asn1.decode('ServerSigned1', serverSigned1_bin))
         output = {}
         output['serverSigned1'] = b64encode2str(serverSigned1_bin)
 
@@ -282,7 +562,7 @@ class SmDppHttpServer:
 
         authenticateServerResp_bin = b64decode(content['authenticateServerResponse'])
         authenticateServerResp = rsp.asn1.decode('AuthenticateServerResponse', authenticateServerResp_bin)
-        print("Rx %s: %s" % authenticateServerResp)
+        logger.debug("Rx %s: %s" % authenticateServerResp)
         if authenticateServerResp[0] == 'authenticateResponseError':
             r_err = authenticateServerResp[1]
             #r_err['transactionId']
@@ -291,8 +571,7 @@ class SmDppHttpServer:
 
         r_ok = authenticateServerResp[1]
         euiccSigned1 = r_ok['euiccSigned1']
-        # TODO: use original data, don't re-encode?
-        euiccSigned1_bin = rsp.asn1.encode('EuiccSigned1', euiccSigned1)
+        euiccSigned1_bin = rsp.extract_euiccSigned1(authenticateServerResp_bin)
         euiccSignature1_bin = r_ok['euiccSignature1']
         euiccCertificate_dec = r_ok['euiccCertificate']
         # TODO: use original data, don't re-encode?
@@ -325,29 +604,32 @@ class SmDppHttpServer:
         try:
             cs.verify_cert_chain(euicc_cert)
         except VerifyError:
-            raise ApiError('8.1.3', '6.1', 'Verification failed')
+            raise ApiError('8.1.3', '6.1', 'Verification failed (certificate chain)')
         #   raise ApiError('8.1.3', '6.3', 'Expired')
 
 
         # Verify euiccSignature1 over euiccSigned1 using pubkey from euiccCertificate.
         # Otherwise, the SM-DP+ SHALL return a status code "eUICC - Verification failed"
         if not self._ecdsa_verify(euicc_cert, euiccSignature1_bin, euiccSigned1_bin):
-            raise ApiError('8.1', '6.1', 'Verification failed')
-
-        # TODO: verify EID of eUICC cert is  within permitted range of EUM cert
+            raise ApiError('8.1', '6.1', 'Verification failed (euiccSignature1 over euiccSigned1)')
 
         ss.eid = ss.euicc_cert.subject.get_attributes_for_oid(x509.oid.NameOID.SERIAL_NUMBER)[0].value
-        print("EID (from eUICC cert): %s" % ss.eid)
+        logger.debug("EID (from eUICC cert): %s" % ss.eid)
+
+        # Verify EID is within permitted range of EUM certificate
+        if not validate_eid_range(ss.eid, eum_cert):
+            raise ApiError('8.1.4', '6.1', 'EID is not within the permitted range of the EUM certificate')
 
         # Verify that the serverChallenge attached to the ongoing RSP session matches the
         # serverChallenge returned by the eUICC. Otherwise, the SM-DP+ SHALL return a status code "eUICC -
         # Verification failed".
         if euiccSigned1['serverChallenge'] != ss.serverChallenge:
-            raise ApiError('8.1', '6.1', 'Verification failed')
+            raise ApiError('8.1', '6.1', 'Verification failed (serverChallenge)')
 
         # If ctxParams1 contains a ctxParamsForCommonAuthentication data object, the SM-DP+ Shall [...]
         # TODO: We really do a very simplistic job here, this needs to be properly implemented later,
         # considering all the various cases, profile state, etc.
+        iccid_str = None
         if euiccSigned1['ctxParams1'][0] == 'ctxParamsForCommonAuthentication':
             cpca = euiccSigned1['ctxParams1'][1]
             matchingId = cpca.get('matchingId', None)
@@ -363,11 +645,20 @@ class SmDppHttpServer:
                 if not os.path.isfile(path) or not os.access(path, os.R_OK):
                     raise ApiError('8.2.6', '3.8', 'Refused')
                 ss.matchingId = matchingId
+                with open(path, 'rb') as f:
+                    pes = saip.ProfileElementSequence.from_der(f.read())
+                    iccid_str = b2h(pes.get_pe_for_type('header').decoded['iccid'])
+        else:
+            # there's currently no other option in the ctxParams1 choice, so this cannot happen
+            raise ApiError('1.3.1', '2.2', 'ctxParams1 missing mandatory ctxParamsForCommonAuthentication')
 
-        # FIXME: we actually want to perform the profile binding herr, and read the profile metadat from the profile
+        # FIXME: we actually want to perform the profile binding herr, and read the profile metadata from the profile
 
         # Put together profileMetadata + _bin
-        ss.profileMetadata = ProfileMetadata(iccid_bin= h2b(swap_nibbles('89000123456789012358')), spn="OsmocomSPN", profile_name="OsmocomProfile")
+        ss.profileMetadata = ProfileMetadata(iccid_bin=h2b(swap_nibbles(iccid_str)), spn="OsmocomSPN", profile_name=matchingId)
+        # enable notifications for all operations
+        for event in ['enable', 'disable', 'delete']:
+            ss.profileMetadata.add_notification(event, self.server_hostname)
         profileMetadata_bin = ss.profileMetadata.gen_store_metadata_request()
 
         # Put together smdpSigned2 + _bin
@@ -403,7 +694,7 @@ class SmDppHttpServer:
 
         prepDownloadResp_bin = b64decode(content['prepareDownloadResponse'])
         prepDownloadResp = rsp.asn1.decode('PrepareDownloadResponse', prepDownloadResp_bin)
-        print("Rx %s: %s" % prepDownloadResp)
+        logger.debug("Rx %s: %s" % prepDownloadResp)
 
         if prepDownloadResp[0] == 'downloadResponseError':
             r_err = prepDownloadResp[1]
@@ -415,8 +706,7 @@ class SmDppHttpServer:
 
         # Verify the euiccSignature2 computed over euiccSigned2 and smdpSignature2 using the PK.EUICC.SIG attached to the ongoing RSP session
         euiccSigned2 = r_ok['euiccSigned2']
-        # TODO: use original data, don't re-encode?
-        euiccSigned2_bin = rsp.asn1.encode('EUICCSigned2', euiccSigned2)
+        euiccSigned2_bin = rsp.extract_euiccSigned2(prepDownloadResp_bin)
         if not self._ecdsa_verify(ss.euicc_cert, r_ok['euiccSignature2'], euiccSigned2_bin + ss.smdpSignature2_do):
             raise ApiError('8.1', '6.1', 'eUICC signature is invalid')
 
@@ -426,37 +716,37 @@ class SmDppHttpServer:
 
         # store otPK.EUICC.ECKA in session state
         ss.euicc_otpk = euiccSigned2['euiccOtpk']
-        print("euiccOtpk: %s" % (b2h(ss.euicc_otpk)))
+        logger.debug("euiccOtpk: %s" % (b2h(ss.euicc_otpk)))
 
         # Generate a one-time ECKA key pair (ot{PK,SK}.DP.ECKA) using the curve indicated by the Key Parameter
         # Reference value of CERT.DPpb.ECDDSA
-        print("curve = %s" % self.dp_pb.get_curve())
+        logger.debug("curve = %s" % self.dp_pb.get_curve())
         ss.smdp_ot = ec.generate_private_key(self.dp_pb.get_curve())
         # extract the public key in (hopefully) the right format for the ES8+ interface
         ss.smdp_otpk = ss.smdp_ot.public_key().public_bytes(Encoding.X962, PublicFormat.UncompressedPoint)
-        print("smdpOtpk: %s" % b2h(ss.smdp_otpk))
-        print("smdpOtsk: %s" % b2h(ss.smdp_ot.private_bytes(Encoding.DER, PrivateFormat.PKCS8, NoEncryption())))
+        logger.debug("smdpOtpk: %s" % b2h(ss.smdp_otpk))
+        logger.debug("smdpOtsk: %s" % b2h(ss.smdp_ot.private_bytes(Encoding.DER, PrivateFormat.PKCS8, NoEncryption())))
 
         ss.host_id = b'mahlzeit'
 
-        # Generate Session Keys using the CRT, opPK.eUICC.ECKA and otSK.DP.ECKA according to annex G
+        # Generate Session Keys using the CRT, otPK.eUICC.ECKA and otSK.DP.ECKA according to annex G
         euicc_public_key = ec.EllipticCurvePublicKey.from_encoded_point(ss.smdp_ot.curve, ss.euicc_otpk)
         ss.shared_secret = ss.smdp_ot.exchange(ec.ECDH(), euicc_public_key)
-        print("shared_secret: %s" % b2h(ss.shared_secret))
+        logger.debug("shared_secret: %s" % b2h(ss.shared_secret))
 
         # TODO: Check if this order requires a Confirmation Code verification
 
         #  Perform actual protection + binding of profile package (or return  pre-bound one)
         with open(os.path.join(self.upp_dir, ss.matchingId)+'.der', 'rb') as f:
             upp = UnprotectedProfilePackage.from_der(f.read(), metadata=ss.profileMetadata)
-            # HACK: Use empty PPP as we're still debuggin the configureISDP step, and we want to avoid
+            # HACK: Use empty PPP as we're still debugging the configureISDP step, and we want to avoid
             # cluttering the log with stuff happening after the failure
             #upp = UnprotectedProfilePackage.from_der(b'', metadata=ss.profileMetadata)
         if False:
             # Use random keys
             bpp = BoundProfilePackage.from_upp(upp)
         else:
-            # Use sesssion keys
+            # Use session keys
             ppp = ProtectedProfilePackage.from_upp(upp, BspInstance(b'\x00'*16, b'\x11'*16, b'\x22'*16))
             bpp = BoundProfilePackage.from_ppp(ppp)
 
@@ -471,29 +761,52 @@ class SmDppHttpServer:
     @rsp_api_wrapper
     def handleNotification(self, request: IRequest, content: dict) -> dict:
         """See ES9+ HandleNotification in SGP.22 Section 5.6.4"""
+        # SGP.22 Section 6.3: "A normal notification function execution status (MEP Notification)
+        # SHALL be indicated by the HTTP status code '204' (No Content) with an empty HTTP response body"
+        request.setResponseCode(204)
         pendingNotification_bin = b64decode(content['pendingNotification'])
         pendingNotification = rsp.asn1.decode('PendingNotification', pendingNotification_bin)
-        print("Rx %s: %s" % pendingNotification)
+        logger.debug("Rx %s: %s" % pendingNotification)
         if pendingNotification[0] == 'profileInstallationResult':
             profileInstallRes = pendingNotification[1]
             pird = profileInstallRes['profileInstallationResultData']
             transactionId = b2h(pird['transactionId'])
             ss = self.rss.get(transactionId, None)
             if ss is None:
-                print("Unable to find session for transactionId")
-                return
+                logger.warning(f"Unable to find session for transactionId: {transactionId}")
+                return None  # Will return HTTP 204 with empty body
             profileInstallRes['euiccSignPIR']
             # TODO: use original data, don't re-encode?
             pird_bin = rsp.asn1.encode('ProfileInstallationResultData', pird)
             # verify eUICC signature
             if not self._ecdsa_verify(ss.euicc_cert, profileInstallRes['euiccSignPIR'], pird_bin):
-                print("Unable to verify eUICC signature")
-            print("Profile Installation Final Result: ", pird['finalResult'])
+                raise Exception('ECDSA signature verification failed on notification')
+            logger.debug("Profile Installation Final Result: %s", pird['finalResult'])
             # remove session state
             del self.rss[transactionId]
         elif pendingNotification[0] == 'otherSignedNotification':
-            # TODO
-            pass
+            otherSignedNotif = pendingNotification[1]
+            # TODO: use some kind of partially-parsed original data, don't re-encode?
+            euiccCertificate_bin = rsp.asn1.encode('Certificate', otherSignedNotif['euiccCertificate'])
+            eumCertificate_bin = rsp.asn1.encode('Certificate', otherSignedNotif['eumCertificate'])
+            euicc_cert = x509.load_der_x509_certificate(euiccCertificate_bin)
+            eum_cert = x509.load_der_x509_certificate(eumCertificate_bin)
+            ci_cert_id = cert_get_auth_key_id(eum_cert)
+            # Verify the validity of the eUICC certificate chain
+            cs = CertificateSet(self.ci_get_cert_for_pkid(ci_cert_id))
+            cs.add_intermediate_cert(eum_cert)
+            # TODO v3: otherCertsInChain
+            cs.verify_cert_chain(euicc_cert)
+            tbs_bin = rsp.asn1.encode('NotificationMetadata', otherSignedNotif['tbsOtherNotification'])
+            if not self._ecdsa_verify(euicc_cert, otherSignedNotif['euiccNotificationSignature'], tbs_bin):
+                raise Exception('ECDSA signature verification failed on notification')
+            other_notif = otherSignedNotif['tbsOtherNotification']
+            pmo = PMO.from_bitstring(other_notif['profileManagementOperation'])
+            eid = euicc_cert.subject.get_attributes_for_oid(x509.oid.NameOID.SERIAL_NUMBER)[0].value
+            iccid = other_notif.get('iccid', None)
+            if iccid:
+                iccid = swap_nibbles(b2h(iccid))
+            logger.debug("handleNotification: EID %s: %s of %s" % (eid, pmo, iccid))
         else:
             raise ValueError(pendingNotification)
 
@@ -506,7 +819,7 @@ class SmDppHttpServer:
     @rsp_api_wrapper
     def cancelSession(self, request: IRequest, content: dict) -> dict:
         """See ES9+ CancelSession in SGP.22 Section 5.6.5"""
-        print("Rx JSON: %s" % content)
+        logger.debug("Rx JSON: %s" % content)
         transactionId = content['transactionId']
 
         # Verify that the received transactionId is known and relates to an ongoing RSP session
@@ -516,7 +829,7 @@ class SmDppHttpServer:
 
         cancelSessionResponse_bin = b64decode(content['cancelSessionResponse'])
         cancelSessionResponse = rsp.asn1.decode('CancelSessionResponse', cancelSessionResponse_bin)
-        print("Rx %s: %s" % cancelSessionResponse)
+        logger.debug("Rx %s: %s" % cancelSessionResponse)
 
         if cancelSessionResponse[0] == 'cancelSessionResponseError':
             # FIXME: print some error
@@ -548,15 +861,53 @@ class SmDppHttpServer:
 
 def main(argv):
     parser = argparse.ArgumentParser()
-    #parser.add_argument("-H", "--host", help="Host/IP to bind HTTP to", default="localhost")
-    #parser.add_argument("-p", "--port", help="TCP port to bind HTTP to", default=8000)
-    #parser.add_argument("-v", "--verbose", help="increase output verbosity", action='count', default=0)
-
+    parser.add_argument("-H", "--host", help="Host/IP to bind HTTP(S) to", default="localhost")
+    parser.add_argument("-p", "--port", help="TCP port to bind HTTP(S) to", default=443)
+    parser.add_argument("-c", "--certdir", help=f"cert subdir relative to {DATA_DIR}", default="certs")
+    parser.add_argument("-s", "--nossl", help="disable built in SSL/TLS support", action='store_true', default=False)
+    parser.add_argument("-v", "--verbose", help="dump more raw info", action='store_true', default=False)
+    parser.add_argument("-b", "--brainpool", help="Use Brainpool curves instead of NIST",
+                        action='store_true', default=False)
+    parser.add_argument("-m", "--in-memory", help="Use ephermal in-memory session storage (for concurrent runs)",
+                        action='store_true', default=False)
     args = parser.parse_args()
 
-    hs = SmDppHttpServer(HOSTNAME, os.path.join(DATA_DIR, 'certs', 'CertificateIssuer'), use_brainpool=True)
-    #hs.app.run(endpoint_description="ssl:port=8000:dhParameters=dh_param_2048.pem")
-    hs.app.run("localhost", 8000)
+    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.WARNING)
+
+    common_cert_path = os.path.join(DATA_DIR, args.certdir)
+    hs = SmDppHttpServer(server_hostname=HOSTNAME, ci_certs_path=os.path.join(common_cert_path, 'CertificateIssuer'), common_cert_path=common_cert_path, use_brainpool=args.brainpool)
+    if(args.nossl):
+        hs.app.run(args.host, args.port)
+    else:
+        curve_type = 'BRP' if args.brainpool else 'NIST'
+        cert_derpath = Path(common_cert_path) / 'DPtls' / f'CERT_S_SM_DP_TLS_{curve_type}.der'
+        cert_pempath = Path(common_cert_path) / 'DPtls' / f'CERT_S_SM_DP_TLS_{curve_type}.pem'
+        cert_skpath = Path(common_cert_path) / 'DPtls' / f'SK_S_SM_DP_TLS_{curve_type}.pem'
+        dhparam_path = Path(common_cert_path) / "dhparam2048.pem"
+        if not dhparam_path.exists():
+            print("Generating dh params, this takes a few seconds..")
+            # Generate DH parameters with 2048-bit key size and generator 2
+            parameters = dh.generate_parameters(generator=2, key_size=2048)
+            pem_data = parameters.parameter_bytes(encoding=Encoding.PEM,format=ParameterFormat.PKCS3)
+            with open(dhparam_path, 'wb') as file:
+                file.write(pem_data)
+            print("DH params created successfully")
+
+        if not cert_pempath.exists():
+            print("Translating tls server cert from DER to PEM..")
+            with open(cert_derpath, 'rb') as der_file:
+                der_cert_data = der_file.read()
+
+            cert = x509.load_der_x509_certificate(der_cert_data)
+            pem_cert = cert.public_bytes(Encoding.PEM) #.decode('utf-8')
+
+            with open(cert_pempath, 'wb') as pem_file:
+                pem_file.write(pem_cert)
+
+        SERVER_STRING = f'ssl:{args.port}:privateKey={cert_skpath}:certKey={cert_pempath}:dhParameters={dhparam_path}'
+        print(SERVER_STRING)
+
+        hs.app.run(host=HOSTNAME, port=args.port, endpoint_description=SERVER_STRING)
 
 if __name__ == "__main__":
     main(sys.argv)

pySim-prog.py

@@ -25,190 +25,173 @@
 #
 
 import hashlib
-from optparse import OptionParser
+import argparse
 import os
-import random
 import re
 import sys
 import traceback
 import json
 import csv
+from osmocom.utils import h2b, swap_nibbles, rpad
 
 from pySim.commands import SimCardCommands
-from pySim.transport import init_reader
+from pySim.transport import init_reader, argparse_add_reader_args
 from pySim.legacy.cards import _cards_classes, card_detect
-from pySim.utils import h2b, swap_nibbles, rpad, derive_milenage_opc, calculate_luhn, dec_iccid
+from pySim.utils import derive_milenage_opc, calculate_luhn, dec_iccid
 from pySim.ts_51_011 import EF_AD
 from pySim.legacy.ts_51_011 import EF
 from pySim.card_handler import *
 from pySim.utils import *
 
+from pathlib import Path
+import logging
+from pySim.log import PySimLogger
+
+log = PySimLogger.get(Path(__file__).stem)
 
 def parse_options():
 
-    parser = OptionParser(usage="usage: %prog [options]")
+    parser = argparse.ArgumentParser()
+    argparse_add_reader_args(parser)
 
-    parser.add_option("-d", "--device", dest="device", metavar="DEV",
-                      help="Serial Device for SIM access [default: %default]",
-                      default="/dev/ttyUSB0",
-                      )
-    parser.add_option("-b", "--baud", dest="baudrate", type="int", metavar="BAUD",
-                      help="Baudrate used for SIM access [default: %default]",
-                      default=9600,
-                      )
-    parser.add_option("-p", "--pcsc-device", dest="pcsc_dev", type='int', metavar="PCSC",
-                      help="Which PC/SC reader number for SIM access",
-                      default=None,
-                      )
-    parser.add_option("--modem-device", dest="modem_dev", metavar="DEV",
-                      help="Serial port of modem for Generic SIM Access (3GPP TS 27.007)",
-                      default=None,
-                      )
-    parser.add_option("--modem-baud", dest="modem_baud", type="int", metavar="BAUD",
-                      help="Baudrate used for modem's port [default: %default]",
-                      default=115200,
-                      )
-    parser.add_option("--osmocon", dest="osmocon_sock", metavar="PATH",
-                      help="Socket path for Calypso (e.g. Motorola C1XX) based reader (via OsmocomBB)",
-                      default=None,
-                      )
-    parser.add_option("-t", "--type", dest="type",
-                      help="Card type (user -t list to view) [default: %default]",
+    parser.add_argument("-t", "--type", dest="type",
+                      help="Card type (user -t list to view) [default: %(default)s]",
                       default="auto",
                       )
-    parser.add_option("-T", "--probe", dest="probe",
+    parser.add_argument("-T", "--probe", dest="probe",
                       help="Determine card type",
                       default=False, action="store_true"
                       )
-    parser.add_option("-a", "--pin-adm", dest="pin_adm",
+    parser.add_argument("-a", "--pin-adm", dest="pin_adm",
                       help="ADM PIN used for provisioning (overwrites default)",
                       )
-    parser.add_option("-A", "--pin-adm-hex", dest="pin_adm_hex",
+    parser.add_argument("-A", "--pin-adm-hex", dest="pin_adm_hex",
                       help="ADM PIN used for provisioning, as hex string (16 characters long",
                       )
-    parser.add_option("-e", "--erase", dest="erase", action='store_true',
-                      help="Erase beforehand [default: %default]",
+    parser.add_argument("-e", "--erase", dest="erase", action='store_true',
+                      help="Erase beforehand [default: %(default)s]",
                       default=False,
                       )
 
-    parser.add_option("-S", "--source", dest="source",
-                      help="Data Source[default: %default]",
+    parser.add_argument("-S", "--source", dest="source",
+                      help="Data Source[default: %(default)s]",
                       default="cmdline",
                       )
 
     # if mode is "cmdline"
-    parser.add_option("-n", "--name", dest="name",
-                      help="Operator name [default: %default]",
+    parser.add_argument("-n", "--name", dest="name",
+                      help="Operator name [default: %(default)s]",
                       default="Magic",
                       )
-    parser.add_option("-c", "--country", dest="country", type="int", metavar="CC",
-                      help="Country code [default: %default]",
+    parser.add_argument("-c", "--country", dest="country", type=int, metavar="CC",
+                      help="Country code [default: %(default)s]",
                       default=1,
                       )
-    parser.add_option("-x", "--mcc", dest="mcc", type="string",
-                      help="Mobile Country Code [default: %default]",
+    parser.add_argument("-x", "--mcc", dest="mcc",
+                      help="Mobile Country Code [default: %(default)s]",
                       default="901",
                       )
-    parser.add_option("-y", "--mnc", dest="mnc", type="string",
-                      help="Mobile Network Code [default: %default]",
+    parser.add_argument("-y", "--mnc", dest="mnc",
+                      help="Mobile Network Code [default: %(default)s]",
                       default="55",
                       )
-    parser.add_option("--mnclen", dest="mnclen", type="choice",
-                      help="Length of Mobile Network Code [default: %default]",
+    parser.add_argument("--mnclen", dest="mnclen",
+                      help="Length of Mobile Network Code [default: %(default)s]",
                       default="auto",
                       choices=["2", "3", "auto"],
                       )
-    parser.add_option("-m", "--smsc", dest="smsc",
+    parser.add_argument("-m", "--smsc", dest="smsc",
                       help="SMSC number (Start with + for international no.) [default: '00 + country code + 5555']",
                       )
-    parser.add_option("-M", "--smsp", dest="smsp",
+    parser.add_argument("-M", "--smsp", dest="smsp",
                       help="Raw SMSP content in hex [default: auto from SMSC]",
                       )
 
-    parser.add_option("-s", "--iccid", dest="iccid", metavar="ID",
+    parser.add_argument("-s", "--iccid", dest="iccid", metavar="ID",
                       help="Integrated Circuit Card ID",
                       )
-    parser.add_option("-i", "--imsi", dest="imsi",
+    parser.add_argument("-i", "--imsi", dest="imsi",
                       help="International Mobile Subscriber Identity",
                       )
-    parser.add_option("--msisdn", dest="msisdn",
+    parser.add_argument("--msisdn", dest="msisdn",
                       help="Mobile Subscriber Integrated Services Digital Number",
                       )
-    parser.add_option("-k", "--ki", dest="ki",
+    parser.add_argument("-k", "--ki", dest="ki",
                       help="Ki (default is to randomize)",
                       )
-    parser.add_option("-o", "--opc", dest="opc",
+    parser.add_argument("-o", "--opc", dest="opc",
                       help="OPC (default is to randomize)",
                       )
-    parser.add_option("--op", dest="op",
+    parser.add_argument("--op", dest="op",
                       help="Set OP to derive OPC from OP and KI",
                       )
-    parser.add_option("--acc", dest="acc",
+    parser.add_argument("--acc", dest="acc",
                       help="Set ACC bits (Access Control Code). not all card types are supported",
                       )
-    parser.add_option("--opmode", dest="opmode", type="choice",
+    parser.add_argument("--opmode", dest="opmode",
                       help="Set UE Operation Mode in EF.AD (Administrative Data)",
                       default=None,
                       choices=['{:02X}'.format(int(m)) for m in EF_AD.OP_MODE],
                       )
-    parser.add_option("-f", "--fplmn", dest="fplmn", action="append",
+    parser.add_argument("-f", "--fplmn", dest="fplmn", action="append",
                       help="Set Forbidden PLMN. Add multiple time for multiple FPLMNS",
                       )
-    parser.add_option("--epdgid", dest="epdgid",
+    parser.add_argument("--epdgid", dest="epdgid",
                       help="Set Home Evolved Packet Data Gateway (ePDG) Identifier. (Only FQDN format supported)",
                       )
-    parser.add_option("--epdgSelection", dest="epdgSelection",
+    parser.add_argument("--epdgSelection", dest="epdgSelection",
                       help="Set PLMN for ePDG Selection Information. (Only Operator Identifier FQDN format supported)",
                       )
-    parser.add_option("--pcscf", dest="pcscf",
+    parser.add_argument("--pcscf", dest="pcscf",
                       help="Set Proxy Call Session Control Function (P-CSCF) Address. (Only FQDN format supported)",
                       )
-    parser.add_option("--ims-hdomain", dest="ims_hdomain",
+    parser.add_argument("--ims-hdomain", dest="ims_hdomain",
                       help="Set IMS Home Network Domain Name in FQDN format",
                       )
-    parser.add_option("--impi", dest="impi",
+    parser.add_argument("--impi", dest="impi",
                       help="Set IMS private user identity",
                       )
-    parser.add_option("--impu", dest="impu",
+    parser.add_argument("--impu", dest="impu",
                       help="Set IMS public user identity",
                       )
-    parser.add_option("--read-imsi", dest="read_imsi", action="store_true",
+    parser.add_argument("--read-imsi", dest="read_imsi", action="store_true",
                       help="Read the IMSI from the CARD", default=False
                       )
-    parser.add_option("--read-iccid", dest="read_iccid", action="store_true",
+    parser.add_argument("--read-iccid", dest="read_iccid", action="store_true",
                       help="Read the ICCID from the CARD", default=False
                       )
-    parser.add_option("-z", "--secret", dest="secret", metavar="STR",
+    parser.add_argument("-z", "--secret", dest="secret", metavar="STR",
                       help="Secret used for ICCID/IMSI autogen",
                       )
-    parser.add_option("-j", "--num", dest="num", type=int,
+    parser.add_argument("-j", "--num", dest="num", type=int,
                       help="Card # used for ICCID/IMSI autogen",
                       )
-    parser.add_option("--batch", dest="batch_mode",
-                      help="Enable batch mode [default: %default]",
+    parser.add_argument("--batch", dest="batch_mode",
+                      help="Enable batch mode [default: %(default)s]",
                       default=False, action='store_true',
                       )
-    parser.add_option("--batch-state", dest="batch_state", metavar="FILE",
+    parser.add_argument("--batch-state", dest="batch_state", metavar="FILE",
                       help="Optional batch state file",
                       )
 
     # if mode is "csv"
-    parser.add_option("--read-csv", dest="read_csv", metavar="FILE",
+    parser.add_argument("--read-csv", dest="read_csv", metavar="FILE",
                       help="Read parameters from CSV file rather than command line")
 
-    parser.add_option("--write-csv", dest="write_csv", metavar="FILE",
+    parser.add_argument("--write-csv", dest="write_csv", metavar="FILE",
                       help="Append generated parameters in CSV file",
                       )
-    parser.add_option("--write-hlr", dest="write_hlr", metavar="FILE",
+    parser.add_argument("--write-hlr", dest="write_hlr", metavar="FILE",
                       help="Append generated parameters to OpenBSC HLR sqlite3",
                       )
-    parser.add_option("--dry-run", dest="dry_run",
+    parser.add_argument("--dry-run", dest="dry_run",
                       help="Perform a 'dry run', don't actually program the card",
                       default=False, action="store_true")
-    parser.add_option("--card_handler", dest="card_handler_config", metavar="FILE",
+    parser.add_argument("--card_handler", dest="card_handler_config", metavar="FILE",
                       help="Use automatic card handling machine")
+    parser.add_argument("--verbose", help="Enable verbose logging", action='store_true', default=False)
 
-    (options, args) = parser.parse_args()
+    options = parser.parse_args()
 
     if options.type == 'list':
         for kls in _cards_classes:
@@ -219,15 +202,13 @@ def parse_options():
         return options
 
     if options.source == 'csv':
-        if (options.imsi is None) and (options.batch_mode is False) and (options.read_imsi is False) and (options.read_iccid is False):
-            parser.error(
-                "CSV mode needs either an IMSI, --read-imsi, --read-iccid or batch mode")
+        if (options.imsi is None) and (options.iccid is None)  and (options.read_imsi is False) and (options.read_iccid is False):
+           parser.error("CSV mode requires one additional parameter: --read-iccid, --read-imsi, --iccid or --imsi")
         if options.read_csv is None:
             parser.error("CSV mode requires a CSV input file")
     elif options.source == 'cmdline':
         if ((options.imsi is None) or (options.iccid is None)) and (options.num is None):
-            parser.error(
-                "If either IMSI or ICCID isn't specified, num is required")
+            parser.error("If either IMSI or ICCID isn't specified, num is required")
     else:
         parser.error("Only `cmdline' and `csv' sources supported")
 
@@ -242,9 +223,6 @@ def parse_options():
             parser.error(
                 "Can't give ICCID/IMSI for batch mode, need to use automatic parameters ! see --num and --secret for more information")
 
-    if args:
-        parser.error("Extraneous arguments")
-
     return options
 
 
@@ -457,7 +435,7 @@ def gen_parameters(opts):
         if not re.match('^[0-9a-fA-F]{32}$', ki):
             raise ValueError('Ki needs to be 128 bits, in hex format')
     else:
-        ki = ''.join(['%02x' % random.randrange(0, 256) for i in range(16)])
+        ki = os.urandom(16).hex()
 
     # OPC (random)
     if opts.opc is not None:
@@ -468,7 +446,7 @@ def gen_parameters(opts):
     elif opts.op is not None:
         opc = derive_milenage_opc(ki, opts.op)
     else:
-        opc = ''.join(['%02x' % random.randrange(0, 256) for i in range(16)])
+        opc = os.urandom(16).hex()
 
     pin_adm = sanitize_pin_adm(opts.pin_adm, opts.pin_adm_hex)
 
@@ -613,7 +591,7 @@ def read_params_csv(opts, imsi=None, iccid=None):
         else:
             row['mnc'] = row.get('mnc', mnc_from_imsi(row.get('imsi'), False))
 
-	# NOTE: We might concider to specify a new CSV field "mnclen" in our
+	# NOTE: We might consider to specify a new CSV field "mnclen" in our
 	# CSV files for a better automatization. However, this only makes sense
 	# when the tools and databases we export our files from will also add
 	# such a field.
@@ -649,6 +627,9 @@ def read_params_csv(opts, imsi=None, iccid=None):
 
 def write_params_hlr(opts, params):
     # SQLite3 OpenBSC HLR
+    # FIXME: The format of the osmo-hlr database has evolved, so that the code below will no longer work.
+    print("Warning: the database format of recent OsmoHLR versions is not compatible with pySim-prog!")
+
     if opts.write_hlr:
         import sqlite3
         conn = sqlite3.connect(opts.write_hlr)
@@ -749,16 +730,18 @@ def process_card(scc, opts, first, ch):
             card.erase()
             card.reset()
 
+    cp = None
+
     # Generate parameters
     if opts.source == 'cmdline':
         cp = gen_parameters(opts)
     elif opts.source == 'csv':
-        imsi = None
-        iccid = None
         if opts.read_iccid:
             (res, _) = scc.read_binary(['3f00', '2fe2'], length=10)
             iccid = dec_iccid(res)
-        elif opts.read_imsi:
+        else:
+            iccid = opts.iccid
+        if opts.read_imsi:
             (res, _) = scc.read_binary(EF['IMSI'])
             imsi = swap_nibbles(res)[3:]
         else:
@@ -792,6 +775,9 @@ if __name__ == '__main__':
     # Parse options
     opts = parse_options()
 
+    # Setup logger
+    PySimLogger.setup(print, {logging.WARN: "\033[33m"}, opts.verbose)
+
     # Init card reader driver
     sl = init_reader(opts)
 

pySim-read.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 #
-# Utility to display some informations about a SIM card
+# Utility to display some information about a SIM card
 #
 #
 # Copyright (C) 2009  Sylvain Munaut <tnt@246tNt.com>
@@ -25,10 +25,11 @@
 import hashlib
 import argparse
 import os
-import random
 import re
 import sys
 
+from osmocom.utils import h2b, h2s, swap_nibbles, rpad
+
 from pySim.ts_51_011 import EF_SST_map, EF_AD
 from pySim.legacy.ts_51_011 import EF, DF
 from pySim.ts_31_102 import EF_UST_map
@@ -40,14 +41,21 @@ from pySim.commands import SimCardCommands
 from pySim.transport import init_reader, argparse_add_reader_args
 from pySim.exceptions import SwMatchError
 from pySim.legacy.cards import card_detect, SimCard, UsimCard, IsimCard
-from pySim.utils import h2b, h2s, swap_nibbles, rpad, dec_imsi, dec_iccid, dec_msisdn
-from pySim.legacy.utils import format_xplmn_w_act, dec_st
+from pySim.utils import dec_imsi, dec_iccid
+from pySim.legacy.utils import format_xplmn_w_act, dec_st, dec_msisdn
+from pySim.ts_51_011 import EF_SMSP
+
+from pathlib import Path
+import logging
+from pySim.log import PySimLogger
+
+log = PySimLogger.get(Path(__file__).stem)
 
 option_parser = argparse.ArgumentParser(description='Legacy tool for reading some parts of a SIM card',
                                         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+option_parser.add_argument("--verbose", help="Enable verbose logging", action='store_true', default=False)
 argparse_add_reader_args(option_parser)
 
-
 def select_app(adf: str, card: SimCard):
     """Select application by its AID"""
     sw = 0
@@ -72,6 +80,9 @@ if __name__ == '__main__':
     # Parse options
     opts = option_parser.parse_args()
 
+    # Setup logger
+    PySimLogger.setup(print, {logging.WARN: "\033[33m"}, opts.verbose)
+
     # Init card reader driver
     sl = init_reader(opts)
 
@@ -86,7 +97,7 @@ if __name__ == '__main__':
     scc.sel_ctrl = "0004"
 
     # Testing for Classic SIM or UICC
-    (res, sw) = sl.send_apdu(scc.cla_byte + "a4" + scc.sel_ctrl + "02" + "3f00")
+    (res, sw) = sl.send_apdu(scc.cla_byte + "a4" + scc.sel_ctrl + "02" + "3f00" + "00")
     if sw == '6e00':
         # Just a Classic SIM
         scc.cla_byte = "a0"
@@ -139,6 +150,15 @@ if __name__ == '__main__':
     (res, sw) = card.read_record('SMSP', 1)
     if sw == '9000':
         print("SMSP: %s" % (res,))
+        ef_smsp = EF_SMSP()
+        smsc_a = ef_smsp.decode_record_bin(h2b(res), 1).get('tp_sc_addr', {})
+        smsc_n = smsc_a.get('call_number', None)
+        if smsc_a.get('ton_npi', {}).get('type_of_number', None) == 'international' and smsc_n is not None:
+            smsc = '+' + smsc_n
+        else:
+            smsc = smsc_n
+        if smsc is not None:
+            print("SMSC: %s" % (smsc,))
     else:
         print("SMSP: Can't read, response code = %s" % (sw,))
 

pySim-smpp2sim.py

@@ -0,0 +1,428 @@
+#!/usr/bin/env python3
+#
+# Program to emulate the entire communication path SMSC-MSC-BSC-BTS-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 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.
+
+# (C) 2023-2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import argparse
+import logging
+import colorlog
+
+from twisted.protocols import basic
+from twisted.internet import defer, endpoints, protocol, reactor, task
+from twisted.cred.portal import IRealm
+from twisted.cred.checkers import InMemoryUsernamePasswordDatabaseDontUse
+from twisted.cred.portal import Portal
+from zope.interface import implementer
+
+from smpp.twisted.config import SMPPServerConfig
+from smpp.twisted.server import SMPPServerFactory, SMPPBindManager
+from smpp.twisted.protocol import SMPPSessionStates, DataHandlerResponse
+
+from smpp.pdu import pdu_types, operations, pdu_encoding
+
+from pySim.sms import SMS_DELIVER, SMS_SUBMIT, AddressField
+
+from pySim.transport import LinkBase, ProactiveHandler, argparse_add_reader_args, init_reader, ApduTracer
+from pySim.commands import SimCardCommands
+from pySim.cards import UiccCardBase
+from pySim.exceptions import *
+from pySim.cat import ProactiveCommand, SendShortMessage, SMS_TPDU, SMSPPDownload, BearerDescription
+from pySim.cat import DeviceIdentities, Address, OtherAddress, UiccTransportLevel, BufferSize
+from pySim.cat import ChannelStatus, ChannelData, ChannelDataLength
+from pySim.utils import b2h, h2b
+
+logger = logging.getLogger(__name__)
+
+# MSISDNs to use when generating proactive SMS messages
+SIM_MSISDN='23'
+ESME_MSISDN='12'
+
+# HACK: we need some kind of mapping table between system_id and card-reader
+# or actually route based on MSISDNs
+hackish_global_smpp = None
+
+class MyApduTracer(ApduTracer):
+    def trace_response(self, cmd, sw, resp):
+        print("-> %s %s" % (cmd[:10], cmd[10:]))
+        print("<- %s: %s" % (sw, resp))
+
+class TcpProtocol(protocol.Protocol):
+    def dataReceived(self, data):
+        pass
+
+    def connectionLost(self, reason):
+        pass
+
+
+def tcp_connected_callback(p: protocol.Protocol):
+    """called by twisted TCP client."""
+    logger.error("%s: connected!" % p)
+
+class ProactChannel:
+    """Representation of a single protective channel."""
+    def __init__(self, channels: 'ProactChannels', chan_nr: int):
+        self.channels = channels
+        self.chan_nr = chan_nr
+        self.ep = None
+
+    def close(self):
+        """Close the channel."""
+        if self.ep:
+            self.ep.disconnect()
+        self.channels.channel_delete(self.chan_nr)
+
+class ProactChannels:
+    """Wrapper class for maintaining state of proactive channels."""
+    def __init__(self):
+        self.channels = {}
+
+    def channel_create(self) -> ProactChannel:
+        """Create a new proactive channel, allocating its integer number."""
+        for i in range(1, 9):
+            if not i in self.channels:
+                self.channels[i] = ProactChannel(self, i)
+                return self.channels[i]
+        raise ValueError('Cannot allocate another channel: All channels active')
+
+    def channel_delete(self, chan_nr: int):
+        del self.channels[chan_nr]
+
+class Proact(ProactiveHandler):
+    #def __init__(self, smpp_factory):
+    #    self.smpp_factory = smpp_factory
+    def __init__(self):
+        self.channels = ProactChannels()
+
+    @staticmethod
+    def _find_first_element_of_type(instlist, cls):
+        for i in instlist:
+            if isinstance(i, cls):
+                return i
+        return None
+
+    """Call-back which the pySim transport core calls whenever it receives a
+    proactive command from the SIM."""
+    def handle_SendShortMessage(self, pcmd: ProactiveCommand):
+        # {'smspp_download': [{'device_identities': {'source_dev_id': 'network',
+        #                                            'dest_dev_id': 'uicc'}},
+        #                     {'address': {'ton_npi': {'ext': True,
+        #                                              'type_of_number': 'international',
+        #                                              'numbering_plan_id': 'isdn_e164'},
+        #                                  'call_number': '79'}},
+        #                     {'sms_tpdu': {'tpdu': '40048111227ff6407070611535004d02700000481516011212000001fe4c0943aea42e45021c078ae06c66afc09303608874b72f58bacadb0dcf665c29349c799fbb522e61709c9baf1890015e8e8e196e36153106c8b92f95153774'}}
+        #                    ]}
+        """Card requests sending a SMS. We need to pass it on to the ESME via SMPP."""
+        logger.info("SendShortMessage")
+        logger.info(pcmd)
+        # Relevant parts in pcmd: Address, SMS_TPDU
+        addr_ie = Proact._find_first_element_of_type(pcmd.children, Address)
+        sms_tpdu_ie = Proact._find_first_element_of_type(pcmd.children, SMS_TPDU)
+        raw_tpdu = sms_tpdu_ie.decoded['tpdu']
+        submit = SMS_SUBMIT.from_bytes(raw_tpdu)
+        submit.tp_da = AddressField(addr_ie.decoded['call_number'], addr_ie.decoded['ton_npi']['type_of_number'],
+                                    addr_ie.decoded['ton_npi']['numbering_plan_id'])
+        logger.info(submit)
+        self.send_sms_via_smpp(submit)
+
+    def handle_OpenChannel(self, pcmd: ProactiveCommand):
+        """Card requests opening a new channel via a UDP/TCP socket."""
+        # {'open_channel': [{'command_details': {'command_number': 1,
+        #                                        'type_of_command': 'open_channel',
+        #                                        'command_qualifier': 3}},
+        #                   {'device_identities': {'source_dev_id': 'uicc',
+        #                                          'dest_dev_id': 'terminal'}},
+        #                   {'bearer_description': {'bearer_type': 'default',
+        #                                           'bearer_parameters': ''}},
+        #                   {'buffer_size': 1024},
+        #                   {'uicc_transport_level': {'protocol_type': 'tcp_uicc_client_remote',
+        #                                             'port_number': 32768}},
+        #                   {'other_address': {'type_of_address': 'ipv4',
+        #                                      'address': '01020304'}}
+        #                  ]}
+        logger.info("OpenChannel")
+        logger.info(pcmd)
+        transp_lvl_ie = Proact._find_first_element_of_type(pcmd.children, UiccTransportLevel)
+        other_addr_ie = Proact._find_first_element_of_type(pcmd.children, OtherAddress)
+        bearer_desc_ie = Proact._find_first_element_of_type(pcmd.children, BearerDescription)
+        buffer_size_ie = Proact._find_first_element_of_type(pcmd.children, BufferSize)
+        if transp_lvl_ie.decoded['protocol_type'] != 'tcp_uicc_client_remote':
+            raise ValueError('Unsupported protocol_type')
+        if other_addr_ie.decoded.get('type_of_address', None) != 'ipv4':
+            raise ValueError('Unsupported type_of_address')
+        ipv4_bytes = h2b(other_addr_ie.decoded['address'])
+        ipv4_str = '%u.%u.%u.%u' % (ipv4_bytes[0], ipv4_bytes[1], ipv4_bytes[2], ipv4_bytes[3])
+        port_nr = transp_lvl_ie.decoded['port_number']
+        print("%s:%u" % (ipv4_str, port_nr))
+        channel = self.channels.channel_create()
+        channel.ep = endpoints.TCP4ClientEndpoint(reactor, ipv4_str, port_nr)
+        channel.prot = TcpProtocol()
+        d = endpoints.connectProtocol(channel.ep, channel.prot)
+        # FIXME: why is this never called despite the client showing the inbound connection?
+        d.addCallback(tcp_connected_callback)
+
+        # Terminal Response example: [
+        #  {'command_details': {'command_number': 1,
+        #                       'type_of_command': 'open_channel',
+        #                       'command_qualifier': 3}},
+        #  {'device_identities': {'source_dev_id': 'terminal', 'dest_dev_id': 'uicc'}},
+        #  {'result': {'general_result': 'performed_successfully', 'additional_information': ''}},
+        #  {'channel_status': '8100'},
+        #  {'bearer_description': {'bearer_type': 'default', 'bearer_parameters': ''}},
+        #  {'buffer_size': 1024}
+        # ]
+        return self.prepare_response(pcmd) + [ChannelStatus(decoded='8100'), bearer_desc_ie, buffer_size_ie]
+
+    def handle_CloseChannel(self, pcmd: ProactiveCommand):
+        """Close a channel."""
+        logger.info("CloseChannel")
+        logger.info(pcmd)
+
+    def handle_ReceiveData(self, pcmd: ProactiveCommand):
+        """Receive/read data from the socket."""
+        # {'receive_data': [{'command_details': {'command_number': 1,
+        #                                        'type_of_command': 'receive_data',
+        #                                        'command_qualifier': 0}},
+        #                   {'device_identities': {'source_dev_id': 'uicc',
+        #                                          'dest_dev_id': 'channel_1'}},
+        #                   {'channel_data_length': 9}
+        #                  ]}
+        logger.info("ReceiveData")
+        logger.info(pcmd)
+        # Terminal Response example: [
+        #  {'command_details': {'command_number': 1,
+        #                       'type_of_command': 'receive_data',
+        #                       'command_qualifier': 0}},
+        #  {'device_identities': {'source_dev_id': 'terminal', 'dest_dev_id': 'uicc'}},
+        #  {'result': {'general_result': 'performed_successfully', 'additional_information': ''}},
+        #  {'channel_data': '16030100040e000000'},
+        #  {'channel_data_length': 0}
+        # ]
+        return self.prepare_response(pcmd) + []
+
+    def handle_SendData(self, pcmd: ProactiveCommand):
+        """Send/write data received from the SIM to the socket."""
+        # {'send_data': [{'command_details': {'command_number': 1,
+        #                                     'type_of_command': 'send_data',
+        #                                     'command_qualifier': 1}},
+        #                {'device_identities': {'source_dev_id': 'uicc',
+        #                                       'dest_dev_id': 'channel_1'}},
+        #                {'channel_data': '160301003c010000380303d0f45e12b52ce5bb522750dd037738195334c87a46a847fe2b6886cada9ea6bf00000a00ae008c008b00b0002c010000050001000101'}
+        #               ]}
+        logger.info("SendData")
+        logger.info(pcmd)
+        dev_id_ie = Proact._find_first_element_of_type(pcmd.children, DeviceIdentities)
+        chan_data_ie = Proact._find_first_element_of_type(pcmd.children, ChannelData)
+        chan_str = dev_id_ie.decoded['dest_dev_id']
+        chan_nr = 1 # FIXME
+        chan = self.channels.channels.get(chan_nr, None)
+        # FIXME chan.prot.transport.write(h2b(chan_data_ie.decoded))
+        # Terminal Response example: [
+        #  {'command_details': {'command_number': 1,
+        #                       'type_of_command': 'send_data',
+        #                       'command_qualifier': 1}},
+        #  {'device_identities': {'source_dev_id': 'terminal', 'dest_dev_id': 'uicc'}},
+        #  {'result': {'general_result': 'performed_successfully', 'additional_information': ''}},
+        #  {'channel_data_length': 255}
+        # ]
+        return self.prepare_response(pcmd) + [ChannelDataLength(decoded=255)]
+
+    def handle_SetUpEventList(self, pcmd: ProactiveCommand):
+        # {'set_up_event_list': [{'command_details': {'command_number': 1,
+        #                                             'type_of_command': 'set_up_event_list',
+        #                                             'command_qualifier': 0}},
+        #                        {'device_identities': {'source_dev_id': 'uicc',
+        #                                               'dest_dev_id': 'terminal'}},
+        #                        {'event_list': ['data_available', 'channel_status']}
+        #                       ]}
+        logger.info("SetUpEventList")
+        logger.info(pcmd)
+        # Terminal Response example: [
+        #  {'command_details': {'command_number': 1,
+        #                       'type_of_command': 'set_up_event_list',
+        #                       'command_qualifier': 0}},
+        #  {'device_identities': {'source_dev_id': 'terminal', 'dest_dev_id': 'uicc'}},
+        #  {'result': {'general_result': 'performed_successfully', 'additional_information': ''}}
+        # ]
+        return self.prepare_response(pcmd)
+
+    def getChannelStatus(self, pcmd: ProactiveCommand):
+        logger.info("GetChannelStatus")
+        logger.info(pcmd)
+        return self.prepare_response(pcmd) + []
+
+    def send_sms_via_smpp(self, submit: SMS_SUBMIT):
+        # while in a normal network the phone/ME would *submit* a message to the SMSC,
+        # we are actually emulating the SMSC itself, so we must *deliver* the message
+        # to the ESME
+        deliver = SMS_DELIVER.from_submit(submit)
+        deliver_smpp = deliver.to_smpp()
+
+        hackish_global_smpp.sendDataRequest(deliver_smpp)
+#       # obtain the connection/binding of system_id to be used for delivering MO-SMS to the ESME
+#       connection = smpp_server.getBoundConnections[system_id].getNextBindingForDelivery()
+#       connection.sendDataRequest(deliver_smpp)
+
+
+
+def dcs_is_8bit(dcs):
+    if dcs == pdu_types.DataCoding(pdu_types.DataCodingScheme.DEFAULT,
+                                   pdu_types.DataCodingDefault.OCTET_UNSPECIFIED):
+        return True
+    if dcs == pdu_types.DataCoding(pdu_types.DataCodingScheme.DEFAULT,
+                                   pdu_types.DataCodingDefault.OCTET_UNSPECIFIED_COMMON):
+        return True
+    # pySim-smpp2sim.py:150:21: E1101: Instance of 'DataCodingScheme' has no 'GSM_MESSAGE_CLASS' member (no-member)
+    # pylint: disable=no-member
+    if dcs.scheme == pdu_types.DataCodingScheme.GSM_MESSAGE_CLASS and dcs.schemeData['msgCoding'] == pdu_types.DataCodingGsmMsgCoding.DATA_8BIT:
+        return True
+    else:
+        return False
+
+
+class MyServer:
+
+    @implementer(IRealm)
+    class SmppRealm:
+        def requestAvatar(self, avatarId, mind, *interfaces):
+            return ('SMPP', avatarId, lambda: None)
+
+    def __init__(self, tcp_port:int = 2775, bind_ip = '::', system_id:str = 'test', password:str = 'test'):
+        smpp_config = SMPPServerConfig(msgHandler=self._msgHandler,
+                                       systems={system_id: {'max_bindings': 2}})
+        portal = Portal(self.SmppRealm())
+        credential_checker = InMemoryUsernamePasswordDatabaseDontUse()
+        credential_checker.addUser(system_id, password)
+        portal.registerChecker(credential_checker)
+        self.factory = SMPPServerFactory(smpp_config, auth_portal=portal)
+        logger.info('Binding Virtual SMSC to TCP Port %u at %s' % (tcp_port, bind_ip))
+        smppEndpoint = endpoints.TCP6ServerEndpoint(reactor, tcp_port, interface=bind_ip)
+        smppEndpoint.listen(self.factory)
+        self.tp = self.scc = self.card = None
+
+    def connect_to_card(self, tp: LinkBase):
+        self.tp = tp
+        self.scc = SimCardCommands(self.tp)
+        self.card = UiccCardBase(self.scc)
+        # this should be part of UiccCardBase, but FairewavesSIM breaks with that :/
+        self.scc.cla_byte = "00"
+        self.scc.sel_ctrl = "0004"
+        self.card.read_aids()
+        self.card.select_adf_by_aid(adf='usim')
+        # FIXME: create a more realistic profile than ffffff
+        self.scc.terminal_profile('ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff')
+
+    def _msgHandler(self, system_id, smpp, pdu):
+        """Handler for incoming messages received via SMPP from ESME."""
+        # HACK: we need some kind of mapping table between system_id and card-reader
+        # or actually route based on MSISDNs
+        global hackish_global_smpp
+        hackish_global_smpp = smpp
+        if pdu.id == pdu_types.CommandId.submit_sm:
+            return self.handle_submit_sm(system_id, smpp, pdu)
+        else:
+            logger.warning('Rejecting non-SUBMIT commandID')
+            return pdu_types.CommandStatus.ESME_RINVCMDID
+
+    def handle_submit_sm(self, system_id, smpp, pdu):
+        """SUBMIT-SM was received via SMPP from ESME. We need to deliver it to the SIM."""
+        # check for valid data coding scheme + PID
+        if not dcs_is_8bit(pdu.params['data_coding']):
+            logger.warning('Rejecting non-8bit DCS')
+            return pdu_types.CommandStatus.ESME_RINVDCS
+        if pdu.params['protocol_id'] != 0x7f:
+            logger.warning('Rejecting non-SIM PID')
+            return pdu_types.CommandStatus.ESME_RINVDCS
+
+        # 1) build a SMS-DELIVER (!) from the SMPP-SUBMIT
+        tpdu = SMS_DELIVER.from_smpp_submit(pdu)
+        logger.info(tpdu)
+        # 2) wrap into the CAT ENVELOPE for SMS-PP-Download
+        tpdu_ie = SMS_TPDU(decoded={'tpdu': b2h(tpdu.to_bytes())})
+        addr_ie = Address(decoded={'ton_npi': {'ext':False, 'type_of_number':'unknown', 'numbering_plan_id':'unknown'}, 'call_number': '0123456'})
+        dev_ids = DeviceIdentities(decoded={'source_dev_id': 'network', 'dest_dev_id': 'uicc'})
+        sms_dl = SMSPPDownload(children=[dev_ids, addr_ie, tpdu_ie])
+        # 3) send to the card
+        envelope_hex = b2h(sms_dl.to_tlv())
+        logger.info("ENVELOPE: %s" % envelope_hex)
+        (data, sw) = self.scc.envelope(envelope_hex)
+        logger.info("SW %s: %s" % (sw, data))
+        if sw in ['9200', '9300']:
+            # TODO send back RP-ERROR message with TP-FCS == 'SIM Application Toolkit Busy'
+            return pdu_types.CommandStatus.ESME_RSUBMITFAIL
+        elif sw == '9000' or sw[0:2] in ['6f', '62', '63'] and len(data):
+            # data something like 027100000e0ab000110000000000000001612f or
+            # 027100001c12b000119660ebdb81be189b5e4389e9e7ab2bc0954f963ad869ed7c
+            # which is the user-data portion of the SMS starting with the UDH (027100)
+            # TODO: return the response back to the sender in an RP-ACK; PID/DCS like in CMD
+            deliver = operations.DeliverSM(service_type=pdu.params['service_type'],
+                                           source_addr_ton=pdu.params['dest_addr_ton'],
+                                           source_addr_npi=pdu.params['dest_addr_npi'],
+                                           source_addr=pdu.params['destination_addr'],
+                                           dest_addr_ton=pdu.params['source_addr_ton'],
+                                           dest_addr_npi=pdu.params['source_addr_npi'],
+                                           destination_addr=pdu.params['source_addr'],
+                                           esm_class=pdu.params['esm_class'],
+                                           protocol_id=pdu.params['protocol_id'],
+                                           priority_flag=pdu.params['priority_flag'],
+                                           data_coding=pdu.params['data_coding'],
+                                           short_message=h2b(data))
+            smpp.sendDataRequest(deliver)
+            return pdu_types.CommandStatus.ESME_ROK
+        else:
+            return pdu_types.CommandStatus.ESME_RSUBMITFAIL
+
+
+option_parser = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+argparse_add_reader_args(option_parser)
+smpp_group = option_parser.add_argument_group('SMPP Options')
+smpp_group.add_argument('--smpp-bind-port', type=int, default=2775,
+                        help='TCP Port to bind the SMPP socket to')
+smpp_group.add_argument('--smpp-bind-ip', default='::',
+                        help='IPv4/IPv6 address to bind the SMPP socket to')
+smpp_group.add_argument('--smpp-system-id', default='test',
+                        help='SMPP System-ID used by ESME to bind')
+smpp_group.add_argument('--smpp-password', default='test',
+                        help='SMPP Password used by ESME to bind')
+
+if __name__ == '__main__':
+    log_format='%(log_color)s%(levelname)-8s%(reset)s %(name)s: %(message)s'
+    colorlog.basicConfig(level=logging.INFO, format = log_format)
+    logger = colorlog.getLogger()
+
+    opts = option_parser.parse_args()
+
+    tp = init_reader(opts, proactive_handler = Proact())
+    if tp is None:
+        exit(1)
+    tp.connect()
+
+    global g_ms
+    g_ms = MyServer(opts.smpp_bind_port, opts.smpp_bind_ip, opts.smpp_system_id, opts.smpp_password)
+    g_ms.connect_to_card(tp)
+    reactor.run()
+

pySim-trace.py

@@ -8,17 +8,22 @@ from pprint import pprint as pp
 from pySim.apdu import *
 from pySim.runtime import RuntimeState
 
+from osmocom.utils import JsonEncoder
+
 from pySim.cards import UiccCardBase
 from pySim.commands import SimCardCommands
 from pySim.profile import CardProfile
 from pySim.ts_102_221 import CardProfileUICC
 from pySim.ts_31_102 import CardApplicationUSIM
 from pySim.ts_31_103 import CardApplicationISIM
+from pySim.euicc import CardApplicationISDR, CardApplicationECASD
 from pySim.transport import LinkBase
 
 from pySim.apdu_source.gsmtap import GsmtapApduSource
 from pySim.apdu_source.pyshark_rspro import PysharkRsproPcap, PysharkRsproLive
 from pySim.apdu_source.pyshark_gsmtap import PysharkGsmtapPcap
+from pySim.apdu_source.tca_loader_log import TcaLoaderLogApduSource
+from pySim.apdu_source.stdin_hex import StdinHexApduSource
 
 from pySim.apdu.ts_102_221 import UiccSelect, UiccStatus
 
@@ -51,7 +56,7 @@ class DummySimLink(LinkBase):
     def __str__(self):
         return "dummy"
 
-    def _send_apdu_raw(self, pdu):
+    def _send_apdu(self, pdu):
         #print("DummySimLink-apdu: %s" % pdu)
         return [], '9000'
 
@@ -61,7 +66,7 @@ class DummySimLink(LinkBase):
     def disconnect(self):
         pass
 
-    def reset_card(self):
+    def _reset_card(self):
         return 1
 
     def get_atr(self):
@@ -78,6 +83,8 @@ class Tracer:
         profile = CardProfileUICC()
         profile.add_application(CardApplicationUSIM())
         profile.add_application(CardApplicationISIM())
+        profile.add_application(CardApplicationISDR())
+        profile.add_application(CardApplicationECASD())
         scc = SimCardCommands(transport=DummySimLink())
         card = UiccCardBase(scc)
         self.rs = RuntimeState(card, profile)
@@ -93,7 +100,8 @@ class Tracer:
         """Output a single decoded + processed ApduCommand."""
         if self.show_raw_apdu:
             print(apdu)
-        print("%02u %-16s %-35s %-8s %s %s" % (inst.lchan_nr, inst._name, inst.path_str, inst.col_id, inst.col_sw, inst.processed))
+        print("%02u %-16s %-35s %-8s %s %s" % (inst.lchan_nr, inst._name, inst.path_str, inst.col_id,
+                                               inst.col_sw, json.dumps(inst.processed, cls=JsonEncoder)))
         print("===============================")
 
     def format_reset(self, apdu: CardReset):
@@ -144,7 +152,7 @@ global_group.add_argument('--no-suppress-select', action='store_false', dest='su
 global_group.add_argument('--no-suppress-status', action='store_false', dest='suppress_status',
                           help="""
     Don't suppress displaying STATUS APDUs. We normally suppress them as they don't provide any
-    information that was not already received in resposne to the most recent SEELCT.""")
+    information that was not already received in response to the most recent SEELCT.""")
 global_group.add_argument('--show-raw-apdu', action='store_true', dest='show_raw_apdu',
                           help="""Show the raw APDU in addition to its parsed form.""")
 
@@ -178,6 +186,15 @@ parser_rspro_pyshark_live = subparsers.add_parser('rspro-pyshark-live', help="""
 parser_rspro_pyshark_live.add_argument('-i', '--interface', required=True,
                                        help='Name of the network interface to capture on')
 
+parser_tcaloader_log = subparsers.add_parser('tca-loader-log', help="""
+    Read APDUs from a TCA Loader log file.""")
+parser_tcaloader_log.add_argument('-f', '--log-file', required=True,
+                                  help='Name of the log file to be read')
+
+parser_stdin_hex = subparsers.add_parser('stdin-hex', help="""
+    Read APDUs as hex-string from stdin.""")
+
+
 if __name__ == '__main__':
 
     opts = option_parser.parse_args()
@@ -191,6 +208,12 @@ if __name__ == '__main__':
         s = PysharkRsproLive(opts.interface)
     elif opts.source == 'gsmtap-pyshark-pcap':
         s = PysharkGsmtapPcap(opts.pcap_file)
+    elif opts.source == 'tca-loader-log':
+        s = TcaLoaderLogApduSource(opts.log_file)
+    elif opts.source == 'stdin-hex':
+        s = StdinHexApduSource()
+    else:
+        raise ValueError("unsupported source %s", opts.source)
 
     tracer = Tracer(source=s, suppress_status=opts.suppress_status, suppress_select=opts.suppress_select,
                     show_raw_apdu=opts.show_raw_apdu)

pySim/apdu/__init__.py

@@ -1,4 +1,3 @@
-# coding=utf-8
 """APDU (and TPDU) parser for UICC/USIM/ISIM cards.
 
 The File (and its classes) represent the structure / hierarchy
@@ -10,7 +9,7 @@ is far too simplistic, while this decoder can utilize all of the information
 we already know in pySim about the filesystem structure, file encoding, etc.
 """
 
-# (C) 2022 by Harald Welte <laforge@osmocom.org>
+# (C) 2022-2024 by Harald Welte <laforge@osmocom.org>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -27,14 +26,14 @@ we already know in pySim about the filesystem structure, file encoding, etc.
 
 
 import abc
-from termcolor import colored
 import typing
 from typing import List, Dict, Optional
-
-from construct import *
+from termcolor import colored
+from construct import Byte
 from construct import Optional as COptional
-from pySim.construct import *
-from pySim.utils import *
+from osmocom.construct import *
+from osmocom.utils import *
+
 from pySim.runtime import RuntimeLchan, RuntimeState, lchan_nr_from_cla
 from pySim.filesystem import CardADF, CardFile, TransparentEF, LinFixedEF
 
@@ -52,8 +51,8 @@ from pySim.filesystem import CardADF, CardFile, TransparentEF, LinFixedEF
 class ApduCommandMeta(abc.ABCMeta):
     """A meta-class that we can use to set some class variables when declaring
        a derived class of ApduCommand."""
-    def __new__(metacls, name, bases, namespace, **kwargs):
-        x = super().__new__(metacls, name, bases, namespace)
+    def __new__(mcs, name, bases, namespace, **kwargs):
+        x = super().__new__(mcs, name, bases, namespace)
         x._name = namespace.get('name', kwargs.get('n', None))
         x._ins = namespace.get('ins', kwargs.get('ins', None))
         x._cla = namespace.get('cla', kwargs.get('cla', None))
@@ -150,8 +149,10 @@ class ApduCommand(Apdu, metaclass=ApduCommandMeta):
     # fall-back constructs if the derived class provides no override
     _construct_p1 = Byte
     _construct_p2 = Byte
-    _construct = HexAdapter(GreedyBytes)
-    _construct_rsp = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
+    _construct_rsp = GreedyBytes
+    _tlv = None
+    _tlv_rsp = None
 
     def __init__(self, cmd: BytesOrHex, rsp: Optional[BytesOrHex] = None):
         """Instantiate a new ApduCommand from give cmd + resp."""
@@ -187,44 +188,39 @@ class ApduCommand(Apdu, metaclass=ApduCommandMeta):
         if apdu_case in [1, 2]:
             # data is part of response
             return cls(buffer[:5], buffer[5:])
-        elif apdu_case in [3, 4]:
+        if apdu_case in [3, 4]:
             # data is part of command
             lc = buffer[4]
             return cls(buffer[:5+lc], buffer[5+lc:])
-        else:
-            raise ValueError('%s: Invalid APDU Case %u' % (cls.__name__, apdu_case))
+        raise ValueError('%s: Invalid APDU Case %u' % (cls.__name__, apdu_case))
 
     @property
     def path(self) -> List[str]:
         """Return (if known) the path as list of files to the file on which this command operates."""
         if self.file:
             return self.file.fully_qualified_path()
-        else:
-            return []
+        return []
 
     @property
     def path_str(self) -> str:
         """Return (if known) the path as string to the file on which this command operates."""
         if self.file:
             return self.file.fully_qualified_path_str()
-        else:
-            return ''
+        return ''
 
     @property
     def col_sw(self) -> str:
         """Return the ansi-colorized status word. Green==OK, Red==Error"""
         if self.successful:
             return colored(b2h(self.sw), 'green')
-        else:
-            return colored(b2h(self.sw), 'red')
+        return colored(b2h(self.sw), 'red')
 
     @property
     def lchan_nr(self) -> int:
         """Logical channel number over which this ApduCommand was transmitted."""
         if self.lchan:
             return self.lchan.lchan_nr
-        else:
-            return lchan_nr_from_cla(self.cla)
+        return lchan_nr_from_cla(self.cla)
 
     def __str__(self) -> str:
         return '%02u %s(%s): %s' % (self.lchan_nr, type(self).__name__, self.path_str, self.to_dict())
@@ -236,7 +232,7 @@ class ApduCommand(Apdu, metaclass=ApduCommandMeta):
         """Fall-back function to be called if there is no derived-class-specific
         process_global or process_on_lchan method. Uses information from APDU decode."""
         self.processed = {}
-        if not 'p1' in self.cmd_dict:
+        if 'p1' not in self.cmd_dict:
             self.processed = self.to_dict()
         else:
             self.processed['p1'] = self.cmd_dict['p1']
@@ -275,7 +271,7 @@ class ApduCommand(Apdu, metaclass=ApduCommandMeta):
         """Does the given CLA match the CLA list of the command?."""
         if not isinstance(cla, str):
             cla = '%02X' % cla
-        cla = cla.lower()
+        cla = cla.upper()
         # see https://github.com/PyCQA/pylint/issues/7219
         # pylint: disable=no-member
         for cla_match in cls._cla:
@@ -285,7 +281,7 @@ class ApduCommand(Apdu, metaclass=ApduCommandMeta):
                     cla_masked += 'X'
                 else:
                     cla_masked += cla[i]
-            if cla_masked == cla_match:
+            if cla_masked == cla_match.upper():
                 return True
         return False
 
@@ -295,17 +291,26 @@ class ApduCommand(Apdu, metaclass=ApduCommandMeta):
         if callable(method):
             return method()
         else:
-            r = {}
-            method = getattr(self, '_decode_p1p2', None)
-            if callable(method):
-                r = self._decode_p1p2()
+            return self._cmd_to_dict()
+
+    def _cmd_to_dict(self) -> Dict:
+        """back-end function performing automatic decoding using _construct / _tlv."""
+        r = {}
+        method = getattr(self, '_decode_p1p2', None)
+        if callable(method):
+            r = self._decode_p1p2()
+        else:
+            r['p1'] = parse_construct(self._construct_p1, self.p1.to_bytes(1, 'big'))
+            r['p2'] = parse_construct(self._construct_p2, self.p2.to_bytes(1, 'big'))
+        r['p3'] = self.p3
+        if self.cmd_data:
+            if self._tlv:
+                ie = self._tlv()
+                ie.from_tlv(self.cmd_data)
+                r['body'] = ie.to_dict()
             else:
-                r['p1'] = parse_construct(self._construct_p1, self.p1.to_bytes(1, 'big'))
-                r['p2'] = parse_construct(self._construct_p2, self.p2.to_bytes(1, 'big'))
-            r['p3'] = self.p3
-            if self.cmd_data:
                 r['body'] = parse_construct(self._construct, self.cmd_data)
-            return r
+        return r
 
     def rsp_to_dict(self) -> Dict:
         """Convert the Response part of the APDU to a dict."""
@@ -315,7 +320,12 @@ class ApduCommand(Apdu, metaclass=ApduCommandMeta):
         else:
             r = {}
             if self.rsp_data:
-                r['body'] = parse_construct(self._construct_rsp, self.rsp_data)
+                if self._tlv_rsp:
+                    ie = self._tlv_rsp()
+                    ie.from_tlv(self.rsp_data)
+                    r['body'] = ie.to_dict()
+                else:
+                    r['body'] = parse_construct(self._construct_rsp, self.rsp_data)
             r['sw'] = b2h(self.sw)
             return r
 
@@ -428,8 +438,7 @@ class TpduFilter(ApduHandler):
             apdu = Apdu(icmd, tpdu.rsp)
             if self.apdu_handler:
                 return self.apdu_handler.input(apdu)
-            else:
-                return Apdu(icmd, tpdu.rsp)
+            return Apdu(icmd, tpdu.rsp)
 
     def input(self, cmd: bytes, rsp: bytes):
         if isinstance(cmd, str):
@@ -452,7 +461,6 @@ class CardReset:
         self.atr = atr
 
     def __str__(self):
-        if (self.atr):
+        if self.atr:
             return '%s(%s)' % (type(self).__name__, b2h(self.atr))
-        else:
-            return '%s' % (type(self).__name__)
+        return '%s' % (type(self).__name__)

pySim/apdu/global_platform.py

@@ -1,7 +1,7 @@
 # coding=utf-8
 """APDU definition/decoder of GlobalPLatform Card Spec (currently 2.1.1)
 
-(C) 2022 by Harald Welte <laforge@osmocom.org>
+(C) 2022-2024 by Harald Welte <laforge@osmocom.org>
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -17,7 +17,11 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 """
 
+from construct import FlagsEnum, Struct
+from osmocom.tlv import flatten_dict_lists
+from osmocom.construct import *
 from pySim.apdu import ApduCommand, ApduCommandSet
+from pySim.global_platform import InstallParameters
 
 class GpDelete(ApduCommand, n='DELETE', ins=0xE4, cla=['8X', 'CX', 'EX']):
     _apdu_case = 4
@@ -40,8 +44,29 @@ class GpGetDataCB(ApduCommand, n='GET DATA', ins=0xCB, cla=['8X', 'CX', 'EX']):
 class GpGetStatus(ApduCommand, n='GET STATUS', ins=0xF2, cla=['8X', 'CX', 'EX']):
     _apdu_case = 4
 
+# GPCS Section 11.5.2
 class GpInstall(ApduCommand, n='INSTALL', ins=0xE6, cla=['8X', 'CX', 'EX']):
     _apdu_case = 4
+    _construct_p1 = FlagsEnum(Byte, more_commands=0x80, for_registry_update=0x40,
+                              for_personalization=0x20, for_extradition=0x10,
+                              for_make_selectable=0x08, for_install=0x04, for_load=0x02)
+    _construct_p2 = Enum(Byte, no_info_provided=0x00, beginning_of_combined=0x01,
+                         end_of_combined=0x03)
+    _construct = Struct('load_file_aid'/Prefixed(Int8ub, GreedyBytes),
+                        'module_aid'/Prefixed(Int8ub, GreedyBytes),
+                        'application_aid'/Prefixed(Int8ub, GreedyBytes),
+                        'privileges'/Prefixed(Int8ub, GreedyBytes),
+                        'install_parameters'/Prefixed(Int8ub, GreedyBytes), # TODO: InstallParameters
+                        'install_token'/Prefixed(Int8ub, GreedyBytes))
+    def _decode_cmd(self):
+        # first use _construct* above
+        res = self._cmd_to_dict()
+        # then do TLV decode of install_parameters
+        ip = InstallParameters()
+        ip.from_tlv(res['body']['install_parameters'])
+        res['body']['install_parameters'] = flatten_dict_lists(ip.to_dict())
+        return res
+
 
 class GpLoad(ApduCommand, n='LOAD', ins=0xE8, cla=['8X', 'CX', 'EX']):
     _apdu_case = 4

pySim/apdu/ts_102_221.py

@@ -1,7 +1,7 @@
 # coding=utf-8
 """APDU definitions/decoders of ETSI TS 102 221, the core UICC spec.
 
-(C) 2022 by Harald Welte <laforge@osmocom.org>
+(C) 2022-2024 by Harald Welte <laforge@osmocom.org>
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -17,12 +17,18 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 """
 
+from typing import Optional, Dict
 import logging
-from pySim.construct import *
+
+from construct import GreedyRange, Struct
+
+from osmocom.utils import i2h
+from osmocom.construct import *
+
 from pySim.filesystem import *
 from pySim.runtime import RuntimeLchan
 from pySim.apdu import ApduCommand, ApduCommandSet
-from typing import Optional, Dict, Tuple
+from pySim import cat
 
 logger = logging.getLogger(__name__)
 
@@ -94,7 +100,7 @@ class UiccSelect(ApduCommand, n='SELECT', ins=0xA4, cla=['0X', '4X', '6X']):
                 logger.warning('SELECT UNKNOWN FID %s', file_hex)
         elif mode == 'df_name':
             # Select by AID (can be sub-string!)
-            aid = self.cmd_dict['body']
+            aid = b2h(self.cmd_dict['body'])
             sels = lchan.rs.mf.get_app_selectables(['AIDS'])
             adf = self._find_aid_substr(sels, aid)
             if adf:
@@ -103,7 +109,6 @@ class UiccSelect(ApduCommand, n='SELECT', ins=0xA4, cla=['0X', '4X', '6X']):
                 #print("\tSELECT AID %s" % adf)
             else:
                 logger.warning('SELECT UNKNOWN AID %s', aid)
-                pass
         else:
             raise ValueError('Select Mode %s not implemented' % mode)
         # decode the SELECT response
@@ -111,7 +116,7 @@ class UiccSelect(ApduCommand, n='SELECT', ins=0xA4, cla=['0X', '4X', '6X']):
             self.file = lchan.selected_file
             if 'body' in self.rsp_dict:
                 # not every SELECT is asking for the FCP in response...
-                return lchan.selected_file.decode_select_response(self.rsp_dict['body'])
+                return lchan.selected_file.decode_select_response(b2h(self.rsp_dict['body']))
         return None
 
 
@@ -124,7 +129,7 @@ class UiccStatus(ApduCommand, n='STATUS', ins=0xF2, cla=['8X', 'CX', 'EX']):
 
     def process_on_lchan(self, lchan):
         if self.cmd_dict['p2'] == 'response_like_select':
-            return lchan.selected_file.decode_select_response(self.rsp_dict['body'])
+            return lchan.selected_file.decode_select_response(b2h(self.rsp_dict['body']))
 
 def _decode_binary_p1p2(p1, p2) -> Dict:
     ret = {}
@@ -290,12 +295,9 @@ class VerifyPin(ApduCommand, n='VERIFY PIN', ins=0x20, cla=['0X', '4X', '6X']):
 
     @staticmethod
     def _pin_is_success(sw):
-        if sw[0] == 0x63:
-            return True
-        else:
-            return False
+        return bool(sw[0] == 0x63)
 
-    def process_on_lchan(self, lchan: RuntimeLchan):
+    def process_on_lchan(self, _lchan: RuntimeLchan):
         return VerifyPin._pin_process(self)
 
     def _is_success(self):
@@ -307,7 +309,7 @@ class ChangePin(ApduCommand, n='CHANGE PIN', ins=0x24, cla=['0X', '4X', '6X']):
     _apdu_case = 3
     _construct_p2 = PinConstructP2
 
-    def process_on_lchan(self, lchan: RuntimeLchan):
+    def process_on_lchan(self, _lchan: RuntimeLchan):
         return VerifyPin._pin_process(self)
 
     def _is_success(self):
@@ -319,7 +321,7 @@ class DisablePin(ApduCommand, n='DISABLE PIN', ins=0x26, cla=['0X', '4X', '6X'])
     _apdu_case = 3
     _construct_p2 = PinConstructP2
 
-    def process_on_lchan(self, lchan: RuntimeLchan):
+    def process_on_lchan(self, _lchan: RuntimeLchan):
         return VerifyPin._pin_process(self)
 
     def _is_success(self):
@@ -330,7 +332,7 @@ class DisablePin(ApduCommand, n='DISABLE PIN', ins=0x26, cla=['0X', '4X', '6X'])
 class EnablePin(ApduCommand, n='ENABLE PIN', ins=0x28, cla=['0X', '4X', '6X']):
     _apdu_case = 3
     _construct_p2 = PinConstructP2
-    def process_on_lchan(self, lchan: RuntimeLchan):
+    def process_on_lchan(self, _lchan: RuntimeLchan):
         return VerifyPin._pin_process(self)
 
     def _is_success(self):
@@ -342,7 +344,7 @@ class UnblockPin(ApduCommand, n='UNBLOCK PIN', ins=0x2C, cla=['0X', '4X', '6X'])
     _apdu_case = 3
     _construct_p2 = PinConstructP2
 
-    def process_on_lchan(self, lchan: RuntimeLchan):
+    def process_on_lchan(self, _lchan: RuntimeLchan):
         return VerifyPin._pin_process(self)
 
     def _is_success(self):
@@ -395,13 +397,12 @@ class ManageChannel(ApduCommand, n='MANAGE CHANNEL', ins=0x70, cla=['0X', '4X',
             manage_channel.add_lchan(created_channel_nr)
             self.col_id = '%02u' % created_channel_nr
             return {'mode': mode, 'created_channel': created_channel_nr }
-        elif mode == 'close_channel':
+        if mode == 'close_channel':
             closed_channel_nr = self.cmd_dict['p2']['logical_channel_number']
             rs.del_lchan(closed_channel_nr)
             self.col_id = '%02u' % closed_channel_nr
             return {'mode': mode, 'closed_channel': closed_channel_nr }
-        else:
-            raise ValueError('Unsupported MANAGE CHANNEL P1=%02X' % self.p1)
+        raise ValueError('Unsupported MANAGE CHANNEL P1=%02X' % self.p1)
 
 # TS 102 221 Section 11.1.18
 class GetChallenge(ApduCommand, n='GET CHALLENGE', ins=0x84, cla=['0X', '4X', '6X']):
@@ -419,13 +420,13 @@ class ManageSecureChannel(ApduCommand, n='MANAGE SECURE CHANNEL', ins=0x73, cla=
         p2 = hdr[3]
         if p1 & 0x7 == 0:   # retrieve UICC Endpoints
             return 2
-        elif p1 & 0xf in [1,2,3]:   # establish sa, start secure channel SA
+        if p1 & 0xf in [1,2,3]:   # establish sa, start secure channel SA
             p2_cmd = p2 >> 5
             if p2_cmd in [0,2,4]:   # command data
                 return 3
-            elif p2_cmd in [1,3,5]: # response data
+            if p2_cmd in [1,3,5]: # response data
                 return 2
-        elif p1 & 0xf == 4:         # terminate secure channel SA
+        if p1 & 0xf == 4:         # terminate secure channel SA
             return 3
         raise ValueError('%s: Unable to detect APDU case for %s' % (cls.__name__, b2h(hdr)))
 
@@ -436,8 +437,7 @@ class TransactData(ApduCommand, n='TRANSACT DATA', ins=0x75, cla=['0X', '4X', '6
         p1 = hdr[2]
         if p1 & 0x04:
             return 3
-        else:
-            return 2
+        return 2
 
 # TS 102 221 Section 11.1.22
 class SuspendUicc(ApduCommand, n='SUSPEND UICC', ins=0x76, cla=['80']):
@@ -460,14 +460,17 @@ class TerminalProfile(ApduCommand, n='TERMINAL PROFILE', ins=0x10, cla=['80']):
 # TS 102 221 Section 11.2.2 / TS 102 223
 class Envelope(ApduCommand, n='ENVELOPE', ins=0xC2, cla=['80']):
     _apdu_case = 4
+    _tlv = cat.EventCollection
 
 # TS 102 221 Section 11.2.3 / TS 102 223
 class Fetch(ApduCommand, n='FETCH', ins=0x12, cla=['80']):
     _apdu_case = 2
+    _tlv_rsp = cat.ProactiveCommand
 
 # TS 102 221 Section 11.2.3 / TS 102 223
 class TerminalResponse(ApduCommand, n='TERMINAL RESPONSE', ins=0x14, cla=['80']):
     _apdu_case = 3
+    _tlv = cat.TerminalResponse
 
 # TS 102 221 Section 11.3.1
 class RetrieveData(ApduCommand, n='RETRIEVE DATA', ins=0xCB, cla=['8X', 'CX', 'EX']):

pySim/apdu/ts_102_222.py

@@ -0,0 +1,60 @@
+# coding=utf-8
+"""APDU definitions/decoders of ETSI TS 102 222.
+
+(C) 2022-2024 by Harald Welte <laforge@osmocom.org>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+
+import logging
+
+from construct import Struct
+from osmocom.construct import *
+
+from pySim.apdu import ApduCommand, ApduCommandSet
+from pySim.ts_102_221 import FcpTemplate
+
+logger = logging.getLogger(__name__)
+
+# TS 102 222 Section 6.3
+class CreateFile(ApduCommand, n='CREATE FILE', ins=0xE0, cla=['0X', '4X', 'EX']):
+    _apdu_case = 3
+    _tlv = FcpTemplate
+
+# TS 102 222 Section 6.4
+class DeleteFile(ApduCommand, n='DELETE FILE', ins=0xE4, cla=['0X', '4X']):
+    _apdu_case = 3
+    _construct = Struct('file_id'/Bytes(2))
+
+# TS 102 222 Section 6.7
+class TerminateDF(ApduCommand, n='TERMINATE DF', ins=0xE6, cla=['0X', '4X']):
+    _apdu_case = 1
+
+# TS 102 222 Section 6.8
+class TerminateEF(ApduCommand, n='TERMINATE EF', ins=0xE8, cla=['0X', '4X']):
+    _apdu_case = 1
+
+# TS 102 222 Section 6.9
+class TerminateCardUsage(ApduCommand, n='TERMINATE CARD USAGE', ins=0xFE, cla=['0X', '4X']):
+    _apdu_case = 1
+
+# TS 102 222 Section 6.10
+class ResizeFile(ApduCommand, n='RESIZE FILE', ins=0xD4, cla=['8X', 'CX', 'EX']):
+    _apdu_case = 3
+    _construct_p1 = Enum(Byte, mode_0=0, mode_1=1)
+    _tlv = FcpTemplate
+
+
+ApduCommands = ApduCommandSet('TS 102 222', cmds=[CreateFile, DeleteFile, TerminateDF,
+                                                  TerminateEF, TerminateCardUsage, ResizeFile])

pySim/apdu/ts_31_102.py

@@ -9,12 +9,12 @@ APDU commands of 3GPP TS 31.102 V16.6.0
 """
 from typing import Dict
 
-from construct import *
+from construct import BitStruct, Enum, BitsInteger, Int8ub, this, Struct, If, Switch, Const
 from construct import Optional as COptional
-from pySim.filesystem import *
-from pySim.construct import *
-from pySim.ts_31_102 import SUCI_TlvDataObject
+from osmocom.construct import *
 
+from pySim.filesystem import *
+from pySim.ts_31_102 import SUCI_TlvDataObject
 from pySim.apdu import ApduCommand, ApduCommandSet
 
 # Copyright (C) 2022 Harald Welte <laforge@osmocom.org>
@@ -35,8 +35,6 @@ from pySim.apdu import ApduCommand, ApduCommandSet
 
 # Mapping between USIM Service Number and its description
 
-from pySim.apdu import ApduCommand, ApduCommandSet
-
 # TS 31.102 Section 7.1
 class UsimAuthenticateEven(ApduCommand, n='AUTHENTICATE', ins=0x88, cla=['0X', '4X', '6X']):
     _apdu_case = 4
@@ -44,28 +42,28 @@ class UsimAuthenticateEven(ApduCommand, n='AUTHENTICATE', ins=0x88, cla=['0X', '
                               BitsInteger(4),
                               'authentication_context'/Enum(BitsInteger(3), gsm=0, umts=1,
                                                             vgcs_vbs=2, gba=4))
-    _cs_cmd_gsm_3g =  Struct('_rand_len'/Int8ub, 'rand'/HexAdapter(Bytes(this._rand_len)),
-                         '_autn_len'/COptional(Int8ub), 'autn'/If(this._autn_len, HexAdapter(Bytes(this._autn_len))))
-    _cs_cmd_vgcs = Struct('_vsid_len'/Int8ub, 'vservice_id'/HexAdapter(Bytes(this._vsid_len)),
-                          '_vkid_len'/Int8ub, 'vk_id'/HexAdapter(Bytes(this._vkid_len)),
-                          '_vstk_rand_len'/Int8ub, 'vstk_rand'/HexAdapter(Bytes(this._vstk_rand_len)))
-    _cmd_gba_bs = Struct('_rand_len'/Int8ub, 'rand'/HexAdapter(Bytes(this._rand_len)),
-                         '_autn_len'/Int8ub, 'autn'/HexAdapter(Bytes(this._autn_len)))
-    _cmd_gba_naf = Struct('_naf_id_len'/Int8ub, 'naf_id'/HexAdapter(Bytes(this._naf_id_len)),
-                          '_impi_len'/Int8ub, 'impi'/HexAdapter(Bytes(this._impi_len)))
+    _cs_cmd_gsm_3g =  Struct('_rand_len'/Int8ub, 'rand'/Bytes(this._rand_len),
+                         '_autn_len'/COptional(Int8ub), 'autn'/If(this._autn_len, Bytes(this._autn_len)))
+    _cs_cmd_vgcs = Struct('_vsid_len'/Int8ub, 'vservice_id'/Bytes(this._vsid_len),
+                          '_vkid_len'/Int8ub, 'vk_id'/Bytes(this._vkid_len),
+                          '_vstk_rand_len'/Int8ub, 'vstk_rand'/Bytes(this._vstk_rand_len))
+    _cmd_gba_bs = Struct('_rand_len'/Int8ub, 'rand'/Bytes(this._rand_len),
+                         '_autn_len'/Int8ub, 'autn'/Bytes(this._autn_len))
+    _cmd_gba_naf = Struct('_naf_id_len'/Int8ub, 'naf_id'/Bytes(this._naf_id_len),
+                          '_impi_len'/Int8ub, 'impi'/Bytes(this._impi_len))
     _cs_cmd_gba = Struct('tag'/Int8ub, 'body'/Switch(this.tag, { 0xDD: 'bootstrap'/_cmd_gba_bs,
                                                                  0xDE: 'naf_derivation'/_cmd_gba_naf }))
-    _cs_rsp_gsm = Struct('_len_sres'/Int8ub, 'sres'/HexAdapter(Bytes(this._len_sres)),
-                         '_len_kc'/Int8ub, 'kc'/HexAdapter(Bytes(this._len_kc)))
-    _rsp_3g_ok = Struct('_len_res'/Int8ub, 'res'/HexAdapter(Bytes(this._len_res)),
-                        '_len_ck'/Int8ub, 'ck'/HexAdapter(Bytes(this._len_ck)),
-                        '_len_ik'/Int8ub, 'ik'/HexAdapter(Bytes(this._len_ik)),
-                        '_len_kc'/COptional(Int8ub), 'kc'/If(this._len_kc, HexAdapter(Bytes(this._len_kc))))
-    _rsp_3g_sync = Struct('_len_auts'/Int8ub, 'auts'/HexAdapter(Bytes(this._len_auts)))
+    _cs_rsp_gsm = Struct('_len_sres'/Int8ub, 'sres'/Bytes(this._len_sres),
+                         '_len_kc'/Int8ub, 'kc'/Bytes(this._len_kc))
+    _rsp_3g_ok = Struct('_len_res'/Int8ub, 'res'/Bytes(this._len_res),
+                        '_len_ck'/Int8ub, 'ck'/Bytes(this._len_ck),
+                        '_len_ik'/Int8ub, 'ik'/Bytes(this._len_ik),
+                        '_len_kc'/COptional(Int8ub), 'kc'/If(this._len_kc, Bytes(this._len_kc)))
+    _rsp_3g_sync = Struct('_len_auts'/Int8ub, 'auts'/Bytes(this._len_auts))
     _cs_rsp_3g = Struct('tag'/Int8ub, 'body'/Switch(this.tag, { 0xDB: 'success'/_rsp_3g_ok,
                                                                 0xDC: 'sync_fail'/_rsp_3g_sync}))
-    _cs_rsp_vgcs = Struct(Const(b'\xDB'), '_vstk_len'/Int8ub, 'vstk'/HexAdapter(Bytes(this._vstk_len)))
-    _cs_rsp_gba_naf = Struct(Const(b'\xDB'), '_ks_ext_naf_len'/Int8ub, 'ks_ext_naf'/HexAdapter(Bytes(this._ks_ext_naf_len)))
+    _cs_rsp_vgcs = Struct(Const(b'\xDB'), '_vstk_len'/Int8ub, 'vstk'/Bytes(this._vstk_len))
+    _cs_rsp_gba_naf = Struct(Const(b'\xDB'), '_ks_ext_naf_len'/Int8ub, 'ks_ext_naf'/Bytes(this._ks_ext_naf_len))
     def _decode_cmd(self) -> Dict:
         r = {}
         r['p1'] = parse_construct(self._construct_p1, self.p1.to_bytes(1, 'big'))

pySim/apdu_source/__init__.py

@@ -14,7 +14,6 @@ class ApduSource(abc.ABC):
     @abc.abstractmethod
     def read_packet(self) -> PacketType:
         """Read one packet from the source."""
-        pass
 
     def read(self) -> Union[Apdu, CardReset]:
         """Main function to call by the user: Blocking read, returns Apdu or CardReset."""
@@ -31,5 +30,5 @@ class ApduSource(abc.ABC):
             elif isinstance(r, CardReset):
                 apdu = r
             else:
-                ValueError('Unknown read_packet() return %s' % r)
+                raise ValueError('Unknown read_packet() return %s' % r)
         return apdu

pySim/apdu_source/gsmtap.py

@@ -16,13 +16,16 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
-from pySim.gsmtap import GsmtapMessage, GsmtapSource
-from . import ApduSource, PacketType, CardReset
+from osmocom.gsmtap import GsmtapReceiver
 
 from pySim.apdu.ts_102_221 import ApduCommands as UiccApduCommands
+from pySim.apdu.ts_102_222 import ApduCommands as UiccAdmApduCommands
 from pySim.apdu.ts_31_102 import ApduCommands as UsimApduCommands
 from pySim.apdu.global_platform import ApduCommands as GpApduCommands
-ApduCommands = UiccApduCommands + UsimApduCommands + GpApduCommands
+
+from . import ApduSource, PacketType, CardReset
+
+ApduCommands = UiccApduCommands + UiccAdmApduCommands + UsimApduCommands + GpApduCommands
 
 class GsmtapApduSource(ApduSource):
     """ApduSource for handling GSMTAP-SIM messages received via UDP, such as
@@ -38,19 +41,19 @@ class GsmtapApduSource(ApduSource):
             bind_port: UDP port number to which the socket should be bound (default: 4729)
         """
         super().__init__()
-        self.gsmtap = GsmtapSource(bind_ip, bind_port)
+        self.gsmtap = GsmtapReceiver(bind_ip, bind_port)
 
     def read_packet(self) -> PacketType:
-        gsmtap_msg, addr = self.gsmtap.read_packet()
+        gsmtap_msg, _addr = self.gsmtap.read_packet()
         if gsmtap_msg['type'] != 'sim':
             raise ValueError('Unsupported GSMTAP type %s' % gsmtap_msg['type'])
         sub_type = gsmtap_msg['sub_type']
         if sub_type == 'apdu':
             return ApduCommands.parse_cmd_bytes(gsmtap_msg['body'])
-        elif sub_type == 'atr':
+        if sub_type == 'atr':
             # card has been reset
             return CardReset(gsmtap_msg['body'])
-        elif sub_type in ['pps_req', 'pps_rsp']:
+        if sub_type in ['pps_req', 'pps_rsp']:
             # simply ignore for now
             pass
         else:

pySim/apdu_source/pyshark_gsmtap.py

@@ -16,21 +16,20 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
-import sys
 import logging
-from pprint import pprint as pp
 from typing import Tuple
 import pyshark
+from osmocom.gsmtap import GsmtapMessage
 
-from pySim.utils import h2b, b2h
-from pySim.apdu import Tpdu
-from pySim.gsmtap import GsmtapMessage
-from . import ApduSource, PacketType, CardReset
-
+from pySim.utils import h2b
 from pySim.apdu.ts_102_221 import ApduCommands as UiccApduCommands
+from pySim.apdu.ts_102_222 import ApduCommands as UiccAdmApduCommands
 from pySim.apdu.ts_31_102 import ApduCommands as UsimApduCommands
 from pySim.apdu.global_platform import ApduCommands as GpApduCommands
-ApduCommands = UiccApduCommands + UsimApduCommands + GpApduCommands
+
+from . import ApduSource, PacketType, CardReset
+
+ApduCommands = UiccApduCommands + UiccAdmApduCommands + UsimApduCommands + GpApduCommands
 
 logger = logging.getLogger(__name__)
 
@@ -67,10 +66,10 @@ class _PysharkGsmtap(ApduSource):
         sub_type = gsmtap_msg['sub_type']
         if sub_type == 'apdu':
             return ApduCommands.parse_cmd_bytes(gsmtap_msg['body'])
-        elif sub_type == 'atr':
+        if sub_type == 'atr':
             # card has been reset
             return CardReset(gsmtap_msg['body'])
-        elif sub_type in ['pps_req', 'pps_rsp']:
+        if sub_type in ['pps_req', 'pps_rsp']:
             # simply ignore for now
             pass
         else:
@@ -85,6 +84,5 @@ class PysharkGsmtapPcap(_PysharkGsmtap):
         Args:
             pcap_filename: File name of the pcap file to be opened
         """
-        pyshark_inst = pyshark.FileCapture(pcap_filename, display_filter='gsm_sim', use_json=True, keep_packets=False)
+        pyshark_inst = pyshark.FileCapture(pcap_filename, display_filter='gsm_sim || iso7816.atr', use_json=True, keep_packets=False)
         super().__init__(pyshark_inst)
-

pySim/apdu_source/pyshark_rspro.py

@@ -16,13 +16,11 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
-import sys
 import logging
-from pprint import pprint as pp
 from typing import Tuple
 import pyshark
 
-from pySim.utils import h2b, b2h
+from pySim.utils import h2b
 from pySim.apdu import Tpdu
 from . import ApduSource, PacketType, CardReset
 

pySim/apdu_source/stdin_hex.py

@@ -0,0 +1,39 @@
+# coding=utf-8
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+from pySim.utils import h2b
+
+from pySim.apdu.ts_102_221 import ApduCommands as UiccApduCommands
+from pySim.apdu.ts_102_222 import ApduCommands as UiccAdmApduCommands
+from pySim.apdu.ts_31_102 import ApduCommands as UsimApduCommands
+from pySim.apdu.global_platform import ApduCommands as GpApduCommands
+
+from . import ApduSource, PacketType, CardReset
+
+ApduCommands = UiccApduCommands + UiccAdmApduCommands + UsimApduCommands + GpApduCommands
+
+class StdinHexApduSource(ApduSource):
+    """ApduSource for reading apdu hex-strings from stdin."""
+
+    def read_packet(self) -> PacketType:
+        while True:
+            command = input("C-APDU >")
+            if len(command) == 0:
+                continue
+            response = '9000'
+            return ApduCommands.parse_cmd_bytes(h2b(command) + h2b(response))

pySim/apdu_source/tca_loader_log.py

@@ -0,0 +1,48 @@
+# coding=utf-8
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+from pySim.utils import h2b
+
+from pySim.apdu.ts_102_221 import ApduCommands as UiccApduCommands
+from pySim.apdu.ts_102_222 import ApduCommands as UiccAdmApduCommands
+from pySim.apdu.ts_31_102 import ApduCommands as UsimApduCommands
+from pySim.apdu.global_platform import ApduCommands as GpApduCommands
+
+from . import ApduSource, PacketType, CardReset
+
+ApduCommands = UiccApduCommands + UiccAdmApduCommands + UsimApduCommands + GpApduCommands
+
+class TcaLoaderLogApduSource(ApduSource):
+    """ApduSource for reading log files created by TCALoader."""
+    def __init__(self, filename:str):
+        super().__init__()
+        self.logfile = open(filename, 'r')
+
+    def read_packet(self) -> PacketType:
+        command = None
+        response = None
+        for line in self.logfile:
+            if line.startswith('Command'):
+                command = line.split()[1]
+                print("Command: '%s'" % command)
+                pass
+            elif command and line.startswith('Response'):
+                response = line.split()[1]
+                print("Response: '%s'" % response)
+                return ApduCommands.parse_cmd_bytes(h2b(command) + h2b(response))
+        raise StopIteration

pySim/app.py

@@ -19,13 +19,13 @@ from typing import Tuple
 from pySim.transport import LinkBase
 from pySim.commands import SimCardCommands
 from pySim.filesystem import CardModel, CardApplication
-from pySim.cards import card_detect, SimCardBase, UiccCardBase
-from pySim.exceptions import NoCardError
+from pySim.cards import card_detect, SimCardBase, UiccCardBase, CardBase
 from pySim.runtime import RuntimeState
 from pySim.profile import CardProfile
 from pySim.cdma_ruim import CardProfileRUIM
 from pySim.ts_102_221 import CardProfileUICC
 from pySim.utils import all_subclasses
+from pySim.exceptions import SwMatchError
 
 # we need to import this module so that the SysmocomSJA2 sub-class of
 # CardModel is created, which will add the ATR-based matching and
@@ -42,7 +42,7 @@ import pySim.ara_m
 import pySim.global_platform
 import pySim.euicc
 
-def init_card(sl: LinkBase) -> Tuple[RuntimeState, SimCardBase]:
+def init_card(sl: LinkBase, skip_card_init: bool = False) -> Tuple[RuntimeState, SimCardBase]:
     """
     Detect card in reader and setup card profile and runtime state. This
     function must be called at least once on startup. The card and runtime
@@ -57,6 +57,12 @@ def init_card(sl: LinkBase) -> Tuple[RuntimeState, SimCardBase]:
     print("Waiting for card...")
     sl.wait_for_card(3)
 
+    # The user may opt to skip all card initialization. In this case only the
+    # most basic card profile is selected. This mode is suitable for blank
+    # cards that need card O/S initialization using APDU scripts first.
+    if skip_card_init:
+        return None, CardBase(scc)
+
     generic_card = False
     card = card_detect(scc)
     if card is None:
@@ -107,7 +113,16 @@ def init_card(sl: LinkBase) -> Tuple[RuntimeState, SimCardBase]:
     # inform the transport that we can do context-specific SW interpretation
     sl.set_sw_interpreter(rs)
 
+    # try to obtain the EID, if any
+    isd_r = rs.mf.applications.get(pySim.euicc.AID_ISD_R.lower(), None)
+    if isd_r:
+        rs.lchan[0].select_file(isd_r)
+        try:
+            rs.identity['EID'] = pySim.euicc.CardApplicationISDR.get_eid(scc)
+        except SwMatchError:
+            # has ISD-R but not a SGP.22/SGP.32 eUICC - maybe SGP.02?
+            pass
+        finally:
+            rs.reset()
+
     return rs, card
-
-
-

pySim/ara_m.py

@@ -26,28 +26,29 @@ Support for the Secure Element Access Control, specifically the ARA-M inside an
 #
 
 
-from construct import *
+from construct import GreedyString, Struct, Enum, Int8ub, Int16ub
 from construct import Optional as COptional
-from pySim.construct import *
+from osmocom.construct import *
+from osmocom.tlv import *
+from osmocom.utils import Hexstr
 from pySim.filesystem import *
-from pySim.tlv import *
 import pySim.global_platform
 
 # various BER-TLV encoded Data Objects (DOs)
 
 
 class AidRefDO(BER_TLV_IE, tag=0x4f):
-    # SEID v1.1 Table 6-3
+    # GPD_SPE_013 v1.1 Table 6-3
     _construct = HexAdapter(GreedyBytes)
 
 
 class AidRefEmptyDO(BER_TLV_IE, tag=0xc0):
-    # SEID v1.1 Table 6-3
+    # GPD_SPE_013 v1.1 Table 6-3
     pass
 
 
 class DevAppIdRefDO(BER_TLV_IE, tag=0xc1):
-    # SEID v1.1 Table 6-4
+    # GPD_SPE_013 v1.1 Table 6-4
     _construct = HexAdapter(GreedyBytes)
 
 
@@ -57,59 +58,57 @@ class PkgRefDO(BER_TLV_IE, tag=0xca):
 
 
 class RefDO(BER_TLV_IE, tag=0xe1, nested=[AidRefDO, AidRefEmptyDO, DevAppIdRefDO, PkgRefDO]):
-    # SEID v1.1 Table 6-5
+    # GPD_SPE_013 v1.1 Table 6-5
     pass
 
 
 class ApduArDO(BER_TLV_IE, tag=0xd0):
-    # SEID v1.1 Table 6-8
+    # GPD_SPE_013 v1.1 Table 6-8
     def _from_bytes(self, do: bytes):
         if len(do) == 1:
             if do[0] == 0x00:
                 self.decoded = {'generic_access_rule': 'never'}
                 return self.decoded
-            elif do[0] == 0x01:
+            if do[0] == 0x01:
                 self.decoded = {'generic_access_rule': 'always'}
                 return self.decoded
-            else:
-                return ValueError('Invalid 1-byte generic APDU access rule')
+            raise ValueError('Invalid 1-byte generic APDU access rule')
         else:
             if len(do) % 8:
-                return ValueError('Invalid non-modulo-8 length of APDU filter: %d' % len(do))
-            self.decoded['apdu_filter'] = []
+                raise ValueError('Invalid non-modulo-8 length of APDU filter: %d' % len(do))
+            self.decoded = {'apdu_filter': []}
             offset = 0
             while offset < len(do):
-                self.decoded['apdu_filter'] += {'header': b2h(do[offset:offset+4]),
-                                                'mask': b2h(do[offset+4:offset+8])}
-            self.decoded = res
-            return res
+                self.decoded['apdu_filter'] += [{'header': b2h(do[offset:offset+4]),
+                                                'mask': b2h(do[offset+4:offset+8])}]
+                offset += 8 # Move offset to the beginning of the next apdu_filter object
+            return self.decoded
 
     def _to_bytes(self):
         if 'generic_access_rule' in self.decoded:
             if self.decoded['generic_access_rule'] == 'never':
                 return b'\x00'
-            elif self.decoded['generic_access_rule'] == 'always':
+            if self.decoded['generic_access_rule'] == 'always':
                 return b'\x01'
-            else:
-                return ValueError('Invalid 1-byte generic APDU access rule')
+            raise ValueError('Invalid 1-byte generic APDU access rule')
         else:
             if not 'apdu_filter' in self.decoded:
-                return ValueError('Invalid APDU AR DO')
+                raise ValueError('Invalid APDU AR DO')
             filters = self.decoded['apdu_filter']
             res = b''
             for f in filters:
                 if not 'header' in f or not 'mask' in f:
-                    return ValueError('APDU filter must contain header and mask')
+                    raise ValueError('APDU filter must contain header and mask')
                 header_b = h2b(f['header'])
                 mask_b = h2b(f['mask'])
                 if len(header_b) != 4 or len(mask_b) != 4:
-                    return ValueError('APDU filter header and mask must each be 4 bytes')
+                    raise ValueError('APDU filter header and mask must each be 4 bytes')
                 res += header_b + mask_b
             return res
 
 
 class NfcArDO(BER_TLV_IE, tag=0xd1):
-    # SEID v1.1 Table 6-9
+    # GPD_SPE_013 v1.1 Table 6-9
     _construct = Struct('nfc_event_access_rule' /
                         Enum(Int8ub, never=0, always=1))
 
@@ -121,124 +120,122 @@ class PermArDO(BER_TLV_IE, tag=0xdb):
 
 
 class ArDO(BER_TLV_IE, tag=0xe3, nested=[ApduArDO, NfcArDO, PermArDO]):
-    # SEID v1.1 Table 6-7
+    # GPD_SPE_013 v1.1 Table 6-7
     pass
 
 
 class RefArDO(BER_TLV_IE, tag=0xe2, nested=[RefDO, ArDO]):
-    # SEID v1.1 Table 6-6
+    # GPD_SPE_013 v1.1 Table 6-6
     pass
 
 
 class ResponseAllRefArDO(BER_TLV_IE, tag=0xff40, nested=[RefArDO]):
-    # SEID v1.1 Table 4-2
+    # GPD_SPE_013 v1.1 Table 4-2
     pass
 
 
 class ResponseArDO(BER_TLV_IE, tag=0xff50, nested=[ArDO]):
-    # SEID v1.1 Table 4-3
+    # GPD_SPE_013 v1.1 Table 4-3
     pass
 
 
 class ResponseRefreshTagDO(BER_TLV_IE, tag=0xdf20):
-    # SEID v1.1 Table 4-4
+    # GPD_SPE_013 v1.1 Table 4-4
     _construct = Struct('refresh_tag'/HexAdapter(Bytes(8)))
 
 
 class DeviceInterfaceVersionDO(BER_TLV_IE, tag=0xe6):
-    # SEID v1.1 Table 6-12
+    # GPD_SPE_013 v1.1 Table 6-12
     _construct = Struct('major'/Int8ub, 'minor'/Int8ub, 'patch'/Int8ub)
 
 
 class DeviceConfigDO(BER_TLV_IE, tag=0xe4, nested=[DeviceInterfaceVersionDO]):
-    # SEID v1.1 Table 6-10
+    # GPD_SPE_013 v1.1 Table 6-10
     pass
 
 
 class ResponseDeviceConfigDO(BER_TLV_IE, tag=0xff7f, nested=[DeviceConfigDO]):
-    # SEID v1.1 Table 5-14
+    # GPD_SPE_013 v1.1 Table 5-14
     pass
 
 
 class AramConfigDO(BER_TLV_IE, tag=0xe5, nested=[DeviceInterfaceVersionDO]):
-    # SEID v1.1 Table 6-11
+    # GPD_SPE_013 v1.1 Table 6-11
     pass
 
 
 class ResponseAramConfigDO(BER_TLV_IE, tag=0xdf21, nested=[AramConfigDO]):
-    # SEID v1.1 Table 4-5
+    # GPD_SPE_013 v1.1 Table 4-5
     pass
 
 
 class CommandStoreRefArDO(BER_TLV_IE, tag=0xf0, nested=[RefArDO]):
-    # SEID v1.1 Table 5-2
+    # GPD_SPE_013 v1.1 Table 5-2
     pass
 
 
 class CommandDelete(BER_TLV_IE, tag=0xf1, nested=[AidRefDO, AidRefEmptyDO, RefDO, RefArDO]):
-    # SEID v1.1 Table 5-4
+    # GPD_SPE_013 v1.1 Table 5-4
     pass
 
 
 class CommandUpdateRefreshTagDO(BER_TLV_IE, tag=0xf2):
-    # SEID V1.1 Table 5-6
+    # GPD_SPE_013 V1.1 Table 5-6
     pass
 
 
 class CommandRegisterClientAidsDO(BER_TLV_IE, tag=0xf7, nested=[AidRefDO, AidRefEmptyDO]):
-    # SEID v1.1 Table 5-7
+    # GPD_SPE_013 v1.1 Table 5-7
     pass
 
 
 class CommandGet(BER_TLV_IE, tag=0xf3, nested=[AidRefDO, AidRefEmptyDO]):
-    # SEID v1.1 Table 5-8
+    # GPD_SPE_013 v1.1 Table 5-8
     pass
 
 
 class CommandGetAll(BER_TLV_IE, tag=0xf4):
-    # SEID v1.1 Table 5-9
+    # GPD_SPE_013 v1.1 Table 5-9
     pass
 
 
 class CommandGetClientAidsDO(BER_TLV_IE, tag=0xf6):
-    # SEID v1.1 Table 5-10
+    # GPD_SPE_013 v1.1 Table 5-10
     pass
 
 
 class CommandGetNext(BER_TLV_IE, tag=0xf5):
-    # SEID v1.1 Table 5-11
+    # GPD_SPE_013 v1.1 Table 5-11
     pass
 
 
 class CommandGetDeviceConfigDO(BER_TLV_IE, tag=0xf8):
-    # SEID v1.1 Table 5-12
+    # GPD_SPE_013 v1.1 Table 5-12
     pass
 
 
 class ResponseAracAidDO(BER_TLV_IE, tag=0xff70, nested=[AidRefDO, AidRefEmptyDO]):
-    # SEID v1.1 Table 5-13
+    # GPD_SPE_013 v1.1 Table 5-13
     pass
 
 
 class BlockDO(BER_TLV_IE, tag=0xe7):
-    # SEID v1.1 Table 6-13
+    # GPD_SPE_013 v1.1 Table 6-13
     _construct = Struct('offset'/Int16ub, 'length'/Int8ub)
 
 
-# SEID v1.1 Table 4-1
+# GPD_SPE_013 v1.1 Table 4-1
 class GetCommandDoCollection(TLV_IE_Collection, nested=[RefDO, DeviceConfigDO]):
     pass
 
-# SEID v1.1 Table 4-2
-
 
+# GPD_SPE_013 v1.1 Table 4-2
 class GetResponseDoCollection(TLV_IE_Collection, nested=[ResponseAllRefArDO, ResponseArDO,
                                                          ResponseRefreshTagDO, ResponseAramConfigDO]):
     pass
 
-# SEID v1.1 Table 5-1
-
 
+# GPD_SPE_013 v1.1 Table 5-1
 class StoreCommandDoCollection(TLV_IE_Collection,
                                nested=[BlockDO, CommandStoreRefArDO, CommandDelete,
                                        CommandUpdateRefreshTagDO, CommandRegisterClientAidsDO,
@@ -247,7 +244,7 @@ class StoreCommandDoCollection(TLV_IE_Collection,
     pass
 
 
-# SEID v1.1 Section 5.1.2
+# GPD_SPE_013 v1.1 Section 5.1.2
 class StoreResponseDoCollection(TLV_IE_Collection,
                                 nested=[ResponseAllRefArDO, ResponseAracAidDO, ResponseDeviceConfigDO]):
     pass
@@ -265,71 +262,67 @@ class ADF_ARAM(CardADF):
         return pySim.global_platform.decode_select_response(data_hex)
 
     @staticmethod
-    def xceive_apdu_tlv(tp, hdr: Hexstr, cmd_do, resp_cls, exp_sw='9000'):
+    def xceive_apdu_tlv(scc, hdr: Hexstr, cmd_do, resp_cls, exp_sw='9000'):
         """Transceive an APDU with the card, transparently encoding the command data from TLV
         and decoding the response data tlv."""
         if cmd_do:
             cmd_do_enc = cmd_do.to_ie()
             cmd_do_len = len(cmd_do_enc)
             if cmd_do_len > 255:
-                return ValueError('DO > 255 bytes not supported yet')
+                raise ValueError('DO > 255 bytes not supported yet')
         else:
             cmd_do_enc = b''
             cmd_do_len = 0
         c_apdu = hdr + ('%02x' % cmd_do_len) + b2h(cmd_do_enc)
-        (data, sw) = tp.send_apdu_checksw(c_apdu, exp_sw)
+        (data, _sw) = scc.send_apdu_checksw(c_apdu, exp_sw)
         if data:
             if resp_cls:
                 resp_do = resp_cls()
                 resp_do.from_tlv(h2b(data))
                 return resp_do
-            else:
-                return data
+            return data
         else:
             return None
 
     @staticmethod
-    def store_data(tp, do) -> bytes:
+    def store_data(scc, do) -> bytes:
         """Build the Command APDU for STORE DATA."""
-        return ADF_ARAM.xceive_apdu_tlv(tp, '80e29000', do, StoreResponseDoCollection)
+        return ADF_ARAM.xceive_apdu_tlv(scc, '80e29000', do, StoreResponseDoCollection)
 
     @staticmethod
-    def get_all(tp):
-        return ADF_ARAM.xceive_apdu_tlv(tp, '80caff40', None, GetResponseDoCollection)
+    def get_all(scc):
+        return ADF_ARAM.xceive_apdu_tlv(scc, '80caff40', None, GetResponseDoCollection)
 
     @staticmethod
-    def get_config(tp, v_major=0, v_minor=0, v_patch=1):
+    def get_config(scc, v_major=0, v_minor=0, v_patch=1):
         cmd_do = DeviceConfigDO()
-        cmd_do.from_dict([{'device_interface_version_do': {
-                         'major': v_major, 'minor': v_minor, 'patch': v_patch}}])
-        return ADF_ARAM.xceive_apdu_tlv(tp, '80cadf21', cmd_do, ResponseAramConfigDO)
+        cmd_do.from_val_dict([{'device_interface_version_do': {
+                               'major': v_major, 'minor': v_minor, 'patch': v_patch}}])
+        return ADF_ARAM.xceive_apdu_tlv(scc, '80cadf21', cmd_do, ResponseAramConfigDO)
 
     @with_default_category('Application-Specific Commands')
     class AddlShellCommands(CommandSet):
-        def __init(self):
-            super().__init__()
-
-        def do_aram_get_all(self, opts):
+        def do_aram_get_all(self, _opts):
             """GET DATA [All] on the ARA-M Applet"""
-            res_do = ADF_ARAM.get_all(self._cmd.lchan.scc._tp)
+            res_do = ADF_ARAM.get_all(self._cmd.lchan.scc)
             if res_do:
                 self._cmd.poutput_json(res_do.to_dict())
 
-        def do_aram_get_config(self, opts):
+        def do_aram_get_config(self, _opts):
             """Perform GET DATA [Config] on the ARA-M Applet: Tell it our version and retrieve its version."""
-            res_do = ADF_ARAM.get_config(self._cmd.lchan.scc._tp)
+            res_do = ADF_ARAM.get_config(self._cmd.lchan.scc)
             if res_do:
                 self._cmd.poutput_json(res_do.to_dict())
 
         store_ref_ar_do_parse = argparse.ArgumentParser()
         # REF-DO
         store_ref_ar_do_parse.add_argument(
-            '--device-app-id', required=True, help='Identifies the specific device application that the rule appplies to. Hash of Certificate of Application Provider, or UUID. (20/32 hex bytes)')
+            '--device-app-id', required=True, help='Identifies the specific device application that the rule applies to. Hash of Certificate of Application Provider, or UUID. (20/32 hex bytes)')
         aid_grp = store_ref_ar_do_parse.add_mutually_exclusive_group()
         aid_grp.add_argument(
-            '--aid', help='Identifies the specific SE application for which rules are to be stored. Can be a partial AID, containing for example only the RID.  (5-16 hex bytes)')
+            '--aid', help='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_grp.add_argument('--aid-empty', action='store_true',
-                             help='No specific SE application, applies to all applications')
+                             help='No specific SE application, applies to implicitly selected application (all channels)')
         store_ref_ar_do_parse.add_argument(
             '--pkg-ref', help='Full Android Java package name (up to 127 chars ASCII)')
         # AR-DO
@@ -339,7 +332,7 @@ class ADF_ARAM(CardADF):
         apdu_grp.add_argument(
             '--apdu-always', action='store_true', help='APDU access is allowed')
         apdu_grp.add_argument(
-            '--apdu-filter', help='APDU filter: 4 byte CLA/INS/P1/P2 followed by 4 byte mask (8 hex bytes)')
+            '--apdu-filter', help='APDU filter: multiple groups of 8 hex bytes (4 byte CLA/INS/P1/P2 followed by 4 byte mask)')
         nfc_grp = store_ref_ar_do_parse.add_mutually_exclusive_group()
         nfc_grp.add_argument('--nfc-always', action='store_true',
                              help='NFC event access is allowed')
@@ -353,7 +346,7 @@ class ADF_ARAM(CardADF):
             """Perform STORE DATA [Command-Store-REF-AR-DO] to store a (new) access rule."""
             # REF
             ref_do_content = []
-            if opts.aid != None:
+            if opts.aid is not None:
                 ref_do_content += [{'aid_ref_do': opts.aid}]
             elif opts.aid_empty:
                 ref_do_content += [{'aid_ref_empty_do': None}]
@@ -363,12 +356,19 @@ class ADF_ARAM(CardADF):
             # AR
             ar_do_content = []
             if opts.apdu_never:
-                ar_do_content += [{'apdu_ar_od': {'generic_access_rule': 'never'}}]
+                ar_do_content += [{'apdu_ar_do': {'generic_access_rule': 'never'}}]
             elif opts.apdu_always:
                 ar_do_content += [{'apdu_ar_do': {'generic_access_rule': 'always'}}]
             elif opts.apdu_filter:
-                # TODO: multiple filters
-                ar_do_content += [{'apdu_ar_do': {'apdu_filter': [opts.apdu_filter]}}]
+                if len(opts.apdu_filter) % 16:
+                    raise ValueError(f'Invalid non-modulo-16 length of APDU filter: {len(opts.apdu_filter)}')
+                offset = 0
+                apdu_filter = []
+                while offset < len(opts.apdu_filter):
+                    apdu_filter += [{'header': opts.apdu_filter[offset:offset+8],
+                                     'mask': opts.apdu_filter[offset+8:offset+16]}]
+                    offset += 16 # Move offset to the beginning of the next apdu_filter object
+                ar_do_content += [{'apdu_ar_do': {'apdu_filter': apdu_filter}}]
             if opts.nfc_always:
                 ar_do_content += [{'nfc_ar_do': {'nfc_event_access_rule': 'always'}}]
             elif opts.nfc_never:
@@ -377,24 +377,29 @@ class ADF_ARAM(CardADF):
                 ar_do_content += [{'perm_ar_do': {'permissions': opts.android_permissions}}]
             d = [{'ref_ar_do': [{'ref_do': ref_do_content}, {'ar_do': ar_do_content}]}]
             csrado = CommandStoreRefArDO()
-            csrado.from_dict(d)
-            res_do = ADF_ARAM.store_data(self._cmd.lchan.scc._tp, csrado)
+            csrado.from_val_dict(d)
+            res_do = ADF_ARAM.store_data(self._cmd.lchan.scc, csrado)
             if res_do:
                 self._cmd.poutput_json(res_do.to_dict())
 
-        def do_aram_delete_all(self, opts):
+        def do_aram_delete_all(self, _opts):
             """Perform STORE DATA [Command-Delete[all]] to delete all access rules."""
             deldo = CommandDelete()
-            res_do = ADF_ARAM.store_data(self._cmd.lchan.scc._tp, deldo)
+            res_do = ADF_ARAM.store_data(self._cmd.lchan.scc, deldo)
             if res_do:
                 self._cmd.poutput_json(res_do.to_dict())
 
+        def do_aram_lock(self, opts):
+            """Lock STORE DATA command to prevent unauthorized changes
+            (Proprietary feature that is specific to sysmocom's fork of Bertrand Martel’s ARA-M implementation.)"""
+            self._cmd.lchan.scc.send_apdu_checksw('80e2900001A1', '9000')
+
 
 # SEAC v1.1 Section 4.1.2.2 + 5.1.2.2
 sw_aram = {
     'ARA-M': {
         '6381': 'Rule successfully stored but an access rule already exists',
-        '6382': 'Rule successfully stored bu contained at least one unknown (discarded) BER-TLV',
+        '6382': 'Rule successfully stored but contained at least one unknown (discarded) BER-TLV',
         '6581': 'Memory Problem',
         '6700': 'Wrong Length in Lc',
         '6981': 'DO is not supported by the ARA-M/ARA-C',
@@ -415,3 +420,84 @@ sw_aram = {
 class CardApplicationARAM(CardApplication):
     def __init__(self):
         super().__init__('ARA-M', adf=ADF_ARAM(), sw=sw_aram)
+
+    @staticmethod
+    def __export_get_from_dictlist(key, dictlist):
+        # Data objects are organized in lists that contain dictionaries, usually there is only one dictionary per
+        # list item. This function goes through that list and gets the value of the first dictionary that has the
+        # matching key.
+        if dictlist is None:
+            return None
+        for d in dictlist:
+            if key in d:
+                obj = d.get(key)
+                if obj is None:
+                    return ""
+                return obj
+        return None
+
+    @staticmethod
+    def __export_ref_ar_do_list(ref_ar_do_list):
+        export_str = ""
+        ref_do_list = CardApplicationARAM.__export_get_from_dictlist('ref_do', ref_ar_do_list.get('ref_ar_do'))
+        ar_do_list = CardApplicationARAM.__export_get_from_dictlist('ar_do', ref_ar_do_list.get('ref_ar_do'))
+
+        if ref_do_list and ar_do_list:
+            # Get ref_do parameters
+            aid_ref_do = CardApplicationARAM.__export_get_from_dictlist('aid_ref_do', ref_do_list)
+            aid_ref_empty_do = CardApplicationARAM.__export_get_from_dictlist('aid_ref_empty_do', ref_do_list)
+            dev_app_id_ref_do = CardApplicationARAM.__export_get_from_dictlist('dev_app_id_ref_do', ref_do_list)
+            pkg_ref_do = CardApplicationARAM.__export_get_from_dictlist('pkg_ref_do', ref_do_list)
+
+            # Get ar_do parameters
+            apdu_ar_do = CardApplicationARAM.__export_get_from_dictlist('apdu_ar_do', ar_do_list)
+            nfc_ar_do = CardApplicationARAM.__export_get_from_dictlist('nfc_ar_do', ar_do_list)
+            perm_ar_do = CardApplicationARAM.__export_get_from_dictlist('perm_ar_do', ar_do_list)
+
+            # Write command-line
+            export_str += "aram_store_ref_ar_do"
+            if aid_ref_do is not None and len(aid_ref_do) > 0:
+                export_str += (" --aid %s" % aid_ref_do)
+            elif aid_ref_do is not None:
+                export_str += " --aid \"\""
+            if aid_ref_empty_do is not None:
+                export_str += " --aid-empty"
+            if dev_app_id_ref_do:
+                export_str += (" --device-app-id %s" % dev_app_id_ref_do)
+            if apdu_ar_do and 'generic_access_rule' in apdu_ar_do:
+                export_str += (" --apdu-%s" % apdu_ar_do['generic_access_rule'])
+            elif apdu_ar_do and 'apdu_filter' in apdu_ar_do:
+                export_str += (" --apdu-filter ")
+                for apdu_filter in apdu_ar_do['apdu_filter']:
+                    export_str += apdu_filter['header']
+                    export_str += apdu_filter['mask']
+            if nfc_ar_do and 'nfc_event_access_rule' in nfc_ar_do:
+                export_str += (" --nfc-%s" % nfc_ar_do['nfc_event_access_rule'])
+            if perm_ar_do:
+                export_str += (" --android-permissions %s" % perm_ar_do['permissions'])
+            if pkg_ref_do:
+                export_str += (" --pkg-ref %s" % pkg_ref_do['package_name_string'])
+            export_str += "\n"
+        return export_str
+
+    @staticmethod
+    def export(as_json: bool, lchan):
+
+        # TODO: Add JSON output as soon as aram_store_ref_ar_do is able to process input in JSON format.
+        if as_json:
+            raise NotImplementedError("res_do encoder not yet implemented. Patches welcome.")
+
+        export_str = ""
+        export_str += "aram_delete_all\n"
+
+        res_do = ADF_ARAM.get_all(lchan.scc)
+        if not res_do:
+            return export_str.strip()
+
+        for res_do_dict in res_do.to_dict():
+            if not res_do_dict.get('response_all_ref_ar_do', False):
+                continue
+            for ref_ar_do_list in res_do_dict['response_all_ref_ar_do']:
+                export_str += CardApplicationARAM.__export_ref_ar_do_list(ref_ar_do_list)
+
+        return export_str.strip()

pySim/card_handler.py

@@ -7,7 +7,7 @@ there are also automatic card feeders.
 """
 
 #
-# (C) 2019 by Sysmocom s.f.m.c. GmbH
+# (C) 2019 by sysmocom - s.f.m.c. GmbH
 # All Rights Reserved
 #
 # This program is free software: you can redistribute it and/or modify
@@ -24,12 +24,11 @@ there are also automatic card feeders.
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-from pySim.transport import LinkBase
-
 import subprocess
 import sys
 import yaml
 
+from pySim.transport import LinkBase
 
 class CardHandlerBase:
     """Abstract base class representing a mechanism for card insertion/removal."""
@@ -97,7 +96,7 @@ class CardHandlerAuto(CardHandlerBase):
         print("Card handler Config-file: " + str(config_file))
         with open(config_file) as cfg:
             self.cmds = yaml.load(cfg, Loader=yaml.FullLoader)
-        self.verbose = (self.cmds.get('verbose') == True)
+        self.verbose = self.cmds.get('verbose') is True
 
     def __print_outout(self, out):
         print("")

pySim/card_key_provider.py

@@ -10,10 +10,10 @@ the need of manually entering the related card-individual data on every
 operation with pySim-shell.
 """
 
-# (C) 2021 by Sysmocom s.f.m.c. GmbH
+# (C) 2021-2025 by sysmocom - s.f.m.c. GmbH
 # All Rights Reserved
 #
-# Author: Philipp Maier
+# Author: Philipp Maier, Harald Welte
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -29,96 +29,251 @@ operation with pySim-shell.
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 from typing import List, Dict, Optional
+from Cryptodome.Cipher import AES
+from osmocom.utils import h2b, b2h
+from pySim.log import PySimLogger
 
+import os
 import abc
 import csv
+import logging
+import yaml
+import argparse
+
+log = PySimLogger.get(__name__)
 
 card_key_providers = []  # type: List['CardKeyProvider']
 
+class CardKeyFieldCryptor:
+    """
+    A Card key field encryption class that may be used by Card key provider implementations to add support for
+    a column-based encryption to protect sensitive material (cryptographic key material, ADM keys, etc.).
+    The sensitive material is encrypted using a "key-encryption key", occasionally also known as "transport key"
+    before it is stored into a file or database (see also GSMA FS.28). The "transport key" is then used to decrypt
+    the key material on demand.
+    """
+
+    # well-known groups of columns relate to a given functionality.  This avoids having
+    # to specify the same transport key N number of times, if the same key is used for multiple
+    # fields of one group, like KIC+KID+KID of one SD.
+    __CRYPT_GROUPS = {
+            'UICC_SCP02': ['UICC_SCP02_KIC1', 'UICC_SCP02_KID1', 'UICC_SCP02_KIK1'],
+            'UICC_SCP03': ['UICC_SCP03_KIC1', 'UICC_SCP03_KID1', 'UICC_SCP03_KIK1'],
+            'SCP03_ISDR': ['SCP03_ENC_ISDR', 'SCP03_MAC_ISDR', 'SCP03_DEK_ISDR'],
+            'SCP03_ISDA': ['SCP03_ENC_ISDA', 'SCP03_MAC_ISDA', 'SCP03_DEK_ISDA'],
+            'SCP03_ECASD': ['SCP03_ENC_ECASD', 'SCP03_MAC_ECASD', 'SCP03_DEK_ECASD'],
+    }
+
+    __IV = b'\x23' * 16
+
+    @staticmethod
+    def __dict_keys_to_upper(d: dict) -> dict:
+            return {k.upper():v for k,v in d.items()}
+
+    @staticmethod
+    def __process_transport_keys(transport_keys: dict, crypt_groups: dict):
+        """Apply a single transport key to multiple fields/columns, if the name is a group."""
+        new_dict = {}
+        for name, key in transport_keys.items():
+            if name in crypt_groups:
+                for field in crypt_groups[name]:
+                    new_dict[field] = key
+            else:
+                new_dict[name] = key
+        return new_dict
+
+    def __init__(self, transport_keys: dict):
+        """
+        Create new field encryptor/decryptor object and set transport keys, usually one for each column. In some cases
+        it is also possible to use a single key for multiple columns (see also __CRYPT_GROUPS)
+
+        Args:
+                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
+        """
+        self.transport_keys = self.__process_transport_keys(self.__dict_keys_to_upper(transport_keys),
+                                                            self.__CRYPT_GROUPS)
+        for name, key in self.transport_keys.items():
+                log.debug("Encrypting/decrypting field %s using AES key %s" % (name, key))
+
+    def decrypt_field(self, field_name: str, encrypted_val: str) -> str:
+        """
+        Decrypt a single field. The decryption is only applied if we have a transport key is known under the provided
+        field name, otherwise the field is treated as plaintext and passed through as it is.
+
+        Args:
+                field_name : name of the field to decrypt (used to identify which key to use)
+                encrypted_val : encrypted field value
+
+        Returns:
+                plaintext field value
+        """
+        if not field_name.upper() in self.transport_keys:
+            return encrypted_val
+        cipher = AES.new(h2b(self.transport_keys[field_name.upper()]), AES.MODE_CBC, self.__IV)
+        return b2h(cipher.decrypt(h2b(encrypted_val)))
+
+    def encrypt_field(self, field_name: str, plaintext_val: str) -> str:
+        """
+        Encrypt a single field. The encryption is only applied if we have a transport key is known under the provided
+        field name, otherwise the field is treated as non sensitive and passed through as it is.
+
+        Args:
+                field_name : name of the field to decrypt (used to identify which key to use)
+                encrypted_val : encrypted field value
+
+        Returns:
+                plaintext field value
+        """
+        if not field_name.upper() in self.transport_keys:
+            return plaintext_val
+        cipher = AES.new(h2b(self.transport_keys[field_name.upper()]), AES.MODE_CBC, self.__IV)
+        return b2h(cipher.encrypt(h2b(plaintext_val)))
 
 class CardKeyProvider(abc.ABC):
     """Base class, not containing any concrete implementation."""
 
-    VALID_FIELD_NAMES = ['ICCID', 'ADM1',
-                         'IMSI', 'PIN1', 'PIN2', 'PUK1', 'PUK2']
-
-    # check input parameters, but do nothing concrete yet
-    def _verify_get_data(self, fields: List[str] = [], key: str = 'ICCID', value: str = "") -> Dict[str, str]:
-        """Verify multiple fields for identified card.
-
-        Args:
-                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'
-        """
-        for f in fields:
-            if (f not in self.VALID_FIELD_NAMES):
-                raise ValueError("Requested field name '%s' is not a valid field name, valid field names are: %s" %
-                                 (f, str(self.VALID_FIELD_NAMES)))
-
-        if (key not in self.VALID_FIELD_NAMES):
-            raise ValueError("Key field name '%s' is not a valid field name, valid field names are: %s" %
-                             (key, str(self.VALID_FIELD_NAMES)))
-
-        return {}
-
-    def get_field(self, field: str, key: str = 'ICCID', value: str = "") -> Optional[str]:
-        """get a single field from CSV file using a specified key/value pair"""
-        fields = [field]
-        result = self.get(fields, key, value)
-        return result.get(field)
-
     @abc.abstractmethod
     def get(self, fields: List[str], key: str, value: str) -> Dict[str, str]:
-        """Get multiple card-individual fields for identified card.
+        """
+        Get multiple card-individual fields for identified card. This method should not fail with an exception in
+        case the entry, columns or even the key column itsself is not found.
 
         Args:
                 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'
+                dictionary of {field : value, ...} strings for each requested field from 'fields'. In case nothing is
+                fond None shall be returned.
         """
 
+    @staticmethod
+    def argparse_add_args(arg_parser: argparse.ArgumentParser):
+        """
+        Add the commandline arguments relevant for this card key provider.
+
+        Args:
+                arg_parser : argument parser group
+        """
+
+    def __str__(self):
+        return type(self).__name__
 
 class CardKeyProviderCsv(CardKeyProvider):
-    """Card key provider implementation that allows to query against a specified CSV file"""
-    csv_file = None
-    filename = None
+    """Card key provider implementation that allows to query against a specified CSV file."""
 
-    def __init__(self, filename: str):
+    def __init__(self, csv_filename: str, transport_keys: dict):
         """
         Args:
-                filename : file name (path) of CSV file containing card-individual key/data
+                csv_filename : file name (path) of CSV file containing card-individual key/data
+                transport_keys : (see class CardKeyFieldCryptor)
         """
-        self.csv_file = open(filename, 'r')
+        log.info("Using CSV file as card key data source: %s" % csv_filename)
+        self.csv_file = open(csv_filename, 'r')
         if not self.csv_file:
-            raise RuntimeError("Could not open CSV file '%s'" % filename)
-        self.filename = filename
+            raise RuntimeError("Could not open CSV file '%s'" % csv_filename)
+        self.csv_filename = csv_filename
+        self.crypt = CardKeyFieldCryptor(transport_keys)
 
     def get(self, fields: List[str], key: str, value: str) -> Dict[str, str]:
-        super()._verify_get_data(fields, key, value)
-
         self.csv_file.seek(0)
         cr = csv.DictReader(self.csv_file)
         if not cr:
-            raise RuntimeError(
-                "Could not open DictReader for CSV-File '%s'" % self.filename)
+            raise RuntimeError("Could not open DictReader for CSV-File '%s'" % self.csv_filename)
         cr.fieldnames = [field.upper() for field in cr.fieldnames]
 
-        rc = {}
+        if key not in cr.fieldnames:
+            return None
+        return_dict = {}
         for row in cr:
             if row[key] == value:
                 for f in fields:
                     if f in row:
-                        rc.update({f: row[f]})
+                        return_dict.update({f: self.crypt.decrypt_field(f, row[f])})
                     else:
-                        raise RuntimeError("CSV-File '%s' lacks column '%s'" %
-                                           (self.filename, f))
-        return rc
+                        raise RuntimeError("CSV-File '%s' lacks column '%s'" % (self.csv_filename, f))
+        if return_dict == {}:
+            return None
+        return return_dict
 
+    @staticmethod
+    def argparse_add_args(arg_parser: argparse.ArgumentParser):
+        arg_parser.add_argument('--csv', metavar='FILE',
+                                default="~/.osmocom/pysim/card_data.csv",
+                                help='Read card data from CSV file')
+
+class CardKeyProviderPgsql(CardKeyProvider):
+    """Card key provider implementation that allows to query against a specified PostgreSQL database table."""
+
+    def __init__(self, config_filename: str, transport_keys: dict):
+        """
+        Args:
+                config_filename : file name (path) of CSV file containing card-individual key/data
+                transport_keys : (see class CardKeyFieldCryptor)
+        """
+        import psycopg2
+        log.info("Using SQL database as card key data source: %s" % config_filename)
+        with open(config_filename, "r") as cfg:
+            config = yaml.load(cfg, Loader=yaml.FullLoader)
+            log.info("Card key database name: %s" % config.get('db_name'))
+            db_users = config.get('db_users')
+            user = db_users.get('reader')
+            if user is None:
+                raise ValueError("user for role 'reader' not set up in config file.")
+            self.conn = psycopg2.connect(dbname=config.get('db_name'),
+                                         user=user.get('name'),
+                                         password=user.get('pass'),
+                                         host=config.get('host'))
+            self.tables = config.get('table_names')
+            log.info("Card key database tables: %s" % str(self.tables))
+            self.crypt = CardKeyFieldCryptor(transport_keys)
+
+    def get(self, fields: List[str], key: str, value: str) -> Dict[str, str]:
+        import psycopg2
+        from psycopg2.sql import Identifier, SQL
+        db_result = None
+        for t in self.tables:
+            self.conn.rollback()
+            cur = self.conn.cursor()
+
+            # Make sure that the database table and the key column actually exists. If not, move on to the next table
+            cur.execute("SELECT column_name FROM information_schema.columns where table_name = %s;", (t,))
+            cols_result = cur.fetchall()
+            if cols_result == []:
+                log.warning("Card Key database seems to lack table %s, check config file!" % t)
+                continue
+            if (key.lower(),) not in cols_result:
+                continue
+
+            # Query requested columns from database table
+            query = SQL("SELECT {}").format(Identifier(fields[0].lower()))
+            for f in fields[1:]:
+                query += SQL(", {}").format(Identifier(f.lower()))
+            query += SQL(" FROM {} WHERE {} = %s LIMIT 1;").format(Identifier(t.lower()),
+                                                                  Identifier(key.lower()))
+            cur.execute(query, (value,))
+            db_result = cur.fetchone()
+            cur.close()
+
+            if db_result:
+                break
+
+        if db_result is None:
+            return None
+        result = dict(zip(fields, db_result))
+
+        for k in result.keys():
+            result[k] = self.crypt.decrypt_field(k, result.get(k))
+        return result
+
+    @staticmethod
+    def argparse_add_args(arg_parser: argparse.ArgumentParser):
+        arg_parser.add_argument('--pgsql', metavar='FILE',
+                                default="~/.osmocom/pysim/card_data_pgsql.cfg",
+                                help='Read card data from PostgreSQL database (config file)')
 
 def card_key_provider_register(provider: CardKeyProvider, provider_list=card_key_providers):
     """Register a new card key provider.
@@ -128,11 +283,10 @@ def card_key_provider_register(provider: CardKeyProvider, provider_list=card_key
             provider_list : override the list of providers from the global default
     """
     if not isinstance(provider, CardKeyProvider):
-        raise ValueError("provider is not a card data provier")
+        raise ValueError("provider is not a card data provider")
     provider_list.append(provider)
 
-
-def card_key_provider_get(fields, key: str, value: str, provider_list=card_key_providers) -> Dict[str, str]:
+def card_key_provider_get(fields: list[str], key: str, value: str, provider_list=card_key_providers) -> Dict[str, str]:
     """Query all registered card data providers for card-individual [key] data.
 
     Args:
@@ -143,17 +297,20 @@ def card_key_provider_get(fields, key: str, value: str, provider_list=card_key_p
     Returns:
             dictionary of {field, value} strings for each requested field from 'fields'
     """
+    key = key.upper()
+    fields = [f.upper() for f in fields]
     for p in provider_list:
         if not isinstance(p, CardKeyProvider):
-            raise ValueError(
-                "provider list contains element which is not a card data provier")
+            raise ValueError("Provider list contains element which is not a card data provider")
+        log.debug("Searching for card key data (key=%s, value=%s, provider=%s)" % (key, value, str(p)))
         result = p.get(fields, key, value)
         if result:
+            log.debug("Found card data: %s" % (str(result)))
             return result
-    return {}
 
+    raise ValueError("Unable to find card key data (key=%s, value=%s, fields=%s)" % (key, value, str(fields)))
 
-def card_key_provider_get_field(field: str, key: str, value: str, provider_list=card_key_providers) -> Optional[str]:
+def card_key_provider_get_field(field: str, key: str, value: str, provider_list=card_key_providers) -> str:
     """Query all registered card data providers for a single field.
 
     Args:
@@ -164,11 +321,29 @@ def card_key_provider_get_field(field: str, key: str, value: str, provider_list=
     Returns:
             dictionary of {field, value} strings for the requested field
     """
-    for p in provider_list:
-        if not isinstance(p, CardKeyProvider):
-            raise ValueError(
-                "provider list contains element which is not a card data provier")
-        result = p.get_field(field, key, value)
-        if result:
-            return result
-    return None
+
+    fields = [field]
+    result = card_key_provider_get(fields, key, value, card_key_providers)
+    return result.get(field.upper())
+
+def argparse_add_card_key_provider_args(arg_parser: argparse.ArgumentParser):
+    """Add card key provider commandline options to the given argument parser"""
+    card_key_group = arg_parser.add_argument_group('Card Key Provider Options')
+    CardKeyProviderCsv.argparse_add_args(card_key_group)
+    CardKeyProviderPgsql.argparse_add_args(card_key_group)
+    card_key_group.add_argument('--column-key', metavar='FIELD:AES_KEY_HEX', default=[], action='append',
+                                help='per-column AES transport key', dest='column_key')
+    # Depprecated argument, replaced by --column-key (see above)
+    card_key_group.add_argument('--csv-column-key', metavar='FIELD:AES_KEY_HEX', default=[], action='append',
+                                help=argparse.SUPPRESS, dest='column_key')
+
+def init_card_key_provider(opts: argparse.Namespace):
+    """Initialize card key provider depending on the user provided commandline options"""
+    column_keys = {}
+    for par in opts.column_key:
+        name, key = par.split(':')
+        column_keys[name] = key
+    if os.path.isfile(os.path.expanduser(opts.csv)):
+        card_key_provider_register(CardKeyProviderCsv(os.path.expanduser(opts.csv), column_keys))
+    if os.path.isfile(os.path.expanduser(opts.pgsql)):
+        card_key_provider_register(CardKeyProviderPgsql(os.path.expanduser(opts.pgsql), column_keys))

pySim/cards.py

@@ -22,12 +22,12 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-from typing import Optional, Dict, Tuple
-from pySim.ts_102_221 import EF_DIR
-from pySim.ts_51_011 import DF_GSM
-import abc
+from typing import Optional, Tuple
+from osmocom.utils import *
 
-from pySim.utils import *
+from pySim.ts_102_221 import EF_DIR, CardProfileUICC
+from pySim.ts_51_011 import DF_GSM
+from pySim.utils import SwHexstr
 from pySim.commands import Path, SimCardCommands
 
 class CardBase:
@@ -40,8 +40,7 @@ class CardBase:
         rc = self._scc.reset_card()
         if rc == 1:
             return self._scc.get_atr()
-        else:
-            return None
+        return None
 
     def set_apdu_parameter(self, cla: Hexstr, sel_ctrl: Hexstr) -> None:
         """Set apdu parameters (class byte and selection control bytes)"""
@@ -54,13 +53,19 @@ class CardBase:
 
     def erase(self):
         print("warning: erasing is not supported for specified card type!")
-        return
 
     def file_exists(self, fid: Path) -> bool:
+        """Determine if the file exists (and is not deactivated)."""
         res_arr = self._scc.try_select_path(fid)
         for res in res_arr:
             if res[1] != '9000':
                 return False
+        try:
+            d = CardProfileUICC.decode_select_response(res_arr[-1][0])
+            if d.get('life_cycle_status_integer', 'operational_activated') != 'operational_activated':
+                return False
+        except:
+            pass
         return True
 
     def read_aids(self) -> List[Hexstr]:
@@ -68,6 +73,16 @@ class CardBase:
         # callers having to do hasattr('read_aids') ahead of every call.
         return []
 
+    def adf_present(self, adf: str = "usim") -> bool:
+        # a non-UICC doesn't have any applications. Convenience helper to avoid
+        # callers having to do hasattr('adf_present') ahead of every call.
+        return False
+
+    def select_adf_by_aid(self, adf: str = "usim", scc: Optional[SimCardCommands] = None) -> Tuple[Optional[Hexstr], Optional[SwHexstr]]:
+        # a non-UICC doesn't have any applications. Convenience helper to avoid
+        # callers having to do hasattr('select_adf_by_aid') ahead of every call.
+        return (None, None)
+
 
 class SimCardBase(CardBase):
     """Here we only add methods for commands specified in TS 51.011, without
@@ -75,7 +90,7 @@ class SimCardBase(CardBase):
     name = 'SIM'
 
     def __init__(self, scc: SimCardCommands):
-        super(SimCardBase, self).__init__(scc)
+        super().__init__(scc)
         self._scc.cla_byte = "A0"
         self._scc.sel_ctrl = "0000"
 
@@ -88,7 +103,7 @@ class UiccCardBase(SimCardBase):
     name = 'UICC'
 
     def __init__(self, scc: SimCardCommands):
-        super(UiccCardBase, self).__init__(scc)
+        super().__init__(scc)
         self._scc.cla_byte = "00"
         self._scc.sel_ctrl = "0004"  # request an FCP
         # See also: ETSI TS 102 221, Table 9.3
@@ -97,6 +112,8 @@ class UiccCardBase(SimCardBase):
     def probe(self) -> bool:
         # EF.DIR is a mandatory EF on all ICCIDs; however it *may* also exist on a TS 51.011 SIM
         ef_dir = EF_DIR()
+        # select MF first
+        self.file_exists("3f00")
         return self.file_exists(ef_dir.fid)
 
     def read_aids(self) -> List[Hexstr]:
@@ -158,9 +175,8 @@ class UiccCardBase(SimCardBase):
             aid_full = self._complete_aid(aid)
             if aid_full:
                 return scc.select_adf(aid_full)
-            else:
-                # If we cannot get the full AID, try with short AID
-                return scc.select_adf(aid)
+            # If we cannot get the full AID, try with short AID
+            return scc.select_adf(aid)
         return (None, None)
 
 def card_detect(scc: SimCardCommands) -> Optional[CardBase]:

pySim/cat.py

@@ -18,43 +18,58 @@ as described in 3GPP TS 31.111."""
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 
-from bidict import bidict
 from typing import List
-from pySim.utils import b2h, h2b, dec_xplmn_w_act
-from pySim.tlv import TLV_IE, COMPR_TLV_IE, BER_TLV_IE, TLV_IE_Collection
-from pySim.construct import PlmnAdapter, BcdAdapter, HexAdapter, GsmStringAdapter, TonNpi
-from construct import Int8ub, Int16ub, Byte, Bytes, Bit, Flag, BitsInteger
-from construct import Struct, Enum, Tell, BitStruct, this, Padding, RepeatUntil
-from construct import GreedyBytes, Switch, GreedyRange, FlagsEnum
+from bidict import bidict
+from construct import Int8ub, Int16ub, Byte, BitsInteger
+from construct import Struct, Enum, BitStruct, this
+from construct import Switch, GreedyRange, FlagsEnum
+from osmocom.tlv import TLV_IE, COMPR_TLV_IE, BER_TLV_IE, TLV_IE_Collection
+from osmocom.construct import PlmnAdapter, BcdAdapter, GsmStringAdapter, TonNpi, GsmString, Bytes, GreedyBytes
+from osmocom.utils import b2h, h2b
+from pySim.utils import dec_xplmn_w_act
 
 # Tag values as per TS 101 220 Table 7.23
 
 # TS 102 223 Section 8.1
-class Address(COMPR_TLV_IE, tag=0x06):
-    _construct = Struct('ton_npi'/Int8ub,
-                        'call_number'/BcdAdapter(Bytes(this._.total_len-1)))
+class Address(COMPR_TLV_IE, tag=0x86):
+    _construct = Struct('ton_npi'/TonNpi,
+                        'call_number'/BcdAdapter(GreedyBytes))
 
 # TS 102 223 Section 8.2
-class AlphaIdentifier(COMPR_TLV_IE, tag=0x05):
+class AlphaIdentifier(COMPR_TLV_IE, tag=0x85):
     # FIXME: like EF.ADN
     pass
 
 # TS 102 223 Section 8.3
-class Subaddress(COMPR_TLV_IE, tag=0x08):
+class Subaddress(COMPR_TLV_IE, tag=0x88):
     pass
 
 # TS 102 223 Section 8.4 + TS 31.111 Section 8.4
-class CapabilityConfigParams(COMPR_TLV_IE, tag=0x07):
+class CapabilityConfigParams(COMPR_TLV_IE, tag=0x87):
     pass
 
 # TS 31.111 Section 8.5
-class CBSPage(COMPR_TLV_IE, tag=0x0C):
+class CBSPage(COMPR_TLV_IE, tag=0x8C):
     pass
 
+# TS 102 223 V15.3.0 Section 9.4
+TypeOfCommand = Enum(Int8ub, refresh=0x01, more_time=0x02, poll_interval=0x03, polling_off=0x04,
+                     set_up_event_list=0x05, set_up_call=0x10, send_ss=0x11, send_ussd=0x12,
+                     send_short_message=0x13, send_dtmf=0x14, launch_browser=0x15, geo_location_req=0x16,
+                     play_tone=0x20, display_text=0x21, get_inkey=0x22, get_input=0x23, select_item=0x24,
+                     set_up_menu=0x25, provide_local_info=0x26, timer_management=0x27,
+                     set_up_idle_mode_text=0x28, perform_card_apdu=0x30, power_on_card=0x31,
+                     power_off_card=0x32, get_reader_status=0x33, run_at_command=0x34,
+                     language_notification=0x35, open_channel=0x40, close_channel=0x41, receive_data=0x42,
+                     send_data=0x43, get_channel_status=0x44, service_search=0x45, get_service_info=0x46,
+                     declare_service=0x47, set_frames=0x50, get_frames_status=0x51, retrieve_mms=0x60,
+                     submit_mms=0x61, display_mms=0x62, activate=0x70, contactless_state_changed=0x71,
+                     command_container=0x72, encapsulated_session_control=0x73)
+
 # TS 102 223 Section 8.6 + TS 31.111 Section 8.6
 class CommandDetails(COMPR_TLV_IE, tag=0x81):
     _construct = Struct('command_number'/Int8ub,
-                        'type_of_command'/Int8ub,
+                        'type_of_command'/TypeOfCommand,
                         'command_qualifier'/Int8ub)
 
 # TS 102 223 Section 8.7
@@ -107,26 +122,26 @@ class DeviceIdentities(COMPR_TLV_IE, tag=0x82):
         return bytes([src, dst])
 
 # TS 102 223 Section 8.8
-class Duration(COMPR_TLV_IE, tag=0x04):
+class Duration(COMPR_TLV_IE, tag=0x84):
     _construct = Struct('time_unit'/Enum(Int8ub, minutes=0, seconds=1, tenths_of_seconds=2),
                         'time_interval'/Int8ub)
 
 # TS 102 223 Section 8.9
-class Item(COMPR_TLV_IE, tag=0x0f):
+class Item(COMPR_TLV_IE, tag=0x8f):
     _construct = Struct('identifier'/Int8ub,
                         'text_string'/GsmStringAdapter(GreedyBytes))
 
 # TS 102 223 Section 8.10
-class ItemIdentifier(COMPR_TLV_IE, tag=0x10):
+class ItemIdentifier(COMPR_TLV_IE, tag=0x90):
     _construct = Struct('identifier'/Int8ub)
 
 # TS 102 223 Section 8.11
-class ResponseLength(COMPR_TLV_IE, tag=0x11):
+class ResponseLength(COMPR_TLV_IE, tag=0x91):
     _construct = Struct('minimum_length'/Int8ub,
                         'maximum_length'/Int8ub)
 
 # TS 102 223 Section 8.12
-class Result(COMPR_TLV_IE, tag=0x03):
+class Result(COMPR_TLV_IE, tag=0x83):
     GeneralResult = Enum(Int8ub,
                          # '0X' and '1X' indicate that the command has been performed
                          performed_successfully=0,
@@ -240,24 +255,27 @@ class Result(COMPR_TLV_IE, tag=0x03):
                             'launch_browser_generic_error': AddlInfoLaunchBrowser,
                             'bearer_independent_protocol_error': AddlInfoBip,
                             'frames_error': AddlInfoFrames
-                        }, default=HexAdapter(GreedyBytes)))
+                        }, default=GreedyBytes))
 
 # TS 102 223 Section 8.13  + TS 31.111 Section 8.13
 class SMS_TPDU(COMPR_TLV_IE, tag=0x8B):
-    _construct = Struct('tpdu'/HexAdapter(GreedyBytes))
+    _construct = Struct('tpdu'/GreedyBytes)
 
 # TS 31.111 Section 8.14
 class SsString(COMPR_TLV_IE, tag=0x89):
-    _construct = Struct('ton_npi'/TonNpi, 'ss_string'/HexAdapter(GreedyBytes))
+    _construct = Struct('ton_npi'/TonNpi, 'ss_string'/GreedyBytes)
 
 
 # TS 102 223 Section 8.15
-class TextString(COMPR_TLV_IE, tag=0x0d):
+class TextString(COMPR_TLV_IE, tag=0x8D):
+    _test_de_encode = [
+        ( '8d090470617373776f7264', {'dcs': 4, 'text_string': b'password'} )
+    ]
     _construct = Struct('dcs'/Int8ub, # TS 03.38
-                        'text_string'/HexAdapter(GreedyBytes))
+                        'text_string'/GreedyBytes)
 
 # TS 102 223 Section 8.16
-class Tone(COMPR_TLV_IE, tag=0x0e):
+class Tone(COMPR_TLV_IE, tag=0x8E):
     _construct = Struct('tone'/Enum(Int8ub, dial_tone=0x01,
                                             called_subscriber_busy=0x02,
                                             congestion=0x03,
@@ -288,39 +306,39 @@ class Tone(COMPR_TLV_IE, tag=0x0e):
                                             melody_8=0x47))
 
 # TS 31 111 Section 8.17
-class USSDString(COMPR_TLV_IE, tag=0x0a):
+class USSDString(COMPR_TLV_IE, tag=0x8A):
     _construct = Struct('dcs'/Int8ub,
-                        'ussd_string'/HexAdapter(GreedyBytes))
+                        'ussd_string'/GreedyBytes)
 
 # TS 102 223 Section 8.18
-class FileList(COMPR_TLV_IE, tag=0x12):
-    FileId=HexAdapter(Bytes(2))
+class FileList(COMPR_TLV_IE, tag=0x92):
+    FileId=Bytes(2)
     _construct = Struct('number_of_files'/Int8ub,
                         'files'/GreedyRange(FileId))
 
-# TS 102 223 Secton 8.19
+# TS 102 223 Section 8.19
 class LocationInformation(COMPR_TLV_IE, tag=0x93):
     pass
 
-# TS 102 223 Secton 8.20
+# TS 102 223 Section 8.20
 class IMEI(COMPR_TLV_IE, tag=0x94):
     _construct = BcdAdapter(GreedyBytes)
 
-# TS 102 223 Secton 8.21
+# TS 102 223 Section 8.21
 class HelpRequest(COMPR_TLV_IE, tag=0x95):
     pass
 
-# TS 102 223 Secton 8.22
+# TS 102 223 Section 8.22
 class NetworkMeasurementResults(COMPR_TLV_IE, tag=0x96):
     _construct = BcdAdapter(GreedyBytes)
 
 # TS 102 223 Section 8.23
 class DefaultText(COMPR_TLV_IE, tag=0x97):
     _construct = Struct('dcs'/Int8ub,
-                        'text_string'/HexAdapter(GreedyBytes))
+                        'text_string'/GreedyBytes)
 
 # TS 102 223 Section 8.24
-class ItemsNextActionIndicator(COMPR_TLV_IE, tag=0x18):
+class ItemsNextActionIndicator(COMPR_TLV_IE, tag=0x98):
     _construct = GreedyRange(Int8ub)
 
 class EventList(COMPR_TLV_IE, tag=0x99):
@@ -365,7 +383,7 @@ class LocationStatus(COMPR_TLV_IE, tag=0x9b):
     _construct = Enum(Int8ub, normal_service=0, limited_service=1, no_service=2)
 
 # TS 102 223 Section 8.31
-class IconIdentifier(COMPR_TLV_IE, tag=0x1e):
+class IconIdentifier(COMPR_TLV_IE, tag=0x9e):
     _construct = Struct('icon_qualifier'/FlagsEnum(Int8ub, not_self_explanatory=1),
                         'icon_identifier'/Int8ub)
 
@@ -376,7 +394,7 @@ class ItemIconIdentifierList(COMPR_TLV_IE, tag=0x9f):
 
 # TS 102 223 Section 8.35
 class CApdu(COMPR_TLV_IE, tag=0xA2):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.37
 class TimerIdentifier(COMPR_TLV_IE, tag=0xA4):
@@ -388,28 +406,51 @@ class TimerValue(COMPR_TLV_IE, tag=0xA5):
 
 # TS 102 223 Section 8.40
 class AtCommand(COMPR_TLV_IE, tag=0xA8):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.43
-class ImmediateResponse(COMPR_TLV_IE, tag=0x2b):
+class ImmediateResponse(COMPR_TLV_IE, tag=0xAB):
     pass
 
+# TS 102 223 Section 8.44
+class DtmfString(COMPR_TLV_IE, tag=0xAC):
+    _construct = BcdAdapter(GreedyBytes)
+
 # TS 102 223 Section 8.45
 class Language(COMPR_TLV_IE, tag=0xAD):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 31.111 Section 8.46
-class TimingAdvance(COMPR_TLV_IE, tag=0x46):
+class TimingAdvance(COMPR_TLV_IE, tag=0xC6):
     _construct = Struct('me_status'/Enum(Int8ub, in_idle_state=0, not_in_idle_state=1),
                         'timing_advance'/Int8ub)
 
+# TS 31.111 Section 8.47
+class BrowserIdentity(COMPR_TLV_IE, tag=0xB0):
+    _construct = Enum(Int8ub, default=0, wml=1, html=2, xhtml=3, chtml=4)
+
+# TS 31.111 Section 8.48
+class Url(COMPR_TLV_IE, tag=0xB1):
+    _construct = GsmString(GreedyBytes)
+
 # TS 31.111 Section 8.49
 class Bearer(COMPR_TLV_IE, tag=0xB2):
     SingleBearer = Enum(Int8ub, sms=0, csd=1, ussd=2, packet_Service=3)
     _construct = GreedyRange(SingleBearer)
 
+# TS 102 223 Section 8.50
+class ProvisioningFileReference(COMPR_TLV_IE, tag=0xB3):
+    _construct = GreedyBytes
+
+# TS 102 223 Section 8.51
+class BrowserTerminationCause(COMPR_TLV_IE, tag=0xB4):
+    _construct = Enum(Int8ub, user_termination=0, error_termination=1)
+
 # TS 102 223 Section 8.52
 class BearerDescription(COMPR_TLV_IE, tag=0xB5):
+    _test_de_encode = [
+        ( 'b50103', {'bearer_parameters': b'', 'bearer_type': 'default'} ),
+    ]
     # TS 31.111 Section 8.52.1
     BearerParsCs = Struct('data_rate'/Int8ub,
                           'bearer_service'/Int8ub,
@@ -451,11 +492,11 @@ class BearerDescription(COMPR_TLV_IE, tag=0xB5):
                                                         'packet_grps_utran_eutran': BearerParsPacket,
                                                         'packet_with_extd_params': BearerParsPacketExt,
                                                         'ng_ran': BearerParsNgRan,
-                                                    }, default=HexAdapter(GreedyBytes)))
+                                                    }, default=GreedyBytes))
 
 # TS 102 223 Section 8.53
 class ChannelData(COMPR_TLV_IE, tag = 0xB6):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.54
 class ChannelDataLength(COMPR_TLV_IE, tag = 0xB7):
@@ -465,26 +506,33 @@ class ChannelDataLength(COMPR_TLV_IE, tag = 0xB7):
 class BufferSize(COMPR_TLV_IE, tag = 0xB9):
     _construct = Int16ub
 
-# TS 31.111 Section 8.56
+# TS 102 223 Section 8.56 + TS 31.111 Section 8.56
 class ChannelStatus(COMPR_TLV_IE, tag = 0xB8):
     # complex decoding, depends on out-of-band context/knowledge :(
-    pass
+    # for default / TCP Client mode: bit 8 of first byte indicates connected, 3 LSB indicate channel nr
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.58
 class OtherAddress(COMPR_TLV_IE, tag = 0xBE):
+    _test_de_encode = [
+        ( 'be052101020304', {'address': h2b('01020304'), 'type_of_address': 'ipv4'} ),
+    ]
     _construct = Struct('type_of_address'/Enum(Int8ub, ipv4=0x21, ipv6=0x57),
-                        'address'/HexAdapter(GreedyBytes))
+                        'address'/GreedyBytes)
 
 # TS 102 223 Section 8.59
 class UiccTransportLevel(COMPR_TLV_IE, tag = 0xBC):
+    _test_de_encode = [
+        ( 'bc03028000', {'port_number': 32768, 'protocol_type': 'tcp_uicc_client_remote'} ),
+    ]
     _construct = Struct('protocol_type'/Enum(Int8ub, udp_uicc_client_remote=1, tcp_uicc_client_remote=2,
                                              tcp_uicc_server=3, udp_uicc_client_local=4,
                                              tcp_uicc_client_local=5, direct_channel=6),
                         'port_number'/Int16ub)
 
 # TS 102 223 Section 8.60
-class Aid(COMPR_TLV_IE, tag=0x2f):
-    _construct = Struct('aid'/HexAdapter(GreedyBytes))
+class Aid(COMPR_TLV_IE, tag=0xAF):
+    _construct = Struct('aid'/GreedyBytes)
 
 # TS 102 223 Section 8.61
 class AccessTechnology(COMPR_TLV_IE, tag=0xBF):
@@ -498,35 +546,38 @@ class ServiceRecord(COMPR_TLV_IE, tag=0xC1):
     BearerTechId = Enum(Int8ub, technology_independent=0, bluetooth=1, irda=2, rs232=3, usb=4)
     _construct = Struct('local_bearer_technology'/BearerTechId,
                         'service_identifier'/Int8ub,
-                        'service_record'/HexAdapter(GreedyBytes))
+                        'service_record'/GreedyBytes)
 
 # TS 102 223 Section 8.64
 class DeviceFilter(COMPR_TLV_IE, tag=0xC2):
     _construct = Struct('local_bearer_technology'/ServiceRecord.BearerTechId,
-                        'device_filter'/HexAdapter(GreedyBytes))
+                        'device_filter'/GreedyBytes)
 
 # TS 102 223 Section 8.65
 class ServiceSearchIE(COMPR_TLV_IE, tag=0xC3):
     _construct = Struct('local_bearer_technology'/ServiceRecord.BearerTechId,
-                        'service_search'/HexAdapter(GreedyBytes))
+                        'service_search'/GreedyBytes)
 
 # TS 102 223 Section 8.66
 class AttributeInformation(COMPR_TLV_IE, tag=0xC4):
     _construct = Struct('local_bearer_technology'/ServiceRecord.BearerTechId,
-                        'attribute_information'/HexAdapter(GreedyBytes))
+                        'attribute_information'/GreedyBytes)
 
 
 # TS 102 223 Section 8.68
 class RemoteEntityAddress(COMPR_TLV_IE, tag=0xC9):
     _construct = Struct('coding_type'/Enum(Int8ub, ieee802_16=0, irda=1),
-                        'address'/HexAdapter(GreedyBytes))
+                        'address'/GreedyBytes)
 
 # TS 102 223 Section 8.70
 class NetworkAccessName(COMPR_TLV_IE, tag=0xC7):
-    _construct = HexAdapter(GreedyBytes)
+    _test_de_encode = [
+        ( 'c704036e6161', h2b('036e6161') ),
+    ]
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.72
-class TextAttribute(COMPR_TLV_IE, tag=0x50):
+class TextAttribute(COMPR_TLV_IE, tag=0xD0):
     pass
 
 # TS 31.111 Section 8.72
@@ -562,20 +613,20 @@ class ItemTextAttributeList(COMPR_TLV_IE, tag=0xD1):
     _construct = GreedyRange(Int8ub)
 
 # TS 102 223 Section 8.80
-class FrameIdentifier(COMPR_TLV_IE, tag=0x68):
+class FrameIdentifier(COMPR_TLV_IE, tag=0xE8):
     _construct = Struct('identifier'/Int8ub)
 
 # TS 102 223 Section 8.82
 class MultimediaMessageReference(COMPR_TLV_IE, tag=0xEA):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.83
 class MultimediaMessageIdentifier(COMPR_TLV_IE, tag=0xEB):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.85
 class MmContentIdentifier(COMPR_TLV_IE, tag=0xEE):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.89
 class ActivateDescriptor(COMPR_TLV_IE, tag=0xFB):
@@ -583,11 +634,11 @@ class ActivateDescriptor(COMPR_TLV_IE, tag=0xFB):
 
 # TS 31.111 Section 8.90
 class PlmnWactList(COMPR_TLV_IE, tag=0xF2):
-    def _from_bytes(self, x):
+    def _from_bytes(self, do: bytes):
         r = []
         i = 0
-        while i < len(x):
-            r.append(dec_xplmn_w_act(b2h(x[i:i+5])))
+        while i < len(do):
+            r.append(dec_xplmn_w_act(b2h(do[i:i+5])))
             i += 5
         return r
 
@@ -598,7 +649,7 @@ class ContactlessFunctionalityState(COMPR_TLV_IE, tag=0xD4):
 # TS 31.111 Section 8.91
 class RoutingAreaIdentification(COMPR_TLV_IE, tag=0xF3):
     _construct = Struct('mcc_mnc'/PlmnAdapter(Bytes(3)),
-                        'lac'/HexAdapter(Bytes(2)),
+                        'lac'/Bytes(2),
                         'rac'/Int8ub)
 
 # TS 31.111 Section 8.92
@@ -658,23 +709,23 @@ class EcatSequenceNumber(COMPR_TLV_IE, tag=0xA1):
 
 # TS 102 223 Section 8.99
 class EncryptedTlvList(COMPR_TLV_IE, tag=0xA2):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.100
 class Mac(COMPR_TLV_IE, tag=0xE0):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.101
 class SaTemplate(COMPR_TLV_IE, tag=0xA3):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.103
-class RefreshEnforcementPolicy(COMPR_TLV_IE, tag=0x3A):
+class RefreshEnforcementPolicy(COMPR_TLV_IE, tag=0xBA):
     _construct = FlagsEnum(Byte, even_if_navigating_menus=0, even_if_data_call=1, even_if_voice_call=2)
 
 # TS 102 223 Section 8.104
 class DnsServerAddress(COMPR_TLV_IE, tag=0xC0):
-    _construct = HexAdapter(GreedyBytes)
+    _construct = GreedyBytes
 
 # TS 102 223 Section 8.105
 class SupportedRadioAccessTechnologies(COMPR_TLV_IE, tag=0xB4):
@@ -683,7 +734,7 @@ class SupportedRadioAccessTechnologies(COMPR_TLV_IE, tag=0xB4):
     _construct = GreedyRange(AccessTechTuple)
 
 # TS 102 223 Section 8.107
-class ApplicationSpecificRefreshData(COMPR_TLV_IE, tag=0x3B):
+class ApplicationSpecificRefreshData(COMPR_TLV_IE, tag=0xBB):
     pass
 
 # TS 31.111 Section 8.108
@@ -717,19 +768,194 @@ class SMSCBDownload(BER_TLV_IE, tag=0xD2,
                     nested=[DeviceIdentities, CBSPage]):
     pass
 
+# TS 101 220 Table 7.17
+class MenuSelection(BER_TLV_IE, tag=0xD3,
+                    nested=[DeviceIdentities, ItemIdentifier, HelpRequest]):
+    pass
 
+class BcRepeatIndicator(BER_TLV_IE, tag=0x2A):
+    pass
+
+# TS 101 220 Table 7.17
+class CallControl(BER_TLV_IE, tag=0xD4,
+                  nested=[DeviceIdentities, Address, CapabilityConfigParams, Subaddress,
+                          LocationInformation, BcRepeatIndicator]):
+    pass
+
+# TS 101 220 Table 7.17
+class MoShortMessageControl(BER_TLV_IE, tag=0xD5):
+    pass
+
+
+# TS 101 220 Table 7.23
+class TransactionIdentifier(BER_TLV_IE, tag=0x1C):
+    pass
+
+# TS 101 220 Table 7.23
+class ImsURI(BER_TLV_IE, tag=0x31):
+    pass
+
+# TS 101 220 Table 7.23
+class UriTruncated(BER_TLV_IE, tag=0x73):
+    pass
+
+# TS 101 220 Table 7.23
+class TrackingAreaIdentification(BER_TLV_IE, tag=0x7D):
+    pass
+
+# TS 101 220 Table 7.23
+class ExtendedRejectionCauseCode(BER_TLV_IE, tag=0x57):
+    pass
+
+# TS 101 220 Table 7.23
+class CsgCellSelectionStatus(BER_TLV_IE, tag=0x55):
+    pass
+
+# TS 101 220 Table 7.23
+class CsgId(BER_TLV_IE, tag=0x56):
+    pass
+
+# TS 101 220 Table 7.23
+class HnbName(BER_TLV_IE, tag=0x57):
+    pass
+
+# TS 101 220 Table 7.23
+class PlmnId(BER_TLV_IE, tag=0x09):
+    pass
+
+# TS 101 220 Table 7.23
+class ImsCallDisconnectionStatus(BER_TLV_IE, tag=0x55):
+    pass
+
+# TS 101 220 Table 7.23
+class Iari(BER_TLV_IE, tag=0x76):
+    pass
+
+# TS 101 220 Table 7.23
+class ImpuList(BER_TLV_IE, tag=0x77):
+    pass
+
+# TS 101 220 Table 7.23
+class ImsStatusCode(BER_TLV_IE, tag=0x77):
+    pass
+
+# TS 101 220 Table 7.23
+class DateTimeAndTimezone(BER_TLV_IE, tag=0x26):
+    pass
+
+# TS 101 220 Table 7.23
+class PdpPdnPduType(BER_TLV_IE, tag=0x0B):
+    pass
+
+# TS 101 220 Table 7.23
+class GadShape(BER_TLV_IE, tag=0x77):
+    pass
+
+# TS 101 220 Table 7.23
+class NmeaSentence(BER_TLV_IE, tag=0x78):
+    pass
+
+# TS 101 220 Table 7.23
+class WlanAccessStatus(BER_TLV_IE, tag=0x4B):
+    pass
+
+# TS 101 220 Table 7.17
+class EventDownload(BER_TLV_IE, tag=0xD6,
+                    nested=[EventList, DeviceIdentities,
+                            # 7.5.1.2 (I-)WLAN Access Status
+                            WlanAccessStatus,
+                            # 7.5.1A.2 MT Call
+                            TransactionIdentifier, Address,
+                            Subaddress, ImsURI, MediaType, UriTruncated,
+                            # 7.5.2.2 Network Rejection
+                            LocationInformation, RoutingAreaIdentification, TrackingAreaIdentification,
+                            AccessTechnology, UpdateAttachRegistrationType, RejectionCauseCode,
+                            ExtendedRejectionCauseCode,
+                            # 7.5.2A.2 Call Connected
+                            # TransactionIdentifier, MediaType
+                            # 7.5.3.2 CSG Cell Selection
+                            # AccessTechnology
+                            CsgCellSelectionStatus, CsgId, HnbName, PlmnId,
+                            # 7.5.3A.2 CAll Disconnected
+                            # TransactionIdentifier, MediaType,
+                            ImsCallDisconnectionStatus,
+                            # TS 102 223 7.5.4 LocationStatusEvent
+                            # TS 102 223 7.5.5 UserActivityEvent
+                            # TS 102 223 7.5.6 IdleScreenAvailableEvent
+                            # TS 102 223 7.5.7 CardReaderStatusEvent
+                            # TS 102 223 7.5.8 LanguageSelectionEvent
+                            # TS 102 223 7.5.9 BrowserTerminationEvent
+                            # TS 102 223 7.5.10 DataAvailableEvent
+                            ChannelStatus, ChannelDataLength,
+                            # TS 102 223 7.5.11 ChannelStatusEvent
+                            # TS 102 223 7.5.12 AccessTechnologyChangeEvent
+                            # TS 102 223 7.5.13 DisplayParametersChangedEvent
+                            # TS 102 223 7.5.14 LocalConnectionEvent
+                            # TS 102 223 7.5.15 NetworkSearchModeChangeEvent
+                            # TS 102 223 7.5.16 BrowsingStatusEvent
+                            # TS 102 223 7.5.17 FramesInformationChangedEvent
+                            # 7.5.20 Incoming IMS Data
+                            Iari,
+                            # 7.5.21 MS Registration Event
+                            ImpuList, ImsStatusCode,
+                            # 7.5.24 / TS 102 223 7.5.22 PollIntervalNegotiation
+                            # 7.5.25 DataConnectionStatusChangeEvent
+                            DataConnectionStatus, DataConnectionType, SmCause,
+                            # TransactionIdentifier, LocationInformation, AccessTechnology
+                            DateTimeAndTimezone, LocationStatus, NetworkAccessName, PdpPdnPduType,
+                            # 7.7 / TS 102 223 7.6 MMS Transfer Status
+                            # 7.8 / TS 102 223 MMS Notification Download
+                            # 7.9 / TS 102 223 8.8 Terminal Applications
+                    ]):
+    pass
+
+# TS 101 220 Table 7.17
+class TimerExpiration(BER_TLV_IE, tag=0xD7):
+    pass
+
+# TS 101 220 Table 7.17 + TS 31.111 7.6.2
 class USSDDownload(BER_TLV_IE, tag=0xD9,
                    nested=[DeviceIdentities, USSDString]):
     pass
 
+# TS 101 220 Table 7.17 + TS 102 223 7.6
+class MmsTransferStatus(BER_TLV_IE, tag=0xDA):
+    pass
 
+# TS 101 220 Table 7.17 + 102 223
+class MmsNotificationDownload(BER_TLV_IE, tag=0xDB):
+    pass
 
+# TS 101 220 Table 7.17 + 102 223 7.8
+class TerminalApplication(BER_TLV_IE, tag=0xDC):
+    pass
 
+# TS 101 220 Table 7.17 + TS 31.111 7.10.2
+class GeographicalLocation(BER_TLV_IE, tag=0xDD,
+                           nested=[DeviceIdentities, GadShape, NmeaSentence]):
+    pass
+
+# TS 101 220 Table 7.17
+class EnvelopeContainer(BER_TLV_IE, tag=0xDE):
+    pass
+
+# TS 101 220 Table 7.17
+class ProSeReport(BER_TLV_IE, tag=0xDF):
+    pass
+
+# TS 101 220 Table 7.17
 class ProactiveCmd(BER_TLV_IE):
     def _compute_tag(self) -> int:
         return 0xD0
 
 
+class EventCollection(TLV_IE_Collection,
+                      nested=[SMSPPDownload, SMSCBDownload,
+                              EventDownload, CallControl, MoShortMessageControl,
+                              USSDDownload, GeographicalLocation, ProSeReport]):
+    pass
+
+
 # TS 101 220 Table 7.17 + 102 223 6.6.13/9.4 + TS 31.111 6.6.13
 class Refresh(ProactiveCmd, tag=0x01,
               nested=[CommandDetails, DeviceIdentities, FileList, Aid, AlphaIdentifier,
@@ -737,20 +963,24 @@ class Refresh(ProactiveCmd, tag=0x01,
                       ApplicationSpecificRefreshData, PlmnWactList, PlmnList]):
     pass
 
+# TS 102 223 Section 6.6.4
 class MoreTime(ProactiveCmd, tag=0x02,
-        nested=[CommandDetails]):
+        nested=[CommandDetails, DeviceIdentities]):
     pass
 
+# TS 102 223 Section 6.6.5
 class PollInterval(ProactiveCmd, tag=0x03,
-        nested=[CommandDetails]):
+        nested=[CommandDetails, DeviceIdentities, Duration]):
     pass
 
+# TS 102 223 Section 6.6.14
 class PollingOff(ProactiveCmd, tag=0x04,
-        nested=[CommandDetails]):
+        nested=[CommandDetails, DeviceIdentities]):
     pass
 
+# TS 102 223 Section 6.6.16
 class SetUpEventList(ProactiveCmd, tag=0x05,
-        nested=[CommandDetails]):
+        nested=[CommandDetails, DeviceIdentities, EventList]):
     pass
 
 # TS 31.111 Section 6.6.12
@@ -778,20 +1008,27 @@ class SendShortMessage(ProactiveCmd, tag=0x13,
                                SMS_TPDU, IconIdentifier, TextAttribute, FrameIdentifier]):
     pass
 
+# TS 102 223 6.6.24
 class SendDTMF(ProactiveCmd, tag=0x14,
-        nested=[CommandDetails]):
+        nested=[CommandDetails, DeviceIdentities, AlphaIdentifier,
+                DtmfString, IconIdentifier, TextAttribute, FrameIdentifier]):
     pass
 
+# TS 102 223 6.6.26
 class LaunchBrowser(ProactiveCmd, tag=0x15,
-        nested=[CommandDetails]):
+        nested=[CommandDetails, DeviceIdentities, BrowserIdentity, Url, Bearer, ProvisioningFileReference,
+                TextString, AlphaIdentifier, IconIdentifier, TextAttribute, FrameIdentifier,
+                NetworkAccessName]):
     pass
 
 class GeographicalLocationRequest(ProactiveCmd, tag=0x16,
         nested=[CommandDetails]):
     pass
 
+# TS 102 223 6.6.5
 class PlayTone(ProactiveCmd, tag=0x20,
-        nested=[CommandDetails]):
+        nested=[CommandDetails, DeviceIdentities, AlphaIdentifier,
+                Tone, Duration, IconIdentifier, TextAttribute, FrameIdentifier]):
     pass
 
 # TS 101 220 Table 7.17 + 102 223 6.6.1/9.4 CMD=0x21
@@ -978,8 +1215,8 @@ class ProactiveCommandBase(BER_TLV_IE, tag=0xD0, nested=[CommandDetails]):
         for c in self.children:
             if type(c).__name__ == 'CommandDetails':
                 return c
-        else:
-            return None
+            else:
+                return None
 
 class ProactiveCommand(TLV_IE_Collection,
                        nested=[Refresh, MoreTime, PollInterval, PollingOff, SetUpEventList, SetUpCall,
@@ -997,17 +1234,17 @@ class ProactiveCommand(TLV_IE_Collection,
     more difficult than any normal TLV IE Collection, because the content of one of the IEs defines the
     definitions of all the other IEs.  So we first need to find the CommandDetails, and then parse according
     to the command type indicated in that IE data."""
-    def from_bytes(self, binary: bytes) -> List[TLV_IE]:
+    def from_bytes(self, binary: bytes, context: dict = {}) -> List[TLV_IE]:
         # do a first parse step to get the CommandDetails
         pcmd = ProactiveCommandBase()
         pcmd.from_tlv(binary)
         cmd_details = pcmd.find_cmd_details()
         # then do a second decode stage for the specific
-        cmd_type = cmd_details.decoded['type_of_command']
+        cmd_type = TypeOfCommand.encmapping[cmd_details.decoded['type_of_command']]
         if cmd_type in self.members_by_tag:
             cls = self.members_by_tag[cmd_type]
             inst = cls()
-            dec, remainder = inst.from_tlv(binary)
+            _dec, remainder = inst.from_tlv(binary)
             self.decoded = inst
         else:
             self.decoded = pcmd
@@ -1019,9 +1256,18 @@ class ProactiveCommand(TLV_IE_Collection,
     def to_dict(self):
         return self.decoded.to_dict()
 
-    def to_bytes(self):
+    def to_bytes(self, context: dict = {}):
         return self.decoded.to_tlv()
 
+# TS 101 223 Section 6.8.0
+class TerminalResponse(TLV_IE_Collection,
+                       nested=[CommandDetails, DeviceIdentities, Result,
+                               Duration, TextString, ItemIdentifier,
+                               #TODO: LocalInformation and other optional/conditional IEs
+                               ChannelData, ChannelDataLength,
+                               ChannelStatus, BufferSize, BearerDescription,
+                               ]):
+    pass
 
 # reasonable default for playing with OTA
 # 010203040506070809101112131415161718192021222324252627282930313233

pySim/cdma_ruim.py

@@ -19,15 +19,15 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import enum
 
-from pySim.utils import *
+from construct import Bytewise, BitStruct, BitsInteger, Struct, FlagsEnum
+from osmocom.utils import *
+from osmocom.construct import *
+
 from pySim.filesystem import *
-from pySim.profile import match_ruim
 from pySim.profile import CardProfile, CardProfileAddon
 from pySim.ts_51_011 import CardProfileSIM
 from pySim.ts_51_011 import DF_TELECOM, DF_GSM
 from pySim.ts_51_011 import EF_ServiceTable
-from pySim.construct import *
-from construct import *
 
 
 # Mapping between CDMA Service Number and its description
@@ -115,7 +115,7 @@ class EF_AD(TransparentEF):
     '''3.4.33 Administrative Data'''
 
     _test_de_encode = [
-        ( "000000", { 'ms_operation_mode' : 'normal', 'additional_info' : '0000', 'rfu' : '' } ),
+        ( "000000", { 'ms_operation_mode' : 'normal', 'additional_info' : b'\x00\x00', 'rfu' : b'' } ),
     ]
     _test_no_pad = True
 
@@ -128,15 +128,15 @@ class EF_AD(TransparentEF):
         cell_test = 0x04
 
     def __init__(self, fid='6f43', sfid=None, name='EF.AD',
-                 desc='Service Provider Name', size=(3, None), **kwargs):
+                 desc='Administrative Data', size=(3, None), **kwargs):
         super().__init__(fid, sfid=sfid, name=name, desc=desc, size=size, **kwargs)
         self._construct = Struct(
-            # Byte 1: Display Condition
+            # Byte 1: MS operation mode
             'ms_operation_mode'/Enum(Byte, self.OP_MODE),
             # Bytes 2-3: Additional information
-            'additional_info'/HexAdapter(Bytes(2)),
+            'additional_info'/Bytes(2),
             # Bytes 4..: RFU
-            'rfu'/HexAdapter(GreedyBytesRFU),
+            'rfu'/GreedyBytesRFU,
         )
 
 
@@ -178,20 +178,23 @@ class DF_CDMA(CardDF):
 class CardProfileRUIM(CardProfile):
     '''R-UIM card profile as per 3GPP2 C.S0023-D'''
 
-    ORDER = 2
+    ORDER = 20
 
     def __init__(self):
         super().__init__('R-UIM', desc='CDMA R-UIM Card', cla="a0",
                          sel_ctrl="0000", files_in_mf=[DF_TELECOM(), DF_GSM(), DF_CDMA()])
 
     @staticmethod
-    def decode_select_response(resp_hex: str) -> object:
+    def decode_select_response(data_hex: str) -> object:
         # TODO: Response parameters/data in case of DF_CDMA (section 2.6)
-        return CardProfileSIM.decode_select_response(resp_hex)
+        return CardProfileSIM.decode_select_response(data_hex)
+
+    @classmethod
+    def _try_match_card(cls, scc: SimCardCommands) -> None:
+        """ Try to access MF/DF.CDMA via 2G APDUs (3GPP TS 11.11), if this works,
+        the card is considered an R-UIM card for CDMA."""
+        cls._mf_select_test(scc, "a0", "0000", ["3f00", "7f25"])
 
-    @staticmethod
-    def match_with_card(scc: SimCardCommands) -> bool:
-        return match_ruim(scc)
 
 class AddonRUIM(CardProfileAddon):
     """An Addon that can be found on on a combined SIM + RUIM or UICC + RUIM to support CDMA."""

pySim/commands.py

@@ -21,13 +21,15 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
-from typing import List, Optional, Tuple
+from typing import List, Tuple
 import typing # construct also has a Union, so we do typing.Union below
+from construct import Construct, Struct, Const, Select
+from construct import Optional as COptional
+from osmocom.construct import LV, filter_dict
+from osmocom.utils import rpad, lpad, b2h, h2b, h2i, i2h, str_sanitize, Hexstr
+from osmocom.tlv import bertlv_encode_len
 
-from construct import *
-from pySim.construct import LV, filter_dict
-from pySim.utils import rpad, lpad, b2h, h2b, sw_match, bertlv_encode_len, Hexstr, h2i, i2h, str_sanitize, expand_hex, SwMatchstr
-from pySim.utils import Hexstr, SwHexstr, ResTuple
+from pySim.utils import sw_match, expand_hex, SwHexstr, ResTuple, SwMatchstr
 from pySim.exceptions import SwMatchError
 from pySim.transport import LinkBase
 
@@ -64,70 +66,67 @@ class SimCardCommands:
     byte by the respective instance. """
     def __init__(self, transport: LinkBase, lchan_nr: int = 0):
         self._tp = transport
-        self._cla_byte = None
         self.sel_ctrl = "0000"
         self.lchan_nr = lchan_nr
         # invokes the setter below
         self.cla_byte = "a0"
+        self.scp = None # Secure Channel Protocol
 
     def fork_lchan(self, lchan_nr: int) -> 'SimCardCommands':
         """Fork a per-lchan specific SimCardCommands instance off the current instance."""
         ret = SimCardCommands(transport = self._tp, lchan_nr = lchan_nr)
-        ret.cla_byte = self._cla_byte
+        ret.cla_byte = self.cla_byte
         ret.sel_ctrl = self.sel_ctrl
         return ret
 
     @property
-    def cla_byte(self) -> Hexstr:
-        """Return the (cached) patched default CLA byte for this card."""
-        return self._cla4lchan
-
-    @cla_byte.setter
-    def cla_byte(self, new_val: Hexstr):
-        """Set the (raw, without lchan) default CLA value for this card."""
-        self._cla_byte = new_val
-        # compute cached result
-        self._cla4lchan = cla_with_lchan(self._cla_byte, self.lchan_nr)
-
-    def cla4lchan(self, cla: Hexstr) -> Hexstr:
-        """Compute the lchan-patched value of the given CLA value. If no CLA
-        value is provided as argument, the lchan-patched version of the SimCardCommands._cla_byte
-        value is used. Most commands will use the latter, while some wish to override it and
-        can pass it as argument here."""
-        if not cla:
-            # return cached result to avoid re-computing this over and over again
-            return self._cla4lchan
+    def max_cmd_len(self) -> int:
+        """Maximum length of the command apdu data section. Depends on secure channel protocol used."""
+        if self.scp:
+            return 255 - self.scp.overhead
         else:
-            return cla_with_lchan(cla, self.lchan_nr)
+            return 255
 
-    def send_apdu(self, pdu: Hexstr) -> ResTuple:
+    def send_apdu(self, pdu: Hexstr, apply_lchan:bool = True) -> ResTuple:
         """Sends an APDU and auto fetch response data
 
         Args:
            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")
         """
-        return self._tp.send_apdu(pdu)
+        if apply_lchan:
+            pdu = cla_with_lchan(pdu[0:2], self.lchan_nr) + pdu[2:]
+        if self.scp:
+            return self.scp.send_apdu_wrapper(self._tp.send_apdu, pdu)
+        else:
+            return self._tp.send_apdu(pdu)
 
-    def send_apdu_checksw(self, pdu: Hexstr, sw: SwMatchstr = "9000") -> ResTuple:
+    def send_apdu_checksw(self, pdu: Hexstr, sw: SwMatchstr = "9000", apply_lchan:bool = True) -> ResTuple:
         """Sends an APDU and check returned SW
 
         Args:
            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.
+                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")
         """
-        return self._tp.send_apdu_checksw(pdu, sw)
+        if apply_lchan:
+            pdu = cla_with_lchan(pdu[0:2], self.lchan_nr) + pdu[2:]
+        if self.scp:
+            return self.scp.send_apdu_wrapper(self._tp.send_apdu_checksw, pdu, sw)
+        else:
+            return self._tp.send_apdu_checksw(pdu, sw)
 
     def send_apdu_constr(self, cla: Hexstr, ins: Hexstr, p1: Hexstr, p2: Hexstr, cmd_constr: Construct,
-                         cmd_data: Hexstr, resp_constr: Construct) -> Tuple[dict, SwHexstr]:
+                         cmd_data: Hexstr, resp_constr: Construct, apply_lchan:bool = True) -> Tuple[dict, SwHexstr]:
         """Build and sends an APDU using a 'construct' definition; parses response.
 
         Args:
@@ -137,14 +136,16 @@ class SimCardCommands:
                 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
+                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)
         """
-        cmd = cmd_constr.build(cmd_data) if cmd_data else ''
-        p3 = i2h([len(cmd)])
-        pdu = ''.join([cla, ins, p1, p2, p3, b2h(cmd)])
-        (data, sw) = self.send_apdu(pdu)
+        cmd = cmd_constr.build(cmd_data) if cmd_data else b''
+        lc = i2h([len(cmd)]) if cmd_data else ''
+        le = '00' if resp_constr else ''
+        pdu = ''.join([cla, ins, p1, p2, lc, b2h(cmd), le])
+        (data, sw) = self.send_apdu(pdu, apply_lchan = apply_lchan)
         if data:
             # filter the resulting dict to avoid '_io' members inside
             rsp = filter_dict(resp_constr.parse(h2b(data)))
@@ -154,7 +155,7 @@ class SimCardCommands:
 
     def send_apdu_constr_checksw(self, cla: Hexstr, ins: Hexstr, p1: Hexstr, p2: Hexstr,
                                  cmd_constr: Construct, cmd_data: Hexstr, resp_constr: Construct,
-                                 sw_exp: SwMatchstr="9000") -> Tuple[dict, SwHexstr]:
+                                 sw_exp: SwMatchstr="9000", apply_lchan:bool = True) -> Tuple[dict, SwHexstr]:
         """Build and sends an APDU using a 'construct' definition; parses response.
 
         Args:
@@ -169,8 +170,8 @@ class SimCardCommands:
         Returns:
                 Tuple of (decoded_data, sw)
         """
-        (rsp, sw) = self.send_apdu_constr(cla, ins,
-                                          p1, p2, cmd_constr, cmd_data, resp_constr)
+        (rsp, sw) = self.send_apdu_constr(cla, ins, p1, p2, cmd_constr, cmd_data, resp_constr,
+                                          apply_lchan = apply_lchan)
         if not sw_match(sw, sw_exp):
             raise SwMatchError(sw, sw_exp.lower(), self._tp.sw_interpreter)
         return (rsp, sw)
@@ -195,6 +196,7 @@ class SimCardCommands:
         # checking if the length of the remaining TLV string matches
         # what we get in the length field.
         # See also ETSI TS 102 221, chapter 11.1.1.3.0 Base coding.
+        # TODO: this likely just is normal BER-TLV ("All data objects are BER-TLV except if otherwise # defined.")
         exp_tlv_len = int(fcp[2:4], 16)
         if len(fcp[4:]) // 2 == exp_tlv_len:
             skip = 4
@@ -202,6 +204,7 @@ class SimCardCommands:
             exp_tlv_len = int(fcp[2:6], 16)
             if len(fcp[4:]) // 2 == exp_tlv_len:
                 skip = 6
+            raise ValueError('Cannot determine length of TLV-length')
 
         # Skip FCP tag and length
         tlv = fcp[skip:]
@@ -242,10 +245,10 @@ class SimCardCommands:
         """
 
         rv = []
-        if type(dir_list) is not list:
+        if not isinstance(dir_list, list):
             dir_list = [dir_list]
         for i in dir_list:
-            data, sw = self.send_apdu(self.cla_byte + "a4" + self.sel_ctrl + "02" + i)
+            data, sw = self.send_apdu(self.cla_byte + "a4" + self.sel_ctrl + "02" + i + "00")
             rv.append((data, sw))
             if sw != '9000':
                 return rv
@@ -261,10 +264,10 @@ class SimCardCommands:
                 list of return values (FCP in hex encoding) for each element of the path
         """
         rv = []
-        if type(dir_list) is not list:
+        if not isinstance(dir_list, list):
             dir_list = [dir_list]
         for i in dir_list:
-            data, sw = self.select_file(i)
+            data, _sw = self.select_file(i)
             rv.append(data)
         return rv
 
@@ -275,21 +278,21 @@ class SimCardCommands:
                 fid : file identifier as hex string
         """
 
-        return self.send_apdu_checksw(self.cla_byte + "a4" + self.sel_ctrl + "02" + fid)
+        return self.send_apdu_checksw(self.cla_byte + "a4" + self.sel_ctrl + "02" + fid + "00")
 
     def select_parent_df(self) -> ResTuple:
         """Execute SELECT to switch to the parent DF """
-        return self.send_apdu_checksw(self.cla_byte + "a4030400")
+        return self.send_apdu_checksw(self.cla_byte + "a40304")
 
     def select_adf(self, aid: Hexstr) -> ResTuple:
-        """Execute SELECT a given Applicaiton ADF.
+        """Execute SELECT a given Application ADF.
 
         Args:
                 aid : application identifier as hex string
         """
 
         aidlen = ("0" + format(len(aid) // 2, 'x'))[-2:]
-        return self.send_apdu_checksw(self.cla_byte + "a4" + "0404" + aidlen + aid)
+        return self.send_apdu_checksw(self.cla_byte + "a4" + "0404" + aidlen + aid + "00")
 
     def read_binary(self, ef: Path, length: int = None, offset: int = 0) -> ResTuple:
         """Execute READD BINARY.
@@ -310,14 +313,14 @@ class SimCardCommands:
         total_data = ''
         chunk_offset = 0
         while chunk_offset < length:
-            chunk_len = min(255, length-chunk_offset)
+            chunk_len = min(self.max_cmd_len, length-chunk_offset)
             pdu = self.cla_byte + \
                 'b0%04x%02x' % (offset + chunk_offset, chunk_len)
             try:
                 data, sw = self.send_apdu_checksw(pdu)
             except Exception as e:
-                raise ValueError('%s, failed to read (offset %d)' %
-                                 (str_sanitize(str(e)), offset))
+                e.add_note('failed to read (offset %d)' % offset)
+                raise e
             total_data += data
             chunk_offset += chunk_len
         return total_data, sw
@@ -368,7 +371,7 @@ class SimCardCommands:
         total_data = ''
         chunk_offset = 0
         while chunk_offset < data_length:
-            chunk_len = min(255, data_length - chunk_offset)
+            chunk_len = min(self.max_cmd_len, data_length - chunk_offset)
             # chunk_offset is bytes, but data slicing is hex chars, so we need to multiply by 2
             pdu = self.cla_byte + \
                 'd6%04x%02x' % (offset + chunk_offset, chunk_len) + \
@@ -376,8 +379,8 @@ class SimCardCommands:
             try:
                 chunk_data, chunk_sw = self.send_apdu_checksw(pdu)
             except Exception as e:
-                raise ValueError('%s, failed to write chunk (chunk_offset %d, chunk_len %d)' %
-                                 (str_sanitize(str(e)), chunk_offset, chunk_len))
+                e.add_note('failed to write chunk (chunk_offset %d, chunk_len %d)' % (chunk_offset, chunk_len))
+                raise e
             total_data += data
             chunk_offset += chunk_len
         if verify:
@@ -433,10 +436,10 @@ class SimCardCommands:
         else:
             # make sure the input data is padded to the record length using 0xFF.
             # In cases where the input data exceed we throw an exception.
-            if (len(data) // 2 > rec_length):
+            if len(data) // 2 > rec_length:
                 raise ValueError('Data length exceeds record length (expected max %d, got %d)' % (
                     rec_length, len(data) // 2))
-            elif (len(data) // 2 < rec_length):
+            elif len(data) // 2 < rec_length:
                 if leftpad:
                     data = lpad(data, rec_length * 2)
                 else:
@@ -492,9 +495,9 @@ class SimCardCommands:
     # TS 102 221 Section 11.3.1 low-level helper
     def _retrieve_data(self, tag: int, first: bool = True) -> ResTuple:
         if first:
-            pdu = self.cla4lchan('80') + 'cb008001%02x' % (tag)
+            pdu = '80cb008001%02x00' % (tag)
         else:
-            pdu = self.cla4lchan('80') + 'cb000000'
+            pdu = '80cb0000'
         return self.send_apdu_checksw(pdu)
 
     def retrieve_data(self, ef: Path, tag: int) -> ResTuple:
@@ -511,7 +514,7 @@ class SimCardCommands:
         # retrieve first block
         data, sw = self._retrieve_data(tag, first=True)
         total_data += data
-        while sw == '62f1' or sw == '62f2':
+        while sw in ['62f1', '62f2']:
             data, sw = self._retrieve_data(tag, first=False)
             total_data += data
         return total_data, sw
@@ -522,9 +525,9 @@ class SimCardCommands:
             p1 = 0x80
         else:
             p1 = 0x00
-        if isinstance(data, bytes) or isinstance(data, bytearray):
+        if isinstance(data, (bytes, bytearray)):
             data = b2h(data)
-        pdu = self.cla4lchan('80') + 'db00%02x%02x%s' % (p1, len(data)//2, data)
+        pdu = '80db00%02x%02x%s' % (p1, len(data)//2, data)
         return self.send_apdu_checksw(pdu)
 
     def set_data(self, ef, tag: int, value: str, verify: bool = False, conserve: bool = False) -> ResTuple:
@@ -552,10 +555,10 @@ class SimCardCommands:
         total_len = len(tlv_bin)
         remaining = tlv_bin
         while len(remaining) > 0:
-            fragment = remaining[:255]
+            fragment = remaining[:self.max_cmd_len]
             rdata, sw = self._set_data(fragment, first=first)
             first = False
-            remaining = remaining[255:]
+            remaining = remaining[self.max_cmd_len:]
         return rdata, sw
 
     def run_gsm(self, rand: Hexstr) -> ResTuple:
@@ -567,21 +570,20 @@ class SimCardCommands:
         if len(rand) != 32:
             raise ValueError('Invalid rand')
         self.select_path(['3f00', '7f20'])
-        return self.send_apdu_checksw(self.cla4lchan('a0') + '88000010' + rand, sw='9000')
+        return self.send_apdu_checksw('a088000010' + rand + '00', sw='9000')
 
     def authenticate(self, rand: Hexstr, autn: Hexstr, context: str = '3g') -> ResTuple:
         """Execute AUTHENTICATE (USIM/ISIM).
 
         Args:
                 rand : 16 byte random data as hex string (RAND)
-                autn : 8 byte Autentication Token (AUTN)
+                autn : 8 byte Authentication Token (AUTN)
                 context : 16 byte random data ('3g' or 'gsm')
         """
         # 3GPP TS 31.102 Section 7.1.2.1
-        AuthCmd3G = Struct('rand'/LV, 'autn'/Optional(LV))
+        AuthCmd3G = Struct('rand'/LV, 'autn'/COptional(LV))
         AuthResp3GSyncFail = Struct(Const(b'\xDC'), 'auts'/LV)
-        AuthResp3GSuccess = Struct(
-            Const(b'\xDB'), 'res'/LV, 'ck'/LV, 'ik'/LV, 'kc'/Optional(LV))
+        AuthResp3GSuccess = Struct(Const(b'\xDB'), 'res'/LV, 'ck'/LV, 'ik'/LV, 'kc'/COptional(LV))
         AuthResp3G = Select(AuthResp3GSyncFail, AuthResp3GSuccess)
         # build parameters
         cmd_data = {'rand': rand, 'autn': autn}
@@ -589,6 +591,8 @@ class SimCardCommands:
             p2 = '81'
         elif context == 'gsm':
             p2 = '80'
+        else:
+            raise ValueError("Unsupported context '%s'" % context)
         (data, sw) = self.send_apdu_constr_checksw(
             self.cla_byte, '88', '00', p2, AuthCmd3G, cmd_data, AuthResp3G)
         if 'auts' in data:
@@ -599,7 +603,7 @@ class SimCardCommands:
 
     def status(self) -> ResTuple:
         """Execute a STATUS command as per TS 102 221 Section 11.1.2."""
-        return self.send_apdu_checksw(self.cla4lchan('80') + 'F20000ff')
+        return self.send_apdu_checksw('80F20000')
 
     def deactivate_file(self) -> ResTuple:
         """Execute DECATIVATE FILE command as per TS 102 221 Section 11.1.14."""
@@ -614,12 +618,12 @@ class SimCardCommands:
         return self.send_apdu_checksw(self.cla_byte + '44000002' + fid)
 
     def create_file(self, payload: Hexstr) -> ResTuple:
-        """Execute CREEATE FILE command as per TS 102 222 Section 6.3"""
+        """Execute CREATE FILE command as per TS 102 222 Section 6.3"""
         return self.send_apdu_checksw(self.cla_byte + 'e00000%02x%s' % (len(payload)//2, payload))
 
     def resize_file(self, payload: Hexstr) -> ResTuple:
         """Execute RESIZE FILE command as per TS 102 222 Section 6.10"""
-        return self.send_apdu_checksw(self.cla4lchan('80') + 'd40000%02x%s' % (len(payload)//2, payload))
+        return self.send_apdu_checksw('80d40000%02x%s' % (len(payload)//2, payload))
 
     def delete_file(self, fid: Hexstr) -> ResTuple:
         """Execute DELETE FILE command as per TS 102 222 Section 6.4"""
@@ -648,7 +652,7 @@ class SimCardCommands:
             p1 = 0x80
         else:
             p1 = 0x00
-        pdu = self.cla_byte + '70%02x%02x00' % (p1, lchan_nr)
+        pdu = self.cla_byte + '70%02x%02x' % (p1, lchan_nr)
         return self.send_apdu_checksw(pdu)
 
     def reset_card(self) -> Hexstr:
@@ -659,8 +663,8 @@ class SimCardCommands:
         if sw_match(sw, '63cx'):
             raise RuntimeError('Failed to %s chv_no 0x%02X with code 0x%s, %i tries left.' %
                                (op_name, chv_no, b2h(pin_code).upper(), int(sw[3])))
-        elif (sw != '9000'):
-            raise SwMatchError(sw, '9000')
+        if sw != '9000':
+            raise SwMatchError(sw, '9000', self._tp.sw_interpreter)
 
     def verify_chv(self, chv_no: int, code: Hexstr) -> ResTuple:
         """Verify a given CHV (Card Holder Verification == PIN)
@@ -731,7 +735,7 @@ class SimCardCommands:
         Args:
                 payload : payload as hex string
         """
-        return self.send_apdu_checksw('80c20000%02x%s' % (len(payload)//2, payload))
+        return self.send_apdu_checksw('80c20000%02x%s' % (len(payload)//2, payload) + "00", apply_lchan = False)
 
     def terminal_profile(self, payload: Hexstr) -> ResTuple:
         """Send TERMINAL PROFILE to card
@@ -740,7 +744,7 @@ class SimCardCommands:
                 payload : payload as hex string
         """
         data_length = len(payload) // 2
-        data, sw = self.send_apdu(('80100000%02x' % data_length) + payload)
+        data, sw = self.send_apdu_checksw(('80100000%02x' % data_length) + payload, apply_lchan = False)
         return (data, sw)
 
     # ETSI TS 102 221 11.1.22
@@ -754,33 +758,31 @@ class SimCardCommands:
         def encode_duration(secs: int) -> Hexstr:
             if secs >= 10*24*60*60:
                 return '04%02x' % (secs // (10*24*60*60))
-            elif secs >= 24*60*60:
+            if secs >= 24*60*60:
                 return '03%02x' % (secs // (24*60*60))
-            elif secs >= 60*60:
+            if secs >= 60*60:
                 return '02%02x' % (secs // (60*60))
-            elif secs >= 60:
+            if secs >= 60:
                 return '01%02x' % (secs // 60)
-            else:
-                return '00%02x' % secs
+            return '00%02x' % secs
 
         def decode_duration(enc: Hexstr) -> int:
             time_unit = enc[:2]
             length = h2i(enc[2:4])[0]
             if time_unit == '04':
                 return length * 10*24*60*60
-            elif time_unit == '03':
+            if time_unit == '03':
                 return length * 24*60*60
-            elif time_unit == '02':
+            if time_unit == '02':
                 return length * 60*60
-            elif time_unit == '01':
+            if time_unit == '01':
                 return length * 60
-            elif time_unit == '00':
+            if time_unit == '00':
                 return length
-            else:
-                raise ValueError('Time unit must be 0x00..0x04')
+            raise ValueError('Time unit must be 0x00..0x04')
         min_dur_enc = encode_duration(min_len_secs)
         max_dur_enc = encode_duration(max_len_secs)
-        data, sw = self.send_apdu_checksw('8076000004' + min_dur_enc + max_dur_enc)
+        data, sw = self.send_apdu_checksw('8076000004' + min_dur_enc + max_dur_enc, apply_lchan = False)
         negotiated_duration_secs = decode_duration(data[:4])
         resume_token = data[4:]
         return (negotiated_duration_secs, resume_token, sw)
@@ -790,11 +792,12 @@ class SimCardCommands:
         """Send SUSPEND UICC (resume) to the card."""
         if len(h2b(token)) != 8:
             raise ValueError("Token must be 8 bytes long")
-        data, sw = self.send_apdu_checksw('8076010008' + token)
+        data, sw = self.send_apdu_checksw('8076010008' + token, apply_lchan = False)
         return (data, sw)
 
+    # GPC_SPE_034 11.3
     def get_data(self, tag: int, cla: int = 0x00):
-        data, sw = self.send_apdu('%02xca%04x00' % (cla, tag))
+        data, sw = self.send_apdu_checksw('%02xca%04x00' % (cla, tag))
         return (data, sw)
 
     # TS 31.102 Section 7.5.2

pySim/construct.py

@@ -1,552 +0,0 @@
-from construct.lib.containers import Container, ListContainer
-from construct.core import EnumIntegerString
-import typing
-from construct import *
-from construct.core import evaluate, BitwisableString
-from construct.lib import integertypes
-from pySim.utils import b2h, h2b, swap_nibbles
-import gsm0338
-import codecs
-import ipaddress
-
-"""Utility code related to the integration of the 'construct' declarative parser."""
-
-# (C) 2021-2022 by Harald Welte <laforge@osmocom.org>
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 2 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-
-class HexAdapter(Adapter):
-    """convert a bytes() type to a string of hex nibbles."""
-
-    def _decode(self, obj, context, path):
-        return b2h(obj)
-
-    def _encode(self, obj, context, path):
-        return h2b(obj)
-
-class Utf8Adapter(Adapter):
-    """convert a bytes() type that contains utf8 encoded text to human readable text."""
-
-    def _decode(self, obj, context, path):
-        # In case the string contains only 0xff bytes we interpret it as an empty string
-        if obj == b'\xff' * len(obj):
-                return ""
-        return codecs.decode(obj, "utf-8")
-
-    def _encode(self, obj, context, path):
-        return codecs.encode(obj, "utf-8")
-
-class GsmOrUcs2Adapter(Adapter):
-    """Try to encode into a GSM 03.38 string; if that fails, fall back to UCS-2 as described
-    in TS 102 221 Annex A."""
-    def _decode(self, obj, context, path):
-        # In case the string contains only 0xff bytes we interpret it as an empty string
-        if obj == b'\xff' * len(obj):
-                return ""
-        # one of the magic bytes of TS 102 221 Annex A
-        if obj[0] in [0x80, 0x81, 0x82]:
-            ad = Ucs2Adapter(GreedyBytes)
-        else:
-            ad = GsmString(GreedyBytes)
-        return ad._decode(obj, context, path)
-
-    def _encode(self, obj, context, path):
-        # first try GSM 03.38; then fall back to TS 102 221 Annex A UCS-2
-        try:
-            ad = GsmString(GreedyBytes)
-            return ad._encode(obj, context, path)
-        except:
-            ad = Ucs2Adapter(GreedyBytes)
-            return ad._encode(obj, context, path)
-
-class Ucs2Adapter(Adapter):
-    """convert a bytes() type that contains UCS2 encoded characters encoded as defined in TS 102 221
-    Annex A to normal python string representation (and back)."""
-    def _decode(self, obj, context, path):
-        # In case the string contains only 0xff bytes we interpret it as an empty string
-        if obj == b'\xff' * len(obj):
-                return ""
-        if obj[0] == 0x80:
-            # TS 102 221 Annex A Variant 1
-            return codecs.decode(obj[1:], 'utf_16_be')
-        elif obj[0] == 0x81:
-            # TS 102 221 Annex A Variant 2
-            out = ""
-            # second byte contains a value indicating the number of characters
-            num_of_chars = obj[1]
-            # the third byte contains an 8 bit number which defines bits 15 to 8 of a 16 bit base
-            # pointer, where bit 16 is set to zero, and bits 7 to 1 are also set to zero. These
-            # sixteen bits constitute a base pointer to a "half-page" in the UCS2 code space
-            base_ptr = obj[2] << 7
-            for ch in obj[3:3+num_of_chars]:
-                # if bit 8 of the byte is set to zero, the remaining 7 bits of the byte contain a
-                # GSM Default Alphabet character, whereas if bit 8 of the byte is set to one, then
-                # the remaining seven bits are an offset value added to the 16 bit base pointer
-                # defined earlier, and the resultant 16 bit value is a UCS2 code point
-                if ch & 0x80:
-                    codepoint = (ch & 0x7f) + base_ptr
-                    out += codecs.decode(codepoint.to_bytes(2, byteorder='big'), 'utf_16_be')
-                else:
-                    out += codecs.decode(bytes([ch]), 'gsm03.38')
-            return out
-        elif obj[0] == 0x82:
-            # TS 102 221 Annex A Variant 3
-            out = ""
-            # second byte contains a value indicating the number of characters
-            num_of_chars = obj[1]
-            # third and fourth bytes contain a 16 bit number which defines the complete 16 bit base
-            # pointer to a half-page in the UCS2 code space, for use with some or all of the
-            # remaining bytes in the string
-            base_ptr = obj[2] << 8 | obj[3]
-            for ch in obj[4:4+num_of_chars]:
-                # if bit 8 of the byte is set to zero, the remaining 7 bits of the byte contain a
-                # GSM Default Alphabet character, whereas if bit 8 of the byte is set to one, the
-                # remaining seven bits are an offset value added to the base pointer defined in
-                # bytes three and four, and the resultant 16 bit value is a UCS2 code point, else: #
-                # GSM default alphabet
-                if ch & 0x80:
-                    codepoint = (ch & 0x7f) + base_ptr
-                    out += codecs.decode(codepoint.to_bytes(2, byteorder='big'), 'utf_16_be')
-                else:
-                    out += codecs.decode(bytes([ch]), 'gsm03.38')
-            return out
-        else:
-            raise ValueError('First byte of TS 102 221 UCS-2 must be 0x80, 0x81 or 0x82')
-
-    def _encode(self, obj, context, path):
-        def encodable_in_gsm338(instr: str) -> bool:
-            """Determine if given input string is encode-ale in gsm03.38."""
-            try:
-                # TODO: figure out if/how we can constrain to default alphabet.  The gsm0338
-                # library seems to include the spanish lock/shift table
-                codecs.encode(instr, 'gsm03.38')
-            except ValueError:
-                return False
-            return True
-
-        def codepoints_not_in_gsm338(instr: str) -> typing.List[int]:
-            """Return an integer list of UCS2 codepoints for all characters of 'inster'
-            which are not representable in the GSM 03.38 default alphabet."""
-            codepoint_list = []
-            for c in instr:
-                if encodable_in_gsm338(c):
-                    continue
-                c_codepoint = int.from_bytes(codecs.encode(c, 'utf_16_be'), byteorder='big')
-                codepoint_list.append(c_codepoint)
-            return codepoint_list
-
-        def diff_between_min_and_max_of_list(inlst: typing.List) -> int:
-            return max(inlst) - min(inlst)
-
-        def encodable_in_variant2(instr: str) -> bool:
-            codepoint_prefix = None
-            for c in instr:
-                if encodable_in_gsm338(c):
-                    continue
-                c_codepoint = int.from_bytes(codecs.encode(c, 'utf_16_be'), byteorder='big')
-                if c_codepoint >= 0x8000:
-                    return False
-                c_prefix = c_codepoint >> 7
-                if codepoint_prefix is None:
-                    codepoint_prefix = c_prefix
-                else:
-                    if c_prefix != codepoint_prefix:
-                        return False
-            return True
-
-        def encodable_in_variant3(instr: str) -> bool:
-            codepoint_list = codepoints_not_in_gsm338(instr)
-            # compute delta between max and min; check if it's encodable in 7 bits
-            if diff_between_min_and_max_of_list(codepoint_list) >= 0x80:
-                return False
-            return True
-
-        def _encode_variant1(instr: str) -> bytes:
-            """Encode according to TS 102 221 Annex A Variant 1"""
-            return b'\x80' + codecs.encode(obj, 'utf_16_be')
-
-        def _encode_variant2(instr: str) -> bytes:
-            """Encode according to TS 102 221 Annex A Variant 2"""
-            codepoint_prefix = None
-            # second byte contains a value indicating the number of characters
-            hdr = b'\x81' + len(instr).to_bytes(1, byteorder='big')
-            chars = b''
-            for c in instr:
-                try:
-                    enc = codecs.encode(c, 'gsm03.38')
-                except ValueError:
-                    c_codepoint = int.from_bytes(codecs.encode(c, 'utf_16_be'), byteorder='big')
-                    c_prefix = c_codepoint >> 7
-                    if codepoint_prefix is None:
-                        codepoint_prefix = c_prefix
-                    assert codepoint_prefix == c_prefix
-                    enc = (0x80 + (c_codepoint & 0x7f)).to_bytes(1, byteorder='big')
-                chars += enc
-            if codepoint_prefix == None:
-                codepoint_prefix = 0
-            return hdr + codepoint_prefix.to_bytes(1, byteorder='big') + chars
-
-        def _encode_variant3(instr: str) -> bytes:
-            """Encode according to TS 102 221 Annex A Variant 3"""
-            # second byte contains a value indicating the number of characters
-            hdr = b'\x82' + len(instr).to_bytes(1, byteorder='big')
-            chars = b''
-            codepoint_list = codepoints_not_in_gsm338(instr)
-            codepoint_base = min(codepoint_list)
-            for c in instr:
-                try:
-                    # if bit 8 of the byte is set to zero, the remaining 7 bits of the byte contain a GSM
-                    # Default # Alphabet character
-                    enc = codecs.encode(c, 'gsm03.38')
-                except ValueError:
-                    # if bit 8 of the byte is set to one, the remaining seven bits are an offset
-                    # value added to the base pointer defined in bytes three and four, and the
-                    # resultant 16 bit value is a UCS2 code point
-                    c_codepoint = int.from_bytes(codecs.encode(c, 'utf_16_be'), byteorder='big')
-                    c_codepoint_delta = c_codepoint - codepoint_base
-                    assert c_codepoint_delta < 0x80
-                    enc = (0x80 + c_codepoint_delta).to_bytes(1, byteorder='big')
-                chars += enc
-            # third and fourth bytes contain a 16 bit number which defines the complete 16 bit base
-            # pointer to a half-page in the UCS2 code space
-            return hdr + codepoint_base.to_bytes(2, byteorder='big') + chars
-
-        if encodable_in_variant2(obj):
-            return _encode_variant2(obj)
-        elif encodable_in_variant3(obj):
-            return _encode_variant3(obj)
-        else:
-            return _encode_variant1(obj)
-
-class BcdAdapter(Adapter):
-    """convert a bytes() type to a string of BCD nibbles."""
-
-    def _decode(self, obj, context, path):
-        return swap_nibbles(b2h(obj))
-
-    def _encode(self, obj, context, path):
-        return h2b(swap_nibbles(obj))
-
-class PlmnAdapter(BcdAdapter):
-    """convert a bytes(3) type to BCD string like 262-02 or 262-002."""
-    def _decode(self, obj, context, path):
-        bcd = super()._decode(obj, context, path)
-        if bcd[3] == 'f':
-            return '-'.join([bcd[:3], bcd[4:]])
-        else:
-            return '-'.join([bcd[:3], bcd[3:]])
-
-    def _encode(self, obj, context, path):
-        l = obj.split('-')
-        if len(l[1]) == 2:
-            bcd = l[0] + 'f' + l[1]
-        else:
-            bcd = l[0] + l[1]
-        return super()._encode(bcd, context, path)
-
-class InvertAdapter(Adapter):
-    """inverse logic (false->true, true->false)."""
-    @staticmethod
-    def _invert_bool_in_obj(obj):
-        for k,v in obj.items():
-            # skip all private entries
-            if k.startswith('_'):
-                continue
-            if v == False:
-                obj[k] = True
-            elif v == True:
-                obj[k] = False
-        return obj
-
-    def _decode(self, obj, context, path):
-        return self._invert_bool_in_obj(obj)
-
-    def _encode(self, obj, context, path):
-        return self._invert_bool_in_obj(obj)
-
-class Rpad(Adapter):
-    """
-    Encoder appends padding bytes (b'\\xff') or characters up to target size.
-    Decoder removes trailing padding bytes/characters.
-
-    Parameters:
-        subcon: Subconstruct as defined by construct library
-        pattern: set padding pattern (default: b'\\xff')
-        num_per_byte: number of 'elements' per byte. E.g. for hex nibbles: 2
-    """
-
-    def __init__(self, subcon, pattern=b'\xff', num_per_byte=1):
-        super().__init__(subcon)
-        self.pattern = pattern
-        self.num_per_byte = num_per_byte
-
-    def _decode(self, obj, context, path):
-        return obj.rstrip(self.pattern)
-
-    def _encode(self, obj, context, path):
-        target_size = self.sizeof() * self.num_per_byte
-        if len(obj) > target_size:
-            raise SizeofError("Input ({}) exceeds target size ({})".format(
-                len(obj), target_size))
-        return obj + self.pattern * (target_size - len(obj))
-
-class MultiplyAdapter(Adapter):
-    """
-    Decoder multiplies by multiplicator
-    Encoder divides by multiplicator
-
-    Parameters:
-        subcon: Subconstruct as defined by construct library
-        multiplier: Multiplier to apply to raw encoded value
-    """
-
-    def __init__(self, subcon, multiplicator):
-        super().__init__(subcon)
-        self.multiplicator = multiplicator
-
-    def _decode(self, obj, context, path):
-        return obj * 8
-
-    def _encode(self, obj, context, path):
-        return obj // 8
-
-
-class GsmStringAdapter(Adapter):
-    """Convert GSM 03.38 encoded bytes to a string."""
-
-    def __init__(self, subcon, codec='gsm03.38', err='strict'):
-        super().__init__(subcon)
-        self.codec = codec
-        self.err = err
-
-    def _decode(self, obj, context, path):
-        return obj.decode(self.codec)
-
-    def _encode(self, obj, context, path):
-        return obj.encode(self.codec, self.err)
-
-class Ipv4Adapter(Adapter):
-    """
-    Encoder converts from 4 bytes to string representation (A.B.C.D).
-    Decoder converts from string representation (A.B.C.D) to four bytes.
-    """
-    def _decode(self, obj, context, path):
-        ia = ipaddress.IPv4Address(obj)
-        return ia.compressed
-
-    def _encode(self, obj, context, path):
-        ia = ipaddress.IPv4Address(obj)
-        return ia.packed
-
-class Ipv6Adapter(Adapter):
-    """
-    Encoder converts from 16 bytes to string representation.
-    Decoder converts from string representation to 16 bytes.
-    """
-    def _decode(self, obj, context, path):
-        ia = ipaddress.IPv6Address(obj)
-        return ia.compressed
-
-    def _encode(self, obj, context, path):
-        ia = ipaddress.IPv6Address(obj)
-        return ia.packed
-
-
-def filter_dict(d, exclude_prefix='_'):
-    """filter the input dict to ensure no keys starting with 'exclude_prefix' remain."""
-    if not isinstance(d, dict):
-        return d
-    res = {}
-    for (key, value) in d.items():
-        if key.startswith(exclude_prefix):
-            continue
-        if type(value) is dict:
-            res[key] = filter_dict(value)
-        else:
-            res[key] = value
-    return res
-
-
-def normalize_construct(c):
-    """Convert a construct specific type to a related base type, mostly useful
-    so we can serialize it."""
-    # we need to include the filter_dict as we otherwise get elements like this
-    # in the dict: '_io': <_io.BytesIO object at 0x7fdb64e05860> which we cannot json-serialize
-    c = filter_dict(c)
-    if isinstance(c, Container) or isinstance(c, dict):
-        r = {k: normalize_construct(v) for (k, v) in c.items()}
-    elif isinstance(c, ListContainer):
-        r = [normalize_construct(x) for x in c]
-    elif isinstance(c, list):
-        r = [normalize_construct(x) for x in c]
-    elif isinstance(c, EnumIntegerString):
-        r = str(c)
-    else:
-        r = c
-    return r
-
-
-def parse_construct(c, raw_bin_data: bytes, length: typing.Optional[int] = None, exclude_prefix: str = '_', context: dict = {}):
-    """Helper function to wrap around normalize_construct() and filter_dict()."""
-    if not length:
-        length = len(raw_bin_data)
-    try:
-        parsed = c.parse(raw_bin_data, total_len=length, **context)
-    except StreamError as e:
-        # if the input is all-ff, this means the content is undefined.  Let's avoid passing StreamError
-        # exceptions in those situations (which might occur if a length field 0xff is 255 but then there's
-        # actually less bytes in the remainder of the file.
-        if all([v == 0xff for v in raw_bin_data]):
-            return None
-        else:
-            raise e
-    return normalize_construct(parsed)
-
-def build_construct(c, decoded_data, context: dict = {}):
-    """Helper function to handle total_len."""
-    return c.build(decoded_data, total_len=None, **context)
-
-# here we collect some shared / common definitions of data types
-LV = Prefixed(Int8ub, HexAdapter(GreedyBytes))
-
-# Default value for Reserved for Future Use (RFU) bits/bytes
-# See TS 31.101 Sec. "3.4 Coding Conventions"
-__RFU_VALUE = 0
-
-# Field that packs Reserved for Future Use (RFU) bit
-FlagRFU = Default(Flag, __RFU_VALUE)
-
-# Field that packs Reserved for Future Use (RFU) byte
-ByteRFU = Default(Byte, __RFU_VALUE)
-
-# Field that packs all remaining Reserved for Future Use (RFU) bytes
-GreedyBytesRFU = Default(GreedyBytes, b'')
-
-
-def BitsRFU(n=1):
-    '''
-    Field that packs Reserved for Future Use (RFU) bit(s)
-    as defined in TS 31.101 Sec. "3.4 Coding Conventions"
-
-    Use this for (currently) unused/reserved bits whose contents
-    should be initialized automatically but should not be cleared
-    in the future or when restoring read data (unlike padding).
-
-    Parameters:
-        n (Integer): Number of bits (default: 1)
-    '''
-    return Default(BitsInteger(n), __RFU_VALUE)
-
-
-def BytesRFU(n=1):
-    '''
-    Field that packs Reserved for Future Use (RFU) byte(s)
-    as defined in TS 31.101 Sec. "3.4 Coding Conventions"
-
-    Use this for (currently) unused/reserved bytes whose contents
-    should be initialized automatically but should not be cleared
-    in the future or when restoring read data (unlike padding).
-
-    Parameters:
-        n (Integer): Number of bytes (default: 1)
-    '''
-    return Default(Bytes(n), __RFU_VALUE)
-
-
-def GsmString(n):
-    '''
-    GSM 03.38 encoded byte string of fixed length n.
-    Encoder appends padding bytes (b'\\xff') to maintain
-    length. Decoder removes those trailing bytes.
-
-    Exceptions are raised for invalid characters
-    and length excess.
-
-    Parameters:
-        n (Integer): Fixed length of the encoded byte string
-    '''
-    return GsmStringAdapter(Rpad(Bytes(n), pattern=b'\xff'), codec='gsm03.38')
-
-def GsmOrUcs2String(n):
-    '''
-    GSM 03.38 or UCS-2 (TS 102 221 Annex A) encoded byte string of fixed length n.
-    Encoder appends padding bytes (b'\\xff') to maintain
-    length. Decoder removes those trailing bytes.
-
-    Exceptions are raised for invalid characters
-    and length excess.
-
-    Parameters:
-        n (Integer): Fixed length of the encoded byte string
-    '''
-    return GsmOrUcs2Adapter(Rpad(Bytes(n), pattern=b'\xff'))
-
-class GreedyInteger(Construct):
-    """A variable-length integer implementation, think of combining GrredyBytes with BytesInteger."""
-    def __init__(self, signed=False, swapped=False, minlen=0):
-        super().__init__()
-        self.signed = signed
-        self.swapped = swapped
-        self.minlen = minlen
-
-    def _parse(self, stream, context, path):
-        data = stream_read_entire(stream, path)
-        if evaluate(self.swapped, context):
-            data = swapbytes(data)
-        try:
-            return int.from_bytes(data, byteorder='big', signed=self.signed)
-        except ValueError as e:
-            raise IntegerError(str(e), path=path)
-
-    def __bytes_required(self, i, minlen=0):
-        if self.signed:
-            raise NotImplementedError("FIXME: Implement support for encoding signed integer")
-
-        # compute how many bytes we need
-        nbytes = 1
-        while True:
-            i = i >> 8
-            if i == 0:
-                break
-            else:
-                nbytes = nbytes + 1
-
-        # round up to the minimum number
-        # of bytes we anticipate
-        if nbytes < minlen:
-            nbytes = minlen
-
-        return nbytes
-
-    def _build(self, obj, stream, context, path):
-        if not isinstance(obj, integertypes):
-            raise IntegerError(f"value {obj} is not an integer", path=path)
-        length = self.__bytes_required(obj, self.minlen)
-        try:
-            data = obj.to_bytes(length, byteorder='big', signed=self.signed)
-        except ValueError as e:
-            raise IntegerError(str(e), path=path)
-        if evaluate(self.swapped, context):
-            data = swapbytes(data)
-        stream_write(stream, data, length, path)
-        return obj
-
-# merged definitions of 24.008 + 23.040
-TypeOfNumber = Enum(BitsInteger(3), unknown=0, international=1, national=2, network_specific=3,
-                    short_code=4, alphanumeric=5, abbreviated=6, reserved_for_extension=7)
-NumberingPlan = Enum(BitsInteger(4), unknown=0, isdn_e164=1, data_x121=3, telex_f69=4,
-                     sc_specific_5=5, sc_specific_6=6, national=8, private=9,
-                     ermes=10, reserved_cts=11, reserved_for_extension=15)
-TonNpi = BitStruct('ext'/Flag, 'type_of_number'/TypeOfNumber, 'numbering_plan_id'/NumberingPlan)

pySim/esim/__init__.py

@@ -1,24 +1,70 @@
 import sys
-from typing import Optional
+from typing import Optional, Tuple
 from importlib import resources
 
-import asn1tools
+class PMO:
+    """Convenience conversion class for ProfileManagementOperation as used in ES9+ notifications."""
+    pmo4operation = {
+        'install': 0x80,
+        'enable': 0x40,
+        'disable': 0x20,
+        'delete': 0x10,
+    }
 
-def compile_asn1_subdir(subdir_name:str):
+    def __init__(self, op: str):
+        if not op in self.pmo4operation:
+            raise ValueError('Unknown operation "%s"' % op)
+        self.op = op
+
+    def to_int(self):
+        return self.pmo4operation[self.op]
+
+    @staticmethod
+    def _num_bits(data: int)-> int:
+        for i in range(0, 8):
+            if data & (1 << i):
+                return 8-i
+        return 0
+
+    def to_bitstring(self) -> Tuple[bytes, int]:
+        """return value in a format as used by asn1tools for BITSTRING."""
+        val = self.to_int()
+        return (bytes([val]), self._num_bits(val))
+
+    @classmethod
+    def from_int(cls, i: int) -> 'PMO':
+        """Parse an integer representation."""
+        for k, v in cls.pmo4operation.items():
+            if v == i:
+                return cls(k)
+        raise ValueError('Unknown PMO 0x%02x' % i)
+
+    @classmethod
+    def from_bitstring(cls, bstr: Tuple[bytes, int]) -> 'PMO':
+        """Parse a asn1tools BITSTRING representation."""
+        return cls.from_int(bstr[0][0])
+
+    def __str__(self):
+        return self.op
+
+def compile_asn1_subdir(subdir_name:str, codec='der'):
     """Helper function that compiles ASN.1 syntax from all files within given subdir"""
+    import asn1tools
     asn_txt = ''
     __ver = sys.version_info
     if (__ver.major, __ver.minor) >= (3, 9):
         for i in resources.files('pySim.esim').joinpath('asn1').joinpath(subdir_name).iterdir():
+            if not i.name.endswith('.asn'):
+                continue
             asn_txt += i.read_text()
             asn_txt += "\n"
     #else:
         #print(resources.read_text(__name__, 'asn1/rsp.asn'))
-    return asn1tools.compile_string(asn_txt, codec='der')
+    return asn1tools.compile_string(asn_txt, codec=codec)
 
 
-# SGP.22 section 4.1 Activation Code
 class ActivationCode:
+    """SGP.22 section 4.1 Activation Code"""
     def __init__(self, hostname:str, token:str, oid: Optional[str] = None, cc_required: Optional[bool] = False):
         if '$' in hostname:
             raise ValueError('$ sign not permitted in hostname')
@@ -34,6 +80,7 @@ class ActivationCode:
 
     @staticmethod
     def decode_str(ac: str) -> dict:
+        """decode an activation code from its string representation."""
         if ac[0] != '1':
             raise ValueError("Unsupported AC_Format '%s'!" % ac[0])
         ac_elements = ac.split('$')

pySim/esim/asn1/saip/PE_Definitions-3.3.1.asn

@@ -983,7 +983,7 @@ keyAccess [22] OCTET STRING (SIZE (1)) DEFAULT '00'H,
 keyIdentifier [2] OCTET STRING (SIZE (1)),
 keyVersionNumber [3] OCTET STRING (SIZE (1)),
 keyCounterValue [5] OCTET STRING OPTIONAL,
-keyCompontents SEQUENCE (SIZE (1..MAX)) OF SEQUENCE {
+keyComponents SEQUENCE (SIZE (1..MAX)) OF SEQUENCE {
 		keyType [0] OCTET STRING,
 		keyData [6] OCTET STRING,
 		macLength[7] UInt8 DEFAULT 8

pySim/esim/bsp.py

@@ -1,11 +1,9 @@
-# Early proof-of-concept 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.
-#
+"""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."""
+
 # (C) 2023 by Harald Welte <laforge@osmocom.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -23,7 +21,6 @@
 
 # SGP.22 v3.0 Section 2.5.3:
 # That block of data is split into segments of a maximum size of 1020 bytes (including the tag, length field and MAC).
-MAX_SEGMENT_SIZE = 1020
 
 import abc
 from typing import List
@@ -36,13 +33,17 @@ from cryptography.hazmat.primitives.kdf.x963kdf import X963KDF
 from Cryptodome.Cipher import AES
 from Cryptodome.Hash import CMAC
 
-from pySim.utils import bertlv_encode_len, bertlv_parse_one, b2h
+from osmocom.utils import b2h
+from osmocom.tlv import bertlv_encode_len, bertlv_parse_one
 
 # don't log by default
 logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
 
+MAX_SEGMENT_SIZE = 1020
+
 class BspAlgo(abc.ABC):
+    """Base class representing a cryptographic algorithm within the BSP (BPP Security Protocol)."""
     blocksize: int
 
     def _get_padding(self, in_len: int, multiple: int, padding: int = 0) -> bytes:
@@ -50,16 +51,17 @@ class BspAlgo(abc.ABC):
         if in_len % multiple == 0:
             return b''
         pad_cnt = multiple - (in_len % multiple)
-        return b'\x00' * pad_cnt
+        return bytes([padding]) * pad_cnt
 
     def _pad_to_multiple(self, indat: bytes, multiple: int, padding: int = 0) -> bytes:
         """Pad the input data to multiples of 'multiple'."""
-        return indat + self._get_padding(len(indat), self.blocksize, padding)
+        return indat + self._get_padding(len(indat), multiple, padding)
 
     def __str__(self):
         return self.__class__.__name__
 
 class BspAlgoCrypt(BspAlgo, abc.ABC):
+    """Base class representing an encryption/decryption algorithm within the BSP (BPP Security Protocol)."""
 
     def __init__(self, s_enc: bytes):
         self.s_enc = s_enc
@@ -71,7 +73,7 @@ class BspAlgoCrypt(BspAlgo, abc.ABC):
         block_nr = self.block_nr
         ciphertext = self._encrypt(padded_data)
         logger.debug("encrypt(block_nr=%u, s_enc=%s, plaintext=%s, padded=%s) -> %s",
-                     block_nr, b2h(self.s_enc), b2h(data), b2h(padded_data), b2h(ciphertext))
+                     block_nr, b2h(self.s_enc)[:20], b2h(data)[:20], b2h(padded_data)[:20], b2h(ciphertext)[:20])
         return ciphertext
 
     def decrypt(self, data:bytes) -> bytes:
@@ -81,19 +83,17 @@ class BspAlgoCrypt(BspAlgo, abc.ABC):
     @abc.abstractmethod
     def _unpad(self, padded: bytes) -> bytes:
         """Remove the padding from padded data."""
-        pass
 
     @abc.abstractmethod
     def _encrypt(self, data:bytes) -> bytes:
         """Actual implementation, to be implemented by derived class."""
-        pass
 
     @abc.abstractmethod
     def _decrypt(self, data:bytes) -> bytes:
         """Actual implementation, to be implemented by derived class."""
-        pass
 
 class BspAlgoCryptAES128(BspAlgoCrypt):
+    """AES-CBC-128 implementation of the BPP Security Protocol for GSMA SGP.22 eSIM."""
     name = 'AES-CBC-128'
     blocksize = 16
 
@@ -134,6 +134,7 @@ class BspAlgoCryptAES128(BspAlgoCrypt):
 
 
 class BspAlgoMac(BspAlgo, abc.ABC):
+    """Base class representing a message authentication code algorithm within the BSP (BPP Security Protocol)."""
     l_mac = 0 # must be overridden by derived class
 
     def __init__(self, s_mac: bytes, initial_mac_chaining_value: bytes):
@@ -148,10 +149,20 @@ class BspAlgoMac(BspAlgo, abc.ABC):
         temp_data = self.mac_chain + tag_and_length + data
         old_mcv = self.mac_chain
         c_mac = self._auth(temp_data)
+
+        # DEBUG: Show MAC computation details
+        logger.debug(f"MAC_DEBUG: tag=0x{tag:02x}, lcc={lcc}")
+        logger.debug(f"MAC_DEBUG: tag_and_length: {tag_and_length.hex()}")
+        logger.debug(f"MAC_DEBUG: mac_chain[:20]: {old_mcv[:20].hex()}")
+        logger.debug(f"MAC_DEBUG: temp_data[:20]: {temp_data[:20].hex()}")
+        logger.debug(f"MAC_DEBUG: c_mac: {c_mac.hex()}")
+
         # The output data is computed by concatenating the following data: the tag, the final length, the result of step 2 and the C-MAC value.
         ret = tag_and_length + data + c_mac
+        logger.debug(f"MAC_DEBUG: final_output[:20]: {ret[:20].hex()}")
+
         logger.debug("auth(tag=0x%x, mcv=%s, s_mac=%s, plaintext=%s, temp=%s) -> %s",
-                     tag, b2h(old_mcv), b2h(self.s_mac), b2h(data), b2h(temp_data), b2h(ret))
+                     tag, b2h(old_mcv)[:20], b2h(self.s_mac)[:20], b2h(data)[:20], b2h(temp_data)[:20], b2h(ret)[:20])
         return ret
 
     def verify(self, ciphertext: bytes) -> bool:
@@ -166,9 +177,9 @@ class BspAlgoMac(BspAlgo, abc.ABC):
     @abc.abstractmethod
     def _auth(self, temp_data: bytes) -> bytes:
         """To be implemented by algorithm specific derived class."""
-        pass
 
 class BspAlgoMacAES128(BspAlgoMac):
+    """AES-CMAC-128 implementation of the BPP Security Protocol for GSMA SGP.22 eSIM."""
     name = 'AES-CMAC-128'
     l_mac = 8
 
@@ -203,6 +214,11 @@ def bsp_key_derivation(shared_secret: bytes, key_type: int, key_length: int, hos
     s_enc = out[l:2*l]
     s_mac = out[l*2:3*l]
 
+    logger.debug(f"BSP_KDF_DEBUG: kdf_out = {b2h(out)}")
+    logger.debug(f"BSP_KDF_DEBUG: initial_mcv = {b2h(initial_mac_chaining_value)}")
+    logger.debug(f"BSP_KDF_DEBUG: s_enc = {b2h(s_enc)}")
+    logger.debug(f"BSP_KDF_DEBUG: s_mac = {b2h(s_mac)}")
+
     return s_enc, s_mac, initial_mac_chaining_value
 
 
@@ -227,12 +243,24 @@ class BspInstance:
         return cls(s_enc, s_mac, initial_mcv)
 
     def encrypt_and_mac_one(self, tag: int, plaintext:bytes) -> bytes:
-        """Encrypt + MAC a single plaintext TLV. Returns the protected ciphertex."""
+        """Encrypt + MAC a single plaintext TLV. Returns the protected ciphertext."""
         assert tag <= 255
         assert len(plaintext) <= self.max_payload_size
-        logger.debug("encrypt_and_mac_one(tag=0x%x, plaintext=%s)", tag, b2h(plaintext))
+
+        # DEBUG: Show what we're processing
+        logger.debug(f"BSP_DEBUG: encrypt_and_mac_one(tag=0x{tag:02x}, plaintext_len={len(plaintext)})")
+        logger.debug(f"BSP_DEBUG: plaintext[:20]: {plaintext[:20].hex()}")
+        logger.debug(f"BSP_DEBUG: s_enc[:20]: {self.c_algo.s_enc[:20].hex()}")
+        logger.debug(f"BSP_DEBUG: s_mac[:20]: {self.m_algo.s_mac[:20].hex()}")
+
+        logger.debug("encrypt_and_mac_one(tag=0x%x, plaintext=%s)", tag, b2h(plaintext)[:20])
         ciphered = self.c_algo.encrypt(plaintext)
+        logger.debug(f"BSP_DEBUG: ciphered[:20]: {ciphered[:20].hex()}")
+
         maced = self.m_algo.auth(tag, ciphered)
+        logger.debug(f"BSP_DEBUG: final_result[:20]: {maced[:20].hex()}")
+        logger.debug(f"BSP_DEBUG: final_result_len: {len(maced)}")
+
         return maced
 
     def encrypt_and_mac(self, tag: int, plaintext:bytes) -> List[bytes]:
@@ -252,11 +280,11 @@ class BspInstance:
         return result
 
     def mac_only_one(self, tag: int, plaintext: bytes) -> bytes:
-        """MAC a single plaintext TLV. Returns the protected ciphertex."""
+        """MAC a single plaintext TLV. Returns the protected ciphertext."""
         assert tag <= 255
-        assert len(plaintext) < self.max_payload_size
+        assert len(plaintext) <= self.max_payload_size
         maced = self.m_algo.auth(tag, plaintext)
-        # The data block counter for ICV caluclation is incremented also for each segment with C-MAC only.
+        # The data block counter for ICV calculation is incremented also for each segment with C-MAC only.
         self.c_algo.block_nr += 1
         return maced
 
@@ -289,7 +317,9 @@ class BspInstance:
 
     def demac_only_one(self, ciphertext: bytes) -> bytes:
         payload = self.m_algo.verify(ciphertext)
-        tdict, l, val, remain = bertlv_parse_one(payload)
+        _tdict, _l, val, _remain = bertlv_parse_one(payload)
+        # The data block counter for ICV calculation is incremented also for each segment with C-MAC only.
+        self.c_algo.block_nr += 1
         return val
 
     def demac_only(self, ciphertext_list: List[bytes]) -> bytes:

pySim/esim/es2p.py

@@ -0,0 +1,362 @@
+"""GSMA eSIM RSP ES2+ interface according to SGP.22 v2.5"""
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import requests
+from klein import Klein
+from twisted.internet import defer, protocol, ssl, task, endpoints, reactor
+from twisted.internet.posixbase import PosixReactorBase
+from pathlib import Path
+from twisted.web.server import Site, Request
+
+import logging
+from datetime import datetime
+import time
+
+from pySim.esim.http_json_api import *
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+class param:
+    class Iccid(ApiParamString):
+        """String representation of 18 to 20 digits, where the 20th digit MAY optionally be the padding
+        character F."""
+        @classmethod
+        def _encode(cls, data):
+            data = str(data)
+            # SGP.22 version prior to 2.2 do not require support for 19-digit ICCIDs, so let's always
+            # encode it with padding F at the end.
+            if len(data) == 19:
+                data += 'F'
+            return data
+
+        @classmethod
+        def verify_encoded(cls, data):
+            if len(data) not in (18, 19, 20):
+                raise ValueError('ICCID (%s) length (%u) invalid' % (data, len(data)))
+
+        @classmethod
+        def _decode(cls, data):
+            # strip trailing padding (if it's 20 digits)
+            if len(data) == 20 and data[-1] in ['F', 'f']:
+                data = data[:-1]
+            return data
+
+        @classmethod
+        def verify_decoded(cls, data):
+            data = str(data)
+            if len(data) not in (18, 19, 20):
+                raise ValueError('ICCID (%s) length (%u) invalid' % (data, len(data)))
+            if len(data) == 19:
+                decimal_part = data
+            else:
+                decimal_part = data[:-1]
+                final_part = data[-1:]
+                if final_part not in ['F', 'f'] and not final_part.isdecimal():
+                    raise ValueError('ICCID (%s) contains non-decimal characters' % data)
+            if not decimal_part.isdecimal():
+                raise ValueError('ICCID (%s) contains non-decimal characters' % data)
+
+
+    class Eid(ApiParamString):
+        """String of 32 decimal characters"""
+        @classmethod
+        def verify_encoded(cls, data):
+            if len(data) != 32:
+                raise ValueError('EID length invalid: "%s" (%u)' % (data, len(data)))
+
+        @classmethod
+        def verify_decoded(cls, data):
+            if not data.isdecimal():
+                raise ValueError('EID (%s) contains non-decimal characters' % data)
+
+    class ProfileType(ApiParamString):
+        pass
+
+    class MatchingId(ApiParamString):
+        pass
+
+    class ConfirmationCode(ApiParamString):
+        pass
+
+    class SmdsAddress(ApiParamFqdn):
+        pass
+
+    class ReleaseFlag(ApiParamBoolean):
+        pass
+
+    class FinalProfileStatusIndicator(ApiParamString):
+        pass
+
+    class Timestamp(ApiParamString):
+        """String format as specified by W3C: YYYY-MM-DDThh:mm:ssTZD"""
+        @classmethod
+        def _decode(cls, data):
+            return datetime.fromisoformat(data)
+
+        @classmethod
+        def _encode(cls, data):
+            return datetime.isoformat(data)
+
+    class NotificationPointId(ApiParamInteger):
+        pass
+
+    class NotificationPointStatus(ApiParam):
+        pass
+
+    class ResultData(ApiParamBase64):
+        pass
+
+class Es2PlusApiFunction(JsonHttpApiFunction):
+    """Base class for representing an ES2+ API Function."""
+    pass
+
+# ES2+ DownloadOrder function (SGP.22 section 5.3.1)
+class DownloadOrder(Es2PlusApiFunction):
+    path = '/gsma/rsp2/es2plus/downloadOrder'
+    input_params = {
+        'header': JsonRequestHeader,
+        'eid': param.Eid,
+        'iccid': param.Iccid,
+        'profileType': param.ProfileType
+      }
+    input_mandatory = ['header']
+    output_params = {
+        'header': JsonResponseHeader,
+        'iccid': param.Iccid,
+      }
+    output_mandatory = ['header', 'iccid']
+
+# ES2+ ConfirmOrder function (SGP.22 section 5.3.2)
+class ConfirmOrder(Es2PlusApiFunction):
+    path = '/gsma/rsp2/es2plus/confirmOrder'
+    input_params = {
+        'header': JsonRequestHeader,
+        'iccid': param.Iccid,
+        'eid': param.Eid,
+        'matchingId': param.MatchingId,
+        'confirmationCode': param.ConfirmationCode,
+        'smdsAddress': param.SmdsAddress,
+        'releaseFlag': param.ReleaseFlag,
+      }
+    input_mandatory = ['header', 'iccid', 'releaseFlag']
+    output_params = {
+        'header': JsonResponseHeader,
+        'eid': param.Eid,
+        'matchingId': param.MatchingId,
+        'smdpAddress': SmdpAddress,
+      }
+    output_mandatory = ['header', 'matchingId']
+
+# ES2+ CancelOrder function (SGP.22 section 5.3.3)
+class CancelOrder(Es2PlusApiFunction):
+    path = '/gsma/rsp2/es2plus/cancelOrder'
+    input_params = {
+        'header': JsonRequestHeader,
+        'iccid': param.Iccid,
+        'eid': param.Eid,
+        'matchingId': param.MatchingId,
+        'finalProfileStatusIndicator': param.FinalProfileStatusIndicator,
+      }
+    input_mandatory = ['header', 'finalProfileStatusIndicator', 'iccid']
+    output_params = {
+        'header': JsonResponseHeader,
+      }
+    output_mandatory = ['header']
+
+# ES2+ ReleaseProfile function (SGP.22 section 5.3.4)
+class ReleaseProfile(Es2PlusApiFunction):
+    path = '/gsma/rsp2/es2plus/releaseProfile'
+    input_params = {
+        'header': JsonRequestHeader,
+        'iccid': param.Iccid,
+      }
+    input_mandatory = ['header', 'iccid']
+    output_params = {
+        'header': JsonResponseHeader,
+      }
+    output_mandatory = ['header']
+
+# ES2+ HandleDownloadProgress function (SGP.22 section 5.3.5)
+class HandleDownloadProgressInfo(Es2PlusApiFunction):
+    path = '/gsma/rsp2/es2plus/handleDownloadProgressInfo'
+    input_params = {
+        'header': JsonRequestHeader,
+        'eid': param.Eid,
+        'iccid': param.Iccid,
+        'profileType': param.ProfileType,
+        'timestamp': param.Timestamp,
+        'notificationPointId': param.NotificationPointId,
+        'notificationPointStatus': param.NotificationPointStatus,
+        'resultData': param.ResultData,
+    }
+    input_mandatory = ['header', 'iccid', 'profileType', 'timestamp', 'notificationPointId', 'notificationPointStatus']
+    expected_http_status = 204
+
+class Es2pApiClient:
+    """Main class representing a full ES2+ API client. Has one method for each API function."""
+    def __init__(self, url_prefix:str, func_req_id:str, server_cert_verify: str = None, client_cert: str = None):
+        self.func_id = 0
+        self.session = requests.Session()
+        if server_cert_verify:
+            self.session.verify = server_cert_verify
+        if client_cert:
+            self.session.cert = client_cert
+
+        self.downloadOrder = JsonHttpApiClient(DownloadOrder(), url_prefix, func_req_id, self.session)
+        self.confirmOrder = JsonHttpApiClient(ConfirmOrder(), url_prefix, func_req_id, self.session)
+        self.cancelOrder = JsonHttpApiClient(CancelOrder(), url_prefix, func_req_id, self.session)
+        self.releaseProfile = JsonHttpApiClient(ReleaseProfile(), url_prefix, func_req_id, self.session)
+        self.handleDownloadProgressInfo = JsonHttpApiClient(HandleDownloadProgressInfo(), url_prefix, func_req_id, self.session)
+
+    def _gen_func_id(self) -> str:
+        """Generate the next function call id."""
+        self.func_id += 1
+        return 'FCI-%u-%u' % (time.time(), self.func_id)
+
+    def call_downloadOrder(self, data: dict) -> dict:
+        """Perform ES2+ DownloadOrder function (SGP.22 section 5.3.1)."""
+        return self.downloadOrder.call(data, self._gen_func_id())
+
+    def call_confirmOrder(self, data: dict) -> dict:
+        """Perform ES2+ ConfirmOrder function (SGP.22 section 5.3.2)."""
+        return self.confirmOrder.call(data, self._gen_func_id())
+
+    def call_cancelOrder(self, data: dict) -> dict:
+        """Perform ES2+ CancelOrder function (SGP.22 section 5.3.3)."""
+        return self.cancelOrder.call(data, self._gen_func_id())
+
+    def call_releaseProfile(self, data: dict) -> dict:
+        """Perform ES2+ CancelOrder function (SGP.22 section 5.3.4)."""
+        return self.releaseProfile.call(data, self._gen_func_id())
+
+    def call_handleDownloadProgressInfo(self, data: dict) -> dict:
+        """Perform ES2+ HandleDownloadProgressInfo function (SGP.22 section 5.3.5)."""
+        return self.handleDownloadProgressInfo.call(data, self._gen_func_id())
+
+class Es2pApiServerHandlerSmdpp(abc.ABC):
+    """ES2+ (SMDP+ side) API Server handler class. The API user is expected to override the contained methods."""
+
+    @abc.abstractmethod
+    def call_downloadOrder(self, data: dict) -> (dict, str):
+        """Perform ES2+ DownloadOrder function (SGP.22 section 5.3.1)."""
+        pass
+
+    @abc.abstractmethod
+    def call_confirmOrder(self, data: dict) -> (dict, str):
+        """Perform ES2+ ConfirmOrder function (SGP.22 section 5.3.2)."""
+        pass
+
+    @abc.abstractmethod
+    def call_cancelOrder(self, data: dict) -> (dict, str):
+        """Perform ES2+ CancelOrder function (SGP.22 section 5.3.3)."""
+        pass
+
+    @abc.abstractmethod
+    def call_releaseProfile(self, data: dict) -> (dict, str):
+        """Perform ES2+ CancelOrder function (SGP.22 section 5.3.4)."""
+        pass
+
+class Es2pApiServerHandlerMno(abc.ABC):
+    """ES2+ (MNO side) API Server handler class. The API user is expected to override the contained methods."""
+
+    @abc.abstractmethod
+    def call_handleDownloadProgressInfo(self, data: dict) -> (dict, str):
+        """Perform ES2+ HandleDownloadProgressInfo function (SGP.22 section 5.3.5)."""
+        pass
+
+class Es2pApiServer(abc.ABC):
+    """Main class representing a full ES2+ API server. Has one method for each API function."""
+    app = None
+
+    def __init__(self, port: int, interface: str, server_cert: str = None, client_cert_verify: str = None):
+        logger.debug("HTTP SRV: starting ES2+ API server on %s:%s" % (interface, port))
+        self.port = port
+        self.interface = interface
+        if server_cert:
+            self.server_cert = ssl.PrivateCertificate.loadPEM(Path(server_cert).read_text())
+        else:
+            self.server_cert = None
+        if client_cert_verify:
+            self.client_cert_verify = ssl.Certificate.loadPEM(Path(client_cert_verify).read_text())
+        else:
+            self.client_cert_verify = None
+
+    def reactor(self, reactor: PosixReactorBase):
+        logger.debug("HTTP SRV: listen on %s:%s" % (self.interface, self.port))
+        if self.server_cert:
+            if self.client_cert_verify:
+                reactor.listenSSL(self.port, Site(self.app.resource()), self.server_cert.options(self.client_cert_verify),
+                                  interface=self.interface)
+            else:
+                reactor.listenSSL(self.port, Site(self.app.resource()), self.server_cert.options(),
+                                  interface=self.interface)
+        else:
+            reactor.listenTCP(self.port, Site(self.app.resource()), interface=self.interface)
+        return defer.Deferred()
+
+class Es2pApiServerSmdpp(Es2pApiServer):
+    """ES2+ (SMDP+ side) API Server."""
+    app = Klein()
+
+    def __init__(self, port: int, interface: str, handler: Es2pApiServerHandlerSmdpp,
+                 server_cert: str = None, client_cert_verify: str = None):
+        super().__init__(port, interface, server_cert, client_cert_verify)
+        self.handler = handler
+        self.downloadOrder = JsonHttpApiServer(DownloadOrder(), handler.call_downloadOrder)
+        self.confirmOrder = JsonHttpApiServer(ConfirmOrder(), handler.call_confirmOrder)
+        self.cancelOrder = JsonHttpApiServer(CancelOrder(), handler.call_cancelOrder)
+        self.releaseProfile = JsonHttpApiServer(ReleaseProfile(), handler.call_releaseProfile)
+        task.react(self.reactor)
+
+    @app.route(DownloadOrder.path)
+    def call_downloadOrder(self, request: Request) -> dict:
+        """Perform ES2+ DownloadOrder function (SGP.22 section 5.3.1)."""
+        return self.downloadOrder.call(request)
+
+    @app.route(ConfirmOrder.path)
+    def call_confirmOrder(self, request: Request) -> dict:
+        """Perform ES2+ ConfirmOrder function (SGP.22 section 5.3.2)."""
+        return self.confirmOrder.call(request)
+
+    @app.route(CancelOrder.path)
+    def call_cancelOrder(self, request: Request) -> dict:
+        """Perform ES2+ CancelOrder function (SGP.22 section 5.3.3)."""
+        return self.cancelOrder.call(request)
+
+    @app.route(ReleaseProfile.path)
+    def call_releaseProfile(self, request: Request) -> dict:
+        """Perform ES2+ CancelOrder function (SGP.22 section 5.3.4)."""
+        return self.releaseProfile.call(request)
+
+class Es2pApiServerMno(Es2pApiServer):
+    """ES2+ (MNO side) API Server."""
+
+    app = Klein()
+
+    def __init__(self, port: int, interface: str, handler: Es2pApiServerHandlerMno,
+                 server_cert: str = None, client_cert_verify: str = None):
+        super().__init__(port, interface, server_cert, client_cert_verify)
+        self.handler = handler
+        self.handleDownloadProgressInfo = JsonHttpApiServer(HandleDownloadProgressInfo(),
+                                                            handler.call_handleDownloadProgressInfo)
+        task.react(self.reactor)
+
+    @app.route(HandleDownloadProgressInfo.path)
+    def call_handleDownloadProgressInfo(self, request: Request) -> dict:
+        """Perform ES2+ HandleDownloadProgressInfo function (SGP.22 section 5.3.5)."""
+        return self.handleDownloadProgressInfo.call(request)

pySim/esim/es8p.py

@@ -1,6 +1,5 @@
-# Implementation of GSMA eSIM RSP (Remote SIM Provisioning) ES8+
-# as per SGP22 v3.0 Section 5.5
-#
+"""Implementation of GSMA eSIM RSP (Remote SIM Provisioning) ES8+ as per SGP22 v3.0 Section 5.5"""
+
 # (C) 2023-2024 by Harald Welte <laforge@osmocom.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -17,10 +16,17 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 from typing import Dict, List, Optional
-from pySim.utils import b2h, h2b, bertlv_encode_tag, bertlv_encode_len
+from cryptography.hazmat.primitives.asymmetric import ec
+from osmocom.utils import b2h, h2b
+from osmocom.tlv import bertlv_encode_tag, bertlv_encode_len, bertlv_parse_one_rawtag
+from osmocom.tlv import bertlv_return_one_rawtlv
 
 import pySim.esim.rsp as rsp
 from pySim.esim.bsp import BspInstance
+from pySim.esim import PMO
+
+import logging
+logger = logging.getLogger(__name__)
 
 # Given that GSMA RSP uses ASN.1 in a very weird way, we actually cannot encode the full data type before
 # signing, but we have to build parts of it separately first, then sign that, so we can put the signature
@@ -70,18 +76,53 @@ def gen_replace_session_keys(ppk_enc: bytes, ppk_cmac: bytes, initial_mcv: bytes
 class ProfileMetadata:
     """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"""
-    def __init__(self, iccid_bin: bytes, spn: str, profile_name: str):
+    def __init__(self, iccid_bin: bytes, spn: str, profile_name: str, profile_class = 'operational'):
         self.iccid_bin = iccid_bin
         self.spn = spn
         self.profile_name = profile_name
+        self.profile_class = profile_class
+        self.icon = None
+        self.icon_type = None
+        self.notifications = []
+
+    def set_icon(self, is_png: bool, icon_data: bytes):
+        """Set the icon that is part of the metadata."""
+        if len(icon_data) > 1024:
+            raise ValueError('Icon data must not exceed 1024 bytes')
+        self.icon = icon_data
+        if is_png:
+            self.icon_type = 1
+        else:
+            self.icon_type = 0
+
+    def add_notification(self, event: str, address: str):
+        """Add an 'other' notification to the notification configuration of the metadata"""
+        self.notifications.append((event, address))
 
     def gen_store_metadata_request(self) -> bytes:
-        """Generate encoded (but unsigned) StoreMetadataReqest DO (SGP.22 5.5.3)"""
+        """Generate encoded (but unsigned) StoreMetadataRequest DO (SGP.22 5.5.3)"""
         smr = {
             'iccid': self.iccid_bin,
             'serviceProviderName': self.spn,
             'profileName': self.profile_name,
         }
+        if self.profile_class == 'test':
+            smr['profileClass'] = 0
+        elif self.profile_class == 'provisioning':
+            smr['profileClass'] = 1
+        elif self.profile_class == 'operational':
+            smr['profileClass'] = 2
+        else:
+            raise ValueError('Unsupported Profile Class %s' % self.profile_class)
+        if self.icon:
+            smr['icon'] = self.icon
+            smr['iconType'] = self.icon_type
+        nci = []
+        for n in self.notifications:
+            pmo = PMO(n[0])
+            nci.append({'profileManagementOperation': pmo.to_bitstring(), 'notificationAddress': n[1]})
+        if len(nci):
+            smr['notificationConfigurationInfo'] = nci
         return rsp.asn1.encode('StoreMetadataRequest', smr)
 
 
@@ -167,8 +208,12 @@ class BoundProfilePackage(ProfilePackage):
         # 'initialiseSecureChannelRequest'
         bpp_seq = rsp.asn1.encode('InitialiseSecureChannelRequest', iscr)
         # firstSequenceOf87
+        logger.debug("BPP_ENCODE_DEBUG: Encrypting ConfigureISDP with BSP keys")
+        logger.debug(f"BPP_ENCODE_DEBUG: BSP S-ENC: {bsp.c_algo.s_enc.hex()}")
+        logger.debug(f"BPP_ENCODE_DEBUG: BSP S-MAC: {bsp.m_algo.s_mac.hex()}")
         bpp_seq += encode_seq(0xa0, bsp.encrypt_and_mac(0x87, conf_idsp_bin))
         # sequenceOF88
+        logger.debug("BPP_ENCODE_DEBUG: MAC-only StoreMetadata with BSP keys")
         bpp_seq += encode_seq(0xa1, bsp.mac_only(0x88, smr_bin))
 
         if self.ppp: # we have to use session keys
@@ -183,3 +228,79 @@ class BoundProfilePackage(ProfilePackage):
 
         # manual DER encode: wrap in outer SEQUENCE
         return bertlv_encode_tag(0xbf36) + bertlv_encode_len(len(bpp_seq)) + bpp_seq
+
+    def decode(self, euicc_ot, eid: str, bpp_bin: bytes):
+        """Decode a BPP into the PPP and subsequently UPP. This is what happens inside an eUICC."""
+
+        def split_bertlv_sequence(sequence: bytes) -> List[bytes]:
+            remainder = sequence
+            ret = []
+            while remainder:
+                _tag, _l, tlv, remainder = bertlv_return_one_rawtlv(remainder)
+                ret.append(tlv)
+            return ret
+
+        # we don't use rsp.asn1.decode('boundProfilePackage') here, as the BSP needs
+        # fully encoded + MACed TLVs including their tag + length values.
+        #bpp = rsp.asn1.decode('BoundProfilePackage', bpp_bin)
+
+        tag, _l, v, _remainder = bertlv_parse_one_rawtag(bpp_bin)
+        if len(_remainder):
+            raise ValueError('Excess data at end of TLV')
+        if tag != 0xbf36:
+            raise ValueError('Unexpected outer tag: %s' % tag)
+
+        # InitialiseSecureChannelRequest
+        tag, _l, iscr_bin, remainder = bertlv_return_one_rawtlv(v)
+        iscr = rsp.asn1.decode('InitialiseSecureChannelRequest', iscr_bin)
+
+        # configureIsdpRequest
+        tag, _l, firstSeqOf87, remainder = bertlv_parse_one_rawtag(remainder)
+        if tag != 0xa0:
+            raise ValueError("Unexpected 'firstSequenceOf87' tag: %s" % tag)
+        firstSeqOf87 = split_bertlv_sequence(firstSeqOf87)
+
+        # storeMetadataRequest
+        tag, _l, seqOf88, remainder = bertlv_parse_one_rawtag(remainder)
+        if tag != 0xa1:
+            raise ValueError("Unexpected 'sequenceOf88' tag: %s" % tag)
+        seqOf88 = split_bertlv_sequence(seqOf88)
+
+        tag, _l, tlv, remainder = bertlv_parse_one_rawtag(remainder)
+        if tag == 0xa2:
+            secondSeqOf87 = split_bertlv_sequence(tlv)
+            tag2, _l, seqOf86, remainder = bertlv_parse_one_rawtag(remainder)
+            if tag2 != 0xa3:
+                raise ValueError("Unexpected 'sequenceOf86' tag: %s" % tag)
+            seqOf86 = split_bertlv_sequence(seqOf86)
+        elif tag == 0xa3:
+            secondSeqOf87 = None
+            seqOf86 = split_bertlv_sequence(tlv)
+        else:
+            raise ValueError("Unexpected 'secondSequenceOf87' tag: %s" % tag)
+
+        # extract smdoOtpk from initialiseSecureChannel
+        smdp_otpk = iscr['smdpOtpk']
+
+        # Generate Session Keys using the CRT, opPK.DP.ECKA and otSK.EUICC.ECKA according to annex G
+        smdp_public_key = ec.EllipticCurvePublicKey.from_encoded_point(euicc_ot.curve, smdp_otpk)
+        self.shared_secret = euicc_ot.exchange(ec.ECDH(), smdp_public_key)
+
+        crt = iscr['controlRefTemplate']
+        bsp = BspInstance.from_kdf(self.shared_secret, int.from_bytes(crt['keyType'], 'big'), int.from_bytes(crt['keyLen'], 'big'), crt['hostId'], h2b(eid))
+
+        self.encoded_configureISDPRequest = bsp.demac_and_decrypt(firstSeqOf87)
+        self.configureISDPRequest = rsp.asn1.decode('ConfigureISDPRequest', self.encoded_configureISDPRequest)
+
+        self.encoded_storeMetadataRequest = bsp.demac_only(seqOf88)
+        self.storeMetadataRequest = rsp.asn1.decode('StoreMetadataRequest', self.encoded_storeMetadataRequest)
+
+        if secondSeqOf87 != None:
+            rsk_bin = bsp.demac_and_decrypt(secondSeqOf87)
+            rsk = rsp.asn1.decode('ReplaceSessionKeysRequest', rsk_bin)
+            # process replace_session_keys!
+            bsp = BspInstance(rsk['ppkEnc'], rsk['ppkCmac'], rsk['initialMacChainingValue'])
+            self.replaceSessionKeysRequest = rsk
+
+        self.upp = bsp.demac_and_decrypt(seqOf86)
+        return self.upp

pySim/esim/es9p.py

@@ -0,0 +1,177 @@
+"""GSMA eSIM RSP ES9+ interface according to SGP.22 v2.5"""
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import requests
+import logging
+import time
+
+import pySim.esim.rsp as rsp
+from pySim.esim.http_json_api import *
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+class param:
+    class RspAsn1Par(ApiParamBase64):
+        """Generalized RSP ASN.1 parameter: base64-wrapped ASN.1 DER. Derived classes must provide
+        the asn1_type class variable to indicate the name of the ASN.1 type to use for encode/decode."""
+        asn1_type = None # must be overridden by derived class
+
+        @classmethod
+        def _decode(cls, data):
+            data = ApiParamBase64.decode(data)
+            return rsp.asn1.decode(cls.asn1_type, data)
+
+        @classmethod
+        def _encode(cls, data):
+            data = rsp.asn1.encode(cls.asn1_type, data)
+            return ApiParamBase64.encode(data)
+
+    class EuiccInfo1(RspAsn1Par):
+        asn1_type = 'EUICCInfo1'
+
+    class ServerSigned1(RspAsn1Par):
+        asn1_type = 'ServerSigned1'
+
+    class PrepareDownloadResponse(RspAsn1Par):
+        asn1_type = 'PrepareDownloadResponse'
+
+    class AuthenticateServerResponse(RspAsn1Par):
+        asn1_type = 'AuthenticateServerResponse'
+
+    class SmdpSigned2(RspAsn1Par):
+        asn1_type = 'SmdpSigned2'
+
+    class StoreMetadataRequest(RspAsn1Par):
+        asn1_type = 'StoreMetadataRequest'
+
+    class PendingNotification(RspAsn1Par):
+        asn1_type = 'PendingNotification'
+
+    class CancelSessionResponse(RspAsn1Par):
+        asn1_type = 'CancelSessionResponse'
+
+    class TransactionId(ApiParamString):
+        pass
+
+class Es9PlusApiFunction(JsonHttpApiFunction):
+    pass
+
+# ES9+ InitiateAuthentication function (SGP.22 section 6.5.2.6)
+class InitiateAuthentication(Es9PlusApiFunction):
+    path = '/gsma/rsp2/es9plus/initiateAuthentication'
+    extra_http_req_headers = { 'User-Agent': 'gsma-rsp-lpad' }
+    input_params = {
+        'euiccChallenge': ApiParamBase64,
+        'euiccInfo1': param.EuiccInfo1,
+        'smdpAddress': SmdpAddress,
+      }
+    input_mandatory = ['euiccChallenge', 'euiccInfo1', 'smdpAddress']
+    output_params = {
+        'header': JsonResponseHeader,
+        'transactionId': param.TransactionId,
+        'serverSigned1': param.ServerSigned1,
+        'serverSignature1': ApiParamBase64,
+        'euiccCiPKIdToBeUsed': ApiParamBase64,
+        'serverCertificate': ApiParamBase64,
+      }
+    output_mandatory = ['header', 'transactionId', 'serverSigned1', 'serverSignature1',
+                        'euiccCiPKIdToBeUsed', 'serverCertificate']
+
+# ES9+ GetBoundProfilePackage function (SGP.22 section 6.5.2.7)
+class GetBoundProfilePackage(Es9PlusApiFunction):
+    path = '/gsma/rsp2/es9plus/getBoundProfilePackage'
+    extra_http_req_headers = { 'User-Agent': 'gsma-rsp-lpad' }
+    input_params = {
+        'transactionId': param.TransactionId,
+        'prepareDownloadResponse': param.PrepareDownloadResponse,
+      }
+    input_mandatory = ['transactionId', 'prepareDownloadResponse']
+    output_params = {
+        'header': JsonResponseHeader,
+        'transactionId': param.TransactionId,
+        'boundProfilePackage': ApiParamBase64,
+      }
+    output_mandatory = ['header', 'transactionId', 'boundProfilePackage']
+
+# ES9+ AuthenticateClient function (SGP.22 section 6.5.2.8)
+class AuthenticateClient(Es9PlusApiFunction):
+    path= '/gsma/rsp2/es9plus/authenticateClient'
+    extra_http_req_headers = { 'User-Agent': 'gsma-rsp-lpad' }
+    input_params = {
+        'transactionId': param.TransactionId,
+        'authenticateServerResponse': param.AuthenticateServerResponse,
+      }
+    input_mandatory = ['transactionId', 'authenticateServerResponse']
+    output_params = {
+        'header': JsonResponseHeader,
+        'transactionId': param.TransactionId,
+        'profileMetadata': param.StoreMetadataRequest,
+        'smdpSigned2': param.SmdpSigned2,
+        'smdpSignature2': ApiParamBase64,
+        'smdpCertificate': ApiParamBase64,
+      }
+    output_mandatory = ['header', 'transactionId', 'profileMetadata', 'smdpSigned2',
+                        'smdpSignature2', 'smdpCertificate']
+
+# ES9+ HandleNotification function (SGP.22 section 6.5.2.9)
+class HandleNotification(Es9PlusApiFunction):
+    path = '/gsma/rsp2/es9plus/handleNotification'
+    extra_http_req_headers = { 'User-Agent': 'gsma-rsp-lpad' }
+    input_params = {
+        'pendingNotification': param.PendingNotification,
+      }
+    input_mandatory = ['pendingNotification']
+    expected_http_status = 204
+
+# ES9+ CancelSession function (SGP.22 section 6.5.2.10)
+class CancelSession(Es9PlusApiFunction):
+    path = '/gsma/rsp2/es9plus/cancelSession'
+    extra_http_req_headers = { 'User-Agent': 'gsma-rsp-lpad' }
+    input_params = {
+        'transactionId': param.TransactionId,
+        'cancelSessionResponse': param.CancelSessionResponse,
+      }
+    input_mandatory = ['transactionId', 'cancelSessionResponse']
+
+class Es9pApiClient:
+    def __init__(self, url_prefix:str, server_cert_verify: str = None):
+        self.session = requests.Session()
+        self.session.verify = False # FIXME HACK
+        if server_cert_verify:
+            self.session.verify = server_cert_verify
+
+        self.initiateAuthentication = JsonHttpApiClient(InitiateAuthentication(), url_prefix, '', self.session)
+        self.authenticateClient = JsonHttpApiClient(AuthenticateClient(), url_prefix, '', self.session)
+        self.getBoundProfilePackage = JsonHttpApiClient(GetBoundProfilePackage(), url_prefix, '', self.session)
+        self.handleNotification = JsonHttpApiClient(HandleNotification(), url_prefix, '', self.session)
+        self.cancelSession = JsonHttpApiClient(CancelSession(), url_prefix, '', self.session)
+
+    def call_initiateAuthentication(self, data: dict) -> dict:
+        return self.initiateAuthentication.call(data)
+
+    def call_authenticateClient(self, data: dict) -> dict:
+        return self.authenticateClient.call(data)
+
+    def call_getBoundProfilePackage(self, data: dict) -> dict:
+        return self.getBoundProfilePackage.call(data)
+
+    def call_handleNotification(self, data: dict) -> dict:
+        return self.handleNotification.call(data)
+
+    def call_cancelSession(self, data: dict) -> dict:
+        return self.cancelSession.call(data)

pySim/esim/http_json_api.py

@@ -0,0 +1,490 @@
+"""GSMA eSIM RSP HTTP/REST/JSON interface according to SGP.22 v2.5"""
+
+# (C) 2024 by Harald Welte <laforge@osmocom.org>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import abc
+import requests
+import logging
+import json
+from typing import Optional, Tuple
+import base64
+from twisted.web.server import Request
+
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.DEBUG)
+
+class ApiParam(abc.ABC):
+    """A class representing a single parameter in the API."""
+    @classmethod
+    def verify_decoded(cls, data):
+        """Verify the decoded representation of a value. Should raise an exception if something is odd."""
+        pass
+
+    @classmethod
+    def verify_encoded(cls, data):
+        """Verify the encoded representation of a value. Should raise an exception if something is odd."""
+        pass
+
+    @classmethod
+    def encode(cls, data):
+        """[Validate and] Encode the given value."""
+        cls.verify_decoded(data)
+        encoded = cls._encode(data)
+        cls.verify_decoded(encoded)
+        return encoded
+
+    @classmethod
+    def _encode(cls, data):
+        """encoder function, typically [but not always] overridden by derived class."""
+        return data
+
+    @classmethod
+    def decode(cls, data):
+        """[Validate and] Decode the given value."""
+        cls.verify_encoded(data)
+        decoded = cls._decode(data)
+        cls.verify_decoded(decoded)
+        return decoded
+
+    @classmethod
+    def _decode(cls, data):
+        """decoder function, typically [but not always] overridden by derived class."""
+        return data
+
+class ApiParamString(ApiParam):
+    """Base class representing an API parameter of 'string' type."""
+    pass
+
+
+class ApiParamInteger(ApiParam):
+    """Base class representing an API parameter of 'integer' type."""
+    @classmethod
+    def _decode(cls, data):
+        return int(data)
+
+    @classmethod
+    def _encode(cls, data):
+        return str(data)
+
+    @classmethod
+    def verify_decoded(cls, data):
+        if not isinstance(data, int):
+            raise TypeError('Expected an integer input data type')
+
+    @classmethod
+    def verify_encoded(cls, data):
+        if isinstance(data, int):
+            return
+        if not data.isdecimal():
+            raise ValueError('integer (%s) contains non-decimal characters' % data)
+        assert str(int(data)) == data
+
+class ApiParamBoolean(ApiParam):
+    """Base class representing an API parameter of 'boolean' type."""
+    @classmethod
+    def _encode(cls, data):
+        return bool(data)
+
+class ApiParamFqdn(ApiParam):
+    """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
+    def verify_encoded(cls, data):
+        # FIXME
+        pass
+
+class ApiParamBase64(ApiParam):
+    @classmethod
+    def _decode(cls, data):
+        return base64.b64decode(data)
+
+    @classmethod
+    def _encode(cls, data):
+        return base64.b64encode(data).decode('ascii')
+
+class SmdpAddress(ApiParamFqdn):
+    pass
+
+class JsonResponseHeader(ApiParam):
+    """SGP.22 section 6.5.1.4."""
+    @classmethod
+    def verify_decoded(cls, data):
+        fe_status = data.get('functionExecutionStatus')
+        if not fe_status:
+            raise ValueError('Missing mandatory functionExecutionStatus in header')
+        status = fe_status.get('status')
+        if not status:
+            raise ValueError('Missing mandatory status in header functionExecutionStatus')
+        if status not in ['Executed-Success', 'Executed-WithWarning', 'Failed', 'Expired']:
+            raise ValueError('Unknown/unspecified status "%s"' % status)
+
+class JsonRequestHeader(ApiParam):
+    """SGP.22 section 6.5.1.3."""
+    @classmethod
+    def verify_decoded(cls, data):
+        func_req_id = data.get('functionRequesterIdentifier')
+        if not func_req_id:
+            raise ValueError('Missing mandatory functionRequesterIdentifier in header')
+        func_call_id = data.get('functionCallIdentifier')
+        if not func_call_id:
+            raise ValueError('Missing mandatory functionCallIdentifier in header')
+
+class HttpStatusError(Exception):
+    pass
+
+class HttpHeaderError(Exception):
+    pass
+
+class ApiError(Exception):
+    """Exception representing an error at the API level (status != Executed)."""
+    def __init__(self, func_ex_status: dict):
+        self.status = func_ex_status['status']
+        sec = {
+            'subjectCode': None,
+            'reasonCode': None,
+            'subjectIdentifier': None,
+            'message': None,
+        }
+        actual_sec = func_ex_status.get('statusCodeData', None)
+        if actual_sec:
+            sec.update(actual_sec)
+        self.subject_code = sec['subjectCode']
+        self.reason_code = sec['reasonCode']
+        self.subject_id = sec['subjectIdentifier']
+        self.message = sec['message']
+
+    def __str__(self):
+        return f'{self.status}("{self.subject_code}","{self.reason_code}","{self.subject_id}","{self.message}")'
+
+class JsonHttpApiFunction(abc.ABC):
+    """Base class for representing an HTTP[s] API Function."""
+    # The below class variables are used to describe the properties of the API function. Derived classes are expected
+    # to orverride those class properties with useful values. The prefixes "input_" and "output_" refer to the API
+    # function from an abstract point of view. Seen from the client perspective, "input_" will refer to parameters the
+    # client sends to a HTTP server. Seen from the server perspective, "input_" will refer to parameters the server
+    # receives from the a requesting client. The same applies vice versa to class variables that have an "output_"
+    # prefix.
+
+    # path of the API function (e.g. '/gsma/rsp2/es2plus/confirmOrder', see also method rewrite_url).
+    path = None
+
+    # dictionary of input parameters. key is parameter name, value is ApiParam class
+    input_params = {}
+
+    # list of mandatory input parameters
+    input_mandatory = []
+
+    # dictionary of output parameters. key is parameter name, value is ApiParam class
+    output_params = {}
+
+    # list of mandatory output parameters (for successful response)
+    output_mandatory = []
+
+    # list of mandatory output parameters (for failed response)
+    output_mandatory_failed = []
+
+    # expected HTTP status code of the response
+    expected_http_status = 200
+
+    # the HTTP method used (GET, OPTIONS, HEAD, POST, PUT, PATCH or DELETE)
+    http_method = 'POST'
+
+    # additional custom HTTP headers (client requests)
+    extra_http_req_headers = {}
+
+    # additional custom HTTP headers (server responses)
+    extra_http_res_headers = {}
+
+    def __new__(cls, *args, role = 'legacy_client', **kwargs):
+        """
+        Args:
+                args: (see JsonHttpApiClient and JsonHttpApiServer)
+                role: role ('server' or 'client') in which the JsonHttpApiFunction should be created.
+                kwargs: (see JsonHttpApiClient and JsonHttpApiServer)
+        """
+
+        # Create a dictionary with the class attributes of this class (the properties listed above and the encode_
+        # decode_ methods below). The dictionary will not include any dunder/magic methods
+        cls_attr = {attr_name: getattr(cls, attr_name) for attr_name in dir(cls) if not attr_name.startswith('__')}
+
+        # Normal instantiation as JsonHttpApiFunction:
+        if len(args) == 0 and len(kwargs) == 0:
+            return type(cls.__name__, (abc.ABC,), cls_attr)()
+
+        # Instantiation as as JsonHttpApiFunction with a JsonHttpApiClient or JsonHttpApiServer base
+        if role == 'legacy_client':
+            # Deprecated: With the advent of the server role (JsonHttpApiServer) the API had to be changed. To maintain
+            # compatibility with existing code (out-of-tree) the original behaviour and API interface and behaviour had
+            # to be preserved. Already existing JsonHttpApiFunction definitions will still work and the related objects
+            # may still be created on the original way: my_api_func = MyApiFunc(url_prefix, func_req_id, self.session)
+            logger.warning('implicit role (falling back to legacy JsonHttpApiClient) is deprecated, please specify role explcitly')
+            result = type(cls.__name__, (JsonHttpApiClient,), cls_attr)(None, *args, **kwargs)
+            result.api_func = result
+            result.legacy = True
+            return result
+        elif role == 'client':
+            # Create a JsonHttpApiFunction in client role
+            # Example: my_api_func = MyApiFunc(url_prefix, func_req_id, self.session, role='client')
+            result = type(cls.__name__, (JsonHttpApiClient,), cls_attr)(None, *args, **kwargs)
+            result.api_func = result
+            return result
+        elif role == 'server':
+            # Create a JsonHttpApiFunction in server role
+            # Example: my_api_func = MyApiFunc(url_prefix, func_req_id, self.session, role='server')
+            result = type(cls.__name__, (JsonHttpApiServer,), cls_attr)(None, *args, **kwargs)
+            result.api_func = result
+            return result
+        else:
+            raise ValueError('Invalid role \'%s\' specified' % role)
+
+    def encode_client(self, data: dict) -> dict:
+        """Validate an encode input dict into JSON-serializable dict for request body."""
+        output = {}
+        for p in self.input_mandatory:
+            if not p in data:
+                raise ValueError('Mandatory input parameter %s missing' % p)
+        for p, v in data.items():
+            p_class = self.input_params.get(p)
+            if not p_class:
+                # pySim/esim/http_json_api.py:269:47: E1101: Instance of 'JsonHttpApiFunction' has no 'legacy' member (no-member)
+                # pylint: disable=no-member
+                if hasattr(self, 'legacy') and self.legacy:
+                    output[p] = JsonRequestHeader.encode(v)
+                else:
+                    logger.warning('Unexpected/unsupported input parameter %s=%s', p, v)
+                    output[p] = v
+            else:
+                output[p] = p_class.encode(v)
+        return output
+
+    def decode_client(self, data: dict) -> dict:
+        """[further] Decode and validate the JSON-Dict of the response body."""
+        output = {}
+        output_mandatory = self.output_mandatory
+
+        # In case a provided header (may be optional) indicates that the API function call was unsuccessful, a
+        # different set of mandatory parameters applies.
+        header = data.get('header')
+        if header:
+            if data['header']['functionExecutionStatus']['status'] not in ['Executed-Success','Executed-WithWarning']:
+                output_mandatory = self.output_mandatory_failed
+
+        for p in output_mandatory:
+            if not p in data:
+                raise ValueError('Mandatory output parameter "%s" missing' % p)
+        for p, v in data.items():
+            p_class = self.output_params.get(p)
+            if not p_class:
+                logger.warning('Unexpected/unsupported output parameter "%s"="%s"', p, v)
+                output[p] = v
+            else:
+                output[p] = p_class.decode(v)
+        return output
+
+    def encode_server(self, data: dict) -> dict:
+        """Validate an encode input dict into JSON-serializable dict for response body."""
+        output = {}
+        output_mandatory = self.output_mandatory
+
+        # In case a provided header (may be optional) indicates that the API function call was unsuccessful, a
+        # different set of mandatory parameters applies.
+        header = data.get('header')
+        if header:
+            if data['header']['functionExecutionStatus']['status'] not in ['Executed-Success','Executed-WithWarning']:
+                output_mandatory = self.output_mandatory_failed
+
+        for p in output_mandatory:
+            if not p in data:
+                raise ValueError('Mandatory output parameter %s missing' % p)
+        for p, v in data.items():
+            p_class = self.output_params.get(p)
+            if not p_class:
+                logger.warning('Unexpected/unsupported output parameter %s=%s', p, v)
+                output[p] = v
+            else:
+                output[p] = p_class.encode(v)
+        return output
+
+    def decode_server(self, data: dict) -> dict:
+        """[further] Decode and validate the JSON-Dict of the request body."""
+        output = {}
+
+        for p in self.input_mandatory:
+            if not p in data:
+                raise ValueError('Mandatory input parameter "%s" missing' % p)
+        for p, v in data.items():
+            p_class = self.input_params.get(p)
+            if not p_class:
+                logger.warning('Unexpected/unsupported input parameter "%s"="%s"', p, v)
+                output[p] = v
+            else:
+                output[p] = p_class.decode(v)
+        return output
+
+    def rewrite_url(self, data: dict, url: str) -> Tuple[dict, str]:
+        """
+        Rewrite a static URL using information passed in the data dict. This method may be overloaded by a derived
+        class to allow fully dynamic URLs. The input parameters required for the URL rewriting may be passed using
+        data parameter. In case those parameters are additional parameters that are not intended to be passed to
+        the encode_client method later, they must be removed explcitly.
+
+        Args:
+                data: (see JsonHttpApiClient and JsonHttpApiServer)
+                url: statically generated URL string (see comment in JsonHttpApiClient)
+        """
+
+        # This implementation is a placeholder in which we do not perform any URL rewriting. We just pass through data
+        # and url unmodified.
+        return data, url
+
+class JsonHttpApiClient():
+    def __init__(self, api_func: JsonHttpApiFunction, url_prefix: str, func_req_id: Optional[str],
+                 session: requests.Session):
+        """
+        Args:
+                api_func : API function definition (JsonHttpApiFunction)
+                url_prefix : prefix to be put in front of the API function path (see JsonHttpApiFunction)
+                func_req_id : function requestor id to use for requests
+                session : session object (requests)
+        """
+        self.api_func = api_func
+        self.url_prefix = url_prefix
+        self.func_req_id = func_req_id
+        self.session = session
+
+    def call(self, data: dict, func_call_id: Optional[str] = None, timeout=10) -> Optional[dict]:
+        """
+        Make an API call to the HTTP API endpoint represented by this object. Input data is passed in `data` as
+        json-serializable fields. `data` may also contain additional parameters required for URL rewriting (see
+        rewrite_url in class JsonHttpApiFunction). Output data is returned as json-deserialized dict.
+
+        Args:
+                data: Input data required to perform the request.
+                func_call_id: Function Call Identifier, if present a header field is generated automatically.
+                timeout: Maximum amount of time to wait for the request to complete.
+        """
+
+        # In case a function caller ID is supplied, use it together with the stored function requestor ID to generate
+        # and prepend the header field according to SGP.22, section 6.5.1.1 and 6.5.1.3. (the presence of the header
+        # field is checked by the encode_client method)
+        if func_call_id:
+            data = {'header' : {'functionRequesterIdentifier': self.func_req_id,
+                                'functionCallIdentifier': func_call_id}} | data
+
+        # The URL used for the HTTP request (see below) normally consists of the initially given url_prefix
+        # concatenated with the path defined by the JsonHttpApiFunction definition. This static URL path may be
+        # rewritten by rewrite_url method defined in the JsonHttpApiFunction.
+        data, url = self.api_func.rewrite_url(data, self.url_prefix + self.api_func.path)
+
+        # Encode the message (the presence of mandatory fields is checked during encoding)
+        encoded = json.dumps(self.api_func.encode_client(data))
+
+        # Apply HTTP request headers according to SGP.22, section 6.5.1
+        req_headers = {
+            'Content-Type': 'application/json',
+            'X-Admin-Protocol': 'gsma/rsp/v2.5.0',
+        }
+        req_headers.update(self.api_func.extra_http_req_headers)
+
+        # Perform HTTP request
+        logger.debug("HTTP REQ %s - hdr: %s '%s'" % (url, req_headers, encoded))
+        response = self.session.request(self.api_func.http_method, url, data=encoded, headers=req_headers, timeout=timeout)
+        logger.debug("HTTP RSP-STS: [%u] hdr: %s" % (response.status_code, response.headers))
+        logger.debug("HTTP RSP: %s" % (response.content))
+
+        # Check HTTP response status code and make sure that the returned HTTP headers look plausible (according to
+        # SGP.22, section 6.5.1)
+        if response.status_code != self.api_func.expected_http_status:
+            raise HttpStatusError(response)
+        if response.content and not response.headers.get('Content-Type').startswith(req_headers['Content-Type']):
+            raise HttpHeaderError(response)
+        if not response.headers.get('X-Admin-Protocol', 'gsma/rsp/v2.unknown').startswith('gsma/rsp/v2.'):
+            raise HttpHeaderError(response)
+
+        # Decode response and return the result back to the caller
+        if response.content:
+            output = self.api_func.decode_client(response.json())
+            # In case the response contains a header, check it to make sure that the API call was executed successfully
+            # (the presence of the header field is checked by the decode_client method)
+            if 'header' in output:
+                if output['header']['functionExecutionStatus']['status'] not in ['Executed-Success','Executed-WithWarning']:
+                    raise ApiError(output['header']['functionExecutionStatus'])
+            return output
+        return None
+
+class JsonHttpApiServer():
+    def __init__(self, api_func: JsonHttpApiFunction, call_handler = None):
+        """
+        Args:
+                api_func : API function definition (JsonHttpApiFunction)
+                call_handler : handler function to process the request. This function must accept the
+                               decoded request as a dictionary. The handler function must return a tuple consisting
+                               of the response in the form of a dictionary (may be empty), and a function execution
+                               status string ('Executed-Success', 'Executed-WithWarning', 'Failed' or 'Expired')
+        """
+        self.api_func = api_func
+        if call_handler:
+            self.call_handler = call_handler
+        else:
+            self.call_handler = self.default_handler
+
+    def default_handler(self, data: dict) -> (dict, str):
+        """default handler, used in case no call handler is provided."""
+        logger.error("no handler function for request: %s" % str(data))
+        return {}, 'Failed'
+
+    def call(self, request: Request) -> str:
+        """ Process an incoming request.
+        Args:
+                request : request object as received using twisted.web.server
+        Returns:
+                encoded JSON string (HTTP response code and headers are set by calling the appropriate methods on the
+                provided the request object)
+        """
+
+        # Make sure the request is done with the correct HTTP method
+        if (request.method.decode() != self.api_func.http_method):
+            raise ValueError('Wrong HTTP method %s!=%s' % (request.method.decode(), self.api_func.http_method))
+
+        # Decode the request
+        decoded_request = self.api_func.decode_server(json.loads(request.content.read()))
+
+        # Run call handler (see above)
+        data, fe_status = self.call_handler(decoded_request)
+
+        # In case a function execution status is returned, use it to generate and prepend the header field according to
+        # SGP.22, section 6.5.1.2 and 6.5.1.4 (the presence of the header filed is checked by the encode_server method)
+        if fe_status:
+            data = {'header' : {'functionExecutionStatus': {'status' : fe_status}}} | data
+
+        # Encode the message (the presence of mandatory fields is checked during encoding)
+        encoded = json.dumps(self.api_func.encode_server(data))
+
+        # Apply HTTP request headers according to SGP.22, section 6.5.1
+        res_headers = {
+            'Content-Type': 'application/json',
+            'X-Admin-Protocol': 'gsma/rsp/v2.5.0',
+        }
+        res_headers.update(self.api_func.extra_http_res_headers)
+        for header, value in res_headers.items():
+            request.setHeader(header, value)
+        request.setResponseCode(self.api_func.expected_http_status)
+
+        # Return the encoded result back to the caller for sending (using twisted/klein)
+        return encoded
+

pySim/esim/rsp.py

@@ -1,6 +1,5 @@
-# Implementation of GSMA eSIM RSP (Remote SIM Provisioning)
-# as per SGP22 v3.0
-#
+"""Implementation of GSMA eSIM RSP (Remote SIM Provisioning) as per SGP22 v3.0"""
+
 # (C) 2023-2024 by Harald Welte <laforge@osmocom.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -19,12 +18,12 @@
 
 from typing import Optional
 import shelve
-import copyreg
 
 from cryptography.hazmat.primitives.asymmetric import ec
 from cryptography.hazmat.primitives.serialization import Encoding
 from cryptography import x509
-from collections.abc import MutableMapping
+from osmocom.utils import b2h
+from osmocom.tlv import bertlv_parse_one_rawtag, bertlv_return_one_rawtlv
 
 from pySim.esim import compile_asn1_subdir
 
@@ -38,7 +37,7 @@ class RspSessionState:
     def __init__(self, transactionId: str, serverChallenge: bytes, ci_cert_id: bytes):
         self.transactionId = transactionId
         self.serverChallenge = serverChallenge
-        #  used at a later point between API calsl
+        #  used at a later point between API calls
         self.ci_cert_id = ci_cert_id
         self.euicc_cert: Optional[x509.Certificate] = None
         self.eum_cert: Optional[x509.Certificate] = None
@@ -91,11 +90,90 @@ class RspSessionState:
             # FIXME: how to add the public key from smdp_otpk to an instance of EllipticCurvePrivateKey?
             del state['_smdp_otsk']
             del state['_smdp_ot_curve']
-        # automatically recover all the remainig state
+        # automatically recover all the remaining state
         self.__dict__.update(state)
 
 
-class RspSessionStore(shelve.DbfilenameShelf):
-    """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."""
-    pass
+class RspSessionStore:
+    """A wrapper around the database-backed storage 'shelve' for storing RspSessionState objects.
+    Can be configured to use either file-based storage or in-memory storage.
+    We use it to store RspSessionState objects indexed by transactionId."""
+
+    def __init__(self, filename: Optional[str] = None, in_memory: bool = False):
+        self._in_memory = in_memory
+
+        if in_memory:
+            self._shelf = shelve.Shelf(dict())
+        else:
+            if filename is None:
+                raise ValueError("filename is required for file-based session store")
+            self._shelf = shelve.open(filename)
+
+    # dunder magic
+    def __getitem__(self, key):
+        return self._shelf[key]
+
+    def __setitem__(self, key, value):
+        self._shelf[key] = value
+
+    def __delitem__(self, key):
+        del self._shelf[key]
+
+    def __contains__(self, key):
+        return key in self._shelf
+
+    def __iter__(self):
+        return iter(self._shelf)
+
+    def __len__(self):
+        return len(self._shelf)
+
+    # everything else
+    def __getattr__(self, name):
+        """Delegate attribute access to the underlying shelf object."""
+        return getattr(self._shelf, name)
+
+    def close(self):
+        """Close the session store."""
+        if hasattr(self._shelf, 'close'):
+            self._shelf.close()
+        if self._in_memory:
+            # For in-memory store, clear the reference
+            self._shelf = None
+
+    def sync(self):
+        """Synchronize the cache with the underlying storage."""
+        if hasattr(self._shelf, 'sync'):
+            self._shelf.sync()
+
+def 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."""
+    rawtag, l, v, remainder = bertlv_parse_one_rawtag(authenticateServerResponse)
+    if len(remainder):
+        raise ValueError('Excess data at end of TLV')
+    if rawtag != 0xbf38:
+        raise ValueError('Unexpected outer tag: %s' % b2h(rawtag))
+    rawtag, l, v1, remainder = bertlv_parse_one_rawtag(v)
+    if rawtag != 0xa0:
+        raise ValueError('Unexpected tag where CHOICE was expected')
+    rawtag, l, tlv2, remainder = bertlv_return_one_rawtlv(v1)
+    if rawtag != 0x30:
+        raise ValueError('Unexpected tag where SEQUENCE was expected')
+    return tlv2
+
+def 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."""
+    rawtag, l, v, remainder = bertlv_parse_one_rawtag(prepareDownloadResponse)
+    if len(remainder):
+        raise ValueError('Excess data at end of TLV')
+    if rawtag != 0xbf21:
+        raise ValueError('Unexpected outer tag: %s' % b2h(rawtag))
+    rawtag, l, v1, remainder = bertlv_parse_one_rawtag(v)
+    if rawtag != 0xa0:
+        raise ValueError('Unexpected tag where CHOICE was expected')
+    rawtag, l, tlv2, remainder = bertlv_return_one_rawtlv(v1)
+    if rawtag != 0x30:
+        raise ValueError('Unexpected tag where SEQUENCE was expected')
+    return tlv2

pySim/esim/saip/batch.py

@@ -0,0 +1,120 @@
+"""Implementation of Personalization of eSIM profiles in SimAlliance/TCA Interoperable Profile:
+   Run a batch of N personalizations"""
+
+# (C) 2025-2026 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de>
+#
+# Author: nhofmeyr@sysmocom.de
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import copy
+from typing import Generator
+from pySim.esim.saip.personalization import ConfigurableParameter
+from pySim.esim.saip import param_source
+from pySim.esim.saip import ProfileElementSequence
+
+class BatchPersonalization:
+    """Produce a series of eSIM profiles from predefined parameters.
+    Personalization parameters are derived from pysim.esim.saip.param_source.ParamSource.
+
+    Usage example:
+
+    der_input = open('some_file', 'rb').read()
+    pes = ProfileElementSequence.from_der(der_input)
+    p = BatchPersonalization(
+        n=10,
+        src_pes=pes,
+        csv_rows=get_csv_reader())
+
+    p.add_param_and_src(
+        personalization.Iccid(),
+        param_source.IncDigitSource(
+            num_digits=18,
+            first_value=123456789012340001,
+            last_value=123456789012340010))
+
+    # add more parameters here, using ConfigurableParameter and ParamSource subclass instances to define the profile
+    # ...
+
+    # generate all 10 profiles (from n=10 above)
+    for result_pes in p.generate_profiles():
+        upp = result_pes.to_der()
+        store_upp(upp)
+    """
+
+    class ParamAndSrc:
+        """tie a ConfigurableParameter to a source of actual values"""
+        def __init__(self, param: ConfigurableParameter, src: param_source.ParamSource):
+            if isinstance(param, type):
+                self.param_cls = param
+            else:
+                self.param_cls = param.__class__
+            self.src = src
+
+    def __init__(self,
+                 n: int,
+                 src_pes: ProfileElementSequence,
+                 params: list[ParamAndSrc]=None,
+                 csv_rows: Generator=None,
+                ):
+        """
+        n: number of eSIM profiles to generate.
+        src_pes: a decoded eSIM profile as ProfileElementSequence, to serve as template. This is not modified, only
+                 copied.
+        params: list of ParamAndSrc instances, defining a ConfigurableParameter and corresponding ParamSource to fill in
+                profile values.
+        csv_rows: A generator (e.g. iter(list_of_rows)) producing all CSV rows one at a time, starting with a row
+                  containing the column headers. This is compatible with the python csv.reader. Each row gets passed to
+                  ParamSource.get_next(), such that ParamSource implementations can access the row items. See
+                  param_source.CsvSource.
+        """
+        self.n = n
+        self.params = params or []
+        self.src_pes = src_pes
+        self.csv_rows = csv_rows
+
+    def add_param_and_src(self, param:ConfigurableParameter, src:param_source.ParamSource):
+        self.params.append(BatchPersonalization.ParamAndSrc(param, src))
+
+    def generate_profiles(self):
+        # get first row of CSV: column names
+        csv_columns = None
+        if self.csv_rows:
+            try:
+                csv_columns = next(self.csv_rows)
+            except StopIteration as e:
+                raise ValueError('the input CSV file appears to be empty') from e
+
+        for i in range(self.n):
+            csv_row = None
+            if self.csv_rows and csv_columns:
+                try:
+                    csv_row_list = next(self.csv_rows)
+                except StopIteration as e:
+                    raise ValueError(f'not enough rows in the input CSV for eSIM nr {i+1} of {self.n}') from e
+
+                csv_row = dict(zip(csv_columns, csv_row_list))
+
+            pes = copy.deepcopy(self.src_pes)
+
+            for p in self.params:
+                try:
+                    input_value = p.src.get_next(csv_row=csv_row)
+                    assert input_value is not None
+                    value = p.param_cls.validate_val(input_value)
+                    p.param_cls.apply_val(pes, value)
+                except Exception as e:
+                    raise ValueError(f'{p.param_cls.get_name()} fed by {p.src.name}: {e}') from e
+
+            yield pes

pySim/esim/saip/oid.py

@@ -1,5 +1,5 @@
-# Implementation of SimAlliance/TCA Interoperable Profile OIDs
-#
+"""Implementation of SimAlliance/TCA Interoperable Profile OIDs"""
+
 # (C) 2023-2024 by Harald Welte <laforge@osmocom.org>
 #
 # This program is free software: you can redistribute it and/or modify
@@ -15,8 +15,10 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+from functools import total_ordering
 from typing import List, Union
 
+@total_ordering
 class OID:
     @staticmethod
     def intlist_from_str(instr: str) -> List[int]:
@@ -26,8 +28,12 @@ class OID:
     def str_from_intlist(intlist: List[int]) -> str:
         return '.'.join([str(x) for x in intlist])
 
+    @staticmethod
+    def highest_oid(oids: List['OID']) -> 'OID':
+        return sorted(oids)[-1]
+
     def __init__(self, initializer: Union[List[int], str]):
-        if type(initializer) == str:
+        if isinstance(initializer, str):
             self.intlist = self.intlist_from_str(initializer)
         else:
             self.intlist = initializer
@@ -38,12 +44,49 @@ class OID:
     def __repr__(self) -> str:
         return 'OID(%s)' % (str(self))
 
+    def __eq__(self, other: 'OID'):
+        return (self.intlist == other.intlist)
+
+    def __ne__(self, other: 'OID'):
+        # implement based on __eq__
+        return not (self == other)
+
+    def cmp(self, other: 'OID'):
+        self_len = len(self.intlist)
+        other_len = len(other.intlist)
+        common_len = min(self_len, other_len)
+        max_len = max(self_len, other_len)
+
+        for i in range(0, max_len+1):
+            if i >= self_len:
+                # other list is longer
+                return -1
+            if i >= other_len:
+                # our list is longer
+                return 1
+            if self.intlist[i] > other.intlist[i]:
+                # our version is higher
+                return 1
+            if self.intlist[i] < other.intlist[i]:
+                # other version is higher
+                return -1
+            # continue to next digit
+        return 0
+
+    def __gt__(self, other: 'OID'):
+        if self.cmp(other) > 0:
+            return True
+
+    def prefix_match(self, oid_str: Union[str, 'OID']):
+        """determine if oid_str is equal or below our OID."""
+        return str(oid_str).startswith(str(self))
+
 
 class eOID(OID):
     """OID helper for TCA eUICC prefix"""
     __prefix = [2,23,143,1]
     def __init__(self, initializer):
-        if type(initializer) == str:
+        if isinstance(initializer, str):
             initializer = self.intlist_from_str(initializer)
         super().__init__(self.__prefix + initializer)
 
@@ -53,18 +96,18 @@ DF_TELECOM = eOID("2.3")
 DF_TELECOM_v2 = eOID("2.3.2")
 ADF_USIM_by_default = eOID("2.4")
 ADF_USIM_by_default_v2 = eOID("2.4.2")
-ADF_USIM_not_by_default = eOID("2.5")
-ADF_USIM_not_by_default_v2 = eOID("2.5.2")
-ADF_USIM_not_by_default_v3 = eOID("2.5.3")
+ADF_USIMopt_not_by_default = eOID("2.5")
+ADF_USIMopt_not_by_default_v2 = eOID("2.5.2")
+ADF_USIMopt_not_by_default_v3 = eOID("2.5.3")
 DF_PHONEBOOK_ADF_USIM = eOID("2.6")
 DF_GSM_ACCESS_ADF_USIM = eOID("2.7")
 ADF_ISIM_by_default = eOID("2.8")
-ADF_ISIM_not_by_default = eOID("2.9")
-ADF_ISIM_not_by_default_v2 = eOID("2.9.2")
+ADF_ISIMopt_not_by_default = eOID("2.9")
+ADF_ISIMopt_not_by_default_v2 = eOID("2.9.2")
 ADF_CSIM_by_default = eOID("2.10")
 ADF_CSIM_by_default_v2 = eOID("2.10.2")
-ADF_CSIM_not_by_default = eOID("2.11")
-ADF_CSIM_not_by_default_v2 = eOID("2.11.2")
+ADF_CSIMopt_not_by_default = eOID("2.11")
+ADF_CSIMopt_not_by_default_v2 = eOID("2.11.2")
 DF_EAP = eOID("2.12")
 DF_5GS = eOID("2.13")
 DF_5GS_v2 = eOID("2.13.2")
@@ -73,5 +116,5 @@ DF_5GS_v4 = eOID("2.13.4")
 DF_SAIP = eOID("2.14")
 DF_SNPN = eOID("2.15")
 DF_5GProSe = eOID("2.16")
-IoT_default = eOID("2.17")
-IoT_default = eOID("2.18")
+IoT_by_default = eOID("2.17")
+IoTopt_not_by_default = eOID("2.18")