docs/put_key: add tutorial that explains how to manage global platform keys

With the increased interest in using GlobalPlatform features of
UICC and eUICCs (OTA-SMS, applets, etc.), also comes an increased
interest in how the related GlobalPlatform keys can be managed
(key rotation, adding/removing keysets from/to a Security Domain).

Unfortunately, many aspects of this topic are not immediately
obvious for the average user. Let's add a tutorial that contains
some practical examples to shine some light on the topic.

Related: SYS#7881
Change-Id: I163dfedca3df572cb8442e9a4a280e6c5b00327e

docs/put_key-tutorial.rst

@@ -1,7 +1,7 @@
 Guide: Managing GP Keys
 =======================
 
-Most of todays smartcards follow the GlobalPlatform Card Specification and the included Security Domain model.
+Most of today's smartcards follow the GlobalPlatform Card Specification and the included Security Domain model.
 UICCs and eUCCCs are no exception here.
 
 The Security Domain acts as an on-card representative of a card authority or administrator. It is used to perform tasks
@@ -13,7 +13,7 @@ In this tutorial, we will show how to work with the key material (keysets) store
 rotate (replace) existing keys. We will also show how to provision new keys.
 
 .. warning:: Making changes to keysets requires extreme caution as misconfigured keysets may lock you out permanently.
-	     It also strongly recommended to maintain at least one backup keyset that you can use as fallback in case
+	     It's also strongly recommended to maintain at least one backup keyset that you can use as fallback in case
 	     the primary keyset becomes unusable for some reason.
 
 
@@ -34,69 +34,61 @@ any other file.
       }
    }
 
-When working with eUICCs, multiple Security Domains are involved. The model is slightly different from the classic
-model with one primary ISD. In the case of eUICCs, an ISD-R and an ISD-P exists.
+When working with eUICCs, multiple Security Domains are involved. The model is fundamentally different from the classic
+model with one primary Security Domain (ISD). In the case of eUICCs, an ISD-R (Issuer Security Domain - Root) and an
+ISD-P (Issuer Security Domain - Profile) exist (see also: GSMA SGP.02, section 2.2.1).
 
-The ISD-R (Issuer Security Domain - Root) is indeed the primary ISD. Its purpose is to handle the installation of new
-profiles and to manage the already installed profiles. The ISD-R shows up as a `ADF.ISD-R` and can be selected normally
-(see above) The key material that allows access to the ISD-R is usually only known to the eUICC manufacturer.
+The ISD-P is established by the ISD-R during the profile installation and serves as a secure container for an eSIM
+profile. Within the ISD-P the eSIM profile establishes a dedicated Security Domain called `MNO-SD` (see also GSMA
+SGP.02, section 2.2.4). This `MNO-SD` is comparable to the Issuer Security Domain (ISD) we find on UICCs. The AID of
+`MNO-SD` is either the default AID for the Issuer Security Domain (see also GlobalPlatform, section H.1.3) or a
+different value specified by the provider of the eSIM profile.
 
-The ISD-P (Issuer Security Domain - Profile) is the primary ISD of the currently enabled profile. The ISD-P is
-comparable to the ISD we find on a UICC. The key material for the ISD-P should be known known to the ISP, which
-is the owner of the installed profile.
-
-Since the AID of the ISD-P is allocated during the profile installation and different for each profile, it is not known
-by pySim-shell. This means there will no `ADF.ISD-P` file show up in the file system, but we can simply select the
-ISD-R, request the AID of the ISD-P and switch over to that ISD-P using a raw APDU:
-``00a4040410`` + ``a0000005591010ffffffff8900001000`` + ``00``
+Since the AID of the `MNO-SD` is not a fixed value, it is not known by `pySim-shell`. This means there will be no
+`ADF.ISD` file shown in the file system, but we can simply select the `ADF.ISD-R` first and then select the `MNO-SD`
+using a raw APDU. In the following example we assume that the default AID (``a000000151000000``) is used  The APDU
+would look like this: ``00a4040408`` + ``a000000151000000`` + ``00``
 
 ::
 
-    pySIM-shell (00:MF)> select ADF.ISD-R
-    {
-        "application_id": "a0000005591010ffffffff8900000100",
-        "proprietary_data": {
-            "maximum_length_of_data_field_in_command_message": 255
-        },
-        "isdr_proprietary_application_template": {
-            "supported_version_number": "020300"
-        }
-    }
-    pySIM-shell (00:MF/ADF.ISD-R)> get_profiles_info 
-    {
-        "profile_info_seq": {
-            "profile_info": {
-                "iccid": "8949449999999990023",
-                "isdp_aid": "a0000005591010ffffffff8900001000",
-                "profile_state": "enabled",
-                "service_provider_name": "OsmocomSPN",
-                "profile_name": "TS48V1-A-UNIQUE",
-                "profile_class": "operational"
-            }
-        }
-    }
-    pySIM-shell (00:MF/ADF.ISD-R)> apdu 00a4040410a0000005591010ffffffff890000100000
-    SW: 9000, RESP: 6f188410a0000005591010ffffffff8900001000a5049f6501ff
-    pySIM-shell (00:MF/ADF.ISD-R)>
+   pySIM-shell (00:MF)> select ADF.ISD-R
+   {
+       "application_id": "a0000005591010ffffffff8900000100",
+       "proprietary_data": {
+           "maximum_length_of_data_field_in_command_message": 255
+       },
+       "isdr_proprietary_application_template": {
+           "supported_version_number": "020300"
+       }
+   }
+   pySIM-shell (00:MF/ADF.ISD-R)> apdu 00a4040408a00000015100000000
+   SW: 9000, RESP: 6f108408a000000151000000a5049f6501ff
 
-After that, the prompt will still show the ADF.ISD-R, but we are actually in ADF.ISD-P and the standard GlobalPlatform
-operations like `establish_scpXX`, `get_data`, and `put_key` should work. The same workaround can also be applied to any
-Supplementary Security Domain as well, provided that the AID is known to the user.
+After that, the prompt will still show the `ADF.ISD-R`, but we are actually in `ADF.ISD` and the standard GlobalPlatform
+operations like `establish_scpXX`, `get_data`, and `put_key` should work. By doing this, we simply have tricked
+`pySim-shell` into making the GlobalPlatform related commands available for some other Security Domain we are not
+interested in. With the raw APDU we then have swapped out the Security Domain under the hood. The same workaround can
+be applied to any Security Domain, provided that the AID is known to the user.
 
 
 Establishing a secure channel
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Before we can make changes to the keysets in the currently selected Security Domain we must first establish a secure channel
-with that Security Domain. The secure channel protocols commonly used for this are `SCP02` (see also GlobalPlatform Card
-Specification, section E.1.1) and `SCP03` (see also GlobalPlatform Card Specification – Amendment D). `SCP02` is slightly
-older and commonly used on UICCs. The more modern `SCP03` is commonly used on eUICCs. The main difference between the
-two is that `SCP02` uses 3DES while `SCP03` is based on AES.
+Before we can make changes to the keysets in the currently selected Security Domain we must first establish a secure
+channel with that Security Domain. In the following examples we will use `SCP02` (see also GlobalPlatform Card
+Specification, section E.1.1) and `SCP03` (see also GlobalPlatform Card Specification – Amendment D) to establish the
+secure channel. `SCP02` is slightly older than `SCP03`. The main difference between the two is that `SCP02` uses 3DES
+while `SCP03` is based on AES.
 
 .. warning:: Secure channel protocols like `SCP02` and `SCP03` may manage an error counter to count failed login
 	     attempts. This means attempting to establish a secure channel with a wrong keyset multiple times may lock
 	     you out permanently. Double check the applied keyset before attempting to establish a secure channel.
 
+.. warning:: The key values used in the following examples are random key values used for illustration purposes only.
+	     Each UICC or eSIM profile is shipped with individual keys, which means that the keys used below will not
+	     work with your UICC or eSIM profile. You must replace the key values with the values you have received
+	     from your UICC vendor or eSIM profile provider.
+
 
 Example: `SCP02`
 ----------------
@@ -119,7 +111,7 @@ establish a secure channel using the SCP02 Secure Channel Protocol.
 
 ::
 
-    pySIM-shell (00:MF/ADF.ISD)> establish_scp02 --key-enc F09C43EE1A0391665CC9F05AF4E0BD10 --key-mac 01981F4A20999F62AF99988007BAF6CA --key-dek 8F8AEE5CDCC5D361368BC45673D99195 --security-level 3
+    pySIM-shell (00:MF/ADF.ISD)> establish_scp02 --key-enc F09C43EE1A0391665CC9F05AF4E0BD10 --key-mac 01981F4A20999F62AF99988007BAF6CA --key-dek 8F8AEE5CDCC5D361368BC45673D99195  --key-ver 112 --security-level 3
     Successfully established a SCP02[03] secure channel
 
 
@@ -127,32 +119,34 @@ Example: `SCP03`
 ----------------
 
 The establishment of a secure channel via SCP03 works just the same. In the following example we will establish a
-secure channel to the ISD-R of an eUICC. The SCP03 keyset we use is tied to KVN 50 and looks like this:
+secure channel to the `MNO-SD` of an eSIM profile. The SCP03 keyset we use is tied to KVN 48 and looks like this:
 
 +---------+------------------------------------------------------------------+
 | Keyname | Keyvalue                                                         |
 +=========+==================================================================+
-| ENC/KIC | 620ff456b0c0328b68dc0d7d5eb24e07dd749aa86c9ff1836a7263e1d8896510 |
+| ENC/KIC | 63af517c29ad6ac6fcadfe6ac8a3c8a041d8141c7eb845ef1cba6112a325e430 |
 +---------+------------------------------------------------------------------+
-| MAC/KID | b38116a2c85f2c8f46bbdc0081d6e8a04b0a58087d0ce5ee0ccc4c945e4aeda6 |
+| MAC/KID | 54b9ad6713ae922f54014ed762132e7b59bdcd2a2a6beba98fb9afe6b4df27e1 |
 +---------+------------------------------------------------------------------+
-| DEK/KIK | d409486cbcb8092a8592ee46d8668dfa97bea5eb7ce9c2b5a3f3bb1db358a153 |
+| DEK/KIK | cbb933ba2389da93c86c112739cd96389139f16c6f80f7d16bf3593e407ca893 |
 +---------+------------------------------------------------------------------+
 
-We assume that ADF.ISD-R is already selected. We may now establish the SCP03 secure channel:
+We assume that the `MNO-SD` is already selected (see above). We may now establish the SCP03 secure channel:
 
 ::
 
-   pySIM-shell (00:MF/ADF.ISD-R)> establish_scp03 --key-enc 620ff456b0c0328b68dc0d7d5eb24e07dd749aa86c9ff1836a7263e1d8896510 --key-mac b38116a2c85f2c8f46bbdc0081d6e8a04b0a58087d0ce5ee0ccc4c945e4aeda6 --key-dek d409486cbcb8092a8592ee46d8668dfa97bea5eb7ce9c2b5a3f3bb1db358a153 --key-ver 50 --security-level 3
+   pySIM-shell (00:MF/ADF.ISD-R)> establish_scp03 --key-enc 63af517c29ad6ac6fcadfe6ac8a3c8a041d8141c7eb845ef1cba6112a325e430 --key-mac 54b9ad6713ae922f54014ed762132e7b59bdcd2a2a6beba98fb9afe6b4df27e1 --key-dek cbb933ba2389da93c86c112739cd96389139f16c6f80f7d16bf3593e407ca893 --key-ver 48 --security-level 3
    Successfully established a SCP03[03] secure channel
 
 
+
 Understanding Keysets
 ~~~~~~~~~~~~~~~~~~~~~
 
 Before making any changes to keysets, it is recommended to check the status of the currently installed keysets. To do
-so, we use the `get_data` command to retrieve the `key_information`. We cannot read back the key values themselves, but
-we get a summary of the installed keys together with their KVN numbers, IDs, algorithm and key length values.
+so, we use the `get_data` command to retrieve the `key_information`. This command does not require the establishment of
+a secure channel. We also cannot read back the key values themselves, but we get a summary of the installed keys
+together with their KVN numbers, IDs, algorithm and key length values.
 
 Example: `key_information` from a `sysmoISIM-SJA5`:
 
@@ -404,6 +398,8 @@ used with which Secure Channel Protocol.
 +-----------+-------------------------------------------------------+
 | 48-63     | reserved for `SCP03`                                  |
 +-----------+-------------------------------------------------------+
+| 64-79     | reserved for `SCP81` (GSMA SGP.02, section 2.2.5.1)   |
++-----------+-------------------------------------------------------+
 | 112       | Token key (RSA public or DES, also used with `SCP02`) |
 +-----------+-------------------------------------------------------+
 | 113       | Receipt key (DES)                                     |
@@ -414,8 +410,6 @@ used with which Secure Channel Protocol.
 +-----------+-------------------------------------------------------+
 | 117       | 16-byte DES key for Ciphered Load File Data Block     |
 +-----------+-------------------------------------------------------+
-| 129-143   | reserved for `SCP81`                                  |
-+-----------+-------------------------------------------------------+
 | 255       | reserved for ISD with SCP02 without SCP80 support     |
 +-----------+-------------------------------------------------------+
 
@@ -450,7 +444,7 @@ In this case, all three keys share the same length and are used with the same al
 to implicitly select sub-types of an algorithm. (e.g. a 16 byte key of type `aes` is associated with `AES128`, where a 32
 byte key would be associated with `AES256`).
 
-That different schemes are possible shows the second example. The `SCP80` keyset from the second example uses a scheme
+The second example shows that different schemes are possible. The `SCP80` keyset from the second example uses a scheme
 that works with two keys:
 
 +----------------+---------+---------------------------------------+

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
-            return ValueError('Invalid 1-byte generic APDU access rule')
+            raise ValueError('Invalid 1-byte generic APDU access rule')
         else:
             if len(do) % 8:
-                return ValueError('Invalid non-modulo-8 length of APDU filter: %d' % len(do))
+                raise 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'
-            return ValueError('Invalid 1-byte generic APDU access rule')
+            raise ValueError('Invalid 1-byte generic APDU access rule')
         else:
             if not 'apdu_filter' in self.decoded:
-                return ValueError('Invalid APDU AR DO')
+                raise ValueError('Invalid APDU AR DO')
             filters = self.decoded['apdu_filter']
             res = b''
             for f in filters:
                 if not 'header' in f or not 'mask' in f:
-                    return ValueError('APDU filter must contain header and mask')
+                    raise ValueError('APDU filter must contain header and mask')
                 header_b = h2b(f['header'])
                 mask_b = h2b(f['mask'])
                 if len(header_b) != 4 or len(mask_b) != 4:
-                    return ValueError('APDU filter header and mask must each be 4 bytes')
+                    raise ValueError('APDU filter header and mask must each be 4 bytes')
                 res += header_b + mask_b
             return res
 
@@ -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:
-                return ValueError('DO > 255 bytes not supported yet')
+                raise ValueError('DO > 255 bytes not supported yet')
         else:
             cmd_do_enc = b''
             cmd_do_len = 0
@@ -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:
-                    return ValueError('Invalid non-modulo-16 length of APDU filter: %d' % len(do))
+                    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):

pySim/cdma_ruim.py

@@ -131,7 +131,7 @@ class EF_AD(TransparentEF):
                  desc='Administrative Data', size=(3, None), **kwargs):
         super().__init__(fid, sfid=sfid, name=name, desc=desc, size=size, **kwargs)
         self._construct = Struct(
-            # Byte 1: Display Condition
+            # Byte 1: MS operation mode
             'ms_operation_mode'/Enum(Byte, self.OP_MODE),
             # Bytes 2-3: Additional information
             'additional_info'/Bytes(2),

pySim/esim/http_json_api.py

@@ -19,7 +19,7 @@ import abc
 import requests
 import logging
 import json
-from typing import Optional
+from typing import Optional, Tuple
 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')
+    # path of the API function (e.g. '/gsma/rsp2/es2plus/confirmOrder', see also method rewrite_url).
     path = None
 
     # dictionary of input parameters. key is parameter name, value is ApiParam class
@@ -336,6 +336,22 @@ 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):
@@ -352,8 +368,16 @@ 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
-        json-serializable dict. Output data is returned as json-deserialized dict."""
+        """
+        Make an API call to the HTTP API endpoint represented by this object. Input data is passed in `data` as
+        json-serializable fields. `data` may also contain additional parameters required for URL rewriting (see
+        rewrite_url in class JsonHttpApiFunction). Output data is returned as json-deserialized dict.
+
+        Args:
+                data: Input data required to perform the request.
+                func_call_id: Function Call Identifier, if present a header field is generated automatically.
+                timeout: Maximum amount of time to wait for the request to complete.
+        """
 
         # In case a function caller ID is supplied, use it together with the stored function requestor ID to generate
         # and prepend the header field according to SGP.22, section 6.5.1.1 and 6.5.1.3. (the presence of the header
@@ -362,6 +386,11 @@ 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))
 
@@ -373,7 +402,6 @@ 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

@@ -441,7 +441,7 @@ class File:
             elif k == 'fillFileContent':
                 stream.write(v)
             else:
-                return ValueError("Unknown key '%s' in tuple list" % k)
+                raise 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):
-    _consuruct = GreedyRange(Int16ub)
+    _construct = 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, ntested=[ApplicationAID]):
+class ApplicationTemplate(BER_TLV_IE, tag=0x61, nested=[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 GET DATA command in order to store some card-specific data.
-            See GlobalPlatform CardSpecification v2.3Section 11.11 for details."""
+            """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 GET DATA command in order to store some card-specific data.
-            See GlobalPlatform CardSpecification v2.3Section 11.11 for details."""
+            """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
@@ -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 data
+            return h2b(response)
 
         put_key_parser = argparse.ArgumentParser()
         put_key_parser.add_argument('--old-key-version-nr', type=auto_uint8, default=0, help='Old Key Version Number')
@@ -859,22 +859,28 @@ class ADF_SD(CardADF):
                 _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()
+        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')
-        install_cap_parser_inst_prm_g = install_cap_parser.add_mutually_exclusive_group()
-        install_cap_parser_inst_prm_g.add_argument('--install-parameters', type=is_hexstr, default=None,
-                                                   help='install Parameters (GPC_SPE_034, section 11.5.2.3.7, table 11-49)')
-        install_cap_parser_inst_prm_g_grp = install_cap_parser_inst_prm_g.add_argument_group()
-        install_cap_parser_inst_prm_g_grp.add_argument('--install-parameters-volatile-memory-quota',
-                                                       type=int, default=None,
-                                                       help='volatile memory quota (GPC_SPE_034, section 11.5.2.3.7, table 11-49)')
-        install_cap_parser_inst_prm_g_grp.add_argument('--install-parameters-non-volatile-memory-quota',
-                                                       type=int, default=None,
-                                                       help='non volatile memory quota (GPC_SPE_034, section 11.5.2.3.7, table 11-49)')
-        install_cap_parser_inst_prm_g_grp.add_argument('--install-parameters-stk',
-                                                       type=is_hexstr, default=None,
-                                                       help='Load Parameters (ETSI TS 102 226, section 8.2.1.3.2.1)')
+        # Ideally, the parser should enforce that:
+        #  * either the `--install-parameters` is given alone,
+        #  * or distinct `--install-parameters-*` are optionally given instead.
+        # We tried to achieve this using mutually exclusive groups (add_mutually_exclusive_group).
+        # However, group nesting was never supported, often failed to work correctly, and was unintentionally
+        # exposed through inheritance.  It has been deprecated since version 3.11, removed in version 3.14.
+        # Hence, we have to implement the enforcement manually.
+        install_cap_parser_inst_prm_grp = install_cap_parser.add_argument_group('Install Parameters')
+        install_cap_parser_inst_prm_grp.add_argument('--install-parameters', type=is_hexstr, default=None,
+                                                     help='install Parameters (GPC_SPE_034, section 11.5.2.3.7, table 11-49)')
+        install_cap_parser_inst_prm_grp.add_argument('--install-parameters-volatile-memory-quota',
+                                                     type=int, default=None,
+                                                     help='volatile memory quota (GPC_SPE_034, section 11.5.2.3.7, table 11-49)')
+        install_cap_parser_inst_prm_grp.add_argument('--install-parameters-non-volatile-memory-quota',
+                                                     type=int, default=None,
+                                                     help='non volatile memory quota (GPC_SPE_034, section 11.5.2.3.7, table 11-49)')
+        install_cap_parser_inst_prm_grp.add_argument('--install-parameters-stk',
+                                                     type=is_hexstr, default=None,
+                                                     help='Load Parameters (ETSI TS 102 226, section 8.2.1.3.2.1)')
 
         @cmd2.with_argparser(install_cap_parser)
         def do_install_cap(self, opts):
@@ -888,9 +894,17 @@ class ADF_SD(CardADF):
             load_file_aid = cap.get_loadfile_aid()
             module_aid = cap.get_applet_aid()
             application_aid = module_aid
-            if opts.install_parameters:
+            if opts.install_parameters is not None:
+                # `--install-parameters` and `--install-parameters-*` are mutually exclusive
+                # make sure that none of `--install-parameters-*` is given; abort otherwise
+                if any(p is not None for p in [opts.install_parameters_non_volatile_memory_quota,
+                                               opts.install_parameters_volatile_memory_quota,
+                                               opts.install_parameters_stk]):
+                    self.install_cap_parser.error('arguments --install-parameters-* are '
+                                                  'not allowed with --install-parameters')
                 install_parameters = opts.install_parameters;
             else:
+                # `--install-parameters-*` are all optional
                 install_parameters = gen_install_parameters(opts.install_parameters_non_volatile_memory_quota,
                                                             opts.install_parameters_volatile_memory_quota,
                                                             opts.install_parameters_stk)

pySim/global_platform/install_param.py

@@ -17,6 +17,8 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
+from typing import Optional
+
 from osmocom.construct import *
 from osmocom.utils import *
 from osmocom.tlv import *
@@ -46,7 +48,9 @@ class InstallParams(TLV_IE_Collection, nested=[AppSpecificParams, SystemSpecific
     # GPD_SPE_013, table 11-49
     pass
 
-def gen_install_parameters(non_volatile_memory_quota:int, volatile_memory_quota:int, stk_parameter:str):
+def gen_install_parameters(non_volatile_memory_quota: Optional[int] = None,
+                           volatile_memory_quota: Optional[int] = None,
+                           stk_parameter: Optional[str] = None):
 
     # GPD_SPE_013, table 11-49
 
@@ -54,19 +58,17 @@ def gen_install_parameters(non_volatile_memory_quota:int, volatile_memory_quota:
     install_params = InstallParams()
     install_params_dict = [{'app_specific_params': None}]
 
-    #Conditional
-    if non_volatile_memory_quota and volatile_memory_quota and stk_parameter:
-        system_specific_params = []
-        #Optional
-        if non_volatile_memory_quota:
-            system_specific_params += [{'non_volatile_memory_quota': non_volatile_memory_quota}]
-        #Optional
-        if volatile_memory_quota:
-            system_specific_params += [{'volatile_memory_quota': volatile_memory_quota}]
-        #Optional
-        if stk_parameter:
-            system_specific_params += [{'stk_parameter': stk_parameter}]
-        install_params_dict += [{'system_specific_params': system_specific_params}]
+    # Collect system specific parameters (optional)
+    system_specific_params = []
+    if non_volatile_memory_quota is not None:
+        system_specific_params.append({'non_volatile_memory_quota': non_volatile_memory_quota})
+    if volatile_memory_quota is not None:
+        system_specific_params.append({'volatile_memory_quota': volatile_memory_quota})
+    if stk_parameter is not None:
+        system_specific_params.append({'stk_parameter': stk_parameter})
+    # Add system specific parameters to the install parameters, if any
+    if system_specific_params:
+        install_params_dict.append({'system_specific_params': system_specific_params})
 
     install_params.from_dict(install_params_dict)
     return b2h(install_params.to_bytes())

pySim/global_platform/scp.py

@@ -438,7 +438,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=False for computing the ICV for R-DEC."""
+            * is_response=True 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_auth)
+        raise ValueError('No implementation for crypt algorithm %s' % otak.algo_crypt)
 
 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_crypt))
+            raise ValueError('Cannot use algorithm %s with key for %s' % (self.enum_name, otak.algo_auth))
         super().__init__(otak)
 
     def sign(self, data:bytes) -> bytes:

pySim/sms.py

@@ -169,8 +169,14 @@ 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, 'tp_udhi'/Flag, 'tp_rp'/Flag, 'tp_sri'/Flag,
-                                Padding(1), 'tp_mms'/Flag, 'tp_mti'/BitsInteger(2))
+    flags_construct = BitStruct('tp_rp'/Flag,
+                                'tp_udhi'/Flag,
+                                '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/transport/pcsc.py

@@ -80,8 +80,7 @@ class PcscSimLink(LinkBaseTpdu):
 
     def connect(self):
         try:
-            # To avoid leakage of resources, make sure the reader
-            # is disconnected
+            # To avoid leakage of resources, make sure the reader is disconnected
             self.disconnect()
 
             # Make card connection and select a suitable communication protocol

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='5S 3GP location information', **kwargs):
+                 desc='5GS 3GPP 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 ProSeConfigDataForUeToNetworkRelayUE(BER_TLV_IE, tag=0xa0,
+    class ProSeConfigDataForUsageInfoReporting(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.ProSeConfigDataForUeToNetworkRelayUE
+        self._tlv = EF_5G_PROSE_UIR.ProSeConfigDataForUsageInfoReporting
 
 # TS 31.102 Section 4.4.13.8 (Rel 18)
 class EF_5G_PROSE_U2URU(TransparentEF):

pySim/ts_51_011.py

@@ -261,6 +261,26 @@ class EF_SMSP(LinFixedEF):
                                                         "numbering_plan_id": "reserved_for_extension" },
                             "call_number": "" },
             "tp_pid": b"\x00", "tp_dcs": b"\x00", "tp_vp_minutes": 1440 } ),
+        ( 'fffffffffffffffffffffffffffffffffffffffffffffffffdffffffffffffffffffffffff07919403214365f7ffffffffffffff',
+          { "alpha_id": "", "parameter_indicators": { "tp_dest_addr": False, "tp_sc_addr": True,
+                                                               "tp_pid": False, "tp_dcs": False, "tp_vp": False },
+            "tp_dest_addr": { "length": 255, "ton_npi": { "ext": True, "type_of_number": "reserved_for_extension",
+                                                          "numbering_plan_id": "reserved_for_extension" },
+                              "call_number": "" },
+            "tp_sc_addr": { "length": 7, "ton_npi": { "ext": True, "type_of_number": "international",
+                                                        "numbering_plan_id": "isdn_e164" },
+                            "call_number": "49301234567" },
+            "tp_pid": b"\xff", "tp_dcs": b"\xff", "tp_vp_minutes": 635040 } ),
+        ( 'fffffffffffffffffffffffffffffffffffffffffffffffffc0b919403214365f7ffffffff07919403214365f7ffffffffffffff',
+          { "alpha_id": "", "parameter_indicators": { "tp_dest_addr": True, "tp_sc_addr": True,
+                                                               "tp_pid": False, "tp_dcs": False, "tp_vp": False },
+            "tp_dest_addr": { "length": 11, "ton_npi": { "ext": True, "type_of_number": "international",
+                                                          "numbering_plan_id": "isdn_e164" },
+                              "call_number": "49301234567" },
+            "tp_sc_addr": { "length": 7, "ton_npi": { "ext": True, "type_of_number": "international",
+                                                        "numbering_plan_id": "isdn_e164" },
+                            "call_number": "49301234567" },
+            "tp_pid": b"\xff", "tp_dcs": b"\xff", "tp_vp_minutes": 635040 } ),
     ]
     _test_no_pad = True
     class ValidityPeriodAdapter(Adapter):
@@ -289,16 +309,28 @@ class EF_SMSP(LinFixedEF):
 
     @staticmethod
     def sc_addr_len(ctx):
-        """Compute the length field for an address field (like TP-DestAddr or TP-ScAddr)."""
+        """Compute the length field for an address field (see also: 3GPP TS 24.011, section 8.2.5.2)."""
         if not hasattr(ctx, 'call_number') or len(ctx.call_number) == 0:
             return 0xff
         else:
+            # octets required for the call_number + one octet for ton_npi
             return bytes_for_nibbles(len(ctx.call_number)) + 1
 
+    @staticmethod
+    def dest_addr_len(ctx):
+        """Compute the length field for an address field (see also: 3GPP TS 23.040, section 9.1.2.5)."""
+        if not hasattr(ctx, 'call_number') or len(ctx.call_number) == 0:
+            return 0xff
+        else:
+            # number of call_number digits
+            return len(ctx.call_number)
+
     def __init__(self, fid='6f42', sfid=None, name='EF.SMSP', desc='Short message service parameters', **kwargs):
         super().__init__(fid, sfid=sfid, name=name, desc=desc, rec_len=(28, None), **kwargs)
         ScAddr = Struct('length'/Rebuild(Int8ub, lambda ctx: EF_SMSP.sc_addr_len(ctx)),
                         'ton_npi'/TonNpi, 'call_number'/PaddedBcdAdapter(Rpad(Bytes(10))))
+        DestAddr = Struct('length'/Rebuild(Int8ub, lambda ctx: EF_SMSP.dest_addr_len(ctx)),
+                        'ton_npi'/TonNpi, 'call_number'/PaddedBcdAdapter(Rpad(Bytes(10))))
         self._construct = Struct('alpha_id'/COptional(GsmOrUcs2Adapter(Rpad(Bytes(this._.total_len-28)))),
                                  'parameter_indicators'/InvertAdapter(BitStruct(
                                                                         Const(7, BitsInteger(3)),
@@ -307,9 +339,8 @@ class EF_SMSP(LinFixedEF):
                                                                         'tp_pid'/Flag,
                                                                         'tp_sc_addr'/Flag,
                                                                         'tp_dest_addr'/Flag)),
-                                 'tp_dest_addr'/ScAddr,
+                                 'tp_dest_addr'/DestAddr,
                                  'tp_sc_addr'/ScAddr,
-
                                  'tp_pid'/Bytes(1),
                                  'tp_dcs'/Bytes(1),
                                  'tp_vp_minutes'/EF_SMSP.ValidityPeriodAdapter(Byte))
@@ -1117,8 +1148,8 @@ class DF_GSM(CardDF):
             EF_MBI(),
             EF_MWIS(),
             EF_CFIS(),
-            EF_EXT('6fc8', None, 'EF.EXT6', desc='Externsion6 (MBDN)'),
-            EF_EXT('6fcc', None, 'EF.EXT7', desc='Externsion7 (CFIS)'),
+            EF_EXT('6fc8', None, 'EF.EXT6', desc='Extension6 (MBDN)'),
+            EF_EXT('6fcc', None, 'EF.EXT7', desc='Extension7 (CFIS)'),
             EF_SPDI(),
             EF_MMSN(),
             EF_EXT('6fcf', None, 'EF.EXT8', desc='Extension8 (MMSN)'),

pySim/utils.py

@@ -139,7 +139,6 @@ 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
@@ -911,7 +910,8 @@ class DataObjectCollection:
     def encode(self, decoded) -> bytes:
         res = bytearray()
         for i in decoded:
-            obj = self.members_by_name(i[0])
+            name = i[0]
+            obj = self.members_by_name[name]
             res.append(obj.to_tlv())
         return res
 

tests/unittests/test_globalplatform.py

@@ -295,7 +295,7 @@ class Install_param_Test(unittest.TestCase):
         load_parameters = gen_install_parameters(256, 256, '010001001505000000000000000000000000')
         self.assertEqual(load_parameters, 'c900ef1cc8020100c7020100ca12010001001505000000000000000000000000')
 
-        load_parameters = gen_install_parameters(None, None, '')
+        load_parameters = gen_install_parameters()
         self.assertEqual(load_parameters, 'c900')
 
 if __name__ == "__main__":