The following document is now part of the official pysim documentation and available here: https://downloads.osmocom.org/docs/pysim/master/html/suci-tutorial.html
This gist is an archive and will not be updated.
SUPI/SUCI Concealment is a new 5G-Standalone (SA) feature to encrypt the IMSI/SUPI with a network operator public key. pySIM now supports writing these 5G-specific files to USIM cards.
In short:
- USIM Service 124 enables SUCI calculation
- SUCI_Calc_Info, stores the public keys, required
- Routing Indicator, required
To enable SUCI concealment, follow all steps. If you want to disable the feature, you can just disable USIM Service 124.
For details, see TS31.102 (minimum Version 16 for 5G stuff).
I highly recommend reading the sysmoUSIM User Manual, Section 9.1, for more and up-to-date information.
Start pySIM-shell and enter the admin key for your card. If you bought the SIM card from your network operator and don't have the admin key, 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 keys:
pySIM-shell (MF)> verify_adm XXXXXXXX
Otherwise, write commands will fail with 'SW Mismatch: Expected 9000 and got 6982.'
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 TS31.121 4.9.4 with test keys from TS33.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.
{
"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"}]}'
The Routing Indicator must be present for the SUCI feature. By default, the file is invalid:
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.
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]
From TS31.102:
| 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 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, Service 124 is already enabled and you’re good to go. The sysmocom ISIM does not support on-SIM calculation, so service 125 must be disabled.
sysmocom-ISIMs come 5GS-enabled. By default however, the USIM configuration is not valid for 5G networks: Service 124 is enabled, but SUCI Calc Info and the Routing Indicator are empty files (hence invalid).
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 service 124.
Note that TS 31.102 4.4.11.11 refers to TS 24.501, which in 9.11.3.4.1 actually states:
So the minimum accepted file content should be "f0ffffff", which is also what I'm going to make the default in the future sysmoISIM-SJA5 cards.
Furthermore, pySim is getting a proper encoder/decoder for the EF.Routing_Indicator in https://gerrit.osmocom.org/c/pysim/+/33064