diff --git a/docs/conf.py b/docs/conf.py index 6fea583d..8455007e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,8 +18,8 @@ sys.path.insert(0, os.path.abspath('..')) # -- Project information ----------------------------------------------------- project = 'osmopysim-usermanual' -copyright = '2009-2022 by Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle' -author = 'Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle' +copyright = '2009-2023 by Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle, Merlin Chlosta' +author = 'Sylvain Munaut, Harald Welte, Philipp Maier, Supreeth Herle, Merlin Chlosta' # -- General configuration --------------------------------------------------- diff --git a/docs/shell.rst b/docs/shell.rst index 8f440c2d..510f4c6c 100644 --- a/docs/shell.rst +++ b/docs/shell.rst @@ -36,6 +36,13 @@ pySim-shell has a variety of command line arguments to control :module: pySim-shell :func: option_parser +Usage Examples +-------------- +.. toctree:: + :maxdepth: 1 + :caption: Tutorials for pySIM-shell: + + suci-tutorial cmd2 basics diff --git a/docs/suci-tutorial.rst b/docs/suci-tutorial.rst new file mode 100644 index 00000000..00c060f3 --- /dev/null +++ b/docs/suci-tutorial.rst @@ -0,0 +1,197 @@ + +Guide: Enabling 5G SUCI +======================== + +SUPI/SUCI Concealment is a feature of 5G-Standalone (SA) to encrypt the +IMSI/SUPI with a network operator public key. 3GPP Specifies two different +variants for this: + +* SUCI calculation *in the UE*, using data from the SIM +* SUCI calculation *on the card itself* + +pySIM supports writing the 5G-specific files for *SUCI calculation in the UE* on USIM cards, assuming that +your cards contain the required files, and you have the privileges/credentials to write to them. This is +the case using sysmocom sysmoISIM-SJA2 cards (or successor products). + +In short, you can enable SUCI with these steps: + +* activate USIM **Service 124** +* make sure USIM **Service 125** is disabled +* store the public keys in **SUCI_Calc_Info** +* set the **Routing Indicator** (required) + +If you want to disable the feature, you can just disable USIM Service 124 (and 125). + +Technical References +~~~~~~~~~~~~~~~~~~~~ + +This guide covers the basic workflow of provisioning SIM cards with the 5G SUCI feature. For detailed information on the SUCI feature and file contents, the following documents are helpful: + +* USIM files and structure: `TS 31.102 `__ +* USIM tests (incl. file content examples) `TS 31.121 `__ + +For specific information on sysmocom SIM cards, refer to Section 9.1 of the `sysmoUSIM User +Manual `__. + +-------------- + +Admin PIN +--------- + +The usual way to authenticate yourself to the card as the cellular +operator is to validate the so-called ADM1 (admin) PIN. This may differ +from card model/vendor to card model/vendor. + +Start pySIM-shell and enter the admin PIN for your card. If you bought +the SIM card from your network operator and don’t have the admin PIN, +you cannot change SIM contents! + +Launch pySIM: + +:: + + $ ./pySim-shell.py -p 0 + + Using PC/SC reader interface + Autodetected card type: sysmoISIM-SJA2 + Welcome to pySim-shell! + pySIM-shell (MF)> + +Enter the ADM PIN: + +:: + + pySIM-shell (MF)> verify_adm XXXXXXXX + +Otherwise, write commands will fail with ``SW Mismatch: Expected 9000 and got 6982.`` + +Key Provisioning +---------------- + +:: + + pySIM-shell (MF)> select MF + pySIM-shell (MF)> select ADF.USIM + pySIM-shell (MF/ADF.USIM)> select DF.5GS + pySIM-shell (MF/ADF.USIM/DF.5GS)> select EF.SUCI_Calc_Info + +By default, the file is present but empty: + +:: + + pySIM-shell (MF/ADF.USIM/DF.5GS/EF.SUCI_Calc_Info)> read_binary_decoded + missing Protection Scheme Identifier List data object tag + 9000: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff -> {} + +The following JSON config defines the testfile from `TS 31.121 `__ Section 4.9.4 with +test keys from `TS 33.501 `__ Annex C.4. Highest priority (``0``) has a +Profile-B (``identifier: 2``) key in key slot ``1``, which means the key +with ``hnet_pubkey_identifier: 27``. + +.. code:: json + + { + "prot_scheme_id_list": [ + {"priority": 0, "identifier": 2, "key_index": 1}, + {"priority": 1, "identifier": 1, "key_index": 2}, + {"priority": 2, "identifier": 0, "key_index": 0}], + "hnet_pubkey_list": [ + {"hnet_pubkey_identifier": 27, + "hnet_pubkey": "0272DA71976234CE833A6907425867B82E074D44EF907DFB4B3E21C1C2256EBCD1"}, + {"hnet_pubkey_identifier": 30, + "hnet_pubkey": "5A8D38864820197C3394B92613B20B91633CBD897119273BF8E4A6F4EEC0A650"}] + } + +Write the config to file (must be single-line input as for now): + +:: + + pySIM-shell (MF/ADF.USIM/DF.5GS/EF.SUCI_Calc_Info)> update_binary_decoded '{ "prot_scheme_id_list": [ {"priority": 0, "identifier": 2, "key_index": 1}, {"priority": 1, "identifier": 1, "key_index": 2}, {"priority": 2, "identifier": 0, "key_index": 0}], "hnet_pubkey_list": [ {"hnet_pubkey_identifier": 27, "hnet_pubkey": "0272DA71976234CE833A6907425867B82E074D44EF907DFB4B3E21C1C2256EBCD1"}, {"hnet_pubkey_identifier": 30, "hnet_pubkey": "5A8D38864820197C3394B92613B20B91633CBD897119273BF8E4A6F4EEC0A650"}]}' + +WARNING: These are TEST KEYS with publicly known/specified private keys, and hence unsafe for live/secure +deployments! For use in production networks, you need to generate your own set[s] of keys. + +Routing Indicator +----------------- + +The Routing Indicator must be present for the SUCI feature. By default, +the contents of the file is **invalid** (ffffffff): + +:: + + pySIM-shell (MF)> select MF + pySIM-shell (MF)> select ADF.USIM + pySIM-shell (MF/ADF.USIM)> select DF.5GS + pySIM-shell (MF/ADF.USIM/DF.5GS)> select EF.Routing_Indicator + pySIM-shell (MF/ADF.USIM/DF.5GS/EF.Routing_Indicator)> read_binary_decoded + 9000: ffffffff -> {'raw': 'ffffffff'} + +The Routing Indicator is a four-byte file but the actual Routing +Indicator goes into bytes 0 and 1 (the other bytes are reserved). To set +the Routing Indicator to 0x71: + +:: + + pySIM-shell (MF/ADF.USIM/DF.5GS/EF.Routing_Indicator)> update_binary 0071ffff + +(the encoding might be different, see `this +comment `__) +You can also set the routing indicator to **0x0**, which is *valid* and +means “routing indicator not specified”, leaving it to the modem. + +USIM Service Table +------------------ + +First, check out the USIM Service Table (UST): + +:: + + pySIM-shell (MF)> select MF + pySIM-shell (MF)> select ADF.USIM + pySIM-shell (MF/ADF.USIM)> select EF.UST + pySIM-shell (MF/ADF.USIM/EF.UST)> read_binary_decoded + 9000: beff9f9de73e0408400170730000002e00000000 -> [2, 3, 4, 5, 6, 9, 10, 11, 12, 13, 14, 15, 17, 18, 19, 20, 21, 25, 27, 28, 29, 33, 34, 35, 38, 39, 42, 43, 44, 45, 46, 51, 60, 71, 73, 85, 86, 87, 89, 90, 93, 94, 95, 122, 123, 124, 126] + +.. list-table:: From TS31.102 + :widths: 15 40 + :header-rows: 1 + + * - Service No. + - Description + * - 122 + - 5GS Mobility Management Information + * - 123 + - 5G Security Parameters + * - 124 + - Subscription identifier privacy support + * - 125 + - SUCI calculation by the USIM + * - 126 + - UAC Access Identities support + * - 129 + - 5GS Operator PLMN List + +If you’d like to enable/disable any UST service: + +:: + + pySIM-shell (MF/ADF.USIM/EF.UST)> ust_service_deactivate 124 + pySIM-shell (MF/ADF.USIM/EF.UST)> ust_service_activate 124 + pySIM-shell (MF/ADF.USIM/EF.UST)> ust_service_deactivate 125 + +In this case, UST Service 124 is already enabled and you’re good to go. The +sysmoISIM-SJA2 does not support on-SIM calculation, so service 125 must +be disabled. + +USIM Error with 5G and sysmoISIM +-------------------------------- + +sysmoISIMs come 5GS-enabled. By default however, the configuration stored +in the card file-system is **not valid** for 5G networks: Service 124 is enabled, +but EF.SUCI_Calc_Info and EF.Routing_Indicator are empty files (hence +do not contain valid data). + +At least for Qualcomm’s X55 modem, this results in an USIM error and the +whole modem shutting 5G down. If you don’t need SUCI concealment but the +smartphone refuses to connect to any 5G network, try to disable the UST +service 124.