In this tutorial I am going to configure a Sysmocom SJS1 SIM for use with Open Air Interface (OAI).
Also I am going to program the SIM to match one of the HSS user entries installed by default as part of the default OAI CN (core network) install.
When done link back to Adventures In Open Source 4G/5G
All the information needed to program the SIM is in the Sysmocom documentation at https://www.sysmocom.de/downloads/sysmousim-manual.pdf. This tutorial just helps get some of the install and programming values correct.
The card will be programmed using the pysim software package from http://git.osmocom.org/pysim/ with a combination of the per card information supplied by Sysmocom and information from the OAI HSS.
The iccid, pin-adm, and acc will be set to match the card you bought. The mcc, mnc, imsi, opc, and ki will come from from the OAI HSS.
To know more generally about SIM cards see: The Secret Life of SIM Cards presented at DEFCON 21. The video on SIM programming from the last linked page is particularly recommended. Note that this video also covers real SIM programming (developing downloadable SIM card java applets), not just the configuration of SIM cards described here.
Buying SIM Cards
The only cards I have tested are the Sysmocom SJS1 programmable SIM cards that can be purchased at: http://shop.sysmocom.de/products/sysmousim-sjs1
- You must buy the SIM variant with the ADM keys.
- Look for item description in the online shop:
- “SIM card provisioning: default 901-70 MCC-MNC (with ADM keys)”.
- We will reprogram the MCC-MNC.
- Look for item description in the online shop:
- Note the SIM can be bought as 3FF or 4FF sim sizes:
- 3FF (Micro SIM): http://shop.sysmocom.de/products/sysmousim-sjs1
- 4FF (Nano SIM): http://shop.sysmocom.de/products/sysmousim-sjs1-4ff
You will have one or more cards and a spreadsheet of codes for each card including: IMSI, ICCID, ACC, PIN1, PUK1, PIN2, PUK2, Ki, KIK1, OPC, ADM1, KIC1, KID1, KIK1
Do not bother proceeding if you do not have all of the above existing codes for the cards in hand.
You have installed and run the OAI HSS for the first time, and you can see users populated in the HSS via the PHP administration screen.
This tutorial uses an existing Ubuntu install (e.g. the Ubuntu 14.04 install as used by the EPC). Might work on other platforms, but note some of the dependent packages do not work well on all other platforms.
Also buy yourself a SIM card programmer – I use the ACS ACR38/39 family of SIM programmers.
Download ‘Standard’ SIM Card Tooling & Test
Install standard tooling:
sudo apt-get install pcscd libccid sudo apt-get install pcsc-tools
The documentation for pcsc-tools is here: http://ludovic.rousseau.free.fr/softwares/pcsc-tools/
Check SIM card reader and insert the USB card reader (with a new SIM card installed, checking the SIM card is in the correct orientation).
Virtual machines only: If using a virtual machine check the USB reader is connected to the VM, not the host machine. On Vmware Fusion and with an ACS programmer I used ‘Connect Shared ACS ACR 39U Programmer’ (may be different for other card reader vendors).
Get output similar to:
PC/SC device scanner V 1.4.22 (c) 2001-2011, Ludovic Rousseau <firstname.lastname@example.org> Compiled with PC/SC lite version: 1.8.10 Using reader plug'n play mechanism Scanning present readers... 0: ACS ACR 38U-CCID 00 00 Thu Dec 29 17:22:16 2016 Reader 0: ACS ACR 38U-CCID 00 00 Card state: Card inserted, ATR: 3B 9F 96 80 1F C7 80 31 A0 73 BE 21 13 67 43 20 07 18 00 00 01 A5 + TS = 3B --> Direct Convention
Hit control-C to terminate the above.
If you do not have a card reader inserted, or there is a card reader problem (e.g. not connected to a virtual machine in a virtualised environment), you will see something like:
PC/SC device scanner V 1.4.22 (c) 2001-2011, Ludovic Rousseau <email@example.com> Compiled with PC/SC lite version: 1.8.10 Using reader plug'n play mechanism Scanning present readers... Waiting for the first reader...
Download SIM card programmer code and dependences
ONLY if you have not done this earlier in the OAI install download latest certificates:
sudo apt-get install ca-certificates
Then in any case run the following to get Linux dependences (you may have some of these already installed):
sudo apt-get install python-pip sudo apt-get install swig
sudo apt-get install python-devsudo apt-get install libpcsclite-dev sudo apt-get install git
Now get the pyscard python library to access SIM cards:
sudo pip install pyscard
Check the install completes with:
Successfully installed pyscard
Next clone the Python to program the card to a directory of your choice:
git clone http://git.osmocom.org/pysim/
Change into the pysim directory and and you should see a listing similar to:
COPYING pySim pySim-prog.py pySim-read.py README
Dry Run Card Program
In this section we test all of the programmer code is installed, and dry run a card programming session using dummy data (the data on the card is not changed).
Run again …
And check you get the same output as before above (e.g. you have a working card in a working card reader, and nothing has got unplugged).
Dry run the programming code (the following line should work as many of the values while “wrong” are not checked and committed to the card):
python pySim-prog.py --pcsc-device=0 --type="sysmoUSIM-SJS1" --mcc=911 --mnc=71 --imsi=901710000011000 --opc=358422278845A5632BBFB7B354DB103A --ki=BDFDFD2BE954A1AA29765DB6DAEEF5E7 --iccid=8988211000000110000 --dry-run
Get the output something like:
Generated card parameters : > Name : Magic > SMSP : e1ffffffffffffffffffffffff0581005155f5ffffffffffff000000 > ICCID : 8988211000000110000 > MCC/MNC : 911/71 > IMSI : 901710000011000 > Ki : BDFDFD2BE954A1AA29765DB6DAEEF5E7 > OPC : 358422278845A5632BBFB7B354DB103A > ACC : None Dry Run: NOT PROGRAMMING! Done !
Extract Info Specific To SIM Card (“Red Values”)
Now lets collect the actual data to program the SIM card …
Note that information in this section is example only. You must recover values specific to the card you bought here, and not just use these example values.
As example one of the SIM cards we bought was programmed with the IMSI: 901700000009480 and the card was accompanied with the following data from Sysmocom when purchased:
Copy into an editor values for your card for the ICCID, ACC, ADM1
In this case the values copied from above are as follows (they will be different for your card):
ICCID 8988211000000094808 ACC 0001 ADM1 60969289
We will refer to these later as “red data”.
Extract User Information From HSS (“Green Values”)
To be lazy in this tutorial we will program the card to match one of the entries already in the HSS as part of the OAI CN install.
So we will just lookup one of the pre-provisioned users (please follow the steps below to verify that the data in the HSS in your version of OAI is identical).
Check you have run the HSS for the first time, and on startup you will see the HSS populating values in the user table.
So use PhpMyAdmin (following instructions in OAI CN docs how to to install) and look at the users table in the HSS and see a table similar to the following:
Note that the last line in the screen grab, as above has the following values (check unchanged in your HSS system).
IMSI 208920100001100 Key (aka Ki) 8baf473f2f8fd09487cccbd7097c6862 Opc e734f8734007d6c5ce7a0508809e7e9c
If any of the following values are null check your HSS install, and that the HSS has run for the first time to populate all of the columns.
The MCC/MNC above (embedded in the IMSI as 208/92) matches the default MCC/MNC used by most of the OAI default configuration files (scroll down in PhpMyAdmin above for more cards with same MCC/MNC).
We will refer to these later as “green data”.
Construct Programmer Command Line
Using the values in “Green” from the HSS screenshot and the “Red” values from the SIM programming spreadsheet, assemble a command similar to the following in your favourite editor.
Remember to collapse all Python parameters to a single line … multiple lines used here for readability only.
#!/bin/sh python pySim-prog.py --pcsc-device=0 --type="sysmoUSIM-SJS1" --mcc=208 --mnc=92 --imsi=208920100001100 --opc=e734f8734007d6c5ce7a0508809e7e9c --ki=8baf473f2f8fd09487cccbd7097c6862 --iccid=8988211000000094808 --pin-adm=60969289 --acc=0001 --dry-run
To be clear: you will have to change the red values (iccid, pin-adm, acc) to match the card you bought. You should be able to use the green values (mcc, mnc, imsi, opc, ki) unchanged for the first SIM card you program if you are happy using the same default installed user from the HSS.
Note the ‘pin-adm’ is the ADM1 value you noted earlier.
Both the red and green data will change when you program a second SIM card for a second UE configured in the HSS.
Run the above command including the ‘dry-run’ parameter. (Suggest you paste the above into a shell script file and run).
If you have not made an error the generated parameters are:
> Name : Magic > SMSP : e1ffffffffffffffffffffffff0581005155f5ffffffffffff000000 > ICCID : 8988211000000094808 > MCC/MNC : 208/92 > IMSI : 208920100001100 > Ki : 8baf473f2f8fd09487cccbd7097c6862 > OPC : e734f8734007d6c5ce7a0508809e7e9c > ACC : 0001 Dry Run: NOT PROGRAMMING! Done !
Finally Programming the SIM
To double check the SIM is still online.
Simply remove the ‘–dry-run’ parameter and re-run the above script.
You should see the following, however note that there is a pause between “Programming … Done!” and the command prompt returning. :
> Name : Magic > SMSP : e1ffffffffffffffffffffffff0581005155f5ffffffffffff000000 > ICCID : 8988211000000094808 > MCC/MNC : 208/92 > IMSI : 208920100001100 > Ki : 8baf473f2f8fd09487cccbd7097c6862 > OPC : e734f8734007d6c5ce7a0508809e7e9c > ACC : 0001 Programming ... Done !
Unlocking The SIM
The programmed SIM may be locked when first used.
Insert the SIM in a UE where you can enter the unlock code on first use (i.e. not some M2M embedded modem with no user interface).
For copying and attribution see Adventures In Open Source 4G/5G