README.md: mention pySim-shell as tool to install cap files

Related: OS#6069

.gitignore

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

.gitmodules

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

README.md

@@ -1,7 +1,125 @@
-# SIM Toolkit Examples
+# SIM Toolkit Examples
 
-Various example Java SIM Toolkit applications. You typically install them using
+This repository contains example Java SIM Toolkit applications.
-the tools from the <http://git.osmocom.org/sim/sim-tools/> repository.
+
+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>

build.xml

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

hello-stk/Makefile

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

hello-stk/README.md

@@ -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
+application.
-<http://git.osmocom.org/sim/sim-tools/> repository.
-
-For more information see
-<https://osmocom.org/projects/cellular-infrastructure/wiki/Shadysimpy>

imsi-change/Makefile

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

imsi-change/README.md

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

imsi-change/applet-project.mk

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

imsi-change/src/org/osmocom/IMSIChange/Test.java

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