catarrh/hello-stk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

merge into: catarrh:laforge/ant
Branches Tags
catarrh:master catarrh:laforge/ant
...
pull from: catarrh:master
Branches Tags
catarrh:master catarrh:laforge/ant

5 Commits
laforge/an ... master

Author SHA1 Message Date
Philipp Maier
b8ff194b16 README.md: mention pySim-shell as tool to install cap files 
Related: OS#6069
 2025-03-13 13:07:16 +01:00
Philipp Maier
a9bee856b0 README.md: remove outdated information 
There is some outdated information in the README.md files of
hello-stk and imsi-change.

Related: OS#6069
 2024-12-10 16:06:37 +01:00
Philipp Maier
55003eed38 README.md: rework documentationn 
Update the README documentation so that it contains state-of-the art
instructions on how to compile the example applets.

Related: OS#6069
 2024-12-10 14:53:04 +01:00
Philipp Maier
ba0cd07c44 README.md: add build instructions 
We do not have any build instructions in our README.md file yet. Let's
add some information about the basic steps that are needed to build the
applets.

Related: OS#6069
 2023-09-06 11:55:39 +02:00
Harald Welte
f08edf94f9 build-system: import build system from HelloSTK2 
The current build system (Makefile) uses a very old java SDK that is no
longer available on modern platforms.

There is a community supported project HelloSTK2 (maintained
by Merlin Chlosta, see also [1]) that uses not only a comfortable ANT
based approach. It also uses more modern Java SDKs which are automatically
downloaded using .gitmodules. All this makes it very comfortable to use
and also lowers the barrier for beginners.

Let's take this approach as an example and use it in our hello-stk.git
as well.

[1] https://github.com/mrlnc/HelloSTK2.git

Related: OS#6069
Change-Id: Ic1828b7ccaf3bf953c0f4889fa1c3f21b80a1b73
 2023-09-06 11:09:44 +02:00
16 changed files with 9376 additions and 163 deletions
Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -1 +1,5 @@
.vscode
ant-javacard.jar
gp.jar
build/

3
.gitmodules vendored Normal file
View File

@@ -0,0 +1,3 @@
[submodule "oracle_javacard_sdks"]
path = oracle_javacard_sdks
url = https://github.com/martinpaljak/oracle_javacard_sdks.git

128
README.md
View File

@@ -1,7 +1,125 @@
# SIM Toolkit Examples
# SIM Toolkit Examples
Various example Java SIM Toolkit applications. You typically install them using
the tools from the <http://git.osmocom.org/sim/sim-tools/> repository.
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
-----------------
To load CAP files onto sysmoUSIM/sysmoISIM cards, pySim-shell can be used:
https://downloads.osmocom.org/docs/pysim/master/html/cap-tutorial.html
Alternatively it is also possible to use the tools from <https://javacard.pro/globalplatform/>,
for more information see: <https://osmocom.org/projects/cellular-infrastructure/wiki/HelloSTK>
For more information see
<https://osmocom.org/projects/cellular-infrastructure/wiki/Shadysimpy>

24
build.xml Normal file
View File

@@ -0,0 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="HelloSTK" default="dist" basedir=".">
<description>Builds the project.</description>
<target name="dist" description="generate the distribution">
<tstamp/>
<get src="https://github.com/martinpaljak/ant-javacard/releases/latest/download/ant-javacard.jar" dest="." skipexisting="true"/>
<!-- Create the distribution directory -->
<taskdef name="javacard" classname="pro.javacard.ant.JavaCard" classpath="ant-javacard.jar"/>
<javacard>
<cap targetsdk="oracle_javacard_sdks/jc221_kit" jckit="oracle_javacard_sdks/jc305u3_kit" output="build/HelloSTK.cap" sources="hello-stk" classes="build/classes" version="1.0">
<applet class="org.toorcamp.HelloSTK.HelloSTK" aid="d0:70:02:CA:44:90:01:01"/>
<import exps="exp" jar="lib/sim.jar"/>
</cap>
<cap targetsdk="oracle_javacard_sdks/jc221_kit" jckit="oracle_javacard_sdks/jc305u3_kit" output="build/ImsiChange.cap" sources="imsi-change" excludes="src/**/Test*.java" classes="build/classes" version="1.0">
<applet class="org.osmocom.IMSIChange.IMSIChange" aid="d0:70:02:CA:44:90:01:02"/>
<import exps="exp" jar="lib/sim.jar"/>
</cap>
</javacard>
</target>
<target name="clean" description="clean up">
<!-- Delete the built applet -->
<delete dir="HelloSTK.cap"/>
</target>
</project>

BIN
exp/sim/access/javacard/access.exp Normal file
View File

Binary file not shown.

3272
exp/sim/access/javacard/access_exp.tex Normal file
View File

File diff suppressed because it is too large Load Diff

BIN
exp/sim/toolkit/javacard/toolkit.exp Normal file
View File

Binary file not shown.

5946
exp/sim/toolkit/javacard/toolkit_exp.tex Normal file
View File

File diff suppressed because it is too large Load Diff

12
hello-stk/Makefile
View File

@@ -1,12 +0,0 @@
SIMTOOLS_DIR = ../../sim-tools
APPLET_AID = 0xd0:0x70:0x02:0xca:0x44:0x90:0x01:0x01
APPLET_NAME = org.toorcamp.HelloSTK.HelloSTK
PACKAGE_AID = 0xd0:0x70:0x02:0xCA:0x44:0x90:0x01
PACKAGE_NAME = org.toorcamp.HelloSTK
PACKAGE_VERSION = 1.0
SOURCES = \
src/org/toorcamp/HelloSTK/HelloSTK.java
include $(SIMTOOLS_DIR)/javacard/makefiles/applet-project.mk

6
hello-stk/README.md
View File

@@ -1,8 +1,4 @@
# Hello World SIM Toolkit Program
This is the source code to a very simple *Hello World* Java SIM Toolkit
application. You typically install it using the tools from the
<http://git.osmocom.org/sim/sim-tools/> repository.
For more information see
<https://osmocom.org/projects/cellular-infrastructure/wiki/Shadysimpy>
application.

71
imsi-change/Makefile
View File

@@ -1,71 +0,0 @@
SIMTOOLS_DIR = ../../sim-tools
APPLET_AID = 0xd0:0x70:0x02:0xca:0x44:0x90:0x01:0x01
APPLET_NAME = org.osmocom.IMSIChange.IMSIChange
PACKAGE_AID = 0xd0:0x70:0x02:0xCA:0x44:0x90:0x01
PACKAGE_NAME = org.osmocom.IMSIChange
PACKAGE_VERSION = 1.0
SOURCES = \
src/org/osmocom/IMSIChange/Bytes.java \
src/org/osmocom/IMSIChange/MobileIdentity.java \
src/org/osmocom/IMSIChange/IMSIChange.java \
$(NULL)
CAP_FILE = build/javacard/org/osmocom/IMSIChange/javacard/IMSIChange.cap
include ./applet-project.mk
.PHONY: flash
flash: classes
$(eval MODULE_AID := $(shell echo $(APPLET_AID) | sed 's/0x//g' | sed 's/\://g'))
$(eval INSTANCE_AID := $(shell echo $(APPLET_AID) | sed 's/0x//g' | sed 's/\://g'))
. $$PWD/.sim-keys && $(SIMTOOLS_DIR)/bin/shadysim \
--pcsc \
-l $(CAP_FILE) \
-i $(CAP_FILE) \
--enable-sim-toolkit \
--access-domain=00 \
--module-aid $(MODULE_AID) \
--instance-aid $(INSTANCE_AID) \
--nonvolatile-memory-required 0100 \
--volatile-memory-for-install 0100 \
--max-menu-entry-text 21 \
--max-menu-entries 01 \
--kic "$$KIC1" \
--kid "$$KID1"
.PHONY: remove
remove:
. $$PWD/.sim-keys && $(SIMTOOLS_DIR)/bin/shadysim \
--pcsc \
-d "$$(echo $(PACKAGE_AID) | sed 's/0x//g' | sed 's/\://g')" \
--kic "$$KIC1" \
--kid "$$KID1"
.PHONY: list
list:
. $$PWD/.sim-keys && $(SIMTOOLS_DIR)/bin/shadysim \
--pcsc \
--list-applets \
--kic "$$KIC1" \
--kid "$$KID1"
.PHONY: delete
delete: remove
.PHONY: reflash
reflash:
$(MAKE) remove
$(MAKE) flash
.PHONY: test
test:
mkdir -p ./test/classes
javac -target 1.1 -source 1.3 -classpath test/classes -g -d ./test/classes src/org/osmocom/IMSIChange/Bytes.java
javac -target 1.1 -source 1.3 -classpath test/classes -g -d ./test/classes src/org/osmocom/IMSIChange/MobileIdentity.java
javac -target 1.1 -source 1.3 -classpath test/classes -g -d ./test/classes src/org/osmocom/IMSIChange/Test.java
java -classpath test/classes org.osmocom.IMSIChange.Test
.PHONY: check
check: test

17
imsi-change/README.md
View File

@@ -4,23 +4,6 @@ Display and change the IMSI of the SIM. This is a standalone version of a debug
feature in the more complex IMSI Pseudonymization applet. To be used as example
code to build other applets.
### How to flash
```
$ cp .sim-keys.example .sim-keys
$ nvim .sim-keys # adjust KIC1, KID1
$ make flash
```
Before flashing a second time, remove the sim applet:
```
$ make remove
```
### Related
* [IMSI Pseudonymization](https://osmocom.org/projects/imsi-pseudo/wiki)
* [Shadysimply in Osmocom wiki](https://osmocom.org/projects/cellular-infrastructure/wiki/Shadysimpy)

51
imsi-change/applet-project.mk
View File

@@ -1,51 +0,0 @@
BUILD_DIR = ./build
BUILD_CLASSES_DIR = $(BUILD_DIR)/classes
BUILD_JAVACARD_DIR = $(BUILD_DIR)/javacard
JAVACARD_SDK_DIR ?= $(SIMTOOLS_DIR)/javacard
JAVACARD_EXPORT_DIR ?= $(JAVACARD_SDK_DIR)/api21_export_files
ifdef COMSPEC
CLASSPATH = $(JAVACARD_SDK_DIR)/lib/api21.jar;$(JAVACARD_SDK_DIR)/lib/sim.jar
else
CLASSPATH = $(JAVACARD_SDK_DIR)/lib/api21.jar:$(JAVACARD_SDK_DIR)/lib/sim.jar
endif
JFLAGS = -target 1.1 -source 1.3 -g -d $(BUILD_CLASSES_DIR) -classpath "$(BUILD_CLASSES_DIR):$(CLASSPATH)"
JAVA ?= java
JC ?= javac
.SUFFIXES: .java .class
.java.class:
@mkdir -p $(BUILD_CLASSES_DIR)
@mkdir -p $(BUILD_JAVACARD_DIR)
$(JC) $(JFLAGS) $*.java
.PHONY: jar
jar: classes
$(JAVA) -jar $(JAVACARD_SDK_DIR)/bin/converter.jar \
-d $(BUILD_JAVACARD_DIR) \
-classdir $(BUILD_CLASSES_DIR) \
-exportpath $(JAVACARD_EXPORT_DIR) \
-applet $(APPLET_AID) $(APPLET_NAME) \
$(PACKAGE_NAME) $(PACKAGE_AID) $(PACKAGE_VERSION)
default: jar
classes: $(SOURCES:.java=.class)
clean:
$(RM) -rf $(BUILD_DIR)
install:
$(eval CAP_FILE := $(shell find $(BUILD_JAVACARD_DIR) -name *.cap))
$(eval MODULE_AID := $(shell echo $(APPLET_AID) | sed 's/0x//g' | sed 's/\://g'))
$(eval INSTANCE_AID := $(shell echo $(APPLET_AID) | sed 's/0x//g' | sed 's/\://g'))
$(SIMTOOLS_DIR)/bin/shadysim \
$(SHADYSIM_OPTIONS) \
-l $(CAP_FILE) \
-i $(CAP_FILE) \
--enable-sim-toolkit \
--module-aid $(MODULE_AID) \
--instance-aid $(INSTANCE_AID) \
--nonvolatile-memory-required 0100 \
--volatile-memory-for-install 0100 \
--max-menu-entry-text 10 \
--max-menu-entries 01

4
imsi-change/src/org/osmocom/IMSIChange/Test.java
View File

@@ -1,7 +1,7 @@
/* Copyright 2020 sysmocom s.f.m.c. GmbH
* SPDX-License-Identifier: Apache-2.0 */
package org.osmocom.IMSIChange;
import org.osmocom.IMSIChange.*;
package org.osmocom.IMSIPseudo;
import org.osmocom.IMSIPseudo.*;
public class Test {
private static byte nibble2hex(byte nibble)

BIN
lib/sim.jar Normal file
View File

Binary file not shown.

1
oracle_javacard_sdks Submodule

Submodule oracle_javacard_sdks added at e305a1a0b9