Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 1 | |
| 2 | Guide: Enabling 5G SUCI |
| 3 | ======================== |
| 4 | |
| 5 | SUPI/SUCI Concealment is a feature of 5G-Standalone (SA) to encrypt the |
| 6 | IMSI/SUPI with a network operator public key. 3GPP Specifies two different |
| 7 | variants for this: |
| 8 | |
| 9 | * SUCI calculation *in the UE*, using data from the SIM |
| 10 | * SUCI calculation *on the card itself* |
| 11 | |
| 12 | pySIM supports writing the 5G-specific files for *SUCI calculation in the UE* on USIM cards, assuming that |
| 13 | your cards contain the required files, and you have the privileges/credentials to write to them. This is |
| 14 | the case using sysmocom sysmoISIM-SJA2 cards (or successor products). |
| 15 | |
| 16 | In short, you can enable SUCI with these steps: |
| 17 | |
| 18 | * activate USIM **Service 124** |
| 19 | * make sure USIM **Service 125** is disabled |
| 20 | * store the public keys in **SUCI_Calc_Info** |
| 21 | * set the **Routing Indicator** (required) |
| 22 | |
| 23 | If you want to disable the feature, you can just disable USIM Service 124 (and 125). |
| 24 | |
| 25 | Technical References |
| 26 | ~~~~~~~~~~~~~~~~~~~~ |
| 27 | |
| 28 | 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: |
| 29 | |
| 30 | * USIM files and structure: `TS 31.102 <https://www.etsi.org/deliver/etsi_ts/131100_131199/131102/16.06.00_60/ts_131102v160600p.pdf>`__ |
| 31 | * USIM tests (incl. file content examples) `TS 31.121 <https://www.etsi.org/deliver/etsi_ts/131100_131199/131121/16.01.00_60/ts_131121v160100p.pdf>`__ |
| 32 | |
| 33 | For specific information on sysmocom SIM cards, refer to Section 9.1 of the `sysmoUSIM User |
| 34 | Manual <https://www.sysmocom.de/manuals/sysmousim-manual.pdf>`__. |
| 35 | |
| 36 | -------------- |
| 37 | |
| 38 | Admin PIN |
| 39 | --------- |
| 40 | |
| 41 | The usual way to authenticate yourself to the card as the cellular |
| 42 | operator is to validate the so-called ADM1 (admin) PIN. This may differ |
| 43 | from card model/vendor to card model/vendor. |
| 44 | |
| 45 | Start pySIM-shell and enter the admin PIN for your card. If you bought |
| 46 | the SIM card from your network operator and don’t have the admin PIN, |
| 47 | you cannot change SIM contents! |
| 48 | |
| 49 | Launch pySIM: |
| 50 | |
| 51 | :: |
| 52 | |
| 53 | $ ./pySim-shell.py -p 0 |
| 54 | |
| 55 | Using PC/SC reader interface |
| 56 | Autodetected card type: sysmoISIM-SJA2 |
| 57 | Welcome to pySim-shell! |
Harald Welte | 237ddb5 | 2023-10-22 10:36:58 +0200 | [diff] [blame] | 58 | pySIM-shell (00:MF)> |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 59 | |
| 60 | Enter the ADM PIN: |
| 61 | |
| 62 | :: |
| 63 | |
Harald Welte | 237ddb5 | 2023-10-22 10:36:58 +0200 | [diff] [blame] | 64 | pySIM-shell (00:MF)> verify_adm XXXXXXXX |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 65 | |
| 66 | Otherwise, write commands will fail with ``SW Mismatch: Expected 9000 and got 6982.`` |
| 67 | |
| 68 | Key Provisioning |
| 69 | ---------------- |
| 70 | |
| 71 | :: |
| 72 | |
Harald Welte | 237ddb5 | 2023-10-22 10:36:58 +0200 | [diff] [blame] | 73 | pySIM-shell (00:MF)> select MF |
| 74 | pySIM-shell (00:MF)> select ADF.USIM |
| 75 | pySIM-shell (00:MF/ADF.USIM)> select DF.5GS |
| 76 | pySIM-shell (00:MF/ADF.USIM/DF.5GS)> select EF.SUCI_Calc_Info |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 77 | |
| 78 | By default, the file is present but empty: |
| 79 | |
| 80 | :: |
| 81 | |
Harald Welte | 237ddb5 | 2023-10-22 10:36:58 +0200 | [diff] [blame] | 82 | pySIM-shell (00:MF/ADF.USIM/DF.5GS/EF.SUCI_Calc_Info)> read_binary_decoded |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 83 | missing Protection Scheme Identifier List data object tag |
| 84 | 9000: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff -> {} |
| 85 | |
| 86 | The following JSON config defines the testfile from `TS 31.121 <https://www.etsi.org/deliver/etsi_ts/131100_131199/131121/16.01.00_60/ts_131121v160100p.pdf>`__ Section 4.9.4 with |
| 87 | test keys from `TS 33.501 <hhttps://www.etsi.org/deliver/etsi_ts/133500_133599/133501/16.05.00_60/ts_133501v160500p.pdf>`__ Annex C.4. Highest priority (``0``) has a |
| 88 | Profile-B (``identifier: 2``) key in key slot ``1``, which means the key |
| 89 | with ``hnet_pubkey_identifier: 27``. |
| 90 | |
| 91 | .. code:: json |
| 92 | |
| 93 | { |
| 94 | "prot_scheme_id_list": [ |
| 95 | {"priority": 0, "identifier": 2, "key_index": 1}, |
| 96 | {"priority": 1, "identifier": 1, "key_index": 2}, |
| 97 | {"priority": 2, "identifier": 0, "key_index": 0}], |
| 98 | "hnet_pubkey_list": [ |
| 99 | {"hnet_pubkey_identifier": 27, |
| 100 | "hnet_pubkey": "0272DA71976234CE833A6907425867B82E074D44EF907DFB4B3E21C1C2256EBCD1"}, |
| 101 | {"hnet_pubkey_identifier": 30, |
| 102 | "hnet_pubkey": "5A8D38864820197C3394B92613B20B91633CBD897119273BF8E4A6F4EEC0A650"}] |
| 103 | } |
| 104 | |
| 105 | Write the config to file (must be single-line input as for now): |
| 106 | |
| 107 | :: |
| 108 | |
Harald Welte | 237ddb5 | 2023-10-22 10:36:58 +0200 | [diff] [blame] | 109 | pySIM-shell (00: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"}]}' |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 110 | |
| 111 | WARNING: These are TEST KEYS with publicly known/specified private keys, and hence unsafe for live/secure |
| 112 | deployments! For use in production networks, you need to generate your own set[s] of keys. |
| 113 | |
| 114 | Routing Indicator |
| 115 | ----------------- |
| 116 | |
| 117 | The Routing Indicator must be present for the SUCI feature. By default, |
| 118 | the contents of the file is **invalid** (ffffffff): |
| 119 | |
| 120 | :: |
| 121 | |
Harald Welte | 237ddb5 | 2023-10-22 10:36:58 +0200 | [diff] [blame] | 122 | pySIM-shell (00:MF)> select MF |
| 123 | pySIM-shell (00:MF)> select ADF.USIM |
| 124 | pySIM-shell (00:MF/ADF.USIM)> select DF.5GS |
| 125 | pySIM-shell (00:MF/ADF.USIM/DF.5GS)> select EF.Routing_Indicator |
| 126 | pySIM-shell (00:MF/ADF.USIM/DF.5GS/EF.Routing_Indicator)> read_binary_decoded |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 127 | 9000: ffffffff -> {'raw': 'ffffffff'} |
| 128 | |
| 129 | The Routing Indicator is a four-byte file but the actual Routing |
| 130 | Indicator goes into bytes 0 and 1 (the other bytes are reserved). To set |
| 131 | the Routing Indicator to 0x71: |
| 132 | |
| 133 | :: |
| 134 | |
Harald Welte | 237ddb5 | 2023-10-22 10:36:58 +0200 | [diff] [blame] | 135 | pySIM-shell (00:MF/ADF.USIM/DF.5GS/EF.Routing_Indicator)> update_binary 17ffffff |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 136 | |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 137 | You can also set the routing indicator to **0x0**, which is *valid* and |
| 138 | means “routing indicator not specified”, leaving it to the modem. |
| 139 | |
| 140 | USIM Service Table |
| 141 | ------------------ |
| 142 | |
| 143 | First, check out the USIM Service Table (UST): |
| 144 | |
| 145 | :: |
| 146 | |
Harald Welte | 237ddb5 | 2023-10-22 10:36:58 +0200 | [diff] [blame] | 147 | pySIM-shell (00:MF)> select MF |
| 148 | pySIM-shell (00:MF)> select ADF.USIM |
| 149 | pySIM-shell (00:MF/ADF.USIM)> select EF.UST |
| 150 | pySIM-shell (00:MF/ADF.USIM/EF.UST)> read_binary_decoded |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 151 | 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] |
| 152 | |
| 153 | .. list-table:: From TS31.102 |
| 154 | :widths: 15 40 |
| 155 | :header-rows: 1 |
| 156 | |
| 157 | * - Service No. |
| 158 | - Description |
| 159 | * - 122 |
| 160 | - 5GS Mobility Management Information |
| 161 | * - 123 |
| 162 | - 5G Security Parameters |
| 163 | * - 124 |
| 164 | - Subscription identifier privacy support |
| 165 | * - 125 |
| 166 | - SUCI calculation by the USIM |
| 167 | * - 126 |
| 168 | - UAC Access Identities support |
| 169 | * - 129 |
| 170 | - 5GS Operator PLMN List |
| 171 | |
| 172 | If you’d like to enable/disable any UST service: |
| 173 | |
| 174 | :: |
| 175 | |
Harald Welte | 237ddb5 | 2023-10-22 10:36:58 +0200 | [diff] [blame] | 176 | pySIM-shell (00:MF/ADF.USIM/EF.UST)> ust_service_deactivate 124 |
| 177 | pySIM-shell (00:MF/ADF.USIM/EF.UST)> ust_service_activate 124 |
| 178 | pySIM-shell (00:MF/ADF.USIM/EF.UST)> ust_service_deactivate 125 |
Merlin Chlosta | 69b69d4 | 2023-05-11 12:59:01 +0200 | [diff] [blame] | 179 | |
| 180 | In this case, UST Service 124 is already enabled and you’re good to go. The |
| 181 | sysmoISIM-SJA2 does not support on-SIM calculation, so service 125 must |
| 182 | be disabled. |
| 183 | |
| 184 | USIM Error with 5G and sysmoISIM |
| 185 | -------------------------------- |
| 186 | |
| 187 | sysmoISIMs come 5GS-enabled. By default however, the configuration stored |
| 188 | in the card file-system is **not valid** for 5G networks: Service 124 is enabled, |
| 189 | but EF.SUCI_Calc_Info and EF.Routing_Indicator are empty files (hence |
| 190 | do not contain valid data). |
| 191 | |
| 192 | At least for Qualcomm’s X55 modem, this results in an USIM error and the |
| 193 | whole modem shutting 5G down. If you don’t need SUCI concealment but the |
| 194 | smartphone refuses to connect to any 5G network, try to disable the UST |
| 195 | service 124. |