mrlnc/pysim-suci.md

## pysim-suci.md

      
    Raw
  

              pysim-suci.md
            
          
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.

Admin Keys

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.'
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 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"}]}'

Routing Indicator

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.
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]

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.
USIM Error with 5G and sysmocom-ISIM

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.
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