Cellular Network Infrastructure

Dieter Spaar has modified the shadysim.py to support the configured OTA mode on the sysmoUSIM-SJS1 (and by extension the SIM Cards issued at 31C3, the following camp and 32C3).

h2. What is it about

(U)SIM cards are Java capable and there is the Globalplatform that specifies standards API. SMS can be addressed directly to the SIM card, the SIM card will get events for network selection and others, it can modify call establishment attempts.

The following will show how to build the example applet and install it on your USIM. If you create plugins please make them available as Free Software and point us to them. If you find interesting Globalplatform APIs or hacks please talk about it.

h2. What you will need

* sysmoUSIM-SJS1 card

* KIC, KID private keys of the card

* PCSC, serial card reader or be able to send SMS to the SIM card

* JDK to create Java1.1 bytecode to create/customize SIM Toolkit applets.

* Dependency for sim-tools: python-pyscard

h2. What you can read

* JavaCard? API specification (​http://www.andresteder.com/static/api/simtoolkitapi/sim/toolkit/package-summary.html)

* 3GPP sim.toolkit API (​http://www.etsi.org/deliver/etsi_ts/101400_101499/101476/07.00.00_60/ts_101476v070000p.pdf). Specially setEvent is a good keyword to look at!

* 3GPP TS 31.102 Characteristics of the Universal Subscriber Identity Module (USIM) application, describes the file system in 4.7 https://www.etsi.org/deliver/etsi_ts/131100_131199/131102/15.08.00_60/ts_131102v150800p.pdf

h2. Building an example applet

* Install a JAVA compiler and ANT first:

<pre>

$ sudo apt-get install default-jdk ant

</pre>

* Clone hello-stk.git and prepare the build system:

<pre>

$ git clone https://gitea.osmocom.org/sim-card/hello-stk

$ cd hello-stk

$ git submodule update --init --recursive

</pre>

* Build example applets by running ANT:

<pre>

$ ant

Buildfile: /home/owner/work/git_master/hello-stk/build.xml

dist:

      [get] Getting: https://github.com/martinpaljak/ant-javacard/releases/latest/download/ant-javacard.jar

      [get] To: /home/owner/work/git_master/hello-stk/ant-javacard.jar

      [get] https://github.com/martinpaljak/ant-javacard/releases/latest/download/ant-javacard.jar moved to https://github.com/martinpaljak/ant-javacard/releases/download/v23.08.29/ant-javacard.jar

      [get] https://github.com/martinpaljak/ant-javacard/releases/download/v23.08.29/ant-javacard.jar moved to https://objects.githubusercontent.com/github-production-release-asset-2e65be/28853876/2cb87380-f21f-45e7-894e-54ca5a3513d0?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20230906%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230906T085907Z&X-Amz-Expires=300&X-Amz-Signature=d16ac3b8e6a53831e85ec8315daa51b90f0ccfc09dcfd55d76bd8ff416a0651c&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=28853876&response-content-disposition=attachment%3B%20filename%3Dant-javacard.jar&response-content-type=application%2Foctet-stream

      [cap] INFO: using JavaCard 3.0.5 SDK in /home/owner/work/git_master/hello-stk/oracle_javacard_sdks/jc305u3_kit with JDK 11

      [cap] INFO: targeting JavaCard 2.2.1 SDK in /home/owner/work/git_master/hello-stk/oracle_javacard_sdks/jc221_kit

      [cap] INFO: Setting package name to org.toorcamp.HelloSTK

      [cap] Building CAP with 1 applet from package org.toorcamp.HelloSTK (AID: D07002CA44)

      [cap] org.toorcamp.HelloSTK.HelloSTK D07002CA44900101

  [compile] Compiling files from /home/owner/work/git_master/hello-stk/hello-stk

  [compile] Compiling 1 source file to /home/owner/work/git_master/hello-stk/build/classes

  [compile] /home/owner/work/git_master/hello-stk/hello-stk/src/org/toorcamp/HelloSTK/HelloSTK.java

  [convert] [ INFO: ] Converter [v3.0.5]

  [convert] [ INFO: ]     Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.

  [convert]     

  [convert]     

  [convert] [ INFO: ] conversion completed with 0 errors and 0 warnings.

   [verify] Verification passed

      [cap] CAP saved to /home/owner/work/git_master/hello-stk/build/HelloSTK.cap

      [cap] INFO: using JavaCard 3.0.5 SDK in /home/owner/work/git_master/hello-stk/oracle_javacard_sdks/jc305u3_kit with JDK 11

      [cap] INFO: targeting JavaCard 2.2.1 SDK in /home/owner/work/git_master/hello-stk/oracle_javacard_sdks/jc221_kit

      [cap] INFO: Setting package name to org.osmocom.IMSIChange

      [cap] Building CAP with 1 applet from package org.osmocom.IMSIChange (AID: D07002CA44)

      [cap] org.osmocom.IMSIChange.IMSIChange D07002CA44900102

  [compile] Compiling files from /home/owner/work/git_master/hello-stk/imsi-change

  [compile] Compiling 3 source files to /home/owner/work/git_master/hello-stk/build/classes

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/Bytes.java

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/MobileIdentity.java

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:83: warning: [cast] redundant cast to byte

  [compile] 			proHdlr.appendTLV((byte)(TAG_DEFAULT_TEXT), (byte)4, prefillVal, (short)0,

  [compile] 			                  ^

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:134: warning: [cast] redundant cast to short

  [compile] 		gsmFile.select((short) SIMView.FID_DF_GSM);

  [compile] 		               ^

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:135: warning: [cast] redundant cast to short

  [compile] 		gsmFile.select((short) SIMView.FID_EF_IMSI);

  [compile] 		               ^

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:145: warning: [cast] redundant cast to short

  [compile] 		gsmFile.select((short) SIMView.FID_DF_GSM);

  [compile] 		               ^

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:146: warning: [cast] redundant cast to short

  [compile] 		gsmFile.select((short) SIMView.FID_EF_IMSI);

  [compile] 		               ^

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:173: warning: [cast] redundant cast to byte

  [compile] 		proHdlr.init((byte)PRO_CMD_REFRESH, SIM_REFRESH_SIM_INIT_FULL_FILE_CHANGE, DEV_ID_ME);

  [compile] 		             ^

  [compile] /home/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/MobileIdentity.java:41: warning: [cast] redundant cast to byte

  [compile] 			byte nibble = bcd[(byte)nibble_i >> 1];

  [compile] 			                  ^

  [compile] 7 warnings

  [convert] [ INFO: ] Converter [v3.0.5]

  [convert] [ INFO: ]     Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved.

  [convert]     

  [convert]     

  [convert] [ INFO: ] conversion completed with 0 errors and 0 warnings.

   [verify] Verification passed

      [cap] CAP saved to /home/owner/work/git_master/hello-stk/build/ImsiChange.cap

BUILD SUCCESSFUL

Total time: 7 seconds

</pre>

h2. Working with a PC/SC reader

Make sure you have the KIC1, KIC2, KIC3 and KID1, KID2 and KID3 for your card. If you have a CCC Event card from 31C3 or later you should be set and for the sysmoUSIM-SJS1 be sure to buy the option that includes the ADM1 keys as otherwise no OTA keys will be provided to you (you will have to buy a new batch of cards then).

<pre>

#Clone if you have not done the above

git clone git://git.osmocom.org/sim/sim-tools/

cd sim-tools/shady-sim

# Load the applet

python shadysim.py --pcsc -l HelloSTK.cap -i HelloSTK.cap \

          --enable-sim-toolkit --module-aid d07002ca44900101 \

          --instance-aid d07002CA44900101 \

          --nonvolatile-memory-required 0100 \

          --volatile-memory-for-install 0100 \

          --max-menu-entry-text 15 \

          --max-menu-entries 05 --kic KIC1 \

          --kid KID1

# Delete it (it takes time)

python shadysim.py --pcsc -d d07002CA449001 \

          --kic KIC1 \

          --kid KID1

</pre>

h2. Working with a SMPP reader

Instead of directly interacting with the SIM through a PCSC reader the APDU is sent through SMPP. Replace the --pcsc call with --smpp and lines starting with SMPP are printed. These then need to be sent.

h2. Troubleshooting

h4. "SW match failed! Expected 9000 and got 6985."

You have probably tried to flash twice, without deleting the applet.

h4. "error: Source option 1.3 is no longer supported. Use 6 or later."

Your openjdk version is too new: support for building the source and target versions required for SIM applets has been dropped. Build with openjdk-8. On debian:

<pre>

$ export PATH=/usr/lib/jvm/java-1.8.0-openjdk-amd64/bin:$PATH

</pre>

If you have upgraded your debian from 9 to 10, you might already have it installed (check if @/usr/lib/jvm/java-8-openjdk-amd64@ exists). Otherwise, you can add the debian 9 (stretch) related mirrors to your @/etc/apt/sources.list@ (copy the buster entries, but replace buster with stretch). After @apt update@, the openjdk-8 related packages are available for installation.