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
parent ba0cd07c44
commit 55003eed38
1 changed files with 94 additions and 64 deletions
--- a/README.md
+++ b/README.md
@@ -1,93 +1,123 @@
-# 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.

-For more information see
-<https://osmocom.org/projects/cellular-infrastructure/wiki/Shadysimpy>
+Build requirements
+------------------

+### Install ANT:

-# Build requirements
+ANT is required to control the build process. It can be installed via APT
+(debian)

-Install a JAVA compiler and ANT:
 ```
-$ sudo apt-get install default-jdk ant
+$ sudo apt install ant
 ```

-Download the Javacard SDKs into the (empty) directory oracle_javacard_sdks
+### 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
 ```

-There is also another component "ant-javacard.jar", which is automatically downloaded during the build process.
+Building CAP files
+------------------

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

-The build process is started by calling ANT
 ```
-$ ant
-Buildfile: /home/owner/work/git_master/hello-stk/build.xml
+$ 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] 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
+      [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/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.
+  [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/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] 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/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] 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/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:134: warning: [cast] redundant cast to short
+  [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/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:135: warning: [cast] redundant cast to short
+  [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/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:145: warning: [cast] redundant cast to short
+  [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/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:146: warning: [cast] redundant cast to short
+  [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/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/IMSIChange.java:173: warning: [cast] redundant cast to byte
+  [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/owner/work/git_master/hello-stk/imsi-change/src/org/osmocom/IMSIChange/MobileIdentity.java:41: warning: [cast] redundant cast to byte
+  [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
-  [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
+      [cap] CAP saved to /home/user/work/simcard_applet_loading/hello-stk_osmo/build/ImsiChange.cap

 BUILD SUCCESSFUL
-Total time: 7 seconds
+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>