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.
I am trying to write a Test SIM Card using OmniKey 3121 reader. The Card is detected and able to read the data.
root@reeturaj--ubuntu:/home/reeturaj/SIM_CARD/pyscard-2.0.7/pysim# ./pySim-read.py -p 0
Using PC/SC reader interface
Reading ...
Autodetection failed
ICCID: 89010020000005348023
IMSI: 262800555020091
GID1: ffffffffffffffff
GID2: ffffffffffffffff
SMSP: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
SPN: 12800520091
Show in HPLMN: True
Hide in OPLMN: False
PLMNsel: ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff
PLMNwAcT:
But I am not able to write new data onto the SIM Card.
root@reeturaj--ubuntu:/tmp/pysim# ./pySim-prog.py -p 0 -n OpenBSC -t sysmosim-gr1 --mcc=234 --mnc=015 --iccid=89010020000005348023 --imsi=234015055502000 --msisdn=+12800520000
Using PC/SC reader interface
Ready for Programming: Insert card now (or CTRL-C to cancel)
Generated card parameters :
Card programming failed with an exception:
---------------------8<---------------------
Traceback (most recent call last):
File "/tmp/pysim/./pySim-prog.py", line 824, in
rc = process_card(opts, first, ch)
File "/tmp/pysim/./pySim-prog.py", line 774, in process_card
card.program(cp)
File "/tmp/pysim/pySim/legacy/cards.py", line 736, in program
self._scc.verify_chv(5, pin)
File "/tmp/pysim/pySim/commands.py", line 523, in verify_chv
self._chv_process_sw('verify', chv_no, code, sw)
File "/tmp/pysim/pySim/commands.py", line 511, in _chv_process_sw
raise SwMatchError(sw, '6b00')
pySim.exceptions.SwMatchError: SW match failed! Expected 9000 and got 6b00.
Any suggestion would be appreciated.