diff --git a/README.md b/README.md index 58e0473..091fc20 100644 --- 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 repository. +This repository contains example Java SIM Toolkit applications. -For more information see - +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 + + +OpenJDK 11.0.2 (build 11.0.2+9) + + +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: + +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 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] 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] 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 - [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: + + +Loading CAP files +----------------- + +The loading of the CAP files is typically done using the tools from . + +For more information see: +