Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
pysim-suci.md

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

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.

@dvolvox
Copy link

dvolvox commented Jan 18, 2022

Very good work, congratulations. I was looking for this.

@michalisk13
Copy link

michalisk13 commented Jan 21, 2022

Hi,

I am trying to access the pysim-shell in order to read the EF_SUCI_CALC_INFO of my compatible USIM card, however I get some errors.

Here is the output.

user@ubuntu:~/pysim-github$ ./pySim-shell.py -p 0

Using PC/SC reader interface

Waiting for card...

Autodetection failed

Warning: Could not detect card type - assuming a generic card type...

Info: Card is of type: UICC-SIM

AIDs on card:

USIM: a0000000871002ffffffff89 (EF.DIR)

ISIM: a0000000871004f310ffff89080000ff (EF.DIR)

unknown: a000000063504b43532d3135 (EF.DIR)

unknown: a0000003431002 (EF.DIR)

Card initialization failed with an exception:

---------------------8<---------------------

Traceback (most recent call last):

  File "./pySim-shell.py", line 829, in <module>

    rs, card = init_card(sl)

  File "./pySim-shell.py", line 106, in init_card

    rs = RuntimeState(card, profile)

  File "/home/user/pysim-github/pySim/filesystem.py", line 1074, in __init__

    apps = self._match_applications()

  File "/home/user/pysim-github/pySim/filesystem.py", line 1116, in _match_applications

    data, sw = self.card.select_adf_by_aid(f.aid)

  File "/home/user/pysim-github/pySim/cards.py", line 313, in select_adf_by_aid

    return self._scc.select_adf(aid)

  File "/home/user/pysim-github/pySim/commands.py", line 143, in select_adf

    return self._tp.send_apdu_checksw(self.cla_byte + "a4" + "0404" + aidlen + aid)

  File "/home/user/pysim-github/pySim/transport/__init__.py", line 144, in send_apdu_checksw

    raise SwMatchError(rv[1], sw.lower(), self.sw_interpreter)

pySim.exceptions.SwMatchError: SW match failed! Expected 9000 and got 6a82.

---------------------8<---------------------

(you may still try to recover from this manually by using the 'equip' command.)

it should also be noted that some readers may behave strangely when no card

is inserted.)

 

pySim-shell not equipped!

Welcome to pySim-shell!

pySIM-shell (no card)> equip

Waiting for card...

Autodetection failed

Warning: Could not detect card type - assuming a generic card type...

Info: Card is of type: UICC-SIM

AIDs on card:

USIM: a0000000871002ffffffff89 (EF.DIR)

ISIM: a0000000871004f310ffff89080000ff (EF.DIR)

unknown: a000000063504b43532d3135 (EF.DIR)

unknown: a0000003431002 (EF.DIR)

EXCEPTION of type 'SwMatchError' occurred with message: 'SW match failed! Expected 9000 and got 6a82.'

To enable full traceback, run the following command: 'set debug true'

pySIM-shell (no card)>

Is pysim following the specs as per standards?
I would appreaciate it if someone can help.

@mrlnc
Copy link
Author

mrlnc commented Jan 22, 2022

Best have a look at the pySIM wiki and project page. I think card detection and card-specific quirks are a common thing discussed on the mailing list.

@teslagal
Copy link

teslagal commented Feb 2, 2022

Great work!!!

Have been using it with SysmocomSJA2 cards and has been of so much help!

Just one thing, when updating the Routing Indicator, it is left padded with f's but also inverted. Therefore, to send a value of 0x71 I had to update the EF with:

pySIM-shell (MF/ADF.USIM/DF.5GS/EF.Routing_Indicator)> update_binary 17ffffff

Hope it helps!

@mrlnc
Copy link
Author

mrlnc commented Feb 2, 2022

@teslagal You're right, seems that first and second Byte contain the actual Routing Indicator. I couldn't verify the order, but added a link to your comment to help people figure this out! Thanks!

@Matheus-Garbelini
Copy link

Matheus-Garbelini commented Jun 3, 2022

Hi @mrlnc thanks for your tutorial.
Do you know if it's possible to create such 5G files on a SIM card even if they don't exist?

@mrlnc
Copy link
Author

mrlnc commented Jun 3, 2022

Hey @Matheus-Garbelini - good question. I think file creation is only possible during the "personalization" lifecycle and locked afterwards (my takeaway from Harald Welte's talk here: https://media.ccc.de/v/osmodevcall-20211022-laforge-sim ). So you could only (de-)activate files but not actually create new ones.

@Matheus-Garbelini
Copy link

Matheus-Garbelini commented Jun 3, 2022

thanks @mrlnc
It seems that even if it's possible, they are using proprietary APDUs commands which no one knows:
Screenshot_20220603_152556

@laf0rge
Copy link

laf0rge commented Jul 15, 2022

Hi @mrlnc thanks for your tutorial. Do you know if it's possible to create such 5G files on a SIM card even if they don't exist?

This is highly dependent on the cardOS capabilities and the existing personalization of the card, as well as your access level. On some OS, if the profile permits it, you can create files when authenticated via ADM1 or via OTA. On the sysmoISIM-SJA2 we tried to make it possible, but not many people have played with it. pySim-shell has a create_file command these days.

@laf0rge
Copy link

laf0rge commented Jul 15, 2022

and btw, if you want multi-line JSON input, I suggest to try @edit_binary_decoded@ instead of @update_binary_decoded@ which will spawn your $EDITOR where you can enter multi-line input.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment