Warning
The issues that led to the creation of this guide are now resolved upstream.
- Osmocom wiki has updated instructions.
- Osmocom HelloSTK repository now uses same ant-based buildchain.
This guide will not be maintained any further.
My 2021's guide to HelloSTK with two changes:
- no need for ancient Java JDKs: updated ant-javacard buildchain
- works with sysmoISIM-SJA2
These are just my personal notes, but maybe this "guide" helps you to build and install SIM-Toolkit applets. See here for more information:
The applet itself is rather simple and just an example:
Tested with:
- sysmoISIM-SJA2
- PCSC card reader
- OpenJDK 11
You'll need a Java compiler and ant:
sudo apt install default-jdk ant
Init this repo:
git clone https://github.com/mrlnc/HelloSTK2.git
cd HelloSTK2
Pull the Javacard SDKs:
git submodule update --init --recursive
Then run ant to build the applet. The output should look like this:
$ ant
Buildfile: /home/merlin/HelloSTK2/build.xml
dist:
[get] Destination already exists (skipping): /home/merlin/HelloSTK2/ant-javacard.jar
[cap] INFO: using JavaCard 3.0.5 SDK in /home/merlin/HelloSTK2/oracle_javacard_sdks/jc305u3_kit
[cap] INFO: targeting JavaCard 2.2.1 SDK in /home/merlin/HelloSTK2/oracle_javacard_sdks/jc221_kit
[cap] INFO: Setting package name to com.github.mrlnc.HelloSTK2
[cap] Building CAP with 1 applet from package com.github.mrlnc.HelloSTK2 (AID: D07002CA44900101)
[cap] com.github.mrlnc.HelloSTK2.HelloSTK2 D07002CA44900101
[compile] Compiling files from /home/merlin/HelloSTK2/src
[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/merlin/HelloSTK2/bin/HelloSTK2.cap
BUILD SUCCESSFUL
Total time: 1 second
I've added my resulting binary, just keep in mind that you'll need a compatible SIM:
Some guides tell you to use GlobalPlatformPro or sim-tools by shadysim.
However:
- GlobalPlatformPro works for javacard applets, but our SIM applets are a bit special.
- SIM-Applets require additional OTA security
- this has been added to a fork of sim-tools but not the original tool.
Download the sim-tools fork by @herlesupreeth:
git clone https://github.com/herlesupreeth/sim-tools.git
Dependencies:
pip2 install --user pycrypto pyscard
Then load and install the applet. Make sure you insert KIC1 and KID1. I think you might brick your card if you fail the authentication too many times. Don't skip any parameter. It's intentional to have load and install separate.
python2 ./sim-tools/shadysim/shadysim_isim.py --pcsc \
-l ./HelloSTK2/bin/HelloSTK2.cap \
-i ./HelloSTK2/bin/HelloSTK2.cap \
--kic XXX
--kid XXX
--instance-aid d07002CA44900101
--module-aid d07002CA44900101
--nonvolatile-memory-required 00ff
--volatile-memory-for-install 00ff
--enable-sim-toolkit
--max-menu-entry-text 15
--max-menu-entries 02
- wrong KIC, KID (note to myself: double-check)
- applets cannot be updated. you need to delete, then re-install. common error code in this case:
6985 - The first 5 bytes of Module AID and Instance AID must match with the first 5 bytes of the AID defined in the CAP file.
shadysim_isimrequirespyscard==1.9.9
Use shadysim_isim.py with the flag --list-applets:
$ python2 shadysim/shadysim_isim.py --pcsc --kic xxx --kid xxx --list-applets
AID: a0000000620001, State: 01, Privs: 00
AID: 4a6176656c696e2e6a637265, State: 01, Privs: 00
AID: a0000000620101, State: 01, Privs: 00
AID: a0000000620102, State: 01, Privs: 00
AID: a0000000620201, State: 01, Privs: 00
AID: a000000062020801, State: 01, Privs: 00
AID: a00000006202080101, State: 01, Privs: 00
AID: a0000000620002, State: 01, Privs: 00
AID: a0000000620003, State: 01, Privs: 00
AID: a000000062010101, State: 01, Privs: 00
AID: a00000015100, State: 01, Privs: 00
AID: a0000000090005ffffffff8911000000, State: 01, Privs: 00
AID: a0000000090005ffffffff8912000000, State: 01, Privs: 00
AID: a0000000090005ffffffff8913000000, State: 01, Privs: 00
AID: a0000000090005ffffffff8911010000, State: 01, Privs: 00
AID: a0000000871005ffffffff8913100000, State: 01, Privs: 00
AID: a0000000871005ffffffff8913200000, State: 01, Privs: 00
AID: a0000000090003ffffffff8910710001, State: 01, Privs: 00
AID: a0000000090003ffffffff8910710002, State: 01, Privs: 00
AID: a0000000090005ffffffff8915000000, State: 01, Privs: 00
AID: a00000015141434c, State: 01, Privs: 00
Instance AID: a00000015141434c00
AID: d001935711, State: 01, Privs: 00
Instance AID: d001935711fa7b01
AID: d07002ca44, State: 01, Privs: 00
Instance AID: d07002ca44900101
Note the AID d07002ca44 for the Instance AID: d07002ca44900101 that we just installed. We can use the AID to uninstall the applet:
$ python2 shadysim/shadysim_isim.py --pcsc --kic xxx --kid xxx -d d07002ca44
In build.xml, set targetsdk to the version that is supported by your javacard.
For sysmoISIM-SJA2, use JC 2.2.1:
targetsdk="oracle_javacard_sdks/jc221_kit"
Maybe, aid needs to match the AIDs during installation 🤷🏼♂️
<applet class="com.github.mrlnc.HelloSTK2.HelloSTK2" aid="d0:70:02:CA:44:90:01:01">
Some keywords for people googling for hours like crazy without success, just like me 💫
- sim-tools targets versions that aren’t supported by JDK anymore
error: Source option 1.3 is no longer supported. Use 6 or later.
error: Target option 1.1 is no longer supported. Use 1.6 or later.
- The converter.jar (Java Card 2.2.1 Class File Converter) isn’t happy when changing the target to 1.6:
error: org.toorcamp.HelloSTK.HelloSTK: unsupported class file format of version 50.0.
The key is that ant-javacard uses a new SDK to generate CAPs compatible to the old SDK:
targetsdk="oracle_javacard_sdks/jc221_kit" jckit="oracle_javacard_sdks/jc305u3_kit"
- the
simlibrary comes from 3GPP TS43.019, see this Stack Overflow comment - HelloSTK
- ant-javacard
- oracle_javacard_sdks