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 today's smartcards follow the GlobalPlatform Card Specification and the included Security Domain model.
+Most of todays 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's also strongly recommended to maintain at least one backup keyset that you can use as fallback in case
+	     It 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,61 +34,69 @@ any other file.
       }
    }
 
-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).
+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.
 
-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-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.
 
-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``
+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``
 
 ::
 
-   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
+    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)>
 
-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.
+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.
 
 
 Establishing a secure channel
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Before we can make changes to the keysets in the currently selected Security Domain we must first establish a secure
-channel with that Security Domain. In the following examples we will use `SCP02` (see also GlobalPlatform Card
-Specification, section E.1.1) and `SCP03` (see also GlobalPlatform Card Specification – Amendment D) to establish the
-secure channel. `SCP02` is slightly older than `SCP03`. The main difference between the two is that `SCP02` uses 3DES
-while `SCP03` is based on AES.
+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.
 
 .. 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`
 ----------------
@@ -111,7 +119,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  --key-ver 112 --security-level 3
+    pySIM-shell (00:MF/ADF.ISD)> establish_scp02 --key-enc F09C43EE1A0391665CC9F05AF4E0BD10 --key-mac 01981F4A20999F62AF99988007BAF6CA --key-dek 8F8AEE5CDCC5D361368BC45673D99195 --security-level 3
     Successfully established a SCP02[03] secure channel
 
 
@@ -119,34 +127,32 @@ Example: `SCP03`
 ----------------
 
 The establishment of a secure channel via SCP03 works just the same. In the following example we will establish a
-secure channel to the `MNO-SD` of an eSIM profile. The SCP03 keyset we use is tied to KVN 48 and looks like this:
+secure channel to the ISD-R of an eUICC. The SCP03 keyset we use is tied to KVN 50 and looks like this:
 
 +---------+------------------------------------------------------------------+
 | Keyname | Keyvalue                                                         |
 +=========+==================================================================+
-| ENC/KIC | 63af517c29ad6ac6fcadfe6ac8a3c8a041d8141c7eb845ef1cba6112a325e430 |
+| ENC/KIC | 620ff456b0c0328b68dc0d7d5eb24e07dd749aa86c9ff1836a7263e1d8896510 |
 +---------+------------------------------------------------------------------+
-| MAC/KID | 54b9ad6713ae922f54014ed762132e7b59bdcd2a2a6beba98fb9afe6b4df27e1 |
+| MAC/KID | b38116a2c85f2c8f46bbdc0081d6e8a04b0a58087d0ce5ee0ccc4c945e4aeda6 |
 +---------+------------------------------------------------------------------+
-| DEK/KIK | cbb933ba2389da93c86c112739cd96389139f16c6f80f7d16bf3593e407ca893 |
+| DEK/KIK | d409486cbcb8092a8592ee46d8668dfa97bea5eb7ce9c2b5a3f3bb1db358a153 |
 +---------+------------------------------------------------------------------+
 
-We assume that the `MNO-SD` is already selected (see above). We may now establish the SCP03 secure channel:
+We assume that ADF.ISD-R is already selected. We may now establish the SCP03 secure channel:
 
 ::
    
-   pySIM-shell (00:MF/ADF.ISD-R)> establish_scp03 --key-enc 63af517c29ad6ac6fcadfe6ac8a3c8a041d8141c7eb845ef1cba6112a325e430 --key-mac 54b9ad6713ae922f54014ed762132e7b59bdcd2a2a6beba98fb9afe6b4df27e1 --key-dek cbb933ba2389da93c86c112739cd96389139f16c6f80f7d16bf3593e407ca893 --key-ver 48 --security-level 3
+   pySIM-shell (00:MF/ADF.ISD-R)> establish_scp03 --key-enc 620ff456b0c0328b68dc0d7d5eb24e07dd749aa86c9ff1836a7263e1d8896510 --key-mac b38116a2c85f2c8f46bbdc0081d6e8a04b0a58087d0ce5ee0ccc4c945e4aeda6 --key-dek d409486cbcb8092a8592ee46d8668dfa97bea5eb7ce9c2b5a3f3bb1db358a153 --key-ver 50 --security-level 3
    Successfully established a SCP03[03] secure channel
 
 
-
 Understanding Keysets
 ~~~~~~~~~~~~~~~~~~~~~
 
 Before making any changes to keysets, it is recommended to check the status of the currently installed keysets. To do
-so, we use the `get_data` command to retrieve the `key_information`. This command does not require the establishment of
-a secure channel. We also cannot read back the key values themselves, but we get a summary of the installed keys
-together with their KVN numbers, IDs, algorithm and key length values.
+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.
 
 Example: `key_information` from a `sysmoISIM-SJA5`:
 
@@ -398,8 +404,6 @@ 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)                                     |
@@ -410,6 +414,8 @@ 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     |
 +-----------+-------------------------------------------------------+
 
@@ -444,7 +450,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`).
 
-The second example shows that different schemes are possible. The `SCP80` keyset from the second example uses a scheme
+That different schemes are possible shows the second example. 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
-            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

@@ -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: 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
-        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.
-        """
+        """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."""
 
         # 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

@@ -441,7 +441,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.
-            See GlobalPlatform CardSpecification v2.3 Section 11.11 for details."""
+            """Perform the GlobalPlatform GET DATA command in order to store some card-specific data.
+            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.
-            See GlobalPlatform CardSpecification v2.3 Section 11.11 for details."""
+            """Perform the GlobalPlatform GET DATA command in order to store some card-specific data.
+            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')
@@ -859,28 +859,22 @@ 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(usage='%(prog)s FILE [--install-parameters | --install-parameters-*]')
+        install_cap_parser = argparse.ArgumentParser()
         install_cap_parser.add_argument('cap_file', type=str, metavar='FILE',
                                         help='JAVA-CARD CAP file to install')
-        # 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)')
+        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)')
 
         @cmd2.with_argparser(install_cap_parser)
         def do_install_cap(self, opts):
@@ -894,17 +888,9 @@ 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 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')
+            if opts.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,8 +17,6 @@
 # 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 *
@@ -48,9 +46,7 @@ class InstallParams(TLV_IE_Collection, nested=[AppSpecificParams, SystemSpecific
     # GPD_SPE_013, table 11-49
     pass
 
-def gen_install_parameters(non_volatile_memory_quota: Optional[int] = None,
-                           volatile_memory_quota: Optional[int] = None,
-                           stk_parameter: Optional[str] = None):
+def gen_install_parameters(non_volatile_memory_quota:int, volatile_memory_quota:int, stk_parameter:str):
 
     # GPD_SPE_013, table 11-49
 
@@ -58,17 +54,19 @@ def gen_install_parameters(non_volatile_memory_quota: Optional[int] = None,
     install_params = InstallParams()
     install_params_dict = [{'app_specific_params': None}]
 
-    # 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})
+    #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}]
 
     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=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,
-                                'tp_udhi'/Flag,
-                                'tp_sri'/Flag,
-                                Padding(1),
-                                'tp_lp'/Flag,
-                                'tp_mms'/Flag,
-                                'tp_mti'/BitsInteger(2))
-
+    flags_construct = BitStruct('tp_rp'/Flag, 'tp_udhi'/Flag, 'tp_rp'/Flag, 'tp_sri'/Flag,
+                                Padding(1), 'tp_mms'/Flag, 'tp_mti'/BitsInteger(2))
     def __init__(self, **kwargs):
         kwargs['tp_mti'] = 0
         super().__init__(**kwargs)

pySim/transport/pcsc.py

@@ -80,7 +80,8 @@ 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='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

@@ -261,26 +261,6 @@ 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):
@@ -309,28 +289,16 @@ class EF_SMSP(LinFixedEF):
 
     @staticmethod
     def sc_addr_len(ctx):
-        """Compute the length field for an address field (see also: 3GPP TS 24.011, section 8.2.5.2)."""
+        """Compute the length field for an address field (like TP-DestAddr or TP-ScAddr)."""
         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)),
@@ -339,8 +307,9 @@ class EF_SMSP(LinFixedEF):
                                                                         'tp_pid'/Flag,
                                                                         'tp_sc_addr'/Flag,
                                                                         'tp_dest_addr'/Flag)),
-                                 'tp_dest_addr'/DestAddr,
+                                 'tp_dest_addr'/ScAddr,
                                  'tp_sc_addr'/ScAddr,
+
                                  'tp_pid'/Bytes(1),
                                  'tp_dcs'/Bytes(1),
                                  'tp_vp_minutes'/EF_SMSP.ValidityPeriodAdapter(Byte))
@@ -1148,8 +1117,8 @@ class DF_GSM(CardDF):
             EF_MBI(),
             EF_MWIS(),
             EF_CFIS(),
-            EF_EXT('6fc8', None, 'EF.EXT6', desc='Extension6 (MBDN)'),
-            EF_EXT('6fcc', None, 'EF.EXT7', desc='Extension7 (CFIS)'),
+            EF_EXT('6fc8', None, 'EF.EXT6', desc='Externsion6 (MBDN)'),
+            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[name]
+            obj = self.members_by_name(i[0])
             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()
+        load_parameters = gen_install_parameters(None, None, '')
         self.assertEqual(load_parameters, 'c900')
 
 if __name__ == "__main__":