How to program a Sysmocom SJS1 SIM for use with OAI

Overview

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

Summary

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

Prerequisites

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

Run

pcsc_scan

Get output similar to:

PC/SC device scanner
V 1.4.22 (c) 2001-2011, Ludovic Rousseau <ludovic.rousseau@free.fr>
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 <ludovic.rousseau@free.fr>
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-dev
sudo 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 …

pcsc_scan

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:

IMSI ICCID ACC PIN1 PUK1 PIN2 PUK2 Ki KIK1
901700000009480 8988211000000094808 0001 1090 60956217 7448 25990588 BDFDFD2BE954A1AA29765DB6DAEEF5E7 4F23ABF1469E59938E33831E16C47260
IMSI OPC ADM1 KIC1 KID1 KIK1
901700000009480 358422278845A5632BBFB7B354DB103A 60969289 2D7855D38C62BDBE8AA1C62BC63A10F0 5CD62A10086975599FDE7F604720EFAE 4F23ABF1469E59938E33831E16C47260

IMSI   901700000009480

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:

phpmyadmin_hss

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

Run

pcsc_scan

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

Thats All!

For copying and attribution see Adventures In Open Source 4G/5G

Advertisements