55003eed38
Update the README documentation so that it contains state-of-the art instructions on how to compile the example applets. Related: OS#6069
124 lines
6.0 KiB
Markdown
124 lines
6.0 KiB
Markdown
# SIM Toolkit Examples
|
|
|
|
This repository contains example Java SIM Toolkit applications.
|
|
|
|
Build requirements
|
|
------------------
|
|
|
|
### Install ANT:
|
|
|
|
ANT is required to control the build process. It can be installed via APT
|
|
(debian)
|
|
|
|
```
|
|
$ sudo apt install ant
|
|
```
|
|
|
|
### Download a suitable JDK:
|
|
|
|
For compatibility reasons it is recommended to download a specific JDK and use
|
|
it to compile the javacard applets. The code in this repository has been tested
|
|
with the following JDK variants:
|
|
|
|
Oracle Java SE Development Kit 11.0.24
|
|
<https://www.oracle.com/de/java/technologies/javase/jdk11-archive-downloads.html>
|
|
|
|
OpenJDK 11.0.2 (build 11.0.2+9)
|
|
<https://jdk.java.net/archive/>
|
|
|
|
The easiest method to install the JDK is to download the tar.gz version and to
|
|
unpack it to a suitable location and to let the environment variable `JAVA_HOME`
|
|
point to that location.
|
|
|
|
### Download JAVA-card SDKs:
|
|
|
|
There is a curated github repository that contains a good selection of JAVA-card
|
|
SDKs: <https://github.com/martinpaljak/oracle_javacard_sdks.git>
|
|
|
|
Use the following commandline to download the Javacard SDKs into the (empty)
|
|
directory oracle_javacard_sdks:
|
|
|
|
```
|
|
$ git submodule update --init --recursive
|
|
```
|
|
|
|
Building CAP files
|
|
------------------
|
|
|
|
The build process is started by running `ant`. The environment variable
|
|
`JAVA_HOME` must point to the location of the JDK.
|
|
|
|
ANT will also automatically download another required component called
|
|
"ant-javacard.jar". See <https://github.com/martinpaljak/ant-javacard> for
|
|
more information.
|
|
|
|
```
|
|
$ JAVA_HOME=/home/user/bin/jdk/oracle/jdk-11.0.24/ ant
|
|
Buildfile: /home/user/work/simcard_applet_loading/hello-stk_osmo/build.xml
|
|
|
|
dist:
|
|
[get] Destination already exists (skipping): /home/user/work/simcard_applet_loading/hello-stk_osmo/ant-javacard.jar
|
|
[cap] INFO: using JavaCard 3.0.5 SDK in /home/user/work/simcard_applet_loading/hello-stk_osmo/oracle_javacard_sdks/jc305u3_kit with JDK 11
|
|
[cap] INFO: targeting JavaCard 2.2.1 SDK in /home/user/work/simcard_applet_loading/hello-stk_osmo/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/user/work/simcard_applet_loading/hello-stk_osmo/hello-stk
|
|
[compile] Compiling 1 source file to /home/user/work/simcard_applet_loading/hello-stk_osmo/build/classes
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/hello-stk/src/org/toorcamp/HelloSTK/HelloSTK.java
|
|
[verify] Verification passed
|
|
[cap] CAP saved to /home/user/work/simcard_applet_loading/hello-stk_osmo/build/HelloSTK.cap
|
|
[cap] INFO: using JavaCard 3.0.5 SDK in /home/user/work/simcard_applet_loading/hello-stk_osmo/oracle_java
|
|
[cap] INFO: targeting JavaCard 2.2.1 SDK in /home/user/work/simcard_applet_loading/hello-stk_osmo/oracle_
|
|
[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/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change
|
|
[compile] Compiling 3 source files to /home/user/work/simcard_applet_loading/hello-stk_osmo/build/classes
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/Bytes.
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/IMSICh
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/Mobile
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/IMSICh
|
|
[compile] proHdlr.appendTLV((byte)(TAG_DEFAULT_TEXT), (byte)4, prefillVal, (short)0,
|
|
[compile] ^
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/IMSICh
|
|
[compile] gsmFile.select((short) SIMView.FID_DF_GSM);
|
|
[compile] ^
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/IMSICh
|
|
[compile] gsmFile.select((short) SIMView.FID_EF_IMSI);
|
|
[compile] ^
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/IMSICh
|
|
[compile] gsmFile.select((short) SIMView.FID_DF_GSM);
|
|
[compile] ^
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/IMSICh
|
|
[compile] gsmFile.select((short) SIMView.FID_EF_IMSI);
|
|
[compile] ^
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/IMSICh
|
|
[compile] proHdlr.init((byte)PRO_CMD_REFRESH, SIM_REFRESH_SIM_INIT_FULL_FILE_CHANGE, DEV_ID_ME);
|
|
[compile] ^
|
|
[compile] /home/user/work/simcard_applet_loading/hello-stk_osmo/imsi-change/src/org/osmocom/IMSIChange/Mobile
|
|
[compile] byte nibble = bcd[(byte)nibble_i >> 1];
|
|
[compile] ^
|
|
[compile] 7 warnings
|
|
[verify] Verification passed
|
|
[cap] CAP saved to /home/user/work/simcard_applet_loading/hello-stk_osmo/build/ImsiChange.cap
|
|
|
|
BUILD SUCCESSFUL
|
|
Total time: 2 seconds
|
|
```
|
|
|
|
In case a different JDK has to be chosen it is important to check if the JDK is
|
|
compatible with the JAVA-card SDK. Not all combinations will yield usable
|
|
results.
|
|
|
|
A table with compatible JDK / JAVA-card SDK combinations can be found here:
|
|
<https://github.com/martinpaljak/ant-javacard/wiki/JavaCard-SDK-and-JDK-version-compatibility>
|
|
|
|
Loading CAP files
|
|
-----------------
|
|
|
|
The loading of the CAP files is typically done using the tools from <https://javacard.pro/globalplatform/>.
|
|
|
|
For more information see:
|
|
<https://osmocom.org/projects/cellular-infrastructure/wiki/HelloSTK>
|