WIP: Remote Card Procedure Framework

Problem: When UICC/eUICC cards are deployed into the field it is often
difficult to perform modifications to those cards. One important factor
that makes after-deployment modifications often difficult is that the
key material needed to perform the task must not be handed to the card
holder due to security requirements.

The presented Remote Card Procedure Framework solves this problem. It
provides a so called Remote Card Procedure Client (RCPC), which is a
lightwight software client which can be run by the card holder on the
remote machine.

With the RCPC, the card holder can access a so called Remote Card
Procedure Server (RCPC), to which so called Remote Card Procedure
Modules (RCPM) can subscribe and publish their functionality. With
the RCPC, the card holder can browse the functionality offered by
those connected modules and eventually the card holder may execute
a certain procedure by passing a command to the RCPS.

When a procedure is carried out, the RCPS automatically retrieves the
required key material from a database or CSV file and passes those
keys on to the selected RCPM. The RCPM can then use the key material
to establish a secure channel to carry out the procedure. The procedure
is then protected by a secure channel and the key material is never
disclosed towards the card holder on the remote end.

The framework is desinged in such a way that existing pySim APIs and
functions can be used from the RCPM API user code. Also only minimal
boilerplate code is required. The implementation also ships with a
comprehensive example.

Related: SYS#6959

contrib/rcp/rcp_client.py

@@ -0,0 +1,243 @@
+#!/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 os
+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, load_json_schema, JsonValidator
+from pySim.transport import init_reader, argparse_add_reader_args, LinkBase
+from packaging.version import Version
+
+SERVER_TIMEOUT = 10
+
+# The RCP Client software version shall be incremented when there are changes to the RCP Client (this module) or changes
+# to other related modules, which affect the RCP Client. The RCP Client software version is also disclosed towards the
+# RCP Server.
+RCPC_VERSION_SOFTWARE = "1.0.0"
+
+# The RCP Client protocol version refers to the protocol spoken between RCP Client and RCP Server. The protocol version
+# shall be incremented when there are changes to the protocol (JSON Schema and/or application logic, see also
+# RCPC_VERSION_PROTOCOL in rcp_server.py).
+RCPC_VERSION_PROTOCOL = "1.0.0"
+
+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 check_version(self):
+        """
+        Send the Protocol and Software version of this RCP Client to the RCP Server. The RCP Server will then check
+        if this client is (still) compatible. If an incompatibility is detected, the connection will be closed.
+        """
+        log.info("Checking version ...")
+        tx_json = {'rcpc_version': {'software' : RCPC_VERSION_SOFTWARE,
+                                    'protocol' : RCPC_VERSION_PROTOCOL}}
+        log.info("RCP Client version: software=%s, protocol=%s",
+                RCPC_VERSION_SOFTWARE, RCPC_VERSION_PROTOCOL)
+        rx_json = await self._transact(tx_json)
+        rcps_version_software = Version(rx_json['rcpc_version']['software'])
+        rcps_version_protocol = Version(rx_json['rcpc_version']['protocol'])
+        rcps_version_info = str(rx_json['rcpc_version'].get('info'))
+        if rcps_version_info:
+            log.info("RCP Server version: software=%s, protocol=%s",
+                     rcps_version_software, rcps_version_protocol)
+        else:
+            log.info("RCP Server version: software=%s, protocol=%s, %s",
+                     rcps_version_software, rcps_version_protocol, rcps_version_info)
+
+    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:
+        rcpc_to_rcps_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(), "rcpc_to_rcps_schema.json"))
+        rcps_to_rcpc_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(), "rcps_to_rcpc_schema.json"))
+        json_validator = JsonValidator(rcps_to_rcpc_schema, rcpc_to_rcps_schema)
+        client = RcpcCltConnHdlr(sl, websocket, SERVER_TIMEOUT, json_validator)
+
+        # Check software and protocol version
+        await client.check_version()
+
+        # Retrieve module description
+        module_descrs = await client.describe({"atr" : card_atr})
+
+        # Complete the commandline 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 help screen 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 help screen.
+    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,424 @@
+#!/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, load_json_schema, JsonValidator
+from rcp_server import RCPM_VERSION_PROTOCOL
+from websockets.sync.server import serve, ServerConnection
+from pySim.app import init_card
+from pySim.runtime import RuntimeState
+from pySim.cards import CardBase
+from pySim.card_key_provider import CardKeyFieldCryptor
+from packaging.version import Version
+
+# 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 = {'rcps_instr': {'c_apdu' : apdu.upper()}}
+        rx_json = self.conn_hdlr._transact(tx_json)
+        data = rx_json['rcps_result']['r_apdu']['data']
+        sw = rx_json['rcps_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 entity 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 = {'rcps_instr': {'reset' : None}}
+        rx_json = self.conn_hdlr._transact(tx_json)
+        self._atr = rx_json['rcps_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 check_version(self):
+        """
+        Send the Protocol and Software version of this RCP Module to the RCP Server. The RCP Server and the RCP Module
+        must always use the same protrocol version.
+        """
+        tx_json = {'rcpm_version': {'protocol' : RCPM_VERSION_PROTOCOL}}
+        rx_json = await self._transact(tx_json)
+        rcpm_version_protocol = Version(rx_json['rcpm_version']['protocol'])
+        if Version(RCPM_VERSION_PROTOCOL) != rcpm_version_protocol:
+            raise ValueError("Incompatible protocol version %s != %s", Version(RCPM_VERSION_PROTOCOL), rcpm_version_protocol)
+
+    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,
+                    '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 RCP 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 specification, consisting of
+    # 'name', 'help', and 'args' is is directly passed to agparse on the client side.
+    #
+    # In addition to that, the API user may specify which keys the RCP Server shall retrieve before a command is
+    # executed. This is done via the 'get_keys' field. This field is optional and has the form of a dict with
+    # two optional fields 'uicc' and 'euicc'. The value part of both fields is a list of strings which name the
+    # columns that are passed to the CardKeyProvider for lookup. When the 'uicc' field is set, then the RCP Server
+    # will automatically request the ICCID from the card and do the lookup. When the 'euicc' field is set, the RCP
+    # Server will do the same with the EID. It is possible to mix both fields to request keys for the eUICC and the
+    # currently activated eSIM profile at the same time. However, this may be a very rare corner case.
+    #
+    # Example:
+    # 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' : 'unlock_aram',
+    #               'help': 'unlock a locked ARA-M applet on a sysmoISIM-SJA5',
+    #               'args' : [],
+    #               'get_keys' : {'uicc' : ['KIC', 'KID', 'KIK']}}
+    #              ]
+    cmd_descr = []
+
+    # 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 RcpModuleHdlr).
+    #
+    # Example:
+    # def cmd_reset(self, hdlr: RcpModuleHdlr) -> int: ...
+    # def cmd_read_binary(self, hdlr: RcpModuleHdlr) -> int: ...
+    # def cmd_unlock_aram(self, hdlr: RcpModuleHdlr) -> int: ...
+
+    # When the RCP Module class is passed to rcpm_run_module(), rcpm_run_module() also accepts *args and **kwargs
+    # parameter. Those parameters are passed to the constructor of RCP Module class when it is instaniated by
+    # rcpm_run_module(). API may override this constructor (below) with a custom implementation, if required.
+    def __init__(self, *args, **kwargs):
+        pass
+
+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, field_cryptor: CardKeyFieldCryptor, *args, **kwargs):
+        SrvSyncConnHdlr.__init__(self, *args, *kwargs)
+        self.module = module
+        self.crypt = field_cryptor
+
+    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 = {'rcps_instr': {'print' : message}}
+        rx_json = self._transact(tx_json)
+        if rx_json != {'rcps_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['rcps_command']['cmd']
+        cmd_argv = rx_json['rcps_command']['cmd_argv']
+        keys = rx_json['rcps_command'].get('keys')
+        log.info(str(self) + " -- executing command: %s %s", cmd, str(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)
+
+            # Setup a pySim RuntimeState, CardBase and a RuntimeLchan.
+            rs, card = init_card(RcpsSimLink(self))
+
+            # Hand over control to the command method provided by the specific module implementation.
+            rcp_module_hdlr = RcpModuleHdlr(self.print, rs, card, cmd_args, keys, self.crypt)
+            rs.reset()
+            try:
+                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 = {'rcps_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 RuntimeState (rs), the CardBase (card) and the RuntimeLchan (lchan) are the three major objects through which
+    # an API user may interact with the UICC/eUICC on the other remote end. Those objects have the same objectives as
+    # in pySim-shell.py, with lchan representing the currently selected lchan (set to self.rs.lchan[0] by default, API
+    # users may change the reference to a different lchan)
+    rs = None
+    card = None
+    lchan = 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, print: callable, rs: RuntimeState, card: CardBase, cmd_args: Namespace,
+                 keys: dict, field_cryptor: CardKeyFieldCryptor):
+        self.print = print
+        self.rs = rs
+        self.card = card
+        self.lchan = self.rs.lchan[0]
+        self.cmd_args = cmd_args
+        if keys:
+            if 'uicc' in keys:
+                self.keys_uicc = dict_from_key_value_pairs(keys['uicc'], keylabel='key', valuelabel='value')
+                for key in self.keys_uicc.keys():
+                    self.keys_uicc[key] = field_cryptor.decrypt_field(key, self.keys_uicc.get(key))
+            if 'euicc' in keys:
+                self.keys_euicc = dict_from_key_value_pairs(keys['euicc'], keylabel='key', valuelabel='value')
+                for key in self.keys_euicc.keys():
+                    self.keys_euicc[key] = field_cryptor.decrypt_field(key, self.keys_euicc.get(key))
+
+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)
+    CardKeyFieldCryptor.argparse_add_args(option_parser)
+    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)
+
+    # Load JSON schema for message validation between RCP Server and RCP Module (this process)
+    rcpm_to_rcps_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(), "rcpm_to_rcps_schema.json"))
+    rcps_to_rcpm_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(), "rcps_to_rcpm_schema.json"))
+
+    # Load JSON schema for message validation between RCP Server and RCP Module Command Server (this process)
+    rcpmcs_to_rcps_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(), "rcpmcs_to_rcps_schema.json"))
+    rcps_to_rcpmcs_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(), "rcps_to_rcpmcs_schema.json"))
+
+    # 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):
+        json_validator = JsonValidator(rcps_to_rcpmcs_schema, rcpmcs_to_rcps_schema)
+        transport_keys = CardKeyFieldCryptor.transport_keys_from_opts(opts)
+        field_cryptor = CardKeyFieldCryptor(transport_keys)
+        hdlr = RcpmCmdSrvConnHdlr(module(*args, *kwargs), field_cryptor, websocket, RCP_SERVER_TIMEOUT, json_validator)
+        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:
+            json_validator = JsonValidator(rcps_to_rcpm_schema, rcpm_to_rcps_schema)
+            client = RcpsCltConnHdlr(opts.rcpm_cmd_server_addr, opts.rcpm_cmd_server_port, module, websocket,
+                                     RCP_SERVER_TIMEOUT, json_validator)
+            await client.check_version()
+            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,666 @@
+#!/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
+import time
+import requests
+import json
+import websockets
+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
+from websockets.asyncio.server import serve, ServerConnection
+from rcp_utils import SrvConnHdlr, CltConnHdlr, JsonValidator, FlightRecorder
+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 card_key_provider_argparse_add_args, card_key_provider_init
+from pySim.card_key_provider import card_key_provider_get_field, card_key_provider_get
+from packaging.version import Version
+
+CLIENT_TIMEOUT = 10
+
+# The protocol version between the RCP Server and the RCP Module must always match up. In case there as changes to
+# the protocol (JSON Schema and/or application logic). This version number shall be incremented accordingly. Since
+# RCP Modules usually run from the same pySim modules as the RCP Server, a change to this version number should
+# not affect the RCP Module implementation itself.
+RCPM_VERSION_PROTOCOL = "1.0.0"
+
+# The RCP Server software version shall be incremented when there are changes to the RCP Sever (this module) or changes
+# to other related modules, which affect the RCP Server. The RCP Server software version is also disclosed towards the
+# RCP Client.
+RCPS_VERSION_SOFTWARE = "1.0.0"
+
+# The RCP Server protocol version refers to the protocol spoken between RCP Client and RCP Server. The protocol version
+# shall be incremented when there are changes to the protocol (JSON Schema and/or application logic). When an
+# RCP Client connects, this protocol version is compared against the protocol version that the client sends
+# (see also RCPC_VERSION_PROTOCOL in rcp_client.py). It is up to the RCP Server to decide whether or not a deviation
+# between protocol versions is tolerable or not.
+RCPS_VERSION_PROTOCOL = "1.0.0"
+
+log = PySimLogger.get(Path(__file__).stem)
+runtime_state = None
+rate_limiter = 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("--rcpc-request-limit", help="number of RCP Client requests per minute",
+                           default=600)
+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)
+option_parser.add_argument("--open-observe-url", help="OpenObserve API endpoint URL")
+option_parser.add_argument("--open-observe-email", help="OpenObserve service email address")
+option_parser.add_argument("--open-observe-token", help="OpenObserve service token")
+
+card_key_provider_argparse_add_args(option_parser)
+
+class ModuleRuntimeState:
+    def __init__(self, websocket:ServerConnection, name:str, cmd_descr:list, suitable_for:list, addr:str, port:int):
+        self.name = name
+        self.websocket = websocket
+
+        # Run the cmd_descr through argparse to catch malformed argument specifications early
+        for cmd in cmd_descr:
+            args = deepcopy(cmd['args'])
+            cmd_parser = argparse.ArgumentParser()
+            for arg in args:
+                try:
+                    arg['spec'] = pytype_to_type(arg['spec'])
+                    cmd_parser.add_argument(arg['name'], **arg['spec'])
+                except:
+                    raise ValueError("invalid argument spec %s -- check RCP Module" % str(arg))
+
+        self.cmd_descr = cmd_descr
+        self.suitable_for = suitable_for
+        self.addr = addr
+        self.port = port
+        log.debug("new RCP Module context created: '%s'", name)
+
+    def is_suitable(self, suitable_for:dict) -> bool:
+        """Check if this module is 'suitable_for' a specific card"""
+        if suitable_for in self.suitable_for:
+            return True
+        return False
+
+    def describe(self) -> dict:
+        """Describe this module towards the RCP Client"""
+
+        # The command description sent by the RCP Module also includes fields that are intended to be seen
+        # only by the RCP Server. Here we set up the command description as it is expected by the RCP Client.
+        cmd_descr = []
+        for descr in self.cmd_descr:
+            cmd_descr.append({'name' : descr['name'],
+                              'help' : descr['help'],
+                              'args' : descr['args']})
+
+        # Return module description
+        return {'name': self.name,
+                'cmd_descr': cmd_descr}
+
+    def get_cmd_descr(self, cmd: str) -> dict:
+        """Get the description for a specific command of this module"""
+        for descr in self.cmd_descr:
+            if self.name + "_" + descr['name'] == cmd:
+                return descr
+        raise ValueError("command %s not found in command description %s" % (cmd_name, str(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, rcpm_ca_ssl_context, open_observe_pars):
+        self.module_runtime_states = []
+        self.rcpm_ca_ssl_context = rcpm_ca_ssl_context
+        self.open_observe_pars = open_observe_pars
+
+        # Load JSON schema for message validation between RCP Client and RCP Server (this process)
+        self.rcpc_to_rcps_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(),
+                                                                 "rcpc_to_rcps_schema.json"))
+        self.rcps_to_rcpc_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(),
+                                                                 "rcps_to_rcpc_schema.json"))
+
+        # Load JSON schema for message validation between RCP Module and RCP Server (this process)
+        self.rcpm_to_rcps_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(),
+                                                                 "rcpm_to_rcps_schema.json"))
+        self.rcps_to_rcpm_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(),
+                                                                 "rcps_to_rcpm_schema.json"))
+
+        # Load JSON schema for message validation between RCP Module Command Server and RCP Server (this process)
+        self.rcpmcs_to_rcps_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(),
+                                                                 "rcpmcs_to_rcps_schema.json"))
+        self.rcps_to_rcpmcs_schema = load_json_schema(os.path.join(Path(__file__).parent.resolve(),
+                                                                 "rcps_to_rcpmcs_schema.json"))
+
+        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. Throughout 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.
+    """
+
+    module_client = None
+
+    async def check_version(self):
+        """
+        Check the RCP Client software and protocol version to ensure the requesting RCP Client is compatible with this
+        RCP Server version.
+        """
+
+        # Receive version info from RCP client
+        rx_json = await self._recv()
+        rcpc_version_software = Version(rx_json['rcpc_version']['software'])
+        rcpc_version_protocol = Version(rx_json['rcpc_version']['protocol'])
+        log.debug("RCP Client version: software=%s, protocol=%s",
+                  rcpc_version_software, rcpc_version_protocol)
+        if self.flight_recorder:
+            self.flight_recorder.record_meta('rcpc_version_software', str(rcpc_version_software))
+            self.flight_recorder.record_meta('rcpc_version_protocol', str(rcpc_version_protocol))
+
+        # Check if the RCP Client is compatible with this RCP Server. As of now we expect that the client uses the
+        # exact same protocol version as the server.
+        rcpc_version_protocol_expected = Version(RCPS_VERSION_PROTOCOL)
+        if rcpc_version_protocol != rcpc_version_protocol_expected:
+            info = "RCP Client uses unsupported protocol version (%s != %s)" % (rcpc_version_protocol, rcpc_version_protocol_expected)
+            raise_exception = True
+        else:
+            info = None
+            raise_exception = False
+
+        # Respond with RCP Server version info. We do this before we potentially raise an exception to make sure the
+        # RCP Server version info arrives at the client.
+        tx_json = {'rcpc_version': {'software' : RCPS_VERSION_SOFTWARE,
+                                    'protocol' : RCPS_VERSION_PROTOCOL}}
+        if info:
+            tx_json['rcpc_version']['info'] = info
+        await self._send(tx_json)
+
+        # Raise exception in case problems were detected. This will close the connection, but the client still has the
+        # version info (see above)
+        if raise_exception:
+            raise ValueError(info)
+
+    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 (commandline help, argument validation) from this information.
+        """
+        rx_json = await self._recv()
+        self.suitable_for = rx_json['rcpc_hello']['suitable_for']
+        if self.flight_recorder:
+            self.flight_recorder.record_meta('suitable_for', self.suitable_for)
+        modules = runtime_state.modules_find(self.suitable_for)
+        if self.flight_recorder:
+            suitable_modules = []
+            for m in modules:
+                suitable_modules.append(m['name'])
+            self.flight_recorder.record_meta('suitable_modules', suitable_modules)
+        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)
+        if rx_json is None:
+            raise ValueError("RCP Client vanished unexpectetly")
+        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)
+        if rx_json is None:
+            raise ValueError("RCP Client vanished unexpectetly")
+        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 is None:
+            raise ValueError("RCP Client vanished unexpectedly")
+        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 dedicated connection to that module and
+        forward instruction/response messages between RCP Client and RCP Module until the procedure is done.
+        """
+        # Receive a command from the client.
+        rx_json = await self._recv()
+
+        # The procedure step is not mandatory. In case no procedure shall be executed, the client may close the
+        # connection early on his behalf. This is normal behavior and usually the case when the user instructs the
+        # RCP client to display the commandline help screens.
+        if rx_json is None:
+            log.debug(str(self) + " -- RCP client has closed the connection, no procedure executed")
+            return
+
+        # The RCP client has sent a command, so we continue with the procedure.
+        command = rx_json['rcpc_command']
+        if self.flight_recorder:
+            self.flight_recorder.record_meta('cmd', command['cmd'])
+            self.flight_recorder.record_meta('cmd_argv', command['cmd_argv'])
+
+        # Pick the matching RCP Module
+        module = runtime_state.module_find(self.suitable_for, command['cmd'])
+        if self.flight_recorder:
+            self.flight_recorder.record_meta('module', module.name)
+
+        # Retrieve keys (if the command requires them)
+        cmd_descr = module.get_cmd_descr(command['cmd'])
+        get_keys = cmd_descr.get('get_keys')
+        if get_keys:
+            keys = {}
+            get_keys_uicc = get_keys.get('uicc')
+            if get_keys_uicc:
+                iccid = await self._read_iccid()
+                if self.flight_recorder:
+                    self.flight_recorder.record_meta('iccid', iccid)
+                keys_uicc = card_key_provider_get(get_keys_uicc, 'ICCID', iccid)
+                keys['uicc'] = key_value_pairs_from_dict(keys_uicc, keylabel='key', valuelabel='value')
+            get_keys_euicc = get_keys.get('euicc')
+            if get_keys_euicc:
+                eid = await self._read_eid()
+                if self.flight_recorder:
+                    self.flight_recorder.record_meta('eid', eid)
+                keys_euicc = card_key_provider_get(get_keys_euicc, 'EID', eid)
+                keys['euicc'] = key_value_pairs_from_dict(keys_euicc, keylabel='key', valuelabel='value')
+            command['keys'] = keys
+
+        # Resetting card to ensure the card is in a defined state
+        await self._reset()
+
+        # Create a dedicated connection to the RCP Module and proxy the 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=runtime_state.rcpm_ca_ssl_context) as websocket:
+            # Create a connection to the RCP Module Command Server
+            json_validator = JsonValidator(runtime_state.rcpmcs_to_rcps_schema, runtime_state.rcps_to_rcpmcs_schema)
+            self.module_client = RcpmCltConnHdlr(websocket, CLIENT_TIMEOUT, json_validator, self.flight_recorder)
+
+            # Prepare initial request to be send to the RCP Module Command Server
+            module_tx_json = {'rcps_command' : command}
+
+            # Forward messages between RCP Module Command Server and RCP Client until the procedure ends.
+            while(True):
+                # Send request to the RCP Module Command Server
+                module_rx_json = await self.module_client._transact(module_tx_json)
+
+                # Forward the response to the RCP Client
+                if 'rcps_instr' in module_rx_json:
+                    client_tx_json = {'rcpc_instr' : module_rx_json['rcps_instr']}
+                    await self._send(client_tx_json)
+                elif 'rcps_goodbye' in module_rx_json:
+                    rc = module_rx_json['rcps_goodbye']
+                    log.info(str(self) + " -- command execution done, rc: %d" % rc)
+                    if self.flight_recorder:
+                        self.flight_recorder.record_meta('rc', rc)
+                        if rc != 0:
+                            self.flight_recorder.crash_report()
+                    client_tx_json = {'rcpc_goodbye' : rc}
+                    await self._send(client_tx_json)
+                    break
+                else:
+                    raise ValueError("Unexpected response from RCP Module: %s" % str(module_rx_json))
+
+                # Receive the Result from the client, prepare request (module_tx_json) for the next turn
+                client_rx_json = await self._recv()
+                if client_rx_json is None:
+                    raise ValueError("RCP client vanished unexpectedly")
+                if 'rcpc_result' in client_rx_json:
+                    module_tx_json = {'rcps_result' : client_rx_json['rcpc_result']}
+                else:
+                    raise ValueError("Unexpected result from RCP Client: %s" % str(client_rx_json))
+
+    async def close(self):
+        """
+        Close the connection towards the RCP Module Command Server, then close the connection towards the RCP Client.
+        """
+        if self.module_client:
+            await self.module_client.close()
+        await super().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 check_version(self):
+        """
+        Send the Protocol and Software version of this RCP Module to the RCP Server. The RCP Server and the RCP Module
+        must always use the same protocol version.
+        """
+        tx_json = {'rcpm_version': {'protocol' : RCPM_VERSION_PROTOCOL}}
+        rx_json = await self._transact(tx_json)
+        rcpm_version_protocol = Version(rx_json['rcpm_version']['protocol'])
+        if Version(RCPM_VERSION_PROTOCOL) != rcpm_version_protocol:
+            raise ValueError("Incompatible protocol version %s != %s", Version(RCPM_VERSION_PROTOCOL), rcpm_version_protocol)
+
+    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': None}
+        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__()
+
+class RateLimiter():
+    """
+    Rate limiter: A rate limiter can be used to limit the amount of requests
+    per interval. Once the interval expires, the request counter is reset and
+    the requestor gets a new request budget to spend.
+    """
+
+    def __init__(self, interval:int, requests:int):
+        """
+        Args:
+                interval: reset interval after which request counter is reset.
+                requests: maximum number of requests per interval.
+        Returns:
+                True when rate limit has been exceeded, False otherwise.
+        """
+        self.table = {}
+        self.interval = interval
+        self.requests = requests
+        self.last_collect = time.time()
+        log.info("Rate-Limit: max %d requests per sec.", self.requests / self.interval)
+
+    def __collect_expired(self):
+        new_table = {}
+        for key in self.table.keys():
+            if time.time() - self.table[key]['timestamp'] <= self.interval:
+                new_table[key] = self.table[key]
+        self.table = new_table
+
+    def limit(self, address:str) -> bool:
+        """
+        Rate limit request
+
+        Args:
+                address: requestor address
+        Returns:
+                True when rate limit has been exceeded, False otherwise
+        """
+
+        timestamp = time.time()
+
+        # Collect expired entries once per minute
+        if time.time() - self.last_collect > 60:
+            self.__collect_expired()
+            self.last_collect = timestamp
+
+        # In case no entry exists yet, create a new one => don't block
+        if address not in self.table:
+            self.table[address] = {'timestamp' : timestamp, 'counter' : 1}
+            log.debug("Rate-Limit: %s (new, counter=%d, next reset in %d sec.)",
+                      address, 1, self.interval)
+            return False
+
+        # We have to access multiple times, so its better to story the entry
+        # in a temporary variable.
+        entry = self.table[address]
+
+        # If the entry has expired - delete it => don't block
+        if timestamp - entry['timestamp'] > self.interval:
+            log.debug("Rate-Limit: %s (reset, counter=%d, next reset in %d sec.)",
+                      address, 1, self.interval)
+            self.table[address] = {'timestamp' : timestamp, 'counter' : 1}
+            return False
+
+        # If the rate limit has been reached => block
+        if entry['counter'] >= self.requests:
+            log.warning("Rate-Limit: %s (exceeded, counter=%d, next reset in %d sec.)",
+                        address, entry['counter'], self.interval - (timestamp - entry['timestamp']))
+            return True
+
+        # Increment counter, don't block
+        entry['counter'] += 1
+        log.debug("Rate-Limit: %s (incrementing, counter=%d, next reset in %d sec.)",
+                  address, entry['counter'], self.interval - (timestamp - entry['timestamp']))
+        self.table[address] = entry
+        return False
+
+class OpenObserveFlightRecorder(FlightRecorder):
+    """Concrete implementation of a "flight recorder" using OpenObserve as a monitoring entity."""
+
+    def __init__(self, url: str, email: str, token: str):
+        self.service_auth = requests.auth.HTTPBasicAuth(email, token)
+        self.url = url
+        super().__init__()
+
+    def report(self):
+        report_json = json.dumps(self._gen_report())
+        rc = requests.post(self.url, auth=self.service_auth, data=report_json)
+        if rc.status_code != 200:
+            log.error("POST request to OpenObserve failed: %s", str(rc))
+
+async def rcpc_conn_hdlr(websocket: ServerConnection):
+    """
+    In this handler function we process the request from the the RCP Client. Before we perform any action we check if
+    the rate limit is not exceeded. Then we describe the available commands to the client and execute the procedure
+    the client asks for. When everything is done we close the connection normally. The client may skip executing any
+    procedure by closing the connection early on his behalf.
+
+    The interaction with the client is recorded using a "flight recorder" object. When the interaction is done, the
+    records are analyzed and a report is generated and sent to the OpenObserve monitoring entity.
+    """
+
+    # Immediately close the connection in case the rate limit has been exceeded.
+    if rate_limiter.limit(websocket.remote_address[0]):
+        await websocket.close(code=1008) # Policy Violation
+
+    # Create flight-recorder object
+    flight_recorder = None
+    if runtime_state.open_observe_pars:
+        flight_recorder = OpenObserveFlightRecorder(**runtime_state.open_observe_pars)
+
+    # Execute procedure
+    try:
+        json_validator = JsonValidator(runtime_state.rcpc_to_rcps_schema, runtime_state.rcps_to_rcpc_schema)
+        hdlr = RcpcSrvConnHdlr(websocket, CLIENT_TIMEOUT, json_validator, flight_recorder)
+        await hdlr.check_version()
+        await hdlr.describe()
+        await hdlr.procedure()
+        await hdlr.close()
+    except Exception as e:
+        backtrace("RCPC connection handler")
+        if flight_recorder:
+            flight_recorder.record_backtrace()
+            flight_recorder.crash_report()
+        await websocket.close(code=1011) # Internal Error
+
+    # Generate report from flight-recorder
+    if flight_recorder:
+        flight_recorder.report()
+
+async def rcpm_conn_hdlr(websocket: ServerConnection):
+    """
+    In this handler function we process requests from the RCP Module. We receive the description from the RCP Module.
+    We keep the connection open throughout the whole lifetime of the RCP Module process so that we can know when the
+    RCP Module becomes unavailable for some reason.
+    """
+    try:
+        json_validator = JsonValidator(runtime_state.rcpm_to_rcps_schema, runtime_state.rcps_to_rcpm_schema)
+        hdlr = RcpmSrvConnHdlr(websocket, CLIENT_TIMEOUT, json_validator)
+        await hdlr.check_version()
+        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)
+
+    # 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
+    card_key_provider_init(opts)
+
+    # Prepare parameters for OpenObserve
+    if opts.open_observe_url and opts.open_observe_email and opts.open_observe_token:
+        open_observe_pars = {'url' : opts.open_observe_url,
+                             'email': opts.open_observe_email,
+                             'token' : opts.open_observe_token}
+        log.info("Reporting to OpenObserve: %s", open_observe_pars['url'])
+    else:
+        log.warning("Reporting to OpenObserve: (disabled)")
+        open_observe_pars = None
+
+    # Start RCP server
+    runtime_state = RuntimeState(rcpm_ca_ssl_context, open_observe_pars)
+    rate_limiter = RateLimiter(interval=60, requests=opts.rcpc_request_limit)
+    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,330 @@
+#!/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 time
+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)
+
+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<---------------------")
+
+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
+
+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 occurrence 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.debug("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.debug("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 FlightRecorder(abc.ABC):
+    """
+    Base class to create a FlightRecorder object which can be passed to any ConnHdlr object to record debug information
+    (record_comm, record_debug) and metadata (record_meta) throughout the lifetime of a ConnHdlr object. In case the
+    ConnHdlr throws an exception, the API user may call the record_backtrace method to record a backtrace. Finally,
+    the APU user may call the report method (which calls _gen_report internally) to send a report to an external
+    monitoring enitiy.
+    """
+
+    def __init__(self):
+        self.records_meta = {}
+        self.records_comm = []
+        self.records_debug = []
+        self.crash_report_flag = False
+        self.record_meta('timestamp_start', time.strftime('%Y-%m-%d %H:%M:%S'))
+
+    def record_meta(self, key: str, value):
+        """Record/Update metadata"""
+        self.records_meta[key] = value
+
+    def record_comm(self, key: str, value):
+        """Record communication (automatically called by the ConnHdlr object)"""
+        self.records_comm.append({key : value})
+
+    def record_debug(self, key: str, value):
+        """Record debug information"""
+        self.records_debug.append({key : value})
+
+    def record_backtrace(self):
+        """Record a backtrace"""
+        traceback_lines = traceback.format_exc()
+        traceback_lines_filtered = []
+        for line in traceback_lines.split("\n"):
+            if line:
+                traceback_lines_filtered.append(line)
+        self.record_debug('backtrace', traceback_lines_filtered)
+
+    def crash_report(self):
+        """Set crash_report_flag. Thie method shall be called if an unrecoverable error has occured."""
+        self.crash_report_flag = True
+
+    def _gen_report(self):
+        """
+        Generate a report from the collected data. In case the crash_report flag is set to true, the report will
+        inculde communications (records_comm) and debug information (records_debug). Otherwise only the metadata
+        (records_meta) will be included.
+        """
+        self.record_meta('timestamp_end', time.strftime('%Y-%m-%d %H:%M:%S'))
+        report = self.records_meta
+        if self.crash_report_flag:
+            report['comm'] = self.records_comm
+            report['debug'] = self.records_debug
+            report['report_type'] = 'crash'
+            log.warning("crash report: %s", str(report))
+            return report
+        else:
+            report['report_type'] = 'normal'
+            log.debug("normal report: %s", str(report))
+            return report
+
+    @abc.abstractmethod
+    def report(self):
+        """
+        To be implemented in the derived class. Shall call _gen_report and then send the report to an external
+        monitoring entity.
+        """
+        pass
+
+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, flight_recorder: FlightRecorder = None):
+        self.websocket = websocket
+        self.local_address = websocket.local_address
+        self.remote_address = websocket.remote_address
+        self.timeout = timeout
+        self.json_validator = json_validator
+        self.flight_recorder = flight_recorder
+        log.debug(str(self) + " -- new handler, timeout: %d sec.", self.timeout)
+        if self.flight_recorder:
+            self.flight_recorder.record_meta(type(self).__name__ + '_remote_address',
+                                             str(self.remote_address[0]) + ":" + str(self.remote_address[1]))
+            self.flight_recorder.record_meta(type(self).__name__ + '_timestamp', time.strftime('%Y-%m-%d %H:%M:%S'))
+            self.flight_recorder.record_meta(type(self).__name__ + '_id', id(self))
+
+    def _log_recv_peer(self, rx_json_str: str):
+        peer = "%s:%d<-%s:%d" % (self.local_address[0],
+                           self.local_address[1],
+                           self.remote_address[0],
+                           self.remote_address[1])
+        log.debug(str(self) + " -- RX(%s): %s", peer, rx_json_str)
+        if self.flight_recorder:
+            self.flight_recorder.record_comm(type(self).__name__ + '_rx', rx_json_str)
+
+    def _log_send_peer(self, tx_json_str: str):
+        peer = "%s:%d->%s:%d" % (self.local_address[0],
+                           self.local_address[1],
+                           self.remote_address[0],
+                           self.remote_address[1])
+        log.debug(str(self) + " -- TX(%s): %s", peer, tx_json_str)
+        if self.flight_recorder:
+            self.flight_recorder.record_comm(type(self).__name__ + '_tx', 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"""
+        rx_json_str = self.websocket.recv(self.timeout)
+        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_to_rcps_schema.json

@@ -0,0 +1,99 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "RCP Client to RCP Server",
+    "type": "object",
+    "properties": {
+	"rcpc_version": {
+	    "type": "object",
+	    "properties": {
+		"software": {
+		    "type": "string"
+		},
+		"protocol": {
+		    "type": "string"
+		}
+	    },
+	    "required": [ "software",  "protocol" ],
+	    "additionalProperties": false
+	},
+	"rcpc_hello": {
+	    "type": "object",
+	    "properties": {
+		"suitable_for": {
+		    "type": "object",
+		    "properties": {
+			"atr": {
+			    "type": "string",
+			    "pattern": "^[0-9,A-F]{0,66}$"
+			}
+		    },
+		    "oneOf": [
+			{ "required": [ "atr" ] }
+		    ],
+		    "additionalProperties": false
+		}
+	    },
+	    "required": [ "suitable_for" ],
+	    "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
+		}
+	    },
+	    "required": [ "cmd", "cmd_argv" ],
+	    "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}$"
+			}
+		    },
+		    "required": [ "data", "sw" ],
+		    "additionalProperties": false
+		},
+		"atr": {
+		    "type": "string",
+		    "pattern": "^[0-9,A-F]{0,66}$"
+		},
+		"empty": {
+		    "type": "null"
+		}
+	    },
+	    "oneOf": [
+		{ "required": [ "r_apdu" ] },
+		{ "required": [ "atr" ] },
+		{ "required": [ "empty" ] }
+	    ],
+	    "additionalProperties": false
+	}
+    },
+    "oneOf": [
+	{ "required": [ "rcpc_version" ] },
+	{ "required": [ "rcpc_hello" ] },
+	{ "required": [ "rcpc_command" ] },
+	{ "required": [ "rcpc_result" ] }
+    ],
+    "additionalProperties": false
+}

contrib/rcp/rcpm_to_rcps_schema.json

@@ -0,0 +1,127 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "RCP Module to RCP Server",
+    "type": "object",
+    "properties": {
+	"rcpm_version": {
+	    "type": "object",
+	    "properties": {
+		"protocol": {
+		    "type": "string"
+		}
+	    },
+	    "required": [ "protocol" ],
+	    "additionalProperties": false
+	},
+	"rcpm_hello": {
+	    "type": "object",
+	    "properties": {
+		"name": {
+		    "type": "string"
+		},
+		"cmd_descr": {
+		    "type": "array",
+		    "items": {
+			"type": "object",
+			"properties": {
+			    "name": {
+				"type": "string"
+			    },
+			    "help": {
+				"type": "string"
+			    },
+			    "args": {
+				"type": "array",
+				"items": {
+				    "type": "object",
+				    "properties": {
+					"name": {
+					    "type": "string"
+					},
+					"spec": {
+					    "type": "object",
+					    "properties": {
+						"required" : {
+						    "type": "boolean"
+						},
+						"help": {
+						    "type": "string"
+						},
+						"action": {
+						    "type": "string"
+						},
+						"pytype": {
+						    "type": "string"
+						},
+						"default" : {
+						    "type": ["string", "integer"]
+						}
+					    },
+					    "required": [ "help" ],
+					    "additionalProperties": false
+					}
+				    },
+				    "required": [ "name", "spec" ],
+				    "additionalProperties": false
+				}
+			    },
+			    "get_keys": {
+				"type": "object",
+				"properties": {
+				    "uicc" : {
+					"type": "array",
+					"items": {
+					    "type": "string"
+					}
+				    },
+				    "euicc" : {
+					"type": "array",
+					"items": {
+					    "type": "string"
+					}
+				    }
+				},
+				"oneOf": [
+				    { "required": [ "uicc" ] },
+				    { "required": [ "euicc" ] }
+				],
+				"additionalProperties": false
+			    }
+			},
+			"required": [ "name",  "help", "args" ],
+			"additionalProperties": false
+		    }
+		},
+		"suitable_for": {
+		    "type": "array",
+		    "items": {
+			"type": "object",
+			"properties": {
+			    "atr": {
+				"type": "string",
+				"pattern": "^[0-9,A-F]{0,66}$"
+			    }
+			},
+			"oneOf": [
+			    { "required": [ "atr" ] }
+			],
+			"additionalProperties": false
+		    }
+		},
+		"addr": {
+		    "type": "string"
+		},
+		"port": {
+		    "type": "integer"
+		}
+	    },
+	    "required": [ "name",  "cmd_descr", "suitable_for", "addr", "port" ],
+	    "additionalProperties": false
+	}
+    },
+    "oneOf": [
+	{ "required": [ "rcpm_hello" ] },
+	{ "required": [ "rcpm_version" ] }
+    ],
+    "additionalProperties": false
+}

contrib/rcp/rcpmcs_to_rcps_schema.json

@@ -0,0 +1,36 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "RCP Module Command Server to RCP Server",
+    "type": "object",
+    "properties": {
+	"rcps_instr": {
+	    "type": "object",
+	    "properties": {
+		"print": {
+		    "type": "string"
+		},
+		"reset": {
+		    "type": "null"
+		},
+		"c_apdu": {
+		    "type": "string",
+		    "pattern": "^[0-9,A-F]{0,512}$"
+		}
+	    },
+	    "oneOf": [
+		{ "required": [ "print" ] },
+		{ "required": [ "reset" ] },
+		{ "required": [ "c_apdu" ] }
+	    ],
+	    "additionalProperties": false
+	},
+	"rcps_goodbye": {
+	    "type": "integer"
+	}
+    },
+    "oneOf": [
+	{ "required": [ "rcps_instr" ] },
+	{ "required": [ "rcps_goodbye" ] }
+    ],
+    "additionalProperties": false
+}

contrib/rcp/rcps_to_rcpc_schema.json

@@ -0,0 +1,125 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "RCP Server to RCP Client",
+    "type": "object",
+    "properties": {
+	"rcpc_version": {
+	    "type": "object",
+	    "properties": {
+		"software": {
+		    "type": "string"
+		},
+		"protocol": {
+		    "type": "string"
+		},
+		"info": {
+		    "type": "string"
+		}
+	    },
+	    "required": [ "software",  "protocol" ],
+	    "additionalProperties": false
+	},
+	"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": {
+						"type": "object",
+						"properties": {
+						    "name": {
+							"type": "string"
+						    },
+						    "spec": {
+							"type": "object",
+							"properties": {
+							    "required" : {
+								"type": "boolean"
+							    },
+							    "help": {
+								"type": "string"
+							    },
+							    "action": {
+								"type": "string"
+							    },
+							    "pytype": {
+								"type": "string"
+							    },
+							    "default" : {
+								"type": ["string", "integer"]
+							    }
+							},
+							"required": [ "help" ],
+							"additionalProperties": false
+						    }
+						},
+						"required": [ "name", "spec" ],
+						"additionalProperties": false
+					    }
+					}
+				    },
+				    "required": [ "name",  "help", "args" ],
+				    "additionalProperties": false
+				}
+			    }
+			},
+			"required": [ "name",  "cmd_descr" ],
+			"additionalProperties": false
+		    }
+		}
+	    },
+	    "required": [ "module_descr" ],
+	    "additionalProperties": false
+	},
+	"rcpc_instr": {
+	    "type": "object",
+	    "properties": {
+		"print": {
+		    "type": "string"
+		},
+		"reset": {
+		    "type": "null"
+		},
+		"c_apdu": {
+		    "type": "string",
+		    "pattern": "^[0-9,A-F]{0,512}$"
+		}
+	    },
+	    "oneOf": [
+		{ "required": [ "print" ] },
+		{ "required": [ "reset" ] },
+		{ "required": [ "c_apdu" ] }
+	    ],
+	    "additionalProperties": false
+	},
+	"rcpc_goodbye": {
+	    "type": "integer"
+	}
+    },
+    "oneOf": [
+	{ "required": [ "rcpc_version" ] },
+	{ "required": [ "rcpc_welcome" ] },
+	{ "required": [ "rcpc_instr" ] },
+	{ "required": [ "rcpc_goodbye" ] }
+    ],
+    "additionalProperties": false
+}

contrib/rcp/rcps_to_rcpm_schema.json

@@ -0,0 +1,25 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "RCP Server to RCP Module",
+    "type": "object",
+    "properties": {
+	"rcpm_version": {
+	    "type": "object",
+	    "properties": {
+		"protocol": {
+		    "type": "string"
+		}
+	    },
+	    "required": [ "protocol" ],
+	    "additionalProperties": false
+	},
+	"rcpm_welcome": {
+	    "type": "null"
+	}
+    },
+    "oneOf": [
+	{ "required": [ "rcpm_version" ] },
+	{ "required": [ "rcpm_welcome" ] }
+    ],
+    "additionalProperties": false
+}

contrib/rcp/rcps_to_rcpmcs_schema.json

@@ -0,0 +1,106 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "RCP Server to RCP Module Command Server",
+    "type": "object",
+    "properties": {
+    	"rcps_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
+		},
+		"keys" : {
+		    "type": "object",
+		    "properties": {
+			"uicc" : {
+			    "type": "array",
+			    "items": {
+				"type": "object",
+				"properties": {
+				    "key": {
+					"type": "string"
+				    },
+				    "value": {
+					"type": "string"
+				    }
+				},
+				"required": [ "key", "value" ],
+				"additionalProperties": false
+			    }
+			},
+			"euicc" : {
+			    "type": "array",
+			    "items": {
+				"type": "object",
+				"properties": {
+				    "key": {
+					"type": "string"
+				    },
+				    "value": {
+					"type": "string"
+				    }
+				},
+				"required": [ "key", "value" ],
+				"additionalProperties": false
+			    }
+			}
+		    },
+		    "oneOf": [
+			{ "required": [ "uicc" ] },
+			{ "required": [ "euicc" ] }
+		    ],
+		    "additionalProperties": false
+		}
+	    },
+	    "required": [ "cmd", "cmd_argv" ],
+	    "additionalProperties": false
+	},
+	"rcps_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}$"
+			}
+		    },
+		    "required": [ "data", "sw" ],
+		    "additionalProperties": false
+		},
+		"atr": {
+		    "type": "string",
+		    "pattern": "^[0-9,A-F]{0,66}$"
+		},
+		"empty": {
+		    "type": "null"
+		}
+	    },
+	    "oneOf": [
+		{ "required": [ "r_apdu" ] },
+		{ "required": [ "atr" ] },
+		{ "required": [ "empty" ] }
+	    ],
+	    "additionalProperties": false
+	}
+    },
+    "oneOf": [
+	{ "required": [ "rcps_command" ] },
+	{ "required": [ "rcps_result" ] }
+    ],
+    "additionalProperties": false
+}

contrib/rcp/usage_example/card_data.csv

@@ -0,0 +1,2 @@
+iccid,kic,kid,kik
+8949440000001155306,F09C43EE1A0391665CC9F05AF4E0BD10,01981F4A20999F62AF99988007BAF6CA,8F8AEE5CDCC5D361368BC45673D99195

contrib/rcp/usage_example/card_data.csv.encr

@@ -0,0 +1,2 @@
+"ICCID","KIC","KID","KIK"
+"8949440000001155306","eae46224fa0a4ac1c12cba9d102f1188","3f14b978ddb38c08d832d4e4c2e0639d","9e19db4a5ed5cb8c4f5d96283eab273a"

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/encrypt_card_data.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+. ./params.cfg
+
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/csv-encrypt-columns.py \
+		      --csv-column-key kic:$CSV_COLUMN_KEY \
+		      --csv-column-key kid:$CSV_COLUMN_KEY \
+		      --csv-column-key kik:$CSV_COLUMN_KEY \
+		      card_data.csv

contrib/rcp/usage_example/params.cfg

@@ -0,0 +1,36 @@
+# Verbosity switch passed to all components (comment-out to disable verbose mode)
+#VERBOSE="--verbose"
+
+# PYSIM_DIR passed to all components
+PYSIM_DIR=../../../ # Points to the psyim top directory
+
+# CSV column key to decrypt KIC, KID and KIK in csv_data.csv.encr
+# (use encrypt_card_data.sh to regenerate csv_data.csv.encr from csv_data.csv)
+CSV_COLUMN_KEY="00112233445566778899AABBCCDDEEFF"
+
+# PCSC reader that the RCP Client shall use
+PCSC_READER=0
+
+# CA of the certificates used in this example
+CERT_DIR="./certs"
+CA_CERT="$CERT_DIR/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="$CERT_DIR/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="$CERT_DIR/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="$CERT_DIR/example_ssl_rcps_rcpm_cert.pem"

contrib/rcp/usage_example/rcp_module.py

@@ -0,0 +1,130 @@
+#!/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 pySim.global_platform import GpCardKeyset, SCP02, ADF_SD
+from Cryptodome.Random import get_random_bytes
+from osmocom.utils import h2b, b2h
+from rcp_module_utils import rcpm_setup_argparse, rcpm_run_module, RcpModule, RcpModuleHdlr
+
+log = PySimLogger.get(Path(__file__).stem)
+option_parser = rcpm_setup_argparse("Example Module")
+
+class ExmpleModule(RcpModule):
+
+    def __init__(self, *args, **kwargs):
+        log.info("rcpm_run_module was called with the following additional arguments:")
+        log.info("%s, %s", str(args), str(kwargs))
+
+    name = 'rcp_module'
+    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'},
+                              }
+                            ]},
+                 {'name' : 'unlock_aram',
+                  'help': 'unlock a locked ARA-M applet on a sysmoISIM-SJA5',
+                  'args' : [],
+                  'get_keys' : {'uicc' : ['KIC', 'KID', 'KIK']}}
+                 ]
+    suitable_for = [{'atr' : '3b9f96801f878031e073fe211b674a357530350265f8'}]
+
+    def cmd_reset(self, hdlr: RcpModuleHdlr) -> int:
+        hdlr.print("resetting UICC/eUICC ...")
+        hdlr.card._scc.reset_card()
+        hdlr.print("ATR is: %s" % hdlr.card._scc.get_atr())
+        return 0
+
+    def cmd_read_binary(self, hdlr: RcpModuleHdlr) -> int:
+        fid = hdlr.cmd_args.fid
+        hdlr.print("reading transparent file: %s ..." % fid)
+        (res, _) = hdlr.card._scc.read_binary(fid)
+        hdlr.print("file content is: %s" % res)
+        return 0
+
+    def cmd_read_record(self, hdlr: RcpModuleHdlr) -> int:
+        fid = hdlr.cmd_args.fid
+        record = hdlr.cmd_args.record
+        hdlr.print("reading linear-fixed file: %s ..." % fid)
+        (res, _) = hdlr.card._scc.read_record(fid, record)
+        hdlr.print("file content is: %s" % res)
+        return 0
+
+    def cmd_unlock_aram(self, hdlr: RcpModuleHdlr) -> int:
+        # Select ADF.ISD
+        hdlr.print("Selecting ADF.ISD ...")
+        hdlr.lchan.scc.send_apdu_checksw("00a4040408a00000000300000000")
+
+        # Establish secure channel
+        hdlr.print("Establishing secure channel ...")
+        key_ver = 112
+        key_enc = hdlr.keys_uicc['KIC']
+        key_mac = hdlr.keys_uicc['KID']
+        key_dek = hdlr.keys_uicc['KIK']
+        security_level = 3
+        host_challenge_len = 8
+        host_challenge = get_random_bytes(host_challenge_len)
+        kset = GpCardKeyset(key_ver, h2b(key_enc), h2b(key_mac), h2b(key_dek))
+        scp = SCP02(card_keys=kset)
+        ADF_SD.establish_scp(hdlr.lchan.scc, scp, host_challenge, security_level)
+
+        # To prove that it works, we need to do something that actually requires to be authenticated
+        # via a secure channel. In this example we will send an unlock command to the ARA-M applet
+        # found on any sysmoISIM-SJA5 card. (see also: https://gitea.osmocom.org/sim-card/aram-applet)
+        hdlr.print("Unlocking ARA-M applet ...")
+        ara_m_aid = "a00000015141434c00"
+        ADF_SD.install(hdlr.lchan.scc, 0x20, 0x00, "0000%02x%s000000" % (len(ara_m_aid) // 2, ara_m_aid))
+        ADF_SD.store_data(hdlr.lchan.scc, h2b("A2"), structure = 'ber_tlv')
+
+        # Release the secure channel
+        hdlr.print("Done, releasing secure channel ...")
+        ADF_SD.release_scp(hdlr.lchan.scc)
+        return 0
+
+if __name__ == '__main__':
+    opts = option_parser.parse_args()
+    rcpm_run_module(opts, ExmpleModule,
+                    "arg1", "arg2", "arg3",
+                    kwarg1="kwarg1", kwarg2="kwarg2", kwarg3="kwarg3")

contrib/rcp/usage_example/readme.txt

@@ -0,0 +1,16 @@
+How to try:
+
+Go to the directory that contains the usage example:
+cd pysim/contrib/rcp/usage_example
+
+Edit card_data.csv to fill in the SCP02 keys for the ISD of your sysmoISIM-SJA5
+
+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,28 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/rcp/rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI\
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_reset
+
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/rcp/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 $PYSIM_DIR/contrib/rcp/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
+
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/rcp/rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_unlock_aram

contrib/rcp/usage_example/run_rcp_client_help.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/rcp/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 $PYSIM_DIR/contrib/rcp/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,28 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/rcp/rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_reset --help
+
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/rcp/rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_read_binary --help
+
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/rcp/rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_read_record --help
+
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/rcp/rcp_client.py $VERBOSE \
+		      --uri $RCPC_SERVER_URI \
+		      --ca-cert $CA_CERT \
+		      -p $PCSC_READER \
+		      rcp_module_unlock_aram --help

contrib/rcp/usage_example/start_rcp_module.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+PYTHONPATH=$PYSIM_DIR:$PYSIM_DIR/contrib/rcp ./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 \
+					     --column-key kic:$CSV_COLUMN_KEY \
+					     --column-key kid:$CSV_COLUMN_KEY \
+					     --column-key kik:$CSV_COLUMN_KEY
+

contrib/rcp/usage_example/start_rcp_server.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+. ./params.cfg
+
+set -x
+PYTHONPATH=$PYSIM_DIR $PYSIM_DIR/contrib/rcp/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 \
+		      --csv ./card_data.csv.encr

docs/conf.py

@@ -14,6 +14,8 @@ import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
 sys.path.insert(0, os.path.abspath('.'))   # for local extensions (pysim_fs_sphinx, ...)
+sys.path.insert(0, os.path.abspath('../contrib/rcp'))  # for argparse
+sys.path.insert(0, os.path.abspath('../contrib/rcp/usage_example'))  # for argparse
 
 
 # -- Project information -----------------------------------------------------
@@ -42,6 +44,7 @@ extensions = [
         "sphinx.ext.autosectionlabel",
         "sphinx.ext.napoleon",
         "pysim_fs_sphinx",
+        "sphinx.ext.graphviz",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -50,6 +50,7 @@ pySim consists of several parts:
    suci-keytool
    saip-tool
    smpp-ota-tool
+   rcpf
 
 
 Indices and tables

docs/rcpf.rst

@@ -0,0 +1,690 @@
+Remote Card Procedure Framework
+===============================
+
+The Remote Card Procedure Framework `(RCPF)` is a modular system to provide custom,
+remote controlled, procedures to card `(UICC or eUICC)` holders. The card holder
+uses a minimal client program `(RCP Client)` together with a PC/SC reader. The
+client program will then connect to a remote server `(RCP Server)`. The remote
+server maintains a list and connections to custom modules `(RCP Modules)`, where
+each module implements a set of procedures (commands). Based on its internal list,
+the remote server will offer a set of suitable commands to the client. The card
+holder may then chose a command to request the execution of a specific remote
+card procedure. The server will make the connection to the matching module and act
+as a proxy between the module and the client program.
+
+.. graphviz::
+
+   digraph foo {
+
+      subgraph cluster_server {
+         label = "server (card issuer)"
+         RCPS [label = "RCP Server"];
+         RCPM [label = "RCP Module"];
+	 CKP [label = "CardKeyProvider"];
+      }
+
+      subgraph cluster_field {
+         label = "field (card holder)"
+         ICC [label = "UICC/eUICC"];
+         RCPC [label = "RCP Client"];
+      }
+
+      RCPC -> ICC [label="PC/SC, APDU"];
+      RCPC -> RCPS [label="WS, JSON"];
+      RCPS -> CKP [label="pgSQL or CSV"];
+      RCPS -> RCPM [label="WS, JSON", headlabel="n", taillabel="1", dir=both];
+
+   }
+
+in case the procedure requires a secure channel, the key material is retrieved
+using a `CardKeyProvider` [1]. Since the retrieval of the key material
+as well as the secure channel establishment happens internally, the related
+key material is never disclosed to the client side.
+
+This solves a major problem many card deployments suffer from: Due to security
+reasons it is not always be possible to disclose key material to the card
+holder. This becomes a problem in case card contents have to be modified after
+the card had been deployed. This often means that the card issuer has to
+physically replace the already deployed cards. With `RCPF`, the card issuer can
+replace this process by deploying a suitable RCP Module on his server to offer
+a fix-up procedure that the card holder can call remotely.
+
+[1] :ref:`Retrieving card-individual keys via CardKeyProvider`
+
+In the following we will describe the system components in further detail. We
+will also give an introduction on how users can implement custom `RCP Modules`
+
+RCP Server
+~~~~~~~~~~
+
+The `RCP Server` is the core component in the overall system. It acts as a proxy
+between the `RCP Modules` (see below) and the `RCP Client` (see below). The
+`RCP Server` is permanently aware of which `RCP Modules` are available and knows
+their properties. With this knowledge, the `RCP Server` is able to check which
+module provides suitable procedures for specific card type.
+
+Another responsibility of the `RCP Server` is to retrieve the key material using
+the `CardKeyProvider`. As far as the `CardKeyProvider` is concerned, the RCP
+Server takes the exact same commandline options as pySim-shell.py. However, in
+case column encryption is used. The decryption key shall be passed to the
+`RCP Module` instead to the `RCP Server`. This moves the decryption to the point
+where the key material is actually needed.
+
+To ensure the privacy of the traffic exchanged between `RCP Client`,
+`RCP Server` and the `RCP Modules`, all links use SSL/TLS encrypted channels.
+This is in particular relevant for the `RCP Client` which usually connects to
+the `RCP Server` via the public internet.
+
+Since the `RCP Server` is exposed to the public internet, it also requires some
+level of protection against malicious requests. To minimize the risk arising
+from malformed requests, each incoming and outgoing message is validated against
+a JSON schema (also on the internal interfaces). Incoming requests from the
+RCP Client side are also rate-limited to guard against excessive requests (DoS)
+
+To monitor the `RCP Client` requests, the `RCP Server` support logging to an
+`OpenObserve` monitoring entity. For each request exactly one report es
+generated and sent to `OpenObserve`. For successful request, this report will
+only contain metadata. In case of crashes or when the return code of the
+`RCP Module` procedure is not 0, a full debug log is included as well.
+
+.. argparse::
+   :module: contrib.rcp.rcp_server
+   :func: option_parser
+   :prog: contrib/rcp/rcp_server.py
+
+
+RCP Client
+~~~~~~~~~~
+
+The `RCP Client` is used in the field by the card holder to request command
+lists and to request the execution of procedures from the `RCP Server`.
+
+The execution of a procedure is usually done in two steps. In the first step,
+the card holder will request a list with available commands using the `--help`
+option. The command list is then requested from the `RCP Server` displayed as
+a regular commandline help-screen. The list will only contain commands, which
+are actually suitable for the specific card type/model that card holder owns.
+
+In the second step, the card holder will choose a command to request the
+execution of the related procedure. In case the user already knows exactly
+which command to execute, the first step may also be skipped. The request of
+command lists for the purpose of displaying commandline help-screens is
+entirely optional.
+
+To avoid having to upgrade the RCP Client too often, the implementation is kept
+as simple as possible. Technically, the RCP Client is not much more than a
+proxy between a PC/SC-Reader and the RCP Server. All higher level tasks, like
+requesting the ICCID (UICC or eSIM) or the EID (eUICC) are implemented on the
+server side.
+
+.. argparse::
+   :module: contrib.rcp.rcp_client
+   :func: option_parser
+   :prog: contrib/rcp/rcp_client.py
+
+
+RCP Module
+~~~~~~~~~~
+
+The processing chain terminates in one of multiple `RCP Modules`. The `RCP Module`
+is the custom implementation that implements one or more procedures. The
+framework is designed in such a way that `RCP Modules` have minimal boilerplate
+code. The implementation is kept simple. Users, which are familiar with
+`pySim-shell` and its API will find the implementation of custom `RCP Modules`
+as simple as implementing a new `pySim-shell` command.
+
+From inside a procedure, the API user has access to the same objects (rs, card,
+lchan) that are also usually available in `pySim-shell` environment.
+
+To reset the card, retrieve the ATR and to exchange APDUs, the `pySim.transport`
+API together with a custom `LinkBase (RcpsSimLink)` object is used. This means
+that all modules which depend on the `pySim.transport` API can be used right
+away without modification.
+
+A procedure always runs in a dedicated thread, which means no special
+precautions are necessary. A procedure may wait or sleep without disturbing
+other requests.
+
+Even though there are similarities to `pySim-shell` one has to keep in mind that
+`RCP Modules` are intended to run non-interactively, which means they naturally
+do not provide any support for `cmd2` API calls. This means that before code
+from `pySim-shell` commands can be re-used, any `cmd2` entanglement must be
+removed or separated otherwise.
+
+.. argparse::
+   :module: contrib.rcp.usage_example.rcp_module
+   :func: option_parser
+   :prog: contrib/rcp/usage_example/rcp_module.py
+
+
+Usage Example
+~~~~~~~~~~~~~
+
+All system components and related modules can be found in `contrib/rcp`. The
+sub directory `usage_example` contains an example `RCP Module` and scripts to
+make it easier to get started. The following steps explain in detail how to get
+the `usage_example` running.
+
+Parameters
+----------
+
+The `usage_example` contains a file `params.cfg`. This file contains variables,
+which hold the parameters for the shell-scripts included in the example. The
+parameters set up the system in such a way that everything runs locally.
+Normally no changes are required, but it is strongly advised to review the
+parameters to verify there are no clashes with other services.
+
+Preparing Card Keys
+-------------------
+
+The example assumes a PC/SC reader and a `sysmoISIM-SJA5` or similar. To run
+the `usage_example`, no modification to the card itself are required, but the
+example key material (SCP02) in `card_data.csv` must match the test card.
+
+The following example assumes that the card has the ICCID ``8949440000001155306``
+and the following SCP02 keys:
+
++---------+----------------------------------+
+| Keyname | Keyvalue                         |
++=========+==================================+
+| ENC/KIC | F09C43EE1A0391665CC9F05AF4E0BD10 |
++---------+----------------------------------+
+| MAC/KID | 01981F4A20999F62AF99988007BAF6CA |
++---------+----------------------------------+
+| DEK/KIK | 8F8AEE5CDCC5D361368BC45673D99195 |
++---------+----------------------------------+
+
+This would result into a `card_data.csv` file with the following content:
+
+::
+
+   iccid,kic,kid,kik
+   8949440000001155306,F09C43EE1A0391665CC9F05AF4E0BD10,01981F4A20999F62AF99988007BAF6CA,8F8AEE5CDCC5D361368BC45673D99195
+
+
+See also: :ref:`Retrieving card-individual keys via CardKeyProvider` and :ref:`Guide: Managing GP Keys`
+
+When `card_data.csv` is re-aligned, the columns containing key material need to
+be encrypted. This is done by running `encrypt_card_data.sh`. This script will
+output a file `card_data.csv.encr` which contains the encrypted key material.
+
+Running the RCP Server
+----------------------
+
+The `RCP Server` can be started using the included `start_rcp_server.sh` script.
+
+::
+
+   $ ./start_rcp_server.sh
+   + PYTHONPATH=../../../
+   + ../../..//contrib/rcp/rcp_server.py --rcpc-server-addr 127.0.0.1 --rcpc-server-port 8000 --rcpc-server-cert ./certs/example_ssl_rcpc_rcps_cert.pem --rcpm-server-addr 127.0.0.1 --rcpm-server-port 8010 --rcpm-server-cert ./certs/example_ssl_rcpm_rcps_cert.pem --rcpm-module-ca-cert ./certs/example_ssl_rcp_ca_cert.crt --csv ./card_data.csv.encr
+   INFO: loading SSL/TLS CA certificate (RCP Module Command Server Client): ./certs/example_ssl_rcp_ca_cert.crt
+   INFO: Using CSV file as card key data source: ./card_data.csv.encr
+   WARNING: Reporting to OpenObserve: (disabled)
+   INFO: Rate-Limit: max 10 requests per sec.
+   INFO: RCP Client Server at: 127.0.0.1:8000
+   INFO: RCP Module server at: 127.0.0.1:8010
+
+We can see that now to ports have been opened. `127.0.0.1:8000` is the port
+where `RCP Clients` can connect. In a productive setup, this port would
+normally be reachable from outside. The other port on `127.0.0.1:8010` is
+accepting connections from `RCP Modules` This port should not be reachable
+from the outside. It is intended to be used for the interprocess communication
+between the `RCP Server` and the `RCP Modules`
+
+In this state, the `RCP Server` waits for requests from both `RCP Clients` and
+`RCP Modules`. However, there are not `RCP Modules` registered yet, so any
+request from an `RCP Client` would be quilted with an error message.
+
+Running the RCP Module
+----------------------
+
+For a functioning setup a suitable `RCP Module` is needed. The provided
+`rcp_module.py` python program implements a few procedures which are suitable
+for a `sysmoISIM-SJA5` card.
+
+We can start the `RCP Module` with the provided start script
+`start_rcp_module.sh`
+
+::
+
+   $ ./start_rcp_module.sh
+   + PYTHONPATH=../../../:../../..//contrib/rcp
+   + ./rcp_module.py --uri wss://127.0.0.1:8010 --rcps-ca-cert ./certs/example_ssl_rcp_ca_cert.crt --rcpm-cmd-server-addr 127.0.0.1 --rcpm-cmd-server-port 8020 --rcpm-cmd-server-cert ./certs/example_ssl_rcps_rcpm_cert.pem --column-key kic:00112233445566778899AABBCCDDEEFF --column-key kid:00112233445566778899AABBCCDDEEFF --column-key kik:00112233445566778899AABBCCDDEEFF
+   INFO: RCP Module startup: rcp_module
+   INFO: loading SSL/TLS CA certificate (RCPM Server Client): ./certs/example_ssl_rcp_ca_cert.crt
+   INFO: RCPC command server at: 127.0.0.1:8020
+
+The `RCP Module` is now connected to the `RCP Server`. The log output of the
+`RCP Server` also confirms that there is a new `RCP Module` available.
+
+::
+
+   INFO: new RCP module, RCP modules available: 'rcp_module'
+
+On the output of the `RCP Module` we can see that the `RCP Module` has
+opened another port on `127.0.0.1:8020`. This is where the `RCP Module` accepts
+dedicated connections from the `RCP Server` when an `RCP Client` requests a
+procedure. In an installation with multiple `RCP Modules`, each `RCP Module`
+must use a dedicated port number.
+
+Note that we also pass the column key for the key material using the
+`--column-key` parameter. This parameter works exactly as in `pySim-shell`.
+We supply the column key to the `RCP Module` and not to the `RCP Server`
+move the decryption as close as possible to where it is needed.
+
+
+Running the RCP Client
+----------------------
+
+The `usage_example` provides a shello-script `run_rcp_client.sh` that which
+requests commandline help and requests procedures by calling other scripts.
+However to get an understanding how the `RCP Client` is supposed to be used, it
+makes more sense to call the sub scripts individually. We will now go through
+step by step.
+
+The first shell-script `./run_rcp_client_help.sh` assumes that the card holder
+uses the `RCP Client` for the first time. He does not know which commandline
+arguments are available, so he just calls `rcp_client.py` with the option `-h`.
+
+::
+
+   $ ./run_rcp_client_help.sh
+   + PYTHONPATH=../../../
+     + ../../..//contrib/rcp/rcp_client.py -h
+       usage: rcp_client.py [-h] [-d DEV] [-b BAUD] [--pcsc-shared] [-p PCSC | --pcsc-regex REGEX] [--modem-device DEV] [--modem-baud BAUD] [--osmocon PATH]
+                     [--apdu-trace] [--verbose] [--uri URI] [--ca-cert CA_CERT]
+
+   RCP Client
+
+   options:
+     -h, --help            show this help message and exit
+     --apdu-trace          Trace the command/response APDUs exchanged with the card (default: False)
+     --verbose             Enable verbose logging (default: False)
+     --uri URI             URI of the RCP-Server (default: None)
+     --ca-cert CA_CERT     SSL/TLS CA-Certificate of the RCP-Server (default: None)
+     ...
+
+   PC/SC Reader:
+     Use a PC/SC card reader to talk to the SIM card. PC/SC is a standard API for how applications access smart card readers, and is available on a variety of
+     operating systems, such as Microsoft Windows, MacOS X and Linux. Most vendors of smart card readers provide drivers that offer a PC/SC interface, if not even
+     a generic USB CCID driver is used. You can use a tool like ``pcsc_scan -r`` to obtain a list of readers available on your system.
+
+     --pcsc-shared         Open PC/SC reaer in SHARED access (default: EXCLUSIVE) (default: False)
+     -p, --pcsc-device PCSC
+                           Number of PC/SC reader to use for SIM access (default: None)
+     --pcsc-regex REGEX    Regex matching PC/SC reader to use for SIM access (default: None)
+     ...
+
+
+From the output the card holder learns that there is an `--uri` parameter and
+that the same PC/SC options like in `pySim-shell.py` are supported. There is
+also a `--ca-cert` parameter where a CA certificate can be supplied in case the
+`RCP Server` uses a self-signed CA (which applies to this example)
+
+The second script `run_rcp_client_help_cmd.sh` assumes that the card holder now
+knows that the minimum required parameters are the `--uri` of the `RCP Server`,
+the `--ca-cert` of the `RCP Server` and `-p` to tell the `RCP Client` which PC/SC
+reader to use.
+
+::
+
+   $ ./run_rcp_client_help_cmd.sh
+   + PYTHONPATH=../../../
+   + ../../..//contrib/rcp/rcp_client.py --uri wss://127.0.0.1:8000 --ca-cert ./certs/example_ssl_rcp_ca_cert.crt -p 0 -h
+   INFO: loading SSL/TLS CA certificate (RCP Server CA): ./certs/example_ssl_rcp_ca_cert.crt
+   INFO: Using reader PCSC[Alcor Micro AU9540 00 00]
+   INFO: Detected Card with ATR: 3B9F96801F878031E073FE211B674A357530350265F8
+   INFO: RCP Server URI: wss://127.0.0.1:8000
+   INFO: Checking version ...
+   INFO: RCP Client version: software=1.0.0, protocol=1.0.0
+   INFO: RCP Server version: software=1.0.0, protocol=1.0.0
+   INFO: Requesting module descriptions from RCP Server ...
+   usage: rcp_client.py [-h] [-d DEV] [-b BAUD] [--pcsc-shared] [-p PCSC | --pcsc-regex REGEX] [--modem-device DEV] [--modem-baud BAUD] [--osmocon PATH]
+                     [--apdu-trace] [--verbose] [--uri URI] [--ca-cert CA_CERT]
+                     {rcp_module_reset,rcp_module_read_binary,rcp_module_read_record,rcp_module_unlock_aram} ...
+
+   RCP Client
+
+   positional arguments:
+     {rcp_module_reset,rcp_module_read_binary,rcp_module_read_record,rcp_module_unlock_aram}
+                           RCP command to use
+       rcp_module_reset    reset the card
+       rcp_module_read_binary
+                           read binary data from a transparent file.
+       rcp_module_read_record
+                           read binary data from a transparent file.
+       rcp_module_unlock_aram
+                           unlock a locked ARA-M applet on a sysmoISIM-SJA5
+   ...
+
+The help screen now shows additional positional arguments. Those positional
+arguments are the commands which the card holder can use to request a
+procedure. In this example we have four procedures we can call:
+`rcp_module_reset`, `rcp_module_read_binary`, `rcp_module_read_record`,
+and `rcp_module_unlock_aram`
+
+In the log output above the help screen, we can also see that a connection was
+made and that the `RCP Client` has requested module descriptions from the
+server. The `RCP Client` has sent the ATR of the card to the `RCP Server`. The
+`RCP Server` has used this information to look through its internal list to
+find modules which offer procedures suitable for this specific card.
+
+The card holder now knows which commands or procedures are available, but he
+still does not know if arguments are required and what those arguments are.
+The third script `run_rcp_client_help_cmd_specific.sh` shows how the card
+holder can request a dedicated help-screen for each of the commands.
+
+::
+
+   $ ./run_rcp_client_help_cmd_specific.sh
+   ...
+   + PYTHONPATH=../../../
+   + ../../..//contrib/rcp/rcp_client.py --uri wss://127.0.0.1:8000 --ca-cert ./certs/example_ssl_rcp_ca_cert.crt -p 0 rcp_module_read_record --help
+   INFO: loading SSL/TLS CA certificate (RCP Server CA): ./certs/example_ssl_rcp_ca_cert.crt
+   INFO: Using reader PCSC[Alcor Micro AU9540 00 00]
+   INFO: Detected Card with ATR: 3B9F96801F878031E073FE211B674A357530350265F8
+   INFO: RCP Server URI: wss://127.0.0.1:8000
+   INFO: Checking version ...
+   INFO: RCP Client version: software=1.0.0, protocol=1.0.0
+   INFO: RCP Server version: software=1.0.0, protocol=1.0.0
+   INFO: Requesting module descriptions from RCP Server ...
+   usage: rcp_client.py rcp_module_read_record [-h] --fid FID --record RECORD
+
+   options:
+     -h, --help       show this help message and exit
+     --fid FID        File identifier to of the file to read
+     --record RECORD  File record to read
+   ...
+
+We can see in the log that the `RCP Client` again sends a request to the
+`RCP Server` and retrieves the `RCP Module` descriptions. Then a dedicated
+help-screen for the `rcp_module_read_record` command is displayed. Now the card
+holder knows which parameters are required to perform the related procedure.
+
+Until this point there was only interaction with the `RCP Client` and the
+`RCP Server`. The `RCP Module` has not seen any requests yet. The provided
+script `run_rcp_client_cmd.sh` illustrates how the card holder can run an
+command that performs an actual procedure with the `RCP Module`.
+
+::
+
+   $ ./run_rcp_client_cmd.sh
+   ...
+   + PYTHONPATH=../../../
+   + ../../..//contrib/rcp/rcp_client.py --uri wss://127.0.0.1:8000 --ca-cert ./certs/example_ssl_rcp_ca_cert.crt -p 0 rcp_module_read_record --fid 3f00 --fid 2f00 --record 1
+   INFO: loading SSL/TLS CA certificate (RCP Server CA): ./certs/example_ssl_rcp_ca_cert.crt
+   INFO: Using reader PCSC[Alcor Micro AU9540 00 00]
+   INFO: Detected Card with ATR: 3B9F96801F878031E073FE211B674A357530350265F8
+   INFO: RCP Server URI: wss://127.0.0.1:8000
+   INFO: Checking version ...
+   INFO: RCP Client version: software=1.0.0, protocol=1.0.0
+   INFO: RCP Server version: software=1.0.0, protocol=1.0.0
+   INFO: Requesting module descriptions from RCP Server ...
+   INFO: Executing command with RCP Server ...
+   INFO: RcpcCltConnHdlr(140335960510480) -- reading linear-fixed file: ['3f00', '2f00'] ...
+   INFO: RcpcCltConnHdlr(140335960510480) -- file content is: 61294F10A0000000871002FFFFFFFF890709000050055553696D31730EA00C80011781025F608203454150
+   INFO: Command execution done, rc: 0
+
+The example reads record 1 from the file ``3F00/2F00`` and returns the file
+content. We also can see by the return code that the procedure was successful.
+The return code is also passed to `sys.exit()`, so that the card holder can
+use it in a script.
+
+The APDUs required to perform this action were entirely generated under the
+control of the `RCP Module`. In the log of the `RCP Server` we can see which
+command was executed on which `RCP Module` was used. We also see the return
+code here as well.
+
+::
+
+   ...
+   INFO: RcpcSrvConnHdlr(140093766623552) -- executing procedure for command "rcp_module_read_record" on module "rcp_module" at: wss://127.0.0.1:8020
+   INFO: RcpcSrvConnHdlr(140093766623552) -- command execution done, rc: 0
+   ...
+
+In the log of the `RCP Module` we can follow up on how the procedure was
+carried out.
+
+::
+
+   ...
+   INFO: RcpmCmdSrvConnHdlr(140156091028880) -- executing command: rcp_module_read_record ['--fid', '3f00', '--fid', '2f00', '--record', '1']
+   INFO: Waiting for card...
+   INFO: Card is of type: UICC
+   INFO: Detected UICC Add-on "SIM"
+   INFO: Detected UICC Add-on "GSM-R"
+   INFO: Detected UICC Add-on "RUIM"
+   WARNING: EF.DIR seems to be empty!
+   INFO:  ADF.ISD: a000000003000000
+   INFO:  ARA-M: a00000015141434c00
+   INFO:  ISIM: a0000000871004
+   INFO:  USIM: a0000000871002
+   INFO: Detected CardModel: SysmocomSJA5
+   INFO: RcpmCmdSrvConnHdlr(140156091028880) -- reading linear-fixed file: ['3f00', '2f00'] ...
+   INFO: RcpmCmdSrvConnHdlr(140156091028880) -- file content is: 61294F10A0000000871002FFFFFFFF890709000050055553696D31730EA00C80011781025F608203454150
+   INFO: RcpmCmdSrvConnHdlr(140156091028880) -- command execution done, rc: 0
+   ...
+
+In first line we see the command and its parameters. The lines that follow will
+look familiar to `pySim-shell` users. The last three log lines carry the print
+statements which we also see in the log messages on the `RCP Client`. The last
+line informs about the conclusion of the procedure and also shows the return
+code.
+
+
+Implementing an RCP Module
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To make use of the Remote Card Procedure Framework, it is eventually necessary
+to implement a custom `RCP Module`. In the following section, we will go
+through the implementation of the `RCP Module` that is provided with the
+`usage_example`.
+
+NOTE: much of the following is explained in greater detail in the comments
+found in `rcp_module_utils.py`.
+
+Overview
+~~~~~~~~
+
+`RCP Modules` are normal python programs that can started directly from the
+command prompt. However, due to the location of the file it is necessary that
+`PYTHONPATH` points to the location of the `pySim` modules as well as to the
+modules found in `contrib/rcp` (see `start_rcp_module.sh` for reference).
+
+As mentioned earlier `RCP Modules` may use the `pySim` API like any other
+`pySim` program, given that there is no dependency to `cmd2`. So it is no
+surprise that we find some `pySim` modules in the import section of the
+provided example.
+
+The utilities required to implement an `RCP Module` are imported from
+`rcp_module_utils.py`. From this module we import two functions
+`rcpm_setup_argparse` and `rcpm_run_module` and the two classes `RCP Module`
+and `RcpModuleHdlr`.
+
+Function: rcpm_setup_argparse
+------------------------------
+
+The first function `rcpm_setup_argparse` returns an argument parser that is already
+equipped with the basic commandline arguments that an `RCP Module` needs. In
+case the specific `RCP Module` implementation requires additional arguments,
+those can be added using normal `argparse` API calls.
+
+Function: rcpm_run_module
+-------------------------
+
+The second function `rcpm_run_module` is used to run the `RCP Module`. This
+function gets the parsed commandline options (`opts`) and the `RcpModule` class
+(`module`) as parameters. In addition to that, `rcpm_run_module` also accepts
+custom `*args` and `**kwargs` arguments, which are passed to the constructor of
+the `RcpModule` class.
+
+When `rcpm_run_module` is called. It registers the `RCP Module` and starts the
+RCP Client command server. It also takes care of the proper instantiation of the
+`RcpModule` class, which were passed with the `module` parameter.
+
+Class: RcpModule
+----------------
+
+The Class `RcpModule` is the base class that is used to create a concrete
+`RCP Module` implementaion. Through this class, the API user defines the
+properties of the `RCP Module` as well as the command methods, which implement
+the related `Remote Card Procedures`.
+
+Class: RcpModuleHdlr
+--------------------
+
+The class `RcpModuleHdlr` is used by the framework to instantiate a handler
+object (`hdlr`), which is passed to each of the aforementioned command methods.
+The handler object is used as a vehicle to provide access the resources we need
+to send APDUs, print messages on the `RCP Client`, etc.
+
+Module Properties
+~~~~~~~~~~~~~~~~~
+
+Before we can define any module properties, we first need to create a derived
+class from the `RcpModule` class we have imported from `rcp_module_utils.py`.
+In that class, we then define the basic properties of the `RCP Module`.
+
+name
+----
+
+Each `RCP Module` needs a distinct name. The name must not collide with the
+names of other `RCP Modules`. The name uniquely identifies the `RCP Module` and
+is used as a prefix for the command names used with the user interface of the
+`RCP Client`. Therefore a short name is desirable.
+
+cmd_descr
+---------
+
+The `cmd_descr` property defines the command properties. Since an `RCP Module`
+may offer multiple commands (procedures), this property is an array, where
+each item holds the definition for one specific command.
+
+The command definitions are formatted as a python dict. Like the `RCP Module`
+itself, each command has a `name`. As mentioned before. This name is concatenated
+with the name of the `RCP Module`.
+
+Each command definition also gets a `help` string. The help string will show up
+in the commandline help of the `RCP Client`. It should be short and concise.
+
+Command definitions also need to define commandline arguments. For this an
+`args` array is added to the command definition as well. In case no arguments
+are provided. The array is empty. Otherwise it will contain one or more dict
+members, where each specifies a `name` and a `spec`. The `name` sets the
+argument name (e.g. --fid), and the `spec` specifies the properties of the
+argument. The concept is borrowed from `argparse` and works very similar. API
+users can specify `required`, `help`, `default` and a type. However, to avoid
+name-space collisions, the type field is called `pytype` and the type identifier
+must be passed as a string (e.g. 'int').
+
+In case a procedure requires key material from the `CardKeyProvider`, the API
+user may add a `get_keys` field to the command definition. In case eUICC keys
+are needed. The API user will add a dict member with key `euicc` and populate
+the value with an array that holds the column names of the columns where the
+keys are found. The same also works for UICC keys by using 'uicc' as dict key.
+When `get_keys` is correctly populated and the correct column keys are supplied
+to the `RCP Module` at runtime. The `RCP Framework` will automatically retrieve
+the key material, decrypt it and make it available to the related command
+method.
+
+suitable_for
+------------
+
+`suitable_for` is the third and last property, the API user must define. This
+property holds an array where each member is a dict that defines a distinct
+property of the card for which the module is suitable for. The `RCP Server`
+uses this information to see which modules are suitable for a specific request.
+As of now, the only property we can use to make the distinction, is the ATR of
+the card.
+
+custom resources
+----------------
+
+In case an RCP Module requires custom resources, those may be initialized using
+a custom constructor in the derived class. This constructor receives the
+`*args` and `**kwargs` arguments passed to `rcpm_run_module`. However, this is
+an optional step. In case no constructor is defined, the default constructor
+is used.
+
+In addition to that, the API user may also define additional properties and
+methods, provided they do not collide with existing methods of the base class
+`RcpModule`.
+
+Command Methods
+~~~~~~~~~~~~~~~
+
+Command methods are essentially normal python methods. However, since those
+methods are called by the `RCP Framework`, they must follow a distinct scheme,
+which we will go through in the following.
+
+Each command defined in `cmd_descr` requires a corresponding command method. A
+command method is always prefixed with `cmd_`. Then the exact name of the
+command follows as defined in `cmd_descr`. For example if we have defined a
+command with the name `read_record`, we must also define a method with the name
+`cmd_read_record`.
+
+The parameter list of a command method always contains only `self` and `hdlr`.
+The `hdlr` parameter is the handler object (`RcpModuleHdlr`) through which we
+access the resources provided by the `RCP Framework`.
+
+Inside a command method, the API user is free to perform any task he wants.
+Command Methods always run in a dedicated thread and may sleep or wait at any
+time without disturbing running procedures from other requestors.
+
+A command method should always return an integer as return code. In case the
+procedure ends successfully, the return code shall be `0`. The return code is
+passed through to the `RCP Client`, which returns it on exit to the operating
+system
+
+
+Handler Resources
+~~~~~~~~~~~~~~~~~
+
+As mentioned earlier, a commend method receives a handler object via
+the `hdlr` parameter. This object is of type `RcpModuleHdlr` and vaguely
+comparable to the `app` (`PysimApp`) object found in `pySim-shell.py`.
+
+The handler object provides the command method with the resources it needs to
+perform the card procedure.
+
+rs, card, lchan
+---------------
+
+The Runtime State (`rs`), the Card (`card`)  and the Lchan (`lchan`) Object
+have the same objectives asn in `pySim-shell.py`. Those objects work and are
+used the same way as they would in `pySim-shell.py`. It is assumed that the
+API user is already familiar with those objects.
+
+cmd_args
+--------
+
+The command arguments (`cmd_args`) contains the command line arguments as they
+were passed by the card holder on the `RCP Client` commandline in the form of
+a `Namespace` object.
+
+Even though the command arguments are syntax-checked against the `args`
+description given in `cmd_descr`, caution is required to avoid security
+problems arising from malicious input.
+
+keys_uicc and keys_euicc
+------------------------
+
+In case key material was requested via the `get_keys` in `cmd_descr`,
+`keys_uicc` and `keys_euicc` will contain those keys in the form of a dict. The
+dict key is the is the `CardKeyProvider` column name and the related dict value
+is the key material in its decrypted form.
+
+When accessing `keys_uicc` and `keys_euicc`, extra care should be taken. It may
+make sense to delete/overwrite those dictionaries as soon as the keys were used
+for the intended purpose. However, due to python's internal memory management
+key material may remain longer in the system memory as expected.
+
+print
+-----
+
+The `hdlr` object also provides a `print` method. This method accepts a string
+as the only parameter and can be used to display custom messages in the log
+output of the `RCP Client`. The method can be used to inform the card holder
+about the progress of a procedure or to print error messages in case a
+procedure fails.

pySim-shell.py

@@ -24,21 +24,21 @@ import traceback
 import re
 import cmd2
 from packaging import version
+from cmd2 import style
+
 import logging
 from pySim.log import PySimLogger
 from osmocom.utils import auto_uint8
 
-# cmd2 >= 3.0 replaced Fg + style() with Color + stylize()
-if version.parse(cmd2.__version__) >= version.parse("3.0.0"):
-    from cmd2 import Color, stylize # pylint: disable=no-name-in-module
-    RED = Color.RED
-    YELLOW = Color.YELLOW
-    LIGHT_RED = Color.BRIGHT_RED
-    LIGHT_GREEN = Color.BRIGHT_GREEN
-    def style(text, fg=None, bg=None, bold=False): # pylint: disable=function-redefined
-        return stylize(text, fg) if fg else text
+# cmd2 >= 2.3.0 has deprecated the bg/fg in favor of Bg/Fg :(
+if version.parse(cmd2.__version__) < version.parse("2.3.0"):
+    from cmd2 import fg, bg # pylint: disable=no-name-in-module
+    RED = fg.red
+    YELLOW = fg.yellow
+    LIGHT_RED = fg.bright_red
+    LIGHT_GREEN = fg.bright_green
 else:
-    from cmd2 import style, Fg # pylint: disable=no-name-in-module
+    from cmd2 import Fg, Bg # pylint: disable=no-name-in-module
     RED = Fg.RED
     YELLOW = Fg.YELLOW
     LIGHT_RED = Fg.LIGHT_RED
@@ -76,19 +76,43 @@ from pySim.app import init_card
 
 log = PySimLogger.get(Path(__file__).stem)
 
-class PysimApp(cmd2.Cmd):
+class Cmd2Compat(cmd2.Cmd):
+    """Backwards-compatibility wrapper around cmd2.Cmd to support older and newer
+    releases. See https://github.com/python-cmd2/cmd2/blob/master/CHANGELOG.md"""
+    def run_editor(self, file_path: Optional[str] = None) -> None:
+        if version.parse(cmd2.__version__) < version.parse("2.0.0"):
+            return self._run_editor(file_path) # pylint: disable=no-member
+        else:
+            return super().run_editor(file_path) # pylint: disable=no-member
+
+class Settable2Compat(cmd2.Settable):
+    """Backwards-compatibility wrapper around cmd2.Settable to support older and newer
+    releases. See https://github.com/python-cmd2/cmd2/blob/master/CHANGELOG.md"""
+    def __init__(self, name, val_type, description, settable_object, **kwargs):
+        if version.parse(cmd2.__version__) < version.parse("2.0.0"):
+            super().__init__(name, val_type, description, **kwargs) # pylint: disable=no-value-for-parameter
+        else:
+            super().__init__(name, val_type, description, settable_object, **kwargs) # pylint: disable=too-many-function-args
+
+class PysimApp(Cmd2Compat):
     CUSTOM_CATEGORY = 'pySim Commands'
     BANNER = """Welcome to pySim-shell!
 (C) 2021-2023 by Harald Welte, sysmocom - s.f.m.c. GmbH and contributors
 Online manual available at https://downloads.osmocom.org/docs/pysim/master/html/shell.html """
 
     def __init__(self, verbose, card, rs, sl, ch, script=None):
+        if version.parse(cmd2.__version__) < version.parse("2.0.0"):
+            kwargs = {'use_ipython': True}
+        else:
+            kwargs = {'include_ipy': True}
+
         self.verbose = verbose
         PySimLogger.setup(self.poutput, {logging.WARN: YELLOW})
         self._onchange_verbose('verbose', False, self.verbose)
 
+        # pylint: disable=unexpected-keyword-arg
         super().__init__(persistent_history_file='~/.pysim_shell_history', allow_cli_args=False,
-                         auto_load_commands=False, startup_script=script, include_ipy=True)
+                         auto_load_commands=False, startup_script=script, **kwargs)
         self.intro = style(self.BANNER, fg=RED)
         self.default_category = 'pySim-shell built-in commands'
         self.card = None
@@ -104,24 +128,18 @@ Online manual available at https://downloads.osmocom.org/docs/pysim/master/html/
         self.apdu_trace = False
         self.apdu_strict = False
 
-        self.add_settable(cmd2.Settable('numeric_path', bool,
-                                        'Print File IDs instead of names',
-                                        self, onchange_cb=self._onchange_numeric_path))
-        self.add_settable(cmd2.Settable('conserve_write', bool,
-                                        'Read and compare before write',
-                                        self, onchange_cb=self._onchange_conserve_write))
-        self.add_settable(cmd2.Settable('json_pretty_print', bool,
-                                        'Pretty-Print JSON output',
-                                        self))
-        self.add_settable(cmd2.Settable('apdu_trace', bool,
-                                        'Trace and display APDUs exchanged with card',
-                                        self, onchange_cb=self._onchange_apdu_trace))
-        self.add_settable(cmd2.Settable('apdu_strict', bool,
-                                        'Strictly apply APDU format according to ISO/IEC 7816-3, table 12',
-                                        self))
-        self.add_settable(cmd2.Settable('verbose', bool,
-                                        'Enable/disable verbose logging',
-                                        self, onchange_cb=self._onchange_verbose))
+        self.add_settable(Settable2Compat('numeric_path', bool, 'Print File IDs instead of names', self,
+                                          onchange_cb=self._onchange_numeric_path))
+        self.add_settable(Settable2Compat('conserve_write', bool, 'Read and compare before write', self,
+                                          onchange_cb=self._onchange_conserve_write))
+        self.add_settable(Settable2Compat('json_pretty_print', bool, 'Pretty-Print JSON output', self))
+        self.add_settable(Settable2Compat('apdu_trace', bool, 'Trace and display APDUs exchanged with card', self,
+                                          onchange_cb=self._onchange_apdu_trace))
+        self.add_settable(Settable2Compat('apdu_strict', bool,
+                                          'Strictly apply APDU format according to ISO/IEC 7816-3, table 12', self))
+        self.add_settable(Settable2Compat('verbose', bool,
+                                          'Enable/disable verbose logging', self,
+                                          onchange_cb=self._onchange_verbose))
         self.equip(card, rs)
 
     def equip(self, card, rs):

pySim/ara_m.py

@@ -300,6 +300,51 @@ class ADF_ARAM(CardADF):
                                'major': v_major, 'minor': v_minor, 'patch': v_patch}}])
         return ADF_ARAM.xceive_apdu_tlv(scc, '80cadf21', cmd_do, ResponseAramConfigDO)
 
+    @staticmethod
+    def store_ref_ar_do(scc, aid:Hexstr, aid_empty:bool, device_app_id:Hexstr, pkg_ref:str,
+                        apdu_filter:Hexstr, apdu_never:bool, apdu_always:bool,
+                        nfc_always:bool, nfc_never:bool, android_permissions:Hexstr):
+        # REF
+        ref_do_content = []
+        if aid is not None:
+            ref_do_content += [{'aid_ref_do': aid}]
+        elif aid_empty:
+            ref_do_content += [{'aid_ref_empty_do': None}]
+        ref_do_content += [{'dev_app_id_ref_do': device_app_id}]
+        if pkg_ref:
+            ref_do_content += [{'pkg_ref_do': {'package_name_string': pkg_ref}}]
+        # AR
+        ar_do_content = []
+        if apdu_never:
+            ar_do_content += [{'apdu_ar_do': {'generic_access_rule': 'never'}}]
+        elif apdu_always:
+            ar_do_content += [{'apdu_ar_do': {'generic_access_rule': 'always'}}]
+        elif apdu_filter:
+            if len(apdu_filter) % 16:
+                raise ValueError(f'Invalid non-modulo-16 length of APDU filter: {len(apdu_filter)}')
+            offset = 0
+            apdu_filter_list = []
+            while offset < len(apdu_filter):
+                apdu_filter_list += [{'header': apdu_filter[offset:offset+8],
+                                      'mask': 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_list}}]
+        if nfc_never:
+            ar_do_content += [{'nfc_ar_do': {'nfc_event_access_rule': 'never'}}]
+        elif nfc_always:
+            ar_do_content += [{'nfc_ar_do': {'nfc_event_access_rule': 'always'}}]
+        if android_permissions:
+            ar_do_content += [{'perm_ar_do': {'permissions': android_permissions}}]
+        d = [{'ref_ar_do': [{'ref_do': ref_do_content}, {'ar_do': ar_do_content}]}]
+        csrado = CommandStoreRefArDO()
+        csrado.from_val_dict(d)
+        return ADF_ARAM.store_data(scc, csrado)
+
+    @staticmethod
+    def aram_delete_all(scc):
+        deldo = CommandDelete()
+        return ADF_ARAM.store_data(scc, deldo)
+
     @with_default_category('Application-Specific Commands')
     class AddlShellCommands(CommandSet):
         def do_aram_get_all(self, _opts):
@@ -344,48 +389,15 @@ class ADF_ARAM(CardADF):
         @cmd2.with_argparser(store_ref_ar_do_parse)
         def do_aram_store_ref_ar_do(self, opts):
             """Perform STORE DATA [Command-Store-REF-AR-DO] to store a (new) access rule."""
-            # REF
-            ref_do_content = []
-            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}]
-            ref_do_content += [{'dev_app_id_ref_do': opts.device_app_id}]
-            if opts.pkg_ref:
-                ref_do_content += [{'pkg_ref_do': {'package_name_string': opts.pkg_ref}}]
-            # AR
-            ar_do_content = []
-            if opts.apdu_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:
-                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:
-                ar_do_content += [{'nfc_ar_do': {'nfc_event_access_rule': 'never'}}]
-            if opts.android_permissions:
-                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_val_dict(d)
-            res_do = ADF_ARAM.store_data(self._cmd.lchan.scc, csrado)
+            res_do = ADF_ARAM.store_ref_ar_do(self._cmd.lchan.scc, opts.aid, opts.aid_empty, opts.device_app_id,
+                                              opts.pkg_ref, opts.apdu_filter, opts.apdu_never, opts.apdu_always,
+                                              opts.nfc_always, opts.nfc_never, opts.android_permissions)
             if res_do:
                 self._cmd.poutput_json(res_do.to_dict())
 
         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, deldo)
+            res_do = ADF_ARAM.aram_delete_all(self._cmd.lchan.scc)
             if res_do:
                 self._cmd.poutput_json(res_do.to_dict())
 
@@ -394,7 +406,6 @@ class ADF_ARAM(CardADF):
             (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': {

pySim/esim/saip/batch.py

@@ -19,16 +19,10 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 import copy
-import pprint
-from typing import Generator, Union
+from typing import Generator
 from pySim.esim.saip.personalization import ConfigurableParameter
 from pySim.esim.saip import param_source
-from pySim.esim.saip import ProfileElementSequence, ProfileElementSD
-from pySim.global_platform import KeyUsageQualifier
-from osmocom.utils import b2h
-
-# a list of ConfigurableParameter classes and/or ConfigurableParameter class instances
-ParamList = list[Union[type[ConfigurableParameter], ConfigurableParameter]]
+from pySim.esim.saip import ProfileElementSequence
 
 class BatchPersonalization:
     """Produce a series of eSIM profiles from predefined parameters.
@@ -124,237 +118,3 @@ class BatchPersonalization:
                     raise ValueError(f'{p.param_cls.get_name()} fed by {p.src.name}: {e}') from e
 
             yield pes
-
-
-class UppAudit(dict):
-    """
-    Key-value pairs collected from a single UPP DER or PES.
-
-    UppAudit itself is a dict, callers may use the standard python dict API to access key-value pairs read from the UPP.
-    """
-
-    @classmethod
-    def from_der(cls, der: bytes, params: ParamList, der_size=False, additional_sd_keys=False):
-        """return a dict of parameter name and set of selected parameter values found in a DER encoded profile. Note:
-        some ConfigurableParameter implementations return more than one key-value pair, for example, Imsi returns
-        both 'IMSI' and 'IMSI-ACC' parameters.
-
-        e.g.
-            UppAudit.from_der(my_der, [Imsi, ])
-            --> {'IMSI': {'001010000000023'}, 'IMSI-ACC': {'5'}}
-
-        (where 'IMSI' == Imsi.name)
-
-        Read all parameters listed in params. params is a list of either ConfigurableParameter classes or
-        ConfigurableParameter class instances. This calls only classmethods, so each entry in params can either be the
-        class itself, or a class-instance of, a (non-abstract) ConfigurableParameter subclass.
-        For example, params = [Imsi, ] is equivalent to params = [Imsi(), ].
-
-        For der_size=True, also include a {'der_size':12345} entry.
-
-        For additional_sd_keys=True, output also all Security Domain KVN that there are *no* ConfigurableParameter
-        subclasses for. For example, SCP80 has reserved kvn 0x01..0x0f, but we offer only Scp80Kvn01, Scp80Kvn02,
-        Scp80Kvn03. So we would not show kvn 0x04..0x0f in an audit. additional_sd_keys=True includes audits of all SD
-        key KVN there may be in the UPP. This helps to spot SD keys that may already be present in a UPP template, with
-        unexpected / unusual kvn.
-        """
-
-        # make an instance of this class
-        upp_audit = cls()
-
-        if der_size:
-            upp_audit['der_size'] = set((len(der), ))
-
-        pes = ProfileElementSequence.from_der(der)
-        for param in params:
-            try:
-                for valdict in param.get_values_from_pes(pes):
-                    upp_audit.add_values(valdict)
-            except Exception as e:
-                raise ValueError(f'Error during audit for parameter {param}: {e}') from e
-
-        if not additional_sd_keys:
-            return upp_audit
-
-        # additional_sd_keys
-        for pe in pes.pe_list:
-            if pe.type != 'securityDomain':
-                continue
-            assert isinstance(pe, ProfileElementSD)
-
-            for key in pe.keys:
-                audit_key = f'SdKey_KVN{key.key_version_number:02x}_ID{key.key_identifier:02x}'
-                kuq_bin = KeyUsageQualifier.build(key.key_usage_qualifier).hex()
-                audit_val = f'{key.key_components=!r} key_usage_qualifier=0x{kuq_bin}={key.key_usage_qualifier!r}'
-                upp_audit.add_values({audit_key: audit_val})
-
-        return upp_audit
-
-    def get_single_val(self, key, allow_absent=False, absent_val=None):
-        """
-        Return the audit's value for the given audit key (like 'IMSI' or 'IMSI-ACC').
-        Any kind of value may occur multiple times in a profile. When all of these agree to the same unambiguous value,
-        return that value. When they do not agree, raise a ValueError.
-        """
-        # key should be a string, but if someone passes a ConfigurableParameter, just use its default name
-        if ConfigurableParameter.is_super_of(key):
-            key = key.get_name()
-
-        assert isinstance(key, str)
-        v = self.get(key)
-        if v is None and allow_absent:
-            return absent_val
-        if not isinstance(v, set):
-            raise ValueError(f'audit value should be a set(), got {v!r}')
-        if len(v) != 1:
-            raise ValueError(f'expected a single value for {key}, got {v!r}')
-        v = tuple(v)[0]
-        return v
-
-    @staticmethod
-    def audit_val_to_str(v):
-        """
-        Usually, we want to see a single value in an audit. Still, to be able to collect multiple ambiguous values,
-        audit values are always python sets. Turn it into a nice string representation: only the value when it is
-        unambiguous, otherwise a list of the ambiguous values.
-        A value may also be completely absent, then return 'not present'.
-        """
-        def try_single_val(w):
-            'change single-entry sets to just the single value'
-            if isinstance(w, set):
-                if len(w) == 1:
-                    return tuple(w)[0]
-                if len(w) == 0:
-                    return None
-            return w
-
-        v = try_single_val(v)
-        if isinstance(v, bytes):
-            v = b2h(v)
-        if v is None:
-            return 'not present'
-        return str(v)
-
-    def get_val_str(self, key):
-        """Return a string of the value stored for the given key"""
-        return UppAudit.audit_val_to_str(self.get(key))
-
-    def add_values(self, src:dict):
-        """Merge a plain dict of values into self, which is a dict of sets.
-        For example from
-            self == { 'a': {123} }
-        and
-            src == { 'a': 456, 'b': 789 }
-        then after this function call:
-            self == { 'a': {123, 456}, 'b': {789} }
-        """
-        assert isinstance(src, dict)
-        for key, srcval in src.items():
-            dstvalset = self.get(key)
-            if dstvalset is None:
-                dstvalset = set()
-                self[key] = dstvalset
-            dstvalset.add(srcval)
-
-    def __str__(self):
-        return '\n'.join(f'{key}: {self.get_val_str(key)}' for key in sorted(self.keys()))
-
-class BatchAudit(list):
-    """
-    Collect UppAudit instances for a batch of UPP, for example from a personalization.BatchPersonalization.
-    Produce an output CSV.
-
-    Usage example:
-
-        ba = BatchAudit(params=(personalization.Iccid, ))
-        for upp_der in upps:
-            ba.add_audit(upp_der)
-        print(ba.summarize())
-
-        with open('output.csv', 'wb') as csv_data:
-            csv_str = io.TextIOWrapper(csv_data, 'utf-8', newline='')
-            csv.writer(csv_str).writerows( ba.to_csv_rows() )
-            csv_str.flush()
-
-    BatchAudit itself is a list, callers may use the standard python list API to access the UppAudit instances.
-    """
-
-    def __init__(self, params: ParamList):
-        assert params
-        self.params = params
-
-    def add_audit(self, upp_der:bytes):
-        audit = UppAudit.from_der(upp_der, self.params)
-        self.append(audit)
-        return audit
-
-    def summarize(self):
-        batch_audit = UppAudit()
-
-        audits = self
-
-        if len(audits) > 2:
-            val_sep = ', ..., '
-        else:
-            val_sep = ', '
-
-        first_audit = None
-        last_audit = None
-        if len(audits) >= 1:
-            first_audit = audits[0]
-        if len(audits) >= 2:
-            last_audit = audits[-1]
-
-        if first_audit:
-            if last_audit:
-                for key in first_audit.keys():
-                    first_val = first_audit.get_val_str(key)
-                    last_val = last_audit.get_val_str(key)
-
-                    if first_val == last_val:
-                        val = first_val
-                    else:
-                        val_sep_with_newline = f"{val_sep.rstrip()}\n{' ' * (len(key) + 2)}"
-                        val = val_sep_with_newline.join((first_val, last_val))
-                    batch_audit[key] = val
-            else:
-                batch_audit.update(first_audit)
-
-        return batch_audit
-
-    def to_csv_rows(self, headers=True, sort_key=None):
-        """generator that yields all audits' values as rows, useful feed to a csv.writer."""
-        columns = set()
-        for audit in self:
-            columns.update(audit.keys())
-
-        columns = tuple(sorted(columns, key=sort_key))
-
-        if headers:
-            yield columns
-
-        for audit in self:
-            yield (audit.get_single_val(col, allow_absent=True, absent_val="") for col in columns)
-
-def esim_profile_introspect(upp):
-    pes = ProfileElementSequence.from_der(upp.read())
-    d = {}
-    d['upp'] = repr(pes)
-
-    def show_bytes_as_hexdump(item):
-        if isinstance(item, bytes):
-            return b2h(item)
-        if isinstance(item, list):
-            return list(show_bytes_as_hexdump(i) for i in item)
-        if isinstance(item, tuple):
-            return tuple(show_bytes_as_hexdump(i) for i in item)
-        if isinstance(item, dict):
-            d = {}
-            for k, v in item.items():
-                d[k] = show_bytes_as_hexdump(v)
-            return d
-        return item
-
-    l = list((pe.type, show_bytes_as_hexdump(pe.decoded)) for pe in pes)
-    d['pp'] = pprint.pformat(l, width=120)
-    return d

pySim/esim/saip/param_source.py

@@ -17,7 +17,7 @@
 # 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 secrets
+import random
 import re
 from osmocom.utils import b2h
 
@@ -123,30 +123,19 @@ class DecimalRangeSource(InputExpandingParamSource):
     def val_to_digit(self, val:int):
         return "%0*d" % (self.num_digits, val)  # pylint: disable=consider-using-f-string
 
-class RandomSourceMixin:
-    random_impl = secrets.SystemRandom()
-
-class RandomDigitSource(DecimalRangeSource, RandomSourceMixin):
+class RandomDigitSource(DecimalRangeSource):
     """return a different sequence of random decimal digits each"""
     name = "random decimal digits"
 
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self.used_keys = set()
-
     def get_next(self, csv_row:dict=None):
-        # try to generate random digits that are always different from previously produced random digits
-        for _ in range(10):
-            val = self.random_impl.randint(self.first_value, self.last_value)
-            if val not in self.used_keys:
-                break
-        self.used_keys.add(val)
+        val = random.randint(self.first_value, self.last_value) # TODO secure random source?
         return self.val_to_digit(val)
 
-class RandomHexDigitSource(InputExpandingParamSource, RandomSourceMixin):
+class RandomHexDigitSource(InputExpandingParamSource):
     """return a different sequence of random hexadecimal digits each"""
     name = "random hexadecimal digits"
     numeric_base = 16
+
     def __init__(self, input_str:str):
         super().__init__(input_str)
         input_str = self.input_str
@@ -158,16 +147,9 @@ class RandomHexDigitSource(InputExpandingParamSource, RandomSourceMixin):
         if (num_digits & 1) != 0:
             raise ValueError(f"hexadecimal value should have even number of digits, not {num_digits}")
         self.num_digits = num_digits
-        self.used_keys = set()
 
     def get_next(self, csv_row:dict=None):
-        # try to generate random bytes that are always different from previously produced random bytes
-        for _ in range(10):
-            val = self.random_impl.randbytes(self.num_digits // 2)
-            if val not in self.used_keys:
-                break
-        self.used_keys.add(val)
-
+        val = random.randbytes(self.num_digits // 2) # TODO secure random source?
         return b2h(val)
 
 class IncDigitSource(DecimalRangeSource):

pySim/esim/saip/personalization.py

@@ -52,6 +52,7 @@ class ClassVarMeta(abc.ABCMeta):
         x = super().__new__(metacls, name, bases, namespace)
         for k, v in kwargs.items():
             setattr(x, k, v)
+        setattr(x, 'name', camel_to_snake(name))
         return x
 
 class ConfigurableParameter(abc.ABC, metaclass=ClassVarMeta):
@@ -71,7 +72,6 @@ class ConfigurableParameter(abc.ABC, metaclass=ClassVarMeta):
     min_len: minimum length of an input str; min_len = 4
     max_len: maximum length of an input str; max_len = 8
     allow_len: permit only specific lengths; allow_len = (8, 16, 32)
-    numeric_base: indicate hex / decimal, if any; numeric_base = None; numeric_base = 10; numeric_base = 16
 
     Subclasses may change the meaning of these by overriding validate_val(), for example that the length counts
     resulting bytes instead of a hexstring length. Most subclasses will be covered by the default validate_val().
@@ -127,7 +127,6 @@ class ConfigurableParameter(abc.ABC, metaclass=ClassVarMeta):
     allow_len = None # a list of specific lengths
     example_input = None
     default_source = None # a param_source.ParamSource subclass
-    numeric_base = None # or 10 or 16
 
     def __init__(self, input_value=None):
         self.input_value = input_value # the raw input value as given by caller
@@ -189,28 +188,19 @@ class ConfigurableParameter(abc.ABC, metaclass=ClassVarMeta):
             if cls.allow_chars is not None:
                 if any(c not in cls.allow_chars for c in val):
                     raise ValueError(f"invalid characters in input value {val!r}, valid chars are {cls.allow_chars}")
-        elif isinstance(val, io.BytesIO):
-            val = val.getvalue()
-
-        if hasattr(val, '__len__'):
-            val_len = len(val)
-        else:
-            # e.g. int length
-            val_len = len(str(val))
-
         if cls.allow_len is not None:
             l = cls.allow_len
             # cls.allow_len could be one int, or a tuple of ints. Wrap a single int also in a tuple.
             if not isinstance(l, (tuple, list)):
                 l = (l,)
-            if val_len not in l:
-                raise ValueError(f'length must be one of {cls.allow_len}, not {val_len}: {val!r}')
+            if len(val) not in l:
+                raise ValueError(f'length must be one of {cls.allow_len}, not {len(val)}: {val!r}')
         if cls.min_len is not None:
-            if val_len < cls.min_len:
-                raise ValueError(f'length must be at least {cls.min_len}, not {val_len}: {val!r}')
+            if len(val) < cls.min_len:
+                raise ValueError(f'length must be at least {cls.min_len}, not {len(val)}: {val!r}')
         if cls.max_len is not None:
-            if val_len > cls.max_len:
-                raise ValueError(f'length must be at most {cls.max_len}, not {val_len}: {val!r}')
+            if len(val) > cls.max_len:
+                raise ValueError(f'length must be at most {cls.max_len}, not {len(val)}: {val!r}')
         return val
 
     @classmethod
@@ -219,26 +209,6 @@ class ConfigurableParameter(abc.ABC, metaclass=ClassVarMeta):
         Write the given val in the right format in all the right places in pes."""
         pass
 
-    @classmethod
-    def get_value_from_pes(cls, pes: ProfileElementSequence):
-        """Same as get_values_from_pes() but expecting a single value.
-           get_values_from_pes() may return values like this:
-             [{ 'AlgorithmID': 'Milenage' }, { 'AlgorithmID': 'Milenage' }]
-           This ensures that all these entries are identical and would return only
-              { 'AlgorithmID': 'Milenage' }.
-
-           This is relevant for any profile element that may appear multiple times in the same PES (only a few),
-           where each occurrence should reflect the same value (all currently known parameters).
-        """
-
-        val = None
-        for v in cls.get_values_from_pes(pes):
-            if val is None:
-                val = v
-            elif val != v:
-                raise ValueError(f'get_value_from_pes(): got distinct values: {val!r} != {v!r}')
-        return val
-
     @classmethod
     @abc.abstractmethod
     def get_values_from_pes(cls, pes: ProfileElementSequence) -> Generator:
@@ -290,20 +260,12 @@ class ConfigurableParameter(abc.ABC, metaclass=ClassVarMeta):
            '''
         return cls.get_len_range()[1] or 16
 
-    @classmethod
-    def is_super_of(cls, other_class):
-        try:
-            return issubclass(other_class, cls)
-        except TypeError:
-            return False
-
 class DecimalParam(ConfigurableParameter):
     """Decimal digits. The input value may be a string of decimal digits like '012345', or an int. The output of
     validate_val() is a string with only decimal digits 0-9, in the required length with leading zeros if necessary.
     """
     allow_types = (str, int)
     allow_chars = '0123456789'
-    numeric_base = 10
 
     @classmethod
     def validate_val(cls, val):
@@ -349,7 +311,6 @@ class DecimalHexParam(DecimalParam):
 class IntegerParam(ConfigurableParameter):
     allow_types = (str, int)
     allow_chars = '0123456789'
-    numeric_base = 10
 
     # two integers, if the resulting int should be range limited
     min_val = None
@@ -379,19 +340,14 @@ class IntegerParam(ConfigurableParameter):
             yield valdict
 
 class BinaryParam(ConfigurableParameter):
-    allow_types = (str, io.BytesIO, bytes, bytearray, int)
+    allow_types = (str, io.BytesIO, bytes, bytearray)
     allow_chars = '0123456789abcdefABCDEF'
     strip_chars = ' \t\r\n'
-    numeric_base = 16
     default_source = param_source.RandomHexDigitSource
 
     @classmethod
     def validate_val(cls, val):
         # take care that min_len and max_len are applied to the binary length by converting to bytes first
-        if isinstance(val, int):
-            min_len, _max_len = cls.get_len_range()
-            val = '%0*d' % (min_len, val)
-
         if isinstance(val, str):
             if cls.strip_chars is not None:
                 val = ''.join(c for c in val if c not in cls.strip_chars)
@@ -556,7 +512,6 @@ class SmspTpScAddr(ConfigurableParameter):
     name = 'SMSP-TP-SC-ADDR'
     allow_chars = '+0123456789'
     strip_chars = ' \t\r\n'
-    numeric_base = 10
     max_len = 21 # '+' and 20 digits
     min_len = 1
     example_input = '+49301234567'
@@ -618,28 +573,10 @@ class SmspTpScAddr(ConfigurableParameter):
             ef_smsp_dec['tp_sc_addr']['ton_npi']['type_of_number'] = 'international' if international else 'unknown'
             # ensure the parameter_indicators.tp_sc_addr is True
             ef_smsp_dec['parameter_indicators']['tp_sc_addr'] = True
-
-            # alpha_id padding: to make room for a human readable SMSC name that can be provisioned to the profile later
-            # on, alpha_id needs to be empty but padded 0xff to some length.
-            # - alpha_id is optional, setting alpha_id = '' ensures the IE is present.
-            # - the length of the file is 28+Y where Y is the length of the alpha_id -- here the intended length of our padding
-            #   (see 3GPP TS 31.102 4.2.27 EF.SMSP). So if we want a maximum length of alpha_id = 14, we set the total
-            #   file size to 28+14 = 42.
-            # - this file size has to go in two places: encode_record_bin() needs to know the length to encode the right
-            #   length of fillFileContent.
-            # - the f_smsp needs to show the right file size in the PES, as in
-            #      'ef-smsp': [('fileDescriptor', {'efFileSize': '2a', ...
-            #   (where 2a == 42)
-            # - To generate the right amount of fillFileContent, pass total_len=42 to encode_record_bin().
-            # - To show the right size in the PES, set f_smsp.rec_len = 42
-            ef_smsp_dec['alpha_id'] = ''
-            f_smsp.rec_len = 42
-
-            # re-encode into the File body.
-            #
+            # re-encode into the File body
+            f_smsp.body = ef_smsp.encode_record_bin(ef_smsp_dec, 1)
             #print("SMSP  (new): %s" % f_smsp.body)
             # re-generate the pe.decoded member from the File instance
-            f_smsp.body = ef_smsp.encode_record_bin(ef_smsp_dec, 1, total_len=f_smsp.rec_len)
             pe.file2pe(f_smsp)
 
     @classmethod
@@ -650,23 +587,30 @@ class SmspTpScAddr(ConfigurableParameter):
             ef_smsp_dec = ef_smsp.decode_record_bin(f_smsp.body, 1)
 
             tp_sc_addr = ef_smsp_dec.get('tp_sc_addr', None)
+            if not tp_sc_addr:
+                continue
 
             digits = tp_sc_addr.get('call_number', None)
+            if not digits:
+                continue
 
             ton_npi = tp_sc_addr.get('ton_npi', None)
+            if not ton_npi:
+                continue
             international = ton_npi.get('type_of_number', None)
+            if international is None:
+                continue
             international = (international == 'international')
 
             yield { cls.name: cls.tuple_to_str((international, digits)) }
 
 
-class SdKey(BinaryParam):
-    """Configurable Security Domain (SD) Key.  Value is presented as bytes.
-       Non-abstract implementations are generated in SdKey.generate_sd_key_classes"""
+class SdKey(BinaryParam, metaclass=ClassVarMeta):
+    """Configurable Security Domain (SD) Key.  Value is presented as bytes."""
     # these will be set by subclasses
     key_type = None
-    kvn = None
     key_id = None
+    kvn = None
     key_usage_qual = None
 
     @classmethod
@@ -684,16 +628,11 @@ class SdKey(BinaryParam):
                 key = SecurityDomainKey(
                         key_version_number=cls.kvn,
                         key_id=cls.key_id,
-                        key_usage_qualifier=cls.key_usage_qual,
+                        key_usage_qualifier=KeyUsageQualifier.build(cls.key_usage_qual),
                         key_components=set_components,
                         )
                 pe.add_key(key)
             else:
-                # A key of this KVN and ID already exists in the profile.
-
-                # Keep the key_usage_qualifier as it was in the profile, so skip this here:
-                # key.key_usage_qualifier = cls.key_usage_qual
-
                 key.key_components = set_components
 
     @classmethod
@@ -710,160 +649,60 @@ class SdKey(BinaryParam):
             if kc:
                 yield { cls.name: b2h(kc) }
 
+class SdKeyScp80_01(SdKey, kvn=0x01, key_type=0x88, permitted_len=[16,24,32]): # AES key type
+    pass
+class SdKeyScp80_01Kic(SdKeyScp80_01, key_id=0x01, key_usage_qual=0x18): # FIXME: ordering?
+    pass
+class SdKeyScp80_01Kid(SdKeyScp80_01, key_id=0x02, key_usage_qual=0x14):
+    pass
+class SdKeyScp80_01Kik(SdKeyScp80_01, key_id=0x03, key_usage_qual=0x48):
+    pass
 
-    LEN_128 = (16,)
-    LEN_128_192_256 = (16, 24, 32)
-    LEN_128_256 = (16, 32)
+class SdKeyScp81_01(SdKey, kvn=0x81): # FIXME
+    pass
+class SdKeyScp81_01Psk(SdKeyScp81_01, key_id=0x01, key_type=0x85, key_usage_qual=0x3C):
+    pass
+class SdKeyScp81_01Dek(SdKeyScp81_01, key_id=0x02, key_type=0x88, key_usage_qual=0x48):
+    pass
 
-    DES =    ('DES', dict(key_type=KeyType.des, allow_len=LEN_128) )
-    AES =    ('AES', dict(key_type=KeyType.aes, allow_len=LEN_128_192_256) )
+class SdKeyScp02_20(SdKey, kvn=0x20, key_type=0x88, permitted_len=[16,24,32]): # AES key type
+    pass
+class SdKeyScp02_20Enc(SdKeyScp02_20, key_id=0x01, key_usage_qual=0x18):
+    pass
+class SdKeyScp02_20Mac(SdKeyScp02_20, key_id=0x02, key_usage_qual=0x14):
+    pass
+class SdKeyScp02_20Dek(SdKeyScp02_20, key_id=0x03, key_usage_qual=0x48):
+    pass
 
-    ENC =    ('ENC', dict(key_id=0x01, key_usage_qual=0x18) )
-    MAC =    ('MAC', dict(key_id=0x02, key_usage_qual=0x14) )
-    DEK =    ('DEK', dict(key_id=0x03, key_usage_qual=0x48) )
+class SdKeyScp03_30(SdKey, kvn=0x30, key_type=0x88, permitted_len=[16,24,32]): # AES key type
+    pass
+class SdKeyScp03_30Enc(SdKeyScp03_30, key_id=0x01, key_usage_qual=0x18):
+    pass
+class SdKeyScp03_30Mac(SdKeyScp03_30, key_id=0x02, key_usage_qual=0x14):
+    pass
+class SdKeyScp03_30Dek(SdKeyScp03_30, key_id=0x03, key_usage_qual=0x48):
+    pass
 
-    TLSPSK_PSK = ('TLSPSK', dict(key_type=KeyType.tls_psk, key_id=0x01, key_usage_qual=0x3c, allow_len=LEN_128_192_256) )
-    TLSPSK_DEK = ('DEK',    dict(key_id=0x02, key_usage_qual=0x48) )
+class SdKeyScp03_31(SdKey, kvn=0x31, key_type=0x88, permitted_len=[16,24,32]): # AES key type
+    pass
+class SdKeyScp03_31Enc(SdKeyScp03_31, key_id=0x01, key_usage_qual=0x18):
+    pass
+class SdKeyScp03_31Mac(SdKeyScp03_31, key_id=0x02, key_usage_qual=0x14):
+    pass
+class SdKeyScp03_31Dek(SdKeyScp03_31, key_id=0x03, key_usage_qual=0x48):
+    pass
 
-    # THIS IS THE LIST that controls which SdKeyXxx subclasses exist:
-    SD_KEY_DEFS = (
-        # name    KVN                     x variants            x variants
-        ('SCP02', (0x20, 0x21, 0x22, 0xff), (AES, ),              (ENC, MAC, DEK) ),
-        ('SCP03', (0x30, 0x31, 0x32),       (AES, ),              (ENC, MAC, DEK) ),
-        ('SCP80', (0x01, 0x02, 0x03),       (DES, AES),           (ENC, MAC, DEK) ),
-
-        # key_id=1
-        ('SCP81', (0x40, 0x41, 0x42),       (TLSPSK_PSK, ),                       ),
-        # key_id=2
-        ('SCP81', (0x40, 0x41, 0x42),       (DES, AES),           (TLSPSK_DEK, )  ),
-    )
-
-    all_implementations = None
-
-    @classmethod
-    def generate_sd_key_classes(cls, sd_key_defs=SD_KEY_DEFS):
-        '''This generates python classes to be exported in this module, as subclasses of class SdKey.
-
-        We create SdKey subclasses dynamically from a list.
-        You can list all of them via:
-          from pySim.esim.saip.personalization import SdKey
-          SdKey.all_implementations
-        or
-          print('\n'.join(sorted(f'{x.__name__}\t{x.name}' for x in SdKey.all_implementations)))
-
-        at time of writing this comment, this prints:
-
-        SdKeyScp02Kvn20AesDek	SCP02-KVN20-AES-DEK
-        SdKeyScp02Kvn20AesEnc	SCP02-KVN20-AES-ENC
-        SdKeyScp02Kvn20AesMac	SCP02-KVN20-AES-MAC
-        SdKeyScp02Kvn21AesDek	SCP02-KVN21-AES-DEK
-        SdKeyScp02Kvn21AesEnc	SCP02-KVN21-AES-ENC
-        SdKeyScp02Kvn21AesMac	SCP02-KVN21-AES-MAC
-        SdKeyScp02Kvn22AesDek	SCP02-KVN22-AES-DEK
-        SdKeyScp02Kvn22AesEnc	SCP02-KVN22-AES-ENC
-        SdKeyScp02Kvn22AesMac	SCP02-KVN22-AES-MAC
-        SdKeyScp02KvnffAesDek	SCP02-KVNff-AES-DEK
-        SdKeyScp02KvnffAesEnc	SCP02-KVNff-AES-ENC
-        SdKeyScp02KvnffAesMac	SCP02-KVNff-AES-MAC
-        SdKeyScp03Kvn30AesDek	SCP03-KVN30-AES-DEK
-        SdKeyScp03Kvn30AesEnc	SCP03-KVN30-AES-ENC
-        SdKeyScp03Kvn30AesMac	SCP03-KVN30-AES-MAC
-        SdKeyScp03Kvn31AesDek	SCP03-KVN31-AES-DEK
-        SdKeyScp03Kvn31AesEnc	SCP03-KVN31-AES-ENC
-        SdKeyScp03Kvn31AesMac	SCP03-KVN31-AES-MAC
-        SdKeyScp03Kvn32AesDek	SCP03-KVN32-AES-DEK
-        SdKeyScp03Kvn32AesEnc	SCP03-KVN32-AES-ENC
-        SdKeyScp03Kvn32AesMac	SCP03-KVN32-AES-MAC
-        SdKeyScp80Kvn01AesDek	SCP80-KVN01-AES-DEK
-        SdKeyScp80Kvn01AesEnc	SCP80-KVN01-AES-ENC
-        SdKeyScp80Kvn01AesMac	SCP80-KVN01-AES-MAC
-        SdKeyScp80Kvn01DesDek	SCP80-KVN01-DES-DEK
-        SdKeyScp80Kvn01DesEnc	SCP80-KVN01-DES-ENC
-        SdKeyScp80Kvn01DesMac	SCP80-KVN01-DES-MAC
-        SdKeyScp80Kvn02AesDek	SCP80-KVN02-AES-DEK
-        SdKeyScp80Kvn02AesEnc	SCP80-KVN02-AES-ENC
-        SdKeyScp80Kvn02AesMac	SCP80-KVN02-AES-MAC
-        SdKeyScp80Kvn02DesDek	SCP80-KVN02-DES-DEK
-        SdKeyScp80Kvn02DesEnc	SCP80-KVN02-DES-ENC
-        SdKeyScp80Kvn02DesMac	SCP80-KVN02-DES-MAC
-        SdKeyScp80Kvn03AesDek	SCP80-KVN03-AES-DEK
-        SdKeyScp80Kvn03AesEnc	SCP80-KVN03-AES-ENC
-        SdKeyScp80Kvn03AesMac	SCP80-KVN03-AES-MAC
-        SdKeyScp80Kvn03DesDek	SCP80-KVN03-DES-DEK
-        SdKeyScp80Kvn03DesEnc	SCP80-KVN03-DES-ENC
-        SdKeyScp80Kvn03DesMac	SCP80-KVN03-DES-MAC
-        SdKeyScp81Kvn40AesDek	SCP81-KVN40-AES-DEK
-        SdKeyScp81Kvn40DesDek	SCP81-KVN40-DES-DEK
-        SdKeyScp81Kvn40Tlspsk	SCP81-KVN40-TLSPSK
-        SdKeyScp81Kvn41AesDek	SCP81-KVN41-AES-DEK
-        SdKeyScp81Kvn41DesDek	SCP81-KVN41-DES-DEK
-        SdKeyScp81Kvn41Tlspsk	SCP81-KVN41-TLSPSK
-        SdKeyScp81Kvn42AesDek	SCP81-KVN42-AES-DEK
-        SdKeyScp81Kvn42DesDek	SCP81-KVN42-DES-DEK
-        SdKeyScp81Kvn42Tlspsk	SCP81-KVN42-TLSPSK
-        '''
-
-        SdKey.all_implementations = []
-
-        def camel(s):
-            return s[:1].upper() + s[1:].lower()
-
-        def do_variants(name, kvn, remaining_variants, labels=[], attrs={}):
-            'recurse to unfold as many variants as there may be'
-            if remaining_variants:
-                # not a leaf node, collect more labels and attrs
-                variants = remaining_variants[0]
-                remaining_variants = remaining_variants[1:]
-
-                for label, valdict in variants:
-                    # pass copies to recursion
-                    inner_labels = list(labels)
-                    inner_attrs = dict(attrs)
-
-                    inner_labels.append(label)
-                    inner_attrs.update(valdict)
-                    do_variants(name, kvn, remaining_variants,
-                                labels=inner_labels,
-                                attrs=inner_attrs)
-                return
-
-            # leaf node. create a new class with all the accumulated vals
-            parts = [name, f'KVN{kvn:02x}',] + labels
-            cls_label = '-'.join(p for p in parts if p)
-
-            parts = ['Sd', 'Key', name, f'Kvn{kvn:02x}'] + labels
-            clsname = ''.join(camel(p) for p in parts)
-
-            max_key_len = attrs.get('allow_len')[-1]
-
-            attrs.update({
-                'name' : cls_label,
-                'kvn': kvn,
-                'example_input': f'00*{max_key_len}',
-                })
-
-            # below line is like
-            # class SdKeyScpNNKvnXXYyyZzz(SdKey):
-            #     <set attrs>
-            cls_def = type(clsname, (cls,), attrs)
-
-            # for some unknown reason, subclassing from abc.ABC makes cls_def.__module__ == 'abc',
-            # but we don't want 'abc.SdKeyScp03Kvn32AesEnc'.
-            # Make sure it is 'pySim.esim.saip.personalization.SdKeyScp03Kvn32AesEnc'
-            cls_def.__module__ = __name__
-
-            globals()[clsname] = cls_def
-            SdKey.all_implementations.append(cls_def)
+class SdKeyScp03_32(SdKey, kvn=0x32, key_type=0x88, permitted_len=[16,24,32]): # AES key type
+    pass
+class SdKeyScp03_32Enc(SdKeyScp03_32, key_id=0x01, key_usage_qual=0x18):
+    pass
+class SdKeyScp03_32Mac(SdKeyScp03_32, key_id=0x02, key_usage_qual=0x14):
+    pass
+class SdKeyScp03_32Dek(SdKeyScp03_32, key_id=0x03, key_usage_qual=0x48):
+    pass
 
 
-        for items in sd_key_defs:
-            name, kvns = items[:2]
-            variants = items[2:]
-            for kvn in kvns:
-                do_variants(name, kvn, variants)
 
-# this creates all of the classes named like SdKeyScp02Kvn20AesDek to be published in this python module:
-SdKey.generate_sd_key_classes()
 
 def obtain_all_pe_from_pelist(l: List[ProfileElement], wanted_type: str) -> ProfileElement:
     return (pe for pe in l if pe.type == wanted_type)

pySim/euicc.py

@@ -226,28 +226,9 @@ class Icon(BER_TLV_IE, tag=0x94):
     _construct = GreedyBytes
 class ProfileClass(BER_TLV_IE, tag=0x95):
     _construct = Enum(Int8ub, test=0, provisioning=1, operational=2)
-class ProfilePolicyRules(BER_TLV_IE, tag=0x99):
-    _construct = GreedyBytes
-class NotificationConfigurationInfo(BER_TLV_IE, tag=0xb6):
-    _construct = GreedyBytes
-
-# ProfileOwner
-class ProfileOwnerPLMN(BER_TLV_IE, tag=0x80):
-    _construct = PlmnAdapter(Bytes(3))
-class ProfileOwnerGID1(BER_TLV_IE, tag=0x81):
-    _construct = GreedyBytes
-class ProfileOwnerGID2(BER_TLV_IE, tag=0x82):
-    _construct = GreedyBytes
-class ProfileOwner(BER_TLV_IE, tag=0xb7, nested=[ProfileOwnerPLMN, ProfileOwnerGID1, ProfileOwnerGID2]):
-    _construct = GreedyBytes
-
-class SMDPPProprietaryData(BER_TLV_IE, tag=0xb8):
-    _construct = GreedyBytes
-
 class ProfileInfo(BER_TLV_IE, tag=0xe3, nested=[Iccid, IsdpAid, ProfileState, ProfileNickname,
                                                 ServiceProviderName, ProfileName, IconType, Icon,
-                                                ProfileClass, ProfilePolicyRules, NotificationConfigurationInfo,
-                                                ProfileOwner, SMDPPProprietaryData]):
+                                                ProfileClass]): # FIXME: more IEs
     pass
 class ProfileInfoSeq(BER_TLV_IE, tag=0xa0, nested=[ProfileInfo]):
     pass
@@ -463,28 +444,9 @@ class CardApplicationISDR(pySim.global_platform.CardApplicationSD):
             d = rn.to_dict()
             self._cmd.poutput_json(flatten_dict_lists(d['notification_sent_resp']))
 
-        get_profiles_info_parser = argparse.ArgumentParser()
-        get_profiles_info_parser.add_argument('--all', action='store_true', help='Retrieve all known tags of a profile')
-
-        @cmd2.with_argparser(get_profiles_info_parser)
-        def do_get_profiles_info(self, opts):
+        def do_get_profiles_info(self, _opts):
             """Perform an ES10c GetProfilesInfo function."""
-            if opts.all:
-                tags = [nest.tag for nest in ProfileInfo.nested_collection_cls().nested]
-                u8tags = []
-                # TODO: rework TagList to support 2 byte tags to not filter it into u8 tags
-                for tag in tags:
-                    if tag <= 255:
-                        u8tags.append(tag)
-                    elif tag <= 65535:
-                        u8tags.append(tag >> 8)
-                        u8tags.append(tag & 0xff)
-                    # Ignoring 3 byte tags
-                req = ProfileInfoListReq(children=[TagList(decoded=u8tags)])
-            else:
-                req = ProfileInfoListReq()
-
-            pi = CardApplicationISDR.store_data_tlv(self._cmd.lchan.scc, req, ProfileInfoListResp)
+            pi = CardApplicationISDR.store_data_tlv(self._cmd.lchan.scc, ProfileInfoListReq(), ProfileInfoListResp)
             d = pi.to_dict()
             self._cmd.poutput_json(flatten_dict_lists(d['profile_info_list_resp']))
 

pySim/filesystem.py

@@ -863,8 +863,6 @@ class TransparentEF(CardEF):
             t = self._tlv() if inspect.isclass(self._tlv) else self._tlv
             t.from_dict(abstract_data)
             return t.to_tlv()
-        if 'raw' in abstract_data:
-            return h2b(abstract_data['raw'])
         raise NotImplementedError(
             "%s encoder not yet implemented. Patches welcome." % self)
 
@@ -894,8 +892,6 @@ class TransparentEF(CardEF):
             t = self._tlv() if inspect.isclass(self._tlv) else self._tlv
             t.from_dict(abstract_data)
             return b2h(t.to_tlv())
-        if 'raw' in abstract_data:
-            return abstract_data['raw']
         raise NotImplementedError(
             "%s encoder not yet implemented. Patches welcome." % self)
 
@@ -1170,8 +1166,6 @@ class LinFixedEF(CardEF):
             t = self._tlv() if inspect.isclass(self._tlv) else self._tlv
             t.from_dict(abstract_data)
             return b2h(t.to_tlv())
-        if 'raw' in abstract_data:
-            return abstract_data['raw']
         raise NotImplementedError(
             "%s encoder not yet implemented. Patches welcome." % self)
 
@@ -1201,8 +1195,6 @@ class LinFixedEF(CardEF):
             t = self._tlv() if inspect.isclass(self._tlv) else self._tlv
             t.from_dict(abstract_data)
             return t.to_tlv()
-        if 'raw' in abstract_data:
-            return h2b(abstract_data['raw'])
         raise NotImplementedError(
             "%s encoder not yet implemented. Patches welcome." % self)
 
@@ -1394,8 +1386,6 @@ class TransRecEF(TransparentEF):
             t = self._tlv() if inspect.isclass(self._tlv) else self._tlv
             t.from_dict(abstract_data)
             return b2h(t.to_tlv())
-        if 'raw' in abstract_data:
-            return abstract_data['raw']
         raise NotImplementedError(
             "%s encoder not yet implemented. Patches welcome." % self)
 
@@ -1425,8 +1415,6 @@ class TransRecEF(TransparentEF):
             t = self._tlv() if inspect.isclass(self._tlv) else self._tlv
             t.from_dict(abstract_data)
             return t.to_tlv()
-        if 'raw' in abstract_data:
-            return h2b(abstract_data['raw'])
         raise NotImplementedError(
             "%s encoder not yet implemented. Patches welcome." % self)
 

pySim/global_platform/__init__.py

@@ -29,12 +29,16 @@ from osmocom.tlv import *
 from osmocom.construct import *
 from pySim.utils import ResTuple
 from pySim.card_key_provider import card_key_provider_get_field
-from pySim.global_platform.scp import SCP02, SCP03
+from pySim.global_platform.scp import SCP, SCP02, SCP03
 from pySim.global_platform.install_param import gen_install_parameters
 from pySim.filesystem import *
 from pySim.profile import CardProfile
 from pySim.ota import SimFileAccessAndToolkitAppSpecParams
 from pySim.javacard import CapFile
+from pySim.runtime import RuntimeLchan
+from pySim.log import PySimLogger
+
+log = PySimLogger.get(__name__)
 
 # GPCS Table 11-48 Load Parameter Tags
 class NonVolatileCodeMinMemoryReq(BER_TLV_IE, tag=0xC6):
@@ -527,6 +531,129 @@ class ADF_SD(CardADF):
     def decode_select_response(self, data_hex: str) -> object:
         return decode_select_response(data_hex)
 
+    @staticmethod
+    def store_data(scc: SimCardCommands, data: bytes, structure:str = 'none', encryption:str = 'none',
+                   response_permitted: bool = False) -> bytes:
+        """
+        Perform the GlobalPlatform STORE DATA command in order to store some card-specific data.
+        See GlobalPlatform CardSpecification v2.3 Section 11.11 for details.
+        """
+        max_cmd_len =scc.max_cmd_len
+        # Table 11-89 of GP Card Specification v2.3
+        remainder = data
+        block_nr = 0
+        response = ''
+        while len(remainder):
+            chunk = remainder[:max_cmd_len]
+            remainder = remainder[max_cmd_len:]
+            p1b = build_construct(ADF_SD.StoreData,
+                                  {'last_block': len(remainder) == 0, 'encryption': encryption,
+                                   'structure': structure, 'response': response_permitted})
+            hdr = "80E2%02x%02x%02x" % (p1b[0], block_nr, len(chunk))
+            data, _sw =scc.send_apdu_checksw(hdr + b2h(chunk) + "00")
+            block_nr += 1
+            response += data
+        return h2b(response)
+
+    @staticmethod
+    def get_data(scc: SimCardCommands, tag: int) -> bytes:
+        (data, _sw) =scc.get_data(cla=0x80, tag=tag)
+        return data
+
+    @staticmethod
+    def put_key(scc: SimCardCommands, old_kvn:int, kvn: int, kid: int, key_dict: dict) -> bytes:
+        """
+        Perform the GlobalPlatform PUT KEY command in order to store a new key on the card.
+        See GlobalPlatform CardSpecification v2.3 Section 11.8 for details.
+        """
+
+        # Table 11-68: Key Data Field - Format 1 (Basic Format)
+        KeyDataBasic = GreedyRange(Struct('key_type'/KeyType,
+                                          'kcb'/Prefixed(Int8ub, GreedyBytes),
+                                          'kcv'/Prefixed(Int8ub, GreedyBytes)))
+
+        key_data = kvn.to_bytes(1, 'big') + build_construct(KeyDataBasic, key_dict)
+        hdr = "80D8%02x%02x%02x" % (old_kvn, kid, len(key_data))
+        data, _sw =scc.send_apdu_checksw(hdr + b2h(key_data) + "00")
+        return data
+
+    @staticmethod
+    def get_status(scc: SimCardCommands, subset:str, aid_search_qualifier:Hexstr = '') -> List[GpRegistryRelatedData]:
+        subset_hex = b2h(build_construct(StatusSubset, subset))
+        aid = ApplicationAID(decoded=aid_search_qualifier)
+        cmd_data = aid.to_tlv() + h2b('5c054f9f70c5cc')
+        p2 = 0x02 # TLV format according to Table 11-36
+        grd_list = []
+        while True:
+            hdr = "80F2%s%02x%02x" % (subset_hex, p2, len(cmd_data))
+            data, sw =scc.send_apdu(hdr + b2h(cmd_data) + "00")
+            remainder = h2b(data)
+            while len(remainder):
+                # tlv sequence, each element is one GpRegistryRelatedData()
+                grd = GpRegistryRelatedData()
+                _dec, remainder = grd.from_tlv(remainder)
+                grd_list.append(grd)
+            if sw != '6310':
+                return grd_list
+            else:
+                p2 |= 0x01
+        return grd_list
+
+    @staticmethod
+    def set_status(scc: SimCardCommands, scope:str, status:str, aid:Hexstr = ''):
+        SetStatus = Struct(Const(0x80, Byte), Const(0xF0, Byte),
+                           'scope'/SetStatusScope, 'status'/CLifeCycleState,
+                           'aid'/Prefixed(Int8ub, COptional(GreedyBytes)))
+        apdu = build_construct(SetStatus, {'scope':scope, 'status':status, 'aid':aid})
+        _data, _sw =scc.send_apdu_checksw(b2h(apdu))
+
+    @staticmethod
+    def install(scc: SimCardCommands, p1:int, p2:int, data:Hexstr) -> ResTuple:
+        cmd_hex = "80E6%02x%02x%02x%s00" % (p1, p2, len(data)//2, data)
+        return scc.send_apdu_checksw(cmd_hex)
+
+    @staticmethod
+    def delete(scc: SimCardCommands, p1:int, p2:int, data:Hexstr) -> ResTuple:
+        cmd_hex = "80E4%02x%02x%02x%s00" % (p1, p2, len(data)//2, data)
+        return scc.send_apdu_checksw(cmd_hex)
+
+    @staticmethod
+    def load(scc: SimCardCommands, contents:bytes, chunk_len:int = 240):
+        # TODO:tune chunk_len based on the overhead of the used SCP?
+        # build TLV according to GPC_SPE_034 section 11.6.2.3 / Table 11-58 for unencrypted case
+        remainder = b'\xC4' + bertlv_encode_len(len(contents)) + contents
+        # transfer this in various chunks to the card
+        total_size = len(remainder)
+        block_nr = 0
+        while len(remainder):
+            block = remainder[:chunk_len]
+            remainder = remainder[chunk_len:]
+            # build LOAD command APDU according to GPC_SPE_034 section 11.6.2 / Table 11-56
+            p1 = 0x00 if len(remainder) else 0x80
+            p2 = block_nr % 256
+            block_nr += 1
+            cmd_hex = "80E8%02x%02x%02x%s00" % (p1, p2, len(block), b2h(block))
+            _rsp_hex, _sw =scc.send_apdu_checksw(cmd_hex)
+        log.info("Loaded a total of %u bytes in %u blocks. Don't forget install_for_install (and make selectable) now!",
+                 total_size, block_nr)
+
+    @staticmethod
+    def establish_scp(scc: SimCardCommands, scp: SCP, host_challenge: Optional[bytes] = None,
+                      security_level: int = 0x01):
+        # perform the common functionality shared by SCP02 and SCP03 establishment
+        init_update_apdu = scp.gen_init_update_apdu(host_challenge=host_challenge)
+        init_update_resp, _sw =scc.send_apdu_checksw(b2h(init_update_apdu))
+        scp.parse_init_update_resp(h2b(init_update_resp))
+        ext_auth_apdu = scp.gen_ext_auth_apdu(security_level)
+        _ext_auth_resp, _sw =scc.send_apdu_checksw(b2h(ext_auth_apdu))
+        log.info("Successfully established a %s secure channel", str(scp))
+        # store a reference to the SCP instance
+        scc.scp = scp
+
+    @staticmethod
+    def release_scp(scc: SimCardCommands):
+       scc.scp = None
+
     @with_default_category('Application-Specific Commands')
     class AddlShellCommands(CommandSet):
         get_data_parser = argparse.ArgumentParser()
@@ -544,7 +671,8 @@ class ADF_SD(CardADF):
                 self._cmd.poutput('Unknown data object "%s", available options: %s' % (tlv_cls_name,
                                                                                        do_names))
                 return
-            (data, _sw) = self._cmd.lchan.scc.get_data(cla=0x80, tag=tlv_cls.tag)
+
+            data = ADF_SD.get_data(self._cmd.lchan.scc, tag=tlv_cls.tag)
             ie = tlv_cls()
             ie.from_tlv(h2b(data))
             self._cmd.poutput_json(ie.to_dict())
@@ -565,27 +693,8 @@ class ADF_SD(CardADF):
             """Perform the GlobalPlatform STORE DATA command in order to store some card-specific data.
             See GlobalPlatform CardSpecification v2.3 Section 11.11 for details."""
             response_permitted = opts.response == 'may_be_returned'
-            self.store_data(h2b(opts.DATA), opts.data_structure, opts.encryption, response_permitted)
-
-        def store_data(self, data: bytes, structure:str = 'none', encryption:str = 'none', response_permitted: bool = False) -> bytes:
-            """Perform the GlobalPlatform STORE DATA command in order to store some card-specific data.
-            See GlobalPlatform CardSpecification v2.3 Section 11.11 for details."""
-            max_cmd_len = self._cmd.lchan.scc.max_cmd_len
-            # Table 11-89 of GP Card Specification v2.3
-            remainder = data
-            block_nr = 0
-            response = ''
-            while len(remainder):
-                chunk = remainder[:max_cmd_len]
-                remainder = remainder[max_cmd_len:]
-                p1b = build_construct(ADF_SD.StoreData,
-                                      {'last_block': len(remainder) == 0, 'encryption': encryption,
-                                       'structure': structure, 'response': response_permitted})
-                hdr = "80E2%02x%02x%02x" % (p1b[0], block_nr, len(chunk))
-                data, _sw = self._cmd.lchan.scc.send_apdu_checksw(hdr + b2h(chunk) + "00")
-                block_nr += 1
-                response += data
-            return h2b(response)
+            ADF_SD.store_data(self._cmd.lchan.scc, h2b(opts.DATA), opts.data_structure, opts.encryption,
+                              response_permitted)
 
         put_key_parser = argparse.ArgumentParser()
         put_key_parser.add_argument('--old-key-version-nr', type=auto_uint8, default=0, help='Old Key Version Number')
@@ -636,20 +745,8 @@ class ADF_SD(CardADF):
             p2 = opts.key_id
             if len(opts.key_type) > 1:
                 p2 |= 0x80
-            self.put_key(opts.old_key_version_nr, opts.key_version_nr, p2, kdb)
+            ADF_SD.put_key(self._cmd.lchan.scc, opts.old_key_version_nr, opts.key_version_nr, p2, kdb)
 
-        # Table 11-68: Key Data Field - Format 1 (Basic Format)
-        KeyDataBasic = GreedyRange(Struct('key_type'/KeyType,
-                                          'kcb'/Prefixed(Int8ub, GreedyBytes),
-                                          'kcv'/Prefixed(Int8ub, GreedyBytes)))
-
-        def put_key(self, old_kvn:int, kvn: int, kid: int, key_dict: dict) -> bytes:
-            """Perform the GlobalPlatform PUT KEY command in order to store a new key on the card.
-            See GlobalPlatform CardSpecification v2.3 Section 11.8 for details."""
-            key_data = kvn.to_bytes(1, 'big') + build_construct(ADF_SD.AddlShellCommands.KeyDataBasic, key_dict)
-            hdr = "80D8%02x%02x%02x" % (old_kvn, kid, len(key_data))
-            data, _sw = self._cmd.lchan.scc.send_apdu_checksw(hdr + b2h(key_data) + "00")
-            return data
 
         get_status_parser = argparse.ArgumentParser()
         get_status_parser.add_argument('subset', choices=list(StatusSubset.ksymapping.values()),
@@ -661,31 +758,10 @@ class ADF_SD(CardADF):
         def do_get_status(self, opts):
             """Perform GlobalPlatform GET STATUS command in order to retrieve status information
             on Issuer Security Domain, Executable Load File, Executable Module or Applications."""
-            grd_list = self.get_status(opts.subset, opts.aid)
+            grd_list = ADF_SD.get_status(self._cmd.lchan.scc, opts.subset, opts.aid)
             for grd in grd_list:
                 self._cmd.poutput_json(grd.to_dict())
 
-        def get_status(self, subset:str, aid_search_qualifier:Hexstr = '') -> List[GpRegistryRelatedData]:
-            subset_hex = b2h(build_construct(StatusSubset, subset))
-            aid = ApplicationAID(decoded=aid_search_qualifier)
-            cmd_data = aid.to_tlv() + h2b('5c054f9f70c5cc')
-            p2 = 0x02 # TLV format according to Table 11-36
-            grd_list = []
-            while True:
-                hdr = "80F2%s%02x%02x" % (subset_hex, p2, len(cmd_data))
-                data, sw = self._cmd.lchan.scc.send_apdu(hdr + b2h(cmd_data) + "00")
-                remainder = h2b(data)
-                while len(remainder):
-                    # tlv sequence, each element is one GpRegistryRelatedData()
-                    grd = GpRegistryRelatedData()
-                    _dec, remainder = grd.from_tlv(remainder)
-                    grd_list.append(grd)
-                if sw != '6310':
-                    return grd_list
-                else:
-                    p2 |= 0x01
-            return grd_list
-
         set_status_parser = argparse.ArgumentParser()
         set_status_parser.add_argument('scope', choices=list(SetStatusScope.ksymapping.values()),
                                        help='Defines the scope of the requested status change')
@@ -699,14 +775,7 @@ class ADF_SD(CardADF):
             """Perform GlobalPlatform SET STATUS command in order to change the life cycle state of the
             Issuer Security Domain, Supplementary Security Domain or Application.  This normally requires
             prior authentication with a Secure Channel Protocol."""
-            self.set_status(opts.scope, opts.status, opts.aid)
-
-        def set_status(self, scope:str, status:str, aid:Hexstr = ''):
-            SetStatus = Struct(Const(0x80, Byte), Const(0xF0, Byte),
-                               'scope'/SetStatusScope, 'status'/CLifeCycleState,
-                               'aid'/Prefixed(Int8ub, COptional(GreedyBytes)))
-            apdu = build_construct(SetStatus, {'scope':scope, 'status':status, 'aid':aid})
-            _data, _sw = self._cmd.lchan.scc.send_apdu_checksw(b2h(apdu))
+            ADF_SD.set_status(self._cmd.lchan.scc, opts.scope, opts.status, opts.aid)
 
         inst_perso_parser = argparse.ArgumentParser()
         inst_perso_parser.add_argument('application_aid', type=is_hexstr, help='Application AID')
@@ -716,7 +785,8 @@ class ADF_SD(CardADF):
             """Perform GlobalPlatform INSTALL [for personalization] command in order to inform a Security
             Domain that the following STORE DATA commands are meant for a specific AID (specified here)."""
             # Section 11.5.2.3.6 / Table 11-47
-            self.install(0x20, 0x00, "0000%02x%s000000" % (len(opts.application_aid)//2, opts.application_aid))
+            ADF_SD.install(self._cmd.lchan.scc, 0x20, 0x00, "0000%02x%s000000" %
+                           (len(opts.application_aid)//2, opts.application_aid))
 
         inst_inst_parser = argparse.ArgumentParser()
         inst_inst_parser.add_argument('--load-file-aid', type=is_hexstr, default='',
@@ -751,7 +821,7 @@ class ADF_SD(CardADF):
             # convert from list to "true-dict" as required by construct.FlagsEnum
             decoded['privileges'] = {x: True for x in decoded['privileges']}
             ifi_bytes = build_construct(InstallForInstallCD, decoded)
-            self.install(p1, 0x00, b2h(ifi_bytes))
+            ADF_SD.install(self._cmd.lchan.scc, p1, 0x00, b2h(ifi_bytes))
 
         inst_load_parser = argparse.ArgumentParser()
         inst_load_parser.add_argument('--load-file-aid', type=is_hexstr, required=True,
@@ -776,11 +846,7 @@ class ADF_SD(CardADF):
                                       'load_parameters'/Prefixed(Int8ub, GreedyBytes),
                                       'load_token'/Prefixed(Int8ub, GreedyBytes))
             ifl_bytes = build_construct(InstallForLoadCD, vars(opts))
-            self.install(0x02, 0x00, b2h(ifl_bytes))
-
-        def install(self, p1:int, p2:int, data:Hexstr) -> ResTuple:
-            cmd_hex = "80E6%02x%02x%02x%s00" % (p1, p2, len(data)//2, data)
-            return self._cmd.lchan.scc.send_apdu_checksw(cmd_hex)
+            ADF_SD.install(self._cmd.lchan.scc, 0x02, 0x00, b2h(ifl_bytes))
 
         del_cc_parser = argparse.ArgumentParser()
         del_cc_parser.add_argument('aid', type=is_hexstr,
@@ -794,7 +860,7 @@ class ADF_SD(CardADF):
             File, an Application or an Executable Load File and its related Applications."""
             p2 = 0x80 if opts.delete_related_objects else 0x00
             aid = ApplicationAID(decoded=opts.aid)
-            self.delete(0x00, p2, b2h(aid.to_tlv()))
+            ADF_SD.delete(self._cmd.lchan.scc, 0x00, p2, b2h(aid.to_tlv()))
 
         del_key_parser = argparse.ArgumentParser()
         del_key_parser.add_argument('--key-id', type=auto_uint7, help='Key Identifier (KID)')
@@ -815,11 +881,7 @@ class ADF_SD(CardADF):
                 cmd += "d001%02x" % opts.key_id
             if opts.key_ver is not None:
                 cmd += "d201%02x" % opts.key_ver
-            self.delete(0x00, p2, cmd)
-
-        def delete(self, p1:int, p2:int, data:Hexstr) -> ResTuple:
-            cmd_hex = "80E4%02x%02x%02x%s00" % (p1, p2, len(data)//2, data)
-            return self._cmd.lchan.scc.send_apdu_checksw(cmd_hex)
+            ADF_SD.delete(self._cmd.lchan.scc, 0x00, p2, cmd)
 
         load_parser = argparse.ArgumentParser()
         load_parser_from_grp = load_parser.add_mutually_exclusive_group(required=True)
@@ -832,33 +894,15 @@ class ADF_SD(CardADF):
             """Perform a GlobalPlatform LOAD command. (We currently only support loading without DAP and
             without ciphering.)"""
             if opts.from_hex is not None:
-                self.load(h2b(opts.from_hex))
+                ADF_SD.load(self._cmd.lchan.scc, h2b(opts.from_hex))
             elif opts.from_file is not None:
-                self.load(opts.from_file.read())
+                ADF_SD.load(self._cmd.lchan.scc, opts.from_file.read())
             elif opts.from_cap_file is not None:
                 cap = CapFile(opts.from_cap_file)
-                self.load(cap.get_loadfile())
+                ADF_SD.load(self._cmd.lchan.scc, cap.get_loadfile())
             else:
                 raise ValueError('load source not specified!')
 
-        def load(self, contents:bytes, chunk_len:int = 240):
-            # TODO:tune chunk_len based on the overhead of the used SCP?
-            # build TLV according to GPC_SPE_034 section 11.6.2.3 / Table 11-58 for unencrypted case
-            remainder = b'\xC4' + bertlv_encode_len(len(contents)) + contents
-            # transfer this in various chunks to the card
-            total_size = len(remainder)
-            block_nr = 0
-            while len(remainder):
-                block = remainder[:chunk_len]
-                remainder = remainder[chunk_len:]
-                # build LOAD command APDU according to GPC_SPE_034 section 11.6.2 / Table 11-56
-                p1 = 0x00 if len(remainder) else 0x80
-                p2 = block_nr % 256
-                block_nr += 1
-                cmd_hex = "80E8%02x%02x%02x%s00" % (p1, p2, len(block), b2h(block))
-                _rsp_hex, _sw = self._cmd.lchan.scc.send_apdu_checksw(cmd_hex)
-            self._cmd.poutput("Loaded a total of %u bytes in %u blocks. Don't forget install_for_install (and make selectable) now!" % (total_size, block_nr))
-
         install_cap_parser = argparse.ArgumentParser(usage='%(prog)s FILE [--install-parameters | --install-parameters-*]')
         install_cap_parser.add_argument('cap_file', type=str, metavar='FILE',
                                         help='JAVA-CARD CAP file to install')
@@ -919,7 +963,7 @@ class ADF_SD(CardADF):
             self._cmd.poutput("step #1: install for load...")
             self.do_install_for_load("--load-file-aid %s --security-domain-aid %s" % (load_file_aid, security_domain_aid))
             self._cmd.poutput("step #2: load...")
-            self.load(load_file)
+            ADF_SD.load(self._cmd.lchan.scc, load_file)
             self._cmd.poutput("step #3: install_for_install (and make selectable)...")
             self.do_install_for_install("--load-file-aid %s --module-aid %s --application-aid %s --install-parameters %s --make-selectable" %
                                         (load_file_aid, module_aid, application_aid, install_parameters))
@@ -959,7 +1003,7 @@ class ADF_SD(CardADF):
             host_challenge = h2b(opts.host_challenge) if opts.host_challenge else get_random_bytes(8)
             kset = GpCardKeyset(opts.key_ver, h2b(opts.key_enc), h2b(opts.key_mac), h2b(opts.key_dek))
             scp02 = SCP02(card_keys=kset)
-            self._establish_scp(scp02, host_challenge, opts.security_level)
+            ADF_SD.establish_scp(self._cmd.lchan.scc, scp02, host_challenge, opts.security_level)
 
         est_scp03_parser = deepcopy(est_scp02_parser)
         est_scp03_parser.description = None
@@ -987,27 +1031,14 @@ class ADF_SD(CardADF):
             host_challenge = h2b(opts.host_challenge) if opts.host_challenge else get_random_bytes(s_mode)
             kset = GpCardKeyset(opts.key_ver, h2b(opts.key_enc), h2b(opts.key_mac), h2b(opts.key_dek))
             scp03 = SCP03(card_keys=kset, s_mode = s_mode)
-            self._establish_scp(scp03, host_challenge, opts.security_level)
-
-        def _establish_scp(self, scp, host_challenge, security_level):
-            # perform the common functionality shared by SCP02 and SCP03 establishment
-            init_update_apdu = scp.gen_init_update_apdu(host_challenge=host_challenge)
-            init_update_resp, _sw = self._cmd.lchan.scc.send_apdu_checksw(b2h(init_update_apdu))
-            scp.parse_init_update_resp(h2b(init_update_resp))
-            ext_auth_apdu = scp.gen_ext_auth_apdu(security_level)
-            _ext_auth_resp, _sw = self._cmd.lchan.scc.send_apdu_checksw(b2h(ext_auth_apdu))
-            self._cmd.poutput("Successfully established a %s secure channel" % str(scp))
-            # store a reference to the SCP instance
-            self._cmd.lchan.scc.scp = scp
-            self._cmd.update_prompt()
-
+            ADF_SD.establish_scp(self._cmd.lchan.scc, scp03, host_challenge, opts.security_level)
 
         def do_release_scp(self, _opts):
             """Release a previously establiehed secure channel."""
             if not self._cmd.lchan.scc.scp:
                 self._cmd.poutput("Cannot release SCP as none is established")
                 return
-            self._cmd.lchan.scc.scp = None
+            ADF_SD.release_scp(self._cmd.lchan.scc)
             self._cmd.update_prompt()
 
 

pySim/log.py

@@ -24,15 +24,6 @@
 #
 
 import logging
-import cmd2
-from packaging import version
-
-if version.parse(cmd2.__version__) >= version.parse("3.0.0"):
-    from cmd2 import stylize as _stylize # pylint: disable=no-name-in-module
-    def _style(text, fg=None): # pylint: disable=function-redefined
-        return _stylize(text, fg) if fg else text
-else: # cmd2>=2.6.2
-    from cmd2 import style as _style # pylint: disable=no-name-in-module
 
 class _PySimLogHandler(logging.Handler):
     def __init__(self, log_callback):
@@ -129,7 +120,8 @@ class PySimLogger:
                 if isinstance(color, str):
                     PySimLogger.print_callback(color + formatted_message + "\033[0m")
                 else:
-                    PySimLogger.print_callback(_style(formatted_message, fg = color))
+                    from cmd2 import style
+                    PySimLogger.print_callback(style(formatted_message, fg = color))
             else:
                 PySimLogger.print_callback(formatted_message)
 

pyproject.toml

@@ -4,7 +4,3 @@ build-backend = "setuptools.build_meta"
 
 [tool.pylint.main]
 ignored-classes = ["twisted.internet.reactor"]
-
-[tool.pylint.TYPECHECK]
-# SdKey subclasses are generated dynamically via SdKey.generate_sd_key_classes()
-generated-members = ["SdKey[A-Za-z0-9]+"]

requirements.txt

@@ -1,7 +1,7 @@
 pyscard
 pyserial
 pytlv
-cmd2>=2.6.2,<4.0
+cmd2>=2.6.2,<3.0
 jsonpath-ng
 construct>=2.10.70
 bidict

setup.py

@@ -21,7 +21,7 @@ setup(
         "pyscard",
         "pyserial",
         "pytlv",
-        "cmd2 >= 2.6.2, < 4.0",
+        "cmd2 >= 1.5.0, < 3.0",
         "jsonpath-ng",
         "construct >= 2.10.70",
         "bidict",

tests/unittests/smdpp_data

@@ -1 +0,0 @@
-../../smdpp-data

tests/unittests/test_configurable_parameters.py

@@ -1,633 +0,0 @@
-#!/usr/bin/env python3
-
-# (C) 2025 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de>
-#
-# Author: Neels Hofmeyr
-#
-# 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 enum
-import io
-import sys
-import unittest
-from importlib import resources
-from osmocom.utils import hexstr
-from pySim.esim.saip import ProfileElementSequence
-import pySim.esim.saip.personalization as p13n
-import smdpp_data.upp
-
-import xo
-update_expected_output = False
-
-def valstr(val):
-    if isinstance(val, io.BytesIO):
-        val = val.getvalue()
-    if isinstance(val, bytearray):
-        val = bytes(val)
-    return f'{val!r}'
-
-def valtypestr(val):
-    if isinstance(val, dict):
-        types = []
-        for v in val.values():
-            types.append(f'{type(v).__name__}')
-
-        val_type = '{' + ', '.join(types) + '}'
-    else:
-        val_type = f'{type(val).__name__}'
-    return f'{valstr(val)}:{val_type}'
-
-class ConfigurableParameterTest(unittest.TestCase):
-
-    def test_parameters(self):
-
-        upp_fnames = (
-                'TS48v5_SAIP2.1A_NoBERTLV.der',
-                'TS48v5_SAIP2.3_BERTLV_SUCI.der',
-                'TS48v5_SAIP2.1B_NoBERTLV.der',
-                'TS48v5_SAIP2.3_NoBERTLV.der',
-               )
-
-        class Paramtest:
-            def __init__(self, param_cls, val, expect_val, expect_clean_val=None):
-                self.param_cls = param_cls
-                self.val = val
-                self.expect_clean_val = expect_clean_val
-                self.expect_val = expect_val
-
-        param_tests = [
-            Paramtest(param_cls=p13n.Imsi, val='123456',
-                      expect_clean_val=str('123456'),
-                      expect_val={'IMSI': hexstr('123456'),
-                                  'IMSI-ACC': '0040'}),
-            Paramtest(param_cls=p13n.Imsi, val=int(123456),
-                      expect_val={'IMSI': hexstr('123456'),
-                                  'IMSI-ACC': '0040'}),
-
-            Paramtest(param_cls=p13n.Imsi, val='123456789012345',
-                      expect_clean_val=str('123456789012345'),
-                      expect_val={'IMSI': hexstr('123456789012345'),
-                                  'IMSI-ACC': '0020'}),
-            Paramtest(param_cls=p13n.Imsi, val=int(123456789012345),
-                      expect_val={'IMSI': hexstr('123456789012345'),
-                                  'IMSI-ACC': '0020'}),
-
-            Paramtest(param_cls=p13n.Puk1,
-                      val='12345678',
-                      expect_clean_val=b'12345678',
-                      expect_val='12345678'),
-            Paramtest(param_cls=p13n.Puk1,
-                      val=int(12345678),
-                      expect_clean_val=b'12345678',
-                      expect_val='12345678'),
-
-            Paramtest(param_cls=p13n.Puk2,
-                      val='12345678',
-                      expect_clean_val=b'12345678',
-                      expect_val='12345678'),
-
-            Paramtest(param_cls=p13n.Pin1,
-                      val='1234',
-                      expect_clean_val=b'1234\xff\xff\xff\xff',
-                      expect_val='1234'),
-            Paramtest(param_cls=p13n.Pin1,
-                      val='123456',
-                      expect_clean_val=b'123456\xff\xff',
-                      expect_val='123456'),
-            Paramtest(param_cls=p13n.Pin1,
-                      val='12345678',
-                      expect_clean_val=b'12345678',
-                      expect_val='12345678'),
-            Paramtest(param_cls=p13n.Pin1,
-                      val=int(1234),
-                      expect_clean_val=b'1234\xff\xff\xff\xff',
-                      expect_val='1234'),
-            Paramtest(param_cls=p13n.Pin1,
-                      val=int(123456),
-                      expect_clean_val=b'123456\xff\xff',
-                      expect_val='123456'),
-            Paramtest(param_cls=p13n.Pin1,
-                      val=int(12345678),
-                      expect_clean_val=b'12345678',
-                      expect_val='12345678'),
-
-            Paramtest(param_cls=p13n.Adm1,
-                      val='1234',
-                      expect_clean_val=b'1234\xff\xff\xff\xff',
-                      expect_val='1234'),
-            Paramtest(param_cls=p13n.Adm1,
-                      val='123456',
-                      expect_clean_val=b'123456\xff\xff',
-                      expect_val='123456'),
-            Paramtest(param_cls=p13n.Adm1,
-                      val='12345678',
-                      expect_clean_val=b'12345678',
-                      expect_val='12345678'),
-            Paramtest(param_cls=p13n.Adm1,
-                      val=int(123456),
-                      expect_clean_val=b'123456\xff\xff',
-                      expect_val='123456'),
-
-            Paramtest(param_cls=p13n.AlgorithmID,
-                      val='Milenage',
-                      expect_clean_val=1,
-                      expect_val='Milenage'),
-            Paramtest(param_cls=p13n.AlgorithmID,
-                      val='TUAK',
-                      expect_clean_val=2,
-                      expect_val='TUAK'),
-            Paramtest(param_cls=p13n.AlgorithmID,
-                      val='usim-test',
-                      expect_clean_val=3,
-                      expect_val='usim_test'),
-
-            Paramtest(param_cls=p13n.AlgorithmID,
-                      val=1,
-                      expect_clean_val=1,
-                      expect_val='Milenage'),
-            Paramtest(param_cls=p13n.AlgorithmID,
-                      val=2,
-                      expect_clean_val=2,
-                      expect_val='TUAK'),
-            Paramtest(param_cls=p13n.AlgorithmID,
-                      val=3,
-                      expect_clean_val=3,
-                      expect_val='usim_test'),
-
-            Paramtest(param_cls=p13n.K,
-                      val='01020304050607080910111213141516',
-                      expect_clean_val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_val='01020304050607080910111213141516'),
-            Paramtest(param_cls=p13n.K,
-                      val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_clean_val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_val='01020304050607080910111213141516'),
-            Paramtest(param_cls=p13n.K,
-                      val=bytearray(b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16'),
-                      expect_clean_val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_val='01020304050607080910111213141516'),
-            Paramtest(param_cls=p13n.K,
-                      val=io.BytesIO(b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16'),
-                      expect_clean_val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_val='01020304050607080910111213141516'),
-            Paramtest(param_cls=p13n.K,
-                      val=int(11020304050607080910111213141516),
-                      expect_clean_val=b'\x11\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_val='11020304050607080910111213141516'),
-
-            Paramtest(param_cls=p13n.Opc,
-                      val='01020304050607080910111213141516',
-                      expect_clean_val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_val='01020304050607080910111213141516'),
-            Paramtest(param_cls=p13n.Opc,
-                      val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_clean_val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_val='01020304050607080910111213141516'),
-            Paramtest(param_cls=p13n.Opc,
-                      val=bytearray(b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16'),
-                      expect_clean_val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_val='01020304050607080910111213141516'),
-            Paramtest(param_cls=p13n.Opc,
-                      val=io.BytesIO(b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16'),
-                      expect_clean_val=b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16',
-                      expect_val='01020304050607080910111213141516'),
-
-            Paramtest(param_cls=p13n.SmspTpScAddr,
-                      val='+1234567',
-                      expect_clean_val=(True, '1234567'),
-                      expect_val='+1234567'),
-            Paramtest(param_cls=p13n.SmspTpScAddr,
-                      val=1234567,
-                      expect_clean_val=(False, '1234567'),
-                      expect_val='1234567'),
-
-            Paramtest(param_cls=p13n.TuakNumberOfKeccak,
-                      val='123',
-                      expect_clean_val=123,
-                      expect_val='123'),
-            Paramtest(param_cls=p13n.TuakNumberOfKeccak,
-                      val=123,
-                      expect_clean_val=123,
-                      expect_val='123'),
-
-            Paramtest(param_cls=p13n.MilenageRotationConstants,
-                      val='0a 0b 0c 01 02',
-                      expect_clean_val=b'\x0a\x0b\x0c\x01\x02',
-                      expect_val='0a0b0c0102'),
-            Paramtest(param_cls=p13n.MilenageRotationConstants,
-                      val=b'\x0a\x0b\x0c\x01\x02',
-                      expect_clean_val=b'\x0a\x0b\x0c\x01\x02',
-                      expect_val='0a0b0c0102'),
-            Paramtest(param_cls=p13n.MilenageRotationConstants,
-                      val=bytearray(b'\x0a\x0b\x0c\x01\x02'),
-                      expect_clean_val=b'\x0a\x0b\x0c\x01\x02',
-                      expect_val='0a0b0c0102'),
-
-            Paramtest(param_cls=p13n.MilenageXoringConstants,
-                      val='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
-                          ' bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'
-                          ' cccccccccccccccccccccccccccccccc'
-                          ' 11111111111111111111111111111111'
-                          ' 22222222222222222222222222222222',
-                      expect_clean_val=b'\xaa' * 16
-                                       + b'\xbb' * 16
-                                       + b'\xcc' * 16
-                                       + b'\x11' * 16
-                                       + b'\x22' * 16,
-                      expect_val='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
-                                 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'
-                                 'cccccccccccccccccccccccccccccccc'
-                                 '11111111111111111111111111111111'
-                                 '22222222222222222222222222222222'),
-            Paramtest(param_cls=p13n.MilenageXoringConstants,
-                      val=b'\xaa' * 16
-                          + b'\xbb' * 16
-                          + b'\xcc' * 16
-                          + b'\x11' * 16
-                          + b'\x22' * 16,
-                      expect_clean_val=b'\xaa' * 16
-                                       + b'\xbb' * 16
-                                       + b'\xcc' * 16
-                                       + b'\x11' * 16
-                                       + b'\x22' * 16,
-                      expect_val='aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
-                                 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'
-                                 'cccccccccccccccccccccccccccccccc'
-                                 '11111111111111111111111111111111'
-                                 '22222222222222222222222222222222'),
-
-            ]
-
-        for sdkey_cls in (
-            # thin out the number of tests, as a compromise between completeness and test runtime
-            p13n.SdKeyScp02Kvn20AesDek,
-           #p13n.SdKeyScp02Kvn20AesEnc,
-           #p13n.SdKeyScp02Kvn20AesMac,
-           #p13n.SdKeyScp02Kvn21AesDek,
-            p13n.SdKeyScp02Kvn21AesEnc,
-           #p13n.SdKeyScp02Kvn21AesMac,
-           #p13n.SdKeyScp02Kvn22AesDek,
-           #p13n.SdKeyScp02Kvn22AesEnc,
-            p13n.SdKeyScp02Kvn22AesMac,
-           #p13n.SdKeyScp02KvnffAesDek,
-           #p13n.SdKeyScp02KvnffAesEnc,
-           #p13n.SdKeyScp02KvnffAesMac,
-            p13n.SdKeyScp03Kvn30AesDek,
-           #p13n.SdKeyScp03Kvn30AesEnc,
-           #p13n.SdKeyScp03Kvn30AesMac,
-           #p13n.SdKeyScp03Kvn31AesDek,
-            p13n.SdKeyScp03Kvn31AesEnc,
-           #p13n.SdKeyScp03Kvn31AesMac,
-           #p13n.SdKeyScp03Kvn32AesDek,
-           #p13n.SdKeyScp03Kvn32AesEnc,
-            p13n.SdKeyScp03Kvn32AesMac,
-           #p13n.SdKeyScp80Kvn01AesDek,
-           #p13n.SdKeyScp80Kvn01AesEnc,
-           #p13n.SdKeyScp80Kvn01AesMac,
-            p13n.SdKeyScp80Kvn01DesDek,
-           #p13n.SdKeyScp80Kvn01DesEnc,
-           #p13n.SdKeyScp80Kvn01DesMac,
-           #p13n.SdKeyScp80Kvn02AesDek,
-            p13n.SdKeyScp80Kvn02AesEnc,
-           #p13n.SdKeyScp80Kvn02AesMac,
-           #p13n.SdKeyScp80Kvn02DesDek,
-           #p13n.SdKeyScp80Kvn02DesEnc,
-            p13n.SdKeyScp80Kvn02DesMac,
-           #p13n.SdKeyScp80Kvn03AesDek,
-           #p13n.SdKeyScp80Kvn03AesEnc,
-           #p13n.SdKeyScp80Kvn03AesMac,
-            p13n.SdKeyScp80Kvn03DesDek,
-           #p13n.SdKeyScp80Kvn03DesEnc,
-           #p13n.SdKeyScp80Kvn03DesMac,
-            p13n.SdKeyScp81Kvn40AesDek,
-           #p13n.SdKeyScp81Kvn40Tlspsk,
-           #p13n.SdKeyScp81Kvn41AesDek,
-            p13n.SdKeyScp81Kvn41Tlspsk,
-           #p13n.SdKeyScp81Kvn42AesDek,
-           #p13n.SdKeyScp81Kvn42Tlspsk,
-            ):
-
-            for key_len in sdkey_cls.allow_len:
-                val = '0102030405060708091011121314151617181920212223242526272829303132'
-                expect_clean_val = (b'\x01\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16'
-                                    b'\x17\x18\x19\x20\x21\x22\x23\x24\x25\x26\x27\x28\x29\x30\x31\x32')
-                expect_val = '0102030405060708091011121314151617181920212223242526272829303132'
-
-                val = val[:key_len*2]
-                expect_clean_val = expect_clean_val[:key_len]
-                expect_val = val
-
-                param_tests.append(Paramtest(param_cls=sdkey_cls, val=val, expect_clean_val=expect_clean_val, expect_val=expect_val))
-
-                # test bytes input
-                val = expect_clean_val
-                param_tests.append(Paramtest(param_cls=sdkey_cls, val=val, expect_clean_val=expect_clean_val, expect_val=expect_val))
-
-                # test bytearray input
-                val = bytearray(expect_clean_val)
-                param_tests.append(Paramtest(param_cls=sdkey_cls, val=val, expect_clean_val=expect_clean_val, expect_val=expect_val))
-
-                # test BytesIO input
-                val = io.BytesIO(expect_clean_val)
-                param_tests.append(Paramtest(param_cls=sdkey_cls, val=val, expect_clean_val=expect_clean_val, expect_val=expect_val))
-
-                if key_len == 16:
-                    # test huge integer input.
-                    # needs to start with nonzero.. stupid
-                    val = 11020304050607080910111213141516
-                    expect_clean_val = (b'\x11\x02\x03\x04\x05\x06\x07\x08\x09\x10\x11\x12\x13\x14\x15\x16')
-                    expect_val = '11020304050607080910111213141516'
-                    param_tests.append(Paramtest(param_cls=sdkey_cls, val=val, expect_clean_val=expect_clean_val, expect_val=expect_val))
-
-        outputs = []
-
-        for upp_fname in upp_fnames:
-            test_idx = -1
-            try:
-
-                der = resources.read_binary(smdpp_data.upp, upp_fname)
-
-                for t in param_tests:
-                    test_idx += 1
-                    logloc = f'{upp_fname} {t.param_cls.__name__}(val={valtypestr(t.val)})'
-
-                    param = None
-                    try:
-                        param = t.param_cls()
-                        param.input_value = t.val
-                        param.validate()
-                    except ValueError as e:
-                        raise ValueError(f'{logloc}: {e}') from e
-
-                    clean_val = param.value
-                    logloc = f'{logloc} clean_val={valtypestr(clean_val)}'
-                    if t.expect_clean_val is not None and t.expect_clean_val != clean_val:
-                        raise ValueError(f'{logloc}: expected'
-                                         f' expect_clean_val={valtypestr(t.expect_clean_val)}')
-
-                    # on my laptop, deepcopy is about 30% slower than decoding the DER from scratch:
-                    # pes = copy.deepcopy(orig_pes)
-                    pes = ProfileElementSequence.from_der(der)
-                    try:
-                        param.apply(pes)
-                    except ValueError as e:
-                        raise ValueError(f'{logloc} apply_val(clean_val): {e}') from e
-
-                    changed_der = pes.to_der()
-
-                    pes2 = ProfileElementSequence.from_der(changed_der)
-
-                    read_back_val = t.param_cls.get_value_from_pes(pes2)
-
-                    # compose log string to show the precise type of dict values
-                    if isinstance(read_back_val, dict):
-                        types = set()
-                        for v in read_back_val.values():
-                            types.add(f'{type(v).__name__}')
-
-                        read_back_val_type = '{' + ', '.join(types) + '}'
-                    else:
-                        read_back_val_type = f'{type(read_back_val).__name__}'
-
-                    logloc = (f'{logloc} read_back_val={valtypestr(read_back_val)}')
-
-                    if isinstance(read_back_val, dict) and not t.param_cls.get_name() in read_back_val.keys():
-                        raise ValueError(f'{logloc}: expected to find name {t.param_cls.get_name()!r} in read_back_val')
-
-                    expect_val = t.expect_val
-                    if not isinstance(expect_val, dict):
-                        expect_val = { t.param_cls.get_name(): expect_val }
-                    if read_back_val != expect_val:
-                        raise ValueError(f'{logloc}: expected {expect_val=!r}:{type(t.expect_val).__name__}')
-
-                    ok = logloc.replace(' clean_val', '\n\tclean_val'
-                              ).replace(' read_back_val', '\n\tread_back_val'
-                              ).replace('=', '=\t'
-                              )
-                    output = f'\nok: {ok}'
-                    outputs.append(output)
-                    print(output)
-
-            except Exception as e:
-                raise RuntimeError(f'Error while testing UPP {upp_fname} {test_idx=}: {e}') from e
-
-        output = '\n'.join(outputs) + '\n'
-        xo_name = 'test_configurable_parameters'
-        if update_expected_output:
-            with resources.path(xo, xo_name) as xo_path:
-                with open(xo_path, 'w', encoding='utf-8') as f:
-                    f.write(output)
-        else:
-            xo_str = resources.read_text(xo, xo_name)
-            if xo_str != output:
-                at = 0
-                while at < len(output):
-                    if output[at] == xo_str[at]:
-                        at += 1
-                        continue
-                    break
-
-                raise RuntimeError(f'output differs from expected output at position {at}: "{output[at:at+20]}" != "{xo_str[at:at+20]}"')
-
-
-class TestValidateVal(unittest.TestCase):
-    """validate_val() tests for various ConfigurableParameter subclasses."""
-
-    def _ok(self, cls, val, expected=None):
-        result = cls.validate_val(val)
-        if expected is not None:
-            self.assertEqual(result, expected)
-        return result
-
-    def _err(self, cls, val):
-        with self.assertRaises(ValueError):
-            cls.validate_val(val)
-
-    # --- Iccid ---
-
-    def test_iccid_18digits_adds_luhn(self):
-        result = self._ok(p13n.Iccid, '998877665544332211')
-        self.assertIsInstance(result, str)
-        self.assertEqual(len(result), 19)
-        self.assertTrue(result.isdecimal())
-
-    def test_iccid_19digits_passthrough(self):
-        result = self._ok(p13n.Iccid, '9988776655443322110')
-        self.assertIsInstance(result, str)
-        self.assertEqual(len(result), 19)
-
-    def test_iccid_too_short(self):
-        self._err(p13n.Iccid, '12345678901234567')  # 17 digits
-
-    def test_iccid_too_long(self):
-        self._err(p13n.Iccid, '1' * 21)
-
-    def test_iccid_non_digits(self):
-        self._err(p13n.Iccid, '99887766554433221X')
-
-    # --- Imsi ---
-
-    def test_imsi_valid_short(self):
-        self._ok(p13n.Imsi, '001010', '001010')
-
-    def test_imsi_valid_long(self):
-        self._ok(p13n.Imsi, '001010123456789', '001010123456789')
-
-    def test_imsi_too_short(self):
-        self._err(p13n.Imsi, '12345')  # 5 digits, min is 6
-
-    def test_imsi_too_long(self):
-        self._err(p13n.Imsi, '1' * 16)
-
-    def test_imsi_non_digits(self):
-        self._err(p13n.Imsi, '00101A123456789')
-
-    # --- Pin1 ---
-
-    def test_pin1_4digits(self):
-        # DecimalHexParam encodes each digit as its ASCII byte, then rpad to 8 bytes with 0xff
-        self._ok(p13n.Pin1, '1234', b'1234\xff\xff\xff\xff')
-
-    def test_pin1_8digits(self):
-        self._ok(p13n.Pin1, '12345678', b'12345678')
-
-    def test_pin1_too_short(self):
-        self._err(p13n.Pin1, '123')
-
-    def test_pin1_too_long(self):
-        self._err(p13n.Pin1, '123456789')
-
-    def test_pin1_non_digits(self):
-        self._err(p13n.Pin1, '123A')
-
-    # --- Puk1 ---
-
-    def test_puk1_8digits(self):
-        self._ok(p13n.Puk1, '12345678', b'12345678')
-
-    def test_puk1_wrong_length(self):
-        self._err(p13n.Puk1, '1234567')   # 7 digits
-        self._err(p13n.Puk1, '123456789')  # 9 digits
-
-    def test_puk1_non_digits(self):
-        self._err(p13n.Puk1, '1234567X')
-
-    # --- K (BinaryParam) ---
-
-    def test_k_valid_hex_str(self):
-        self._ok(p13n.K, '000102030405060708090a0b0c0d0e0f',
-                 b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f')
-
-    def test_k_valid_bytes(self):
-        raw = bytes(range(16))
-        self._ok(p13n.K, raw, raw)
-
-    def test_k_wrong_length(self):
-        self._err(p13n.K, '00' * 15)  # 15 bytes, allow_len requires 16 or 32
-
-    def test_k_non_hex(self):
-        self._err(p13n.K, 'gg' * 16)
-
-    def test_k_odd_hex_digits(self):
-        self._err(p13n.K, '0' * 31)   # odd number of hex digits
-
-
-class TestEnumParam(unittest.TestCase):
-    """Tests for the EnumParam machinery, using AlgorithmID as the concrete subclass."""
-
-    # --- validate_val ---
-
-    def test_validate_by_name_exact(self):
-        self.assertEqual(p13n.AlgorithmID.validate_val('Milenage'), 1)
-        self.assertEqual(p13n.AlgorithmID.validate_val('TUAK'), 2)
-        self.assertEqual(p13n.AlgorithmID.validate_val('usim_test'), 3)
-
-    def test_validate_by_int(self):
-        self.assertEqual(p13n.AlgorithmID.validate_val(1), 1)
-        self.assertEqual(p13n.AlgorithmID.validate_val(2), 2)
-        self.assertEqual(p13n.AlgorithmID.validate_val(3), 3)
-
-    def test_validate_fuzzy_case(self):
-        self.assertEqual(p13n.AlgorithmID.validate_val('milenage'), 1)
-        self.assertEqual(p13n.AlgorithmID.validate_val('MILENAGE'), 1)
-        self.assertEqual(p13n.AlgorithmID.validate_val('tuak'), 2)
-
-    def test_validate_fuzzy_hyphen_underscore(self):
-        # 'usim-test' has a hyphen; enum member is 'usim_test' — must fuzzy-match
-        self.assertEqual(p13n.AlgorithmID.validate_val('usim-test'), 3)
-
-    def test_validate_invalid_name(self):
-        with self.assertRaises(ValueError):
-            p13n.AlgorithmID.validate_val('unknown')
-
-    def test_validate_invalid_int(self):
-        with self.assertRaises(ValueError):
-            p13n.AlgorithmID.validate_val(99)
-
-    def test_validate_returns_int(self):
-        result = p13n.AlgorithmID.validate_val('Milenage')
-        self.assertIsInstance(result, int)
-        self.assertNotIsInstance(result, enum.Enum)
-
-    # --- map_name_to_val ---
-
-    def test_map_name_exact(self):
-        self.assertEqual(p13n.AlgorithmID.map_name_to_val('Milenage'), 1)
-
-    def test_map_name_fuzzy(self):
-        self.assertEqual(p13n.AlgorithmID.map_name_to_val('milenage'), 1)
-        self.assertEqual(p13n.AlgorithmID.map_name_to_val('usim-test'), 3)
-
-    def test_map_name_strict_raises(self):
-        with self.assertRaises(ValueError):
-            p13n.AlgorithmID.map_name_to_val('unknown', strict=True)
-
-    def test_map_name_nonstrict_returns_none(self):
-        self.assertIsNone(p13n.AlgorithmID.map_name_to_val('unknown', strict=False))
-
-    # --- map_val_to_name ---
-
-    def test_map_val_known(self):
-        self.assertEqual(p13n.AlgorithmID.map_val_to_name(1), 'Milenage')
-        self.assertEqual(p13n.AlgorithmID.map_val_to_name(2), 'TUAK')
-        self.assertEqual(p13n.AlgorithmID.map_val_to_name(3), 'usim_test')
-
-    def test_map_val_unknown_nonstrict(self):
-        self.assertIsNone(p13n.AlgorithmID.map_val_to_name(99))
-
-    def test_map_val_unknown_strict(self):
-        with self.assertRaises(ValueError):
-            p13n.AlgorithmID.map_val_to_name(99, strict=True)
-
-    # --- name_normalize ---
-
-    def test_name_normalize(self):
-        self.assertEqual(p13n.AlgorithmID.name_normalize('Milenage'), 'Milenage')
-        self.assertEqual(p13n.AlgorithmID.name_normalize('milenage'), 'Milenage')
-        self.assertEqual(p13n.AlgorithmID.name_normalize('usim-test'), 'usim_test')
-
-    # --- clean_name_str ---
-
-    def test_clean_name_str(self):
-        self.assertEqual(p13n.AlgorithmID.clean_name_str('usim-test'), 'usimtest')
-        self.assertEqual(p13n.AlgorithmID.clean_name_str('usim_test'), 'usimtest')
-        self.assertEqual(p13n.AlgorithmID.clean_name_str('Milenage'), 'milenage')
-        self.assertEqual(p13n.AlgorithmID.clean_name_str('foo bar!'), 'foobar')
-
-
-if __name__ == "__main__":
-    if '-u' in sys.argv:
-        update_expected_output = True
-        sys.argv.remove('-u')
-    unittest.main()

tests/unittests/test_esim_saip.py

@@ -21,7 +21,7 @@ import copy
 from osmocom.utils import h2b, b2h
 
 from pySim.esim.saip import *
-from pySim.esim.saip import personalization
+from pySim.esim.saip.personalization import *
 from pprint import pprint as pp
 
 
@@ -55,56 +55,14 @@ class SaipTest(unittest.TestCase):
     def test_personalization(self):
         """Test some of the personalization operations."""
         pes = copy.deepcopy(self.pes)
-        params = [personalization.Puk1('01234567'),
-                  personalization.Puk2(98765432),
-                  personalization.Pin1('1111'),
-                  personalization.Pin2(2222),
-                  personalization.Adm1('11111111'),
-                  personalization.K(h2b('000102030405060708090a0b0c0d0e0f')),
-                  personalization.Opc(h2b('101112131415161718191a1b1c1d1e1f'))]
+        params = [Puk1('01234567'), Puk2(98765432), Pin1('1111'), Pin2(2222), Adm1('11111111'),
+                  K(h2b('000102030405060708090a0b0c0d0e0f')), Opc(h2b('101112131415161718191a1b1c1d1e1f'))]
         for p in params:
             p.validate()
             p.apply(pes)
         # TODO: we don't actually test the results here, but we just verify there is no exception
         pes.to_der()
 
-    def test_personalization2(self):
-        """Test some of the personalization operations."""
-        cls = personalization.SdKeyScp80Kvn01DesEnc
-        pes = ProfileElementSequence.from_der(self.per_input)
-        prev_val = tuple(cls.get_values_from_pes(pes))
-        print(f'{prev_val=}')
-        self.assertTrue(prev_val)
-
-        set_val = '42342342342342342342342342342342'
-        param = cls(set_val)
-        param.validate()
-        param.apply(pes)
-
-        get_val1 = tuple(cls.get_values_from_pes(pes))
-        print(f'{get_val1=} {set_val=}')
-        self.assertEqual(get_val1, ({cls.name: set_val},))
-
-        get_val1b = tuple(cls.get_values_from_pes(pes))
-        print(f'{get_val1b=} {set_val=}')
-        self.assertEqual(get_val1b, ({cls.name: set_val},))
-
-        der = pes.to_der()
-
-        get_val1c = tuple(cls.get_values_from_pes(pes))
-        print(f'{get_val1c=} {set_val=}')
-        self.assertEqual(get_val1c, ({cls.name: set_val},))
-
-        # assertTrue to not dump the entire der.
-        # Expecting the modified DER to be different. If this assertion fails, then no change has happened in the output
-        # DER and the ConfigurableParameter subclass is buggy.
-        self.assertTrue(der != self.per_input)
-
-        pes2 = ProfileElementSequence.from_der(der)
-        get_val2 = tuple(cls.get_values_from_pes(pes2))
-        print(f'{get_val2=} {set_val=}')
-        self.assertEqual(get_val2, ({cls.name: set_val},))
-
     def test_constructor_encode(self):
         """Test that DER-encoding of PE created by "empty" constructor works without raising exception."""
         for cls in [ProfileElementMF, ProfileElementPuk, ProfileElementPin, ProfileElementTelecom,

tests/unittests/test_param_src.py

@@ -1,206 +0,0 @@
-#!/usr/bin/env python3
-
-# (C) 2025 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de>
-#
-# Author: Neels Hofmeyr
-#
-# 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 math
-from importlib import resources
-import unittest
-from pySim.esim.saip import param_source
-
-import xo
-update_expected_output = False
-
-class D:
-    mandatory = set()
-    optional = set()
-
-    def __init__(self, **kwargs):
-        if (set(kwargs.keys()) - set(self.optional)) != set(self.mandatory):
-            raise RuntimeError(f'{self.__class__.__name__}.__init__():'
-                               f' {set(kwargs.keys())=!r} - {self.optional=!r} != {self.mandatory=!r}')
-        for k, v in kwargs.items():
-            setattr(self, k, v)
-        for k in self.optional:
-            if not hasattr(self, k):
-                setattr(self, k, None)
-
-decimals = '0123456789'
-hexadecimals = '0123456789abcdefABCDEF'
-
-class FakeRandom:
-    vals = b'\xab\xcfm\xf0\x98J_\xcf\x96\x87fp5l\xe7f\xd1\xd6\x97\xc1\xf9]\x8c\x86+\xdb\t^ke\xc1r'
-    i = 0
-
-    @classmethod
-    def next(cls):
-        cls.i = (cls.i + 1) % len(cls.vals)
-        return cls.vals[cls.i]
-
-    @staticmethod
-    def randint(a, b):
-        d = b - a
-        n_bytes = math.ceil(math.log(d, 2))
-        r = int.from_bytes( bytes(FakeRandom.next() for i in range(n_bytes)) )
-        return a + (r % (b - a))
-
-    @staticmethod
-    def randbytes(n):
-        return bytes(FakeRandom.next() for i in range(n))
-
-
-class ParamSourceTest(unittest.TestCase):
-
-    def test_param_source(self):
-
-        class Paramtest(D):
-            mandatory = (
-                    'param_source',
-                    'n',
-                    'expect',
-                    )
-            optional = (
-                    'expect_arg',
-                    'csv_rows',
-                    )
-            param_source: param_source.ParamSource
-            n: int
-            expect: object
-            expect_arg: object
-            csv_rows: object
-
-        def expect_const(t, vals):
-            return tuple(t.expect_arg) == tuple(vals)
-
-        def expect_random(t, vals):
-            chars = t.expect_arg.get('digits')
-            repetitions = (t.n - len(set(vals)))
-            if repetitions:
-                raise RuntimeError(f'expect_random: there are {repetitions} repetitions in the returned values: {vals}')
-            for val_i in range(len(vals)):
-                v = vals[val_i]
-                val_minlen = t.expect_arg.get('val_minlen')
-                val_maxlen = t.expect_arg.get('val_maxlen')
-                if len(v) < val_minlen or len(v) > val_maxlen:
-                    raise RuntimeError(f'expect_random: invalid length {len(v)} for value [{val_i}]: {v!r}, expecting'
-                                       f' {val_minlen}..{val_maxlen}')
-
-                if chars is not None and not all(c in chars for c in v):
-                    raise RuntimeError(f'expect_random: invalid char in value [{val_i}]: {v!r}')
-            return True
-
-        param_source_tests = [
-            Paramtest(param_source=param_source.ConstantSource.from_str('123'),
-                      n=3,
-                      expect=expect_const,
-                      expect_arg=('123', '123', '123')),
-            Paramtest(param_source=param_source.RandomDigitSource.from_str('12345'),
-                      n=3,
-                      expect=expect_random,
-                      expect_arg={'digits': decimals,
-                                  'val_minlen': 5,
-                                  'val_maxlen': 5}),
-            Paramtest(param_source=param_source.RandomDigitSource.from_str('1..999'),
-                      n=10,
-                      expect=expect_random,
-                      expect_arg={'digits': decimals,
-                                  'val_minlen': 1,
-                                  'val_maxlen': 3}),
-            Paramtest(param_source=param_source.RandomDigitSource.from_str('001..999'),
-                      n=10,
-                      expect=expect_random,
-                      expect_arg={'digits': decimals,
-                                  'val_minlen': 3,
-                                  'val_maxlen': 3}),
-            Paramtest(param_source=param_source.RandomHexDigitSource.from_str('12345678'),
-                      n=3,
-                      expect=expect_random,
-                      expect_arg={'digits': hexadecimals,
-                                  'val_minlen': 8,
-                                  'val_maxlen': 8}),
-            Paramtest(param_source=param_source.RandomHexDigitSource.from_str('0*8'),
-                      n=3,
-                      expect=expect_random,
-                      expect_arg={'digits': hexadecimals,
-                                  'val_minlen': 8,
-                                  'val_maxlen': 8}),
-            Paramtest(param_source=param_source.RandomHexDigitSource.from_str('00*4'),
-                      n=3,
-                      expect=expect_random,
-                      expect_arg={'digits': hexadecimals,
-                                  'val_minlen': 8,
-                                  'val_maxlen': 8}),
-            Paramtest(param_source=param_source.IncDigitSource.from_str('10001'),
-                      n=3,
-                      expect=expect_const,
-                      expect_arg=('10001', '10002', '10003')),
-            Paramtest(param_source=param_source.CsvSource('column_name'),
-                      n=3,
-                      expect=expect_const,
-                      expect_arg=('first val', 'second val', 'third val'),
-                      csv_rows=(
-                          {'column_name': 'first val'},
-                          {'column_name': 'second val'},
-                          {'column_name': 'third val'},
-                      )),
-            ]
-
-        outputs = []
-
-        for t in param_source_tests:
-            try:
-                if hasattr(t.param_source, 'random_impl'):
-                    t.param_source.random_impl = FakeRandom
-
-                vals = []
-                for i in range(t.n):
-                    csv_row = None
-                    if t.csv_rows is not None:
-                        csv_row = t.csv_rows[i]
-                    vals.append( t.param_source.get_next(csv_row=csv_row) )
-                if not t.expect(t, vals):
-                    raise RuntimeError(f'invalid values returned: returned {vals}')
-                output = f'ok: {t.param_source.__class__.__name__} {vals=!r}'
-                outputs.append(output)
-                print(output)
-            except RuntimeError as e:
-                raise RuntimeError(f'{t.param_source.__class__.__name__} {t.n=} {t.expect.__name__}({t.expect_arg!r}): {e}') from e
-
-        output = '\n'.join(outputs) + '\n'
-        xo_name = 'test_param_src'
-        if update_expected_output:
-            with resources.path(xo, xo_name) as xo_path:
-                with open(xo_path, 'w', encoding='utf-8') as f:
-                    f.write(output)
-        else:
-            xo_str = resources.read_text(xo, xo_name)
-            if xo_str != output:
-                at = 0
-                while at < len(output):
-                    if output[at] == xo_str[at]:
-                        at += 1
-                        continue
-                    break
-
-                raise RuntimeError(f'output differs from expected output at position {at}: {xo_str[at:at+128]!r}')
-
-if __name__ == "__main__":
-    if '-u' in sys.argv:
-        update_expected_output = True
-        sys.argv.remove('-u')
-    unittest.main()

tests/unittests/xo/test_param_src

@@ -1,9 +0,0 @@
-ok: ConstantSource vals=['123', '123', '123']
-ok: RandomDigitSource vals=['13987', '49298', '55670']
-ok: RandomDigitSource vals=['650', '580', '49', '885', '497', '195', '320', '137', '245', '663']
-ok: RandomDigitSource vals=['638', '025', '232', '779', '826', '972', '650', '580', '049', '885']
-ok: RandomHexDigitSource vals=['6b65c172', 'abcf6df0', '984a5fcf']
-ok: RandomHexDigitSource vals=['96876670', '356ce766', 'd1d697c1']
-ok: RandomHexDigitSource vals=['f95d8c86', '2bdb095e', '6b65c172']
-ok: IncDigitSource vals=['10001', '10002', '10003']
-ok: CsvSource vals=['first val', 'second val', 'third val']