docs/smpp-ota-tool: Add documentation/tutorial

We already have documentation that explains how to run pySim-smpp2sim.
With smpp-ota-tool we now have a counterpart for pySim-smpp2sim, so
let's add documentation for this tool as well.

Related: SYS#7881
Change-Id: If0d18a263f5a6dc035b90f5c5c6a942d46bbba49

pySim/ara_m.py

@@ -72,10 +72,10 @@ class ApduArDO(BER_TLV_IE, tag=0xd0):
             if do[0] == 0x01:
                 self.decoded = {'generic_access_rule': 'always'}
                 return self.decoded
-            raise ValueError('Invalid 1-byte generic APDU access rule')
+            return ValueError('Invalid 1-byte generic APDU access rule')
         else:
             if len(do) % 8:
-                raise ValueError('Invalid non-modulo-8 length of APDU filter: %d' % len(do))
+                return ValueError('Invalid non-modulo-8 length of APDU filter: %d' % len(do))
             self.decoded = {'apdu_filter': []}
             offset = 0
             while offset < len(do):
@@ -90,19 +90,19 @@ class ApduArDO(BER_TLV_IE, tag=0xd0):
                 return b'\x00'
             if self.decoded['generic_access_rule'] == 'always':
                 return b'\x01'
-            raise ValueError('Invalid 1-byte generic APDU access rule')
+            return ValueError('Invalid 1-byte generic APDU access rule')
         else:
             if not 'apdu_filter' in self.decoded:
-                raise ValueError('Invalid APDU AR DO')
+                return ValueError('Invalid APDU AR DO')
             filters = self.decoded['apdu_filter']
             res = b''
             for f in filters:
                 if not 'header' in f or not 'mask' in f:
-                    raise ValueError('APDU filter must contain header and mask')
+                    return ValueError('APDU filter must contain header and mask')
                 header_b = h2b(f['header'])
                 mask_b = h2b(f['mask'])
                 if len(header_b) != 4 or len(mask_b) != 4:
-                    raise ValueError('APDU filter header and mask must each be 4 bytes')
+                    return ValueError('APDU filter header and mask must each be 4 bytes')
                 res += header_b + mask_b
             return res
 
@@ -269,7 +269,7 @@ class ADF_ARAM(CardADF):
             cmd_do_enc = cmd_do.to_ie()
             cmd_do_len = len(cmd_do_enc)
             if cmd_do_len > 255:
-                raise ValueError('DO > 255 bytes not supported yet')
+                return ValueError('DO > 255 bytes not supported yet')
         else:
             cmd_do_enc = b''
             cmd_do_len = 0
@@ -361,7 +361,7 @@ class ADF_ARAM(CardADF):
                 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)}')
+                    return ValueError('Invalid non-modulo-16 length of APDU filter: %d' % len(do))
                 offset = 0
                 apdu_filter = []
                 while offset < len(opts.apdu_filter):

pySim/cdma_ruim.py

@@ -128,10 +128,10 @@ class EF_AD(TransparentEF):
         cell_test = 0x04
 
     def __init__(self, fid='6f43', sfid=None, name='EF.AD',
-                 desc='Administrative Data', size=(3, None), **kwargs):
+                 desc='Service Provider Name', size=(3, None), **kwargs):
         super().__init__(fid, sfid=sfid, name=name, desc=desc, size=size, **kwargs)
         self._construct = Struct(
-            # Byte 1: MS operation mode
+            # Byte 1: Display Condition
             'ms_operation_mode'/Enum(Byte, self.OP_MODE),
             # Bytes 2-3: Additional information
             'additional_info'/Bytes(2),

pySim/esim/http_json_api.py

@@ -19,7 +19,7 @@ import abc
 import requests
 import logging
 import json
-from typing import Optional, Tuple
+from typing import Optional
 import base64
 from twisted.web.server import Request
 
@@ -180,7 +180,7 @@ class JsonHttpApiFunction(abc.ABC):
     # receives from the a requesting client. The same applies vice versa to class variables that have an "output_"
     # prefix.
 
-    # path of the API function (e.g. '/gsma/rsp2/es2plus/confirmOrder', see also method rewrite_url).
+    # path of the API function (e.g. '/gsma/rsp2/es2plus/confirmOrder')
     path = None
 
     # dictionary of input parameters. key is parameter name, value is ApiParam class
@@ -336,22 +336,6 @@ class JsonHttpApiFunction(abc.ABC):
                 output[p] = p_class.decode(v)
         return output
 
-    def rewrite_url(self, data: dict, url: str) -> Tuple[dict, str]:
-        """
-        Rewrite a static URL using information passed in the data dict. This method may be overloaded by a derived
-        class to allow fully dynamic URLs. The input parameters required for the URL rewriting may be passed using
-        data parameter. In case those parameters are additional parameters that are not intended to be passed to
-        the encode_client method later, they must be removed explcitly.
-
-        Args:
-                data: (see JsonHttpApiClient and JsonHttpApiServer)
-                url: statically generated URL string (see comment in JsonHttpApiClient)
-        """
-
-        # This implementation is a placeholder in which we do not perform any URL rewriting. We just pass through data
-        # and url unmodified.
-        return data, url
-
 class JsonHttpApiClient():
     def __init__(self, api_func: JsonHttpApiFunction, url_prefix: str, func_req_id: Optional[str],
                  session: requests.Session):
@@ -368,16 +352,8 @@ class JsonHttpApiClient():
         self.session = session
 
     def call(self, data: dict, func_call_id: Optional[str] = None, timeout=10) -> Optional[dict]:
-        """
+        """Make an API call to the HTTP API endpoint represented by this object. Input data is passed in `data` as
-        Make an API call to the HTTP API endpoint represented by this object. Input data is passed in `data` as
+        json-serializable dict. Output data is returned as json-deserialized dict."""
-        json-serializable fields. `data` may also contain additional parameters required for URL rewriting (see
-        rewrite_url in class JsonHttpApiFunction). Output data is returned as json-deserialized dict.
-
-        Args:
-                data: Input data required to perform the request.
-                func_call_id: Function Call Identifier, if present a header field is generated automatically.
-                timeout: Maximum amount of time to wait for the request to complete.
-        """
 
         # In case a function caller ID is supplied, use it together with the stored function requestor ID to generate
         # and prepend the header field according to SGP.22, section 6.5.1.1 and 6.5.1.3. (the presence of the header
@@ -386,11 +362,6 @@ class JsonHttpApiClient():
             data = {'header' : {'functionRequesterIdentifier': self.func_req_id,
                                 'functionCallIdentifier': func_call_id}} | data
 
-        # The URL used for the HTTP request (see below) normally consists of the initially given url_prefix
-        # concatenated with the path defined by the JsonHttpApiFunction definition. This static URL path may be
-        # rewritten by rewrite_url method defined in the JsonHttpApiFunction.
-        data, url = self.api_func.rewrite_url(data, self.url_prefix + self.api_func.path)
-
         # Encode the message (the presence of mandatory fields is checked during encoding)
         encoded = json.dumps(self.api_func.encode_client(data))
 
@@ -402,6 +373,7 @@ class JsonHttpApiClient():
         req_headers.update(self.api_func.extra_http_req_headers)
 
         # Perform HTTP request
+        url = self.url_prefix + self.api_func.path
         logger.debug("HTTP REQ %s - hdr: %s '%s'" % (url, req_headers, encoded))
         response = self.session.request(self.api_func.http_method, url, data=encoded, headers=req_headers, timeout=timeout)
         logger.debug("HTTP RSP-STS: [%u] hdr: %s" % (response.status_code, response.headers))

pySim/esim/saip/__init__.py

@@ -151,8 +151,6 @@ class File:
         self.df_name = None
         self.fill_pattern = None
         self.fill_pattern_repeat = False
-        self.pstdo = None # pinStatusTemplateDO, mandatory for DF/ADF
-        self.lcsi = None # optional life cycle status indicator
         # apply some defaults from profile
         if self.template:
             self.from_template(self.template)
@@ -280,8 +278,6 @@ class File:
         elif self.file_type in ['MF', 'DF', 'ADF']:
             fdb_dec['file_type'] = 'df'
             fdb_dec['structure'] = 'no_info_given'
-            # pinStatusTemplateDO is mandatory for DF/ADF
-            fileDescriptor['pinStatusTemplateDO'] = self.pstdo
         # build file descriptor based on above input data
         fd_dict = {}
         if len(fdb_dec):
@@ -308,8 +304,6 @@ class File:
             # desired fill or repeat pattern in the "proprietaryEFInfo" element for the EF in Profiles
             # downloaded to a V2.2 or earlier eUICC.
             fileDescriptor['proprietaryEFInfo'] = pefi
-        if self.lcsi:
-            fileDescriptor['lcsi'] = self.lcsi
         logger.debug("%s: to_fileDescriptor(%s)" % (self, fileDescriptor))
         return fileDescriptor
 
@@ -329,8 +323,6 @@ class File:
         if efFileSize:
             self._file_size = self._decode_file_size(efFileSize)
 
-        self.pstdo = fileDescriptor.get('pinStatusTemplateDO', None)
-        self.lcsi = fileDescriptor.get('lcsi', None)
         pefi = fileDescriptor.get('proprietaryEFInfo', {})
         securityAttributesReferenced = fileDescriptor.get('securityAttributesReferenced', None)
         if securityAttributesReferenced:
@@ -441,7 +433,7 @@ class File:
             elif k == 'fillFileContent':
                 stream.write(v)
             else:
-                raise ValueError("Unknown key '%s' in tuple list" % k)
+                return ValueError("Unknown key '%s' in tuple list" % k)
         return stream.getvalue()
 
     def file_content_to_tuples(self, optimize:bool = False) -> List[Tuple]:

pySim/global_platform/__init__.py

@@ -276,7 +276,7 @@ class ListOfSupportedOptions(BER_TLV_IE, tag=0x81):
 class SupportedKeysForScp03(BER_TLV_IE, tag=0x82):
     _construct = FlagsEnum(Byte, aes128=0x01, aes192=0x02, aes256=0x04)
 class SupportedTlsCipherSuitesForScp81(BER_TLV_IE, tag=0x83):
-    _construct = GreedyRange(Int16ub)
+    _consuruct = GreedyRange(Int16ub)
 class ScpInformation(BER_TLV_IE, tag=0xa0, nested=[ScpType, ListOfSupportedOptions, SupportedKeysForScp03,
                                                    SupportedTlsCipherSuitesForScp81]):
     pass
@@ -319,7 +319,7 @@ class CurrentSecurityLevel(BER_TLV_IE, tag=0xd3):
 # GlobalPlatform v2.3.1 Section 11.3.3.1.3
 class ApplicationAID(BER_TLV_IE, tag=0x4f):
     _construct = GreedyBytes
-class ApplicationTemplate(BER_TLV_IE, tag=0x61, nested=[ApplicationAID]):
+class ApplicationTemplate(BER_TLV_IE, tag=0x61, ntested=[ApplicationAID]):
     pass
 class ListOfApplications(BER_TLV_IE, tag=0x2f00, nested=[ApplicationTemplate]):
     pass
@@ -562,14 +562,14 @@ class ADF_SD(CardADF):
 
         @cmd2.with_argparser(store_data_parser)
         def do_store_data(self, opts):
-            """Perform the GlobalPlatform STORE DATA command in order to store some card-specific data.
+            """Perform the GlobalPlatform GET DATA command in order to store some card-specific data.
-            See GlobalPlatform CardSpecification v2.3 Section 11.11 for details."""
+            See GlobalPlatform CardSpecification v2.3Section 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.
+            """Perform the GlobalPlatform GET DATA command in order to store some card-specific data.
-            See GlobalPlatform CardSpecification v2.3 Section 11.11 for details."""
+            See GlobalPlatform CardSpecification v2.3Section 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
@@ -585,7 +585,7 @@ class ADF_SD(CardADF):
                 data, _sw = self._cmd.lchan.scc.send_apdu_checksw(hdr + b2h(chunk) + "00")
                 block_nr += 1
                 response += data
-            return h2b(response)
+            return data
 
         put_key_parser = argparse.ArgumentParser()
         put_key_parser.add_argument('--old-key-version-nr', type=auto_uint8, default=0, help='Old Key Version Number')

pySim/global_platform/scp.py

@@ -266,13 +266,11 @@ class SCP02(SCP):
         super().__init__(*args, **kwargs)
 
     def dek_encrypt(self, plaintext:bytes) -> bytes:
-        # See also GPC section B.1.1.2, E.4.7, and E.4.1
+        cipher = DES.new(self.card_keys.dek[:8], DES.MODE_ECB)
-        cipher = DES3.new(self.sk.data_enc, DES.MODE_ECB)
         return cipher.encrypt(plaintext)
 
     def dek_decrypt(self, ciphertext:bytes) -> bytes:
-        # See also GPC section B.1.1.2, E.4.7, and E.4.1
+        cipher = DES.new(self.card_keys.dek[:8], DES.MODE_ECB)
-        cipher = DES3.new(self.sk.data_enc, DES.MODE_ECB)
         return cipher.decrypt(ciphertext)
 
     def _compute_cryptograms(self, card_challenge: bytes, host_challenge: bytes):
@@ -438,7 +436,7 @@ class Scp03SessionKeys:
         """Obtain the ICV value computed as described in 6.2.6.
         This method has two modes:
             * is_response=False for computing the ICV for C-ENC. Will pre-increment the counter.
-            * is_response=True for computing the ICV for R-DEC."""
+            * is_response=False for computing the ICV for R-DEC."""
         if not is_response:
             self.block_nr += 1
         # The binary value of this number SHALL be left padded with zeroes to form a full block.

pySim/ota.py

@@ -221,12 +221,12 @@ class OtaAlgoCrypt(OtaAlgo, abc.ABC):
         for subc in cls.__subclasses__():
             if subc.enum_name == otak.algo_crypt:
                 return subc(otak)
-        raise ValueError('No implementation for crypt algorithm %s' % otak.algo_crypt)
+        raise ValueError('No implementation for crypt algorithm %s' % otak.algo_auth)
 
 class OtaAlgoAuth(OtaAlgo, abc.ABC):
     def __init__(self, otak: OtaKeyset):
         if self.enum_name != otak.algo_auth:
-            raise ValueError('Cannot use algorithm %s with key for %s' % (self.enum_name, otak.algo_auth))
+            raise ValueError('Cannot use algorithm %s with key for %s' % (self.enum_name, otak.algo_crypt))
         super().__init__(otak)
 
     def sign(self, data:bytes) -> bytes:

pySim/sms.py

@@ -169,14 +169,8 @@ class SMS_TPDU(abc.ABC):
 
 class SMS_DELIVER(SMS_TPDU):
     """Representation of a SMS-DELIVER T-PDU. This is the Network to MS/UE (downlink) direction."""
-    flags_construct = BitStruct('tp_rp'/Flag,
+    flags_construct = BitStruct('tp_rp'/Flag, 'tp_udhi'/Flag, 'tp_rp'/Flag, 'tp_sri'/Flag,
-                                'tp_udhi'/Flag,
+                                Padding(1), 'tp_mms'/Flag, 'tp_mti'/BitsInteger(2))
-                                'tp_sri'/Flag,
-                                Padding(1),
-                                'tp_lp'/Flag,
-                                'tp_mms'/Flag,
-                                'tp_mti'/BitsInteger(2))
-
     def __init__(self, **kwargs):
         kwargs['tp_mti'] = 0
         super().__init__(**kwargs)

pySim/ts_31_102.py

@@ -1058,7 +1058,7 @@ class EF_OCSGL(LinFixedEF):
 # TS 31.102 Section 4.4.11.2 (Rel 15)
 class EF_5GS3GPPLOCI(TransparentEF):
     def __init__(self, fid='4f01', sfid=0x01, name='EF.5GS3GPPLOCI', size=(20, 20),
-                 desc='5GS 3GPP location information', **kwargs):
+                 desc='5S 3GP location information', **kwargs):
         super().__init__(fid, sfid=sfid, name=name, desc=desc, size=size, **kwargs)
         upd_status_constr = Enum(
             Byte, updated=0, not_updated=1, roaming_not_allowed=2)
@@ -1326,7 +1326,7 @@ class EF_5G_PROSE_UIR(TransparentEF):
         pass
     class FiveGDdnmfCtfAddrForUploading(BER_TLV_IE, tag=0x97):
         pass
-    class ProSeConfigDataForUsageInfoReporting(BER_TLV_IE, tag=0xa0,
+    class ProSeConfigDataForUeToNetworkRelayUE(BER_TLV_IE, tag=0xa0,
                                                nested=[EF_5G_PROSE_DD.ValidityTimer,
                                                        CollectionPeriod, ReportingWindow,
                                                        ReportingIndicators,
@@ -1336,7 +1336,7 @@ class EF_5G_PROSE_UIR(TransparentEF):
                  desc='5G ProSe configuration data for usage information reporting', **kwargs):
         super().__init__(fid, sfid=sfid, name=name, desc=desc, **kwargs)
         # contains TLV structure despite being TransparentEF, not BER-TLV ?!?
-        self._tlv = EF_5G_PROSE_UIR.ProSeConfigDataForUsageInfoReporting
+        self._tlv = EF_5G_PROSE_UIR.ProSeConfigDataForUeToNetworkRelayUE
 
 # TS 31.102 Section 4.4.13.8 (Rel 18)
 class EF_5G_PROSE_U2URU(TransparentEF):

pySim/ts_51_011.py

@@ -1117,8 +1117,8 @@ class DF_GSM(CardDF):
             EF_MBI(),
             EF_MWIS(),
             EF_CFIS(),
-            EF_EXT('6fc8', None, 'EF.EXT6', desc='Extension6 (MBDN)'),
+            EF_EXT('6fc8', None, 'EF.EXT6', desc='Externsion6 (MBDN)'),
-            EF_EXT('6fcc', None, 'EF.EXT7', desc='Extension7 (CFIS)'),
+            EF_EXT('6fcc', None, 'EF.EXT7', desc='Externsion7 (CFIS)'),
             EF_SPDI(),
             EF_MMSN(),
             EF_EXT('6fcf', None, 'EF.EXT8', desc='Extension8 (MMSN)'),

pySim/utils.py

@@ -139,6 +139,7 @@ def enc_plmn(mcc: Hexstr, mnc: Hexstr) -> Hexstr:
 
 def dec_plmn(threehexbytes: Hexstr) -> dict:
     res = {'mcc': "0", 'mnc': "0"}
+    dec_mcc_from_plmn_str(threehexbytes)
     res['mcc'] = dec_mcc_from_plmn_str(threehexbytes)
     res['mnc'] = dec_mnc_from_plmn_str(threehexbytes)
     return res
@@ -910,8 +911,7 @@ class DataObjectCollection:
     def encode(self, decoded) -> bytes:
         res = bytearray()
         for i in decoded:
-            name = i[0]
+            obj = self.members_by_name(i[0])
-            obj = self.members_by_name[name]
             res.append(obj.to_tlv())
         return res