mirror of
https://gitea.osmocom.org/sim-card/pysim.git
synced 2026-03-16 18:38:32 +03:00
15140aae44
Installing JAVA-card applets from a CAP file is a multi step process, which is difficult when done manually. Fortunately it is easy to automate the process, so let's add a dedicated command for that. Change-Id: I6cbd37f0fad5579b20e83c27349bd5acc129e6d0 Related: OS#6679
104 lines
5.1 KiB
ReStructuredText
104 lines
5.1 KiB
ReStructuredText
|
|
Guide: Installing JAVA-card applets
|
|
===================================
|
|
|
|
Almost all modern-day UICC cards have some form of JAVA-card / Sim-Toolkit support, which allows the installation
|
|
of customer specific JAVA-card applets. The installation of JAVA-card applets is usually done via the standardized
|
|
GlobalPlatform (GPC_SPE_034) ISD (Issuer Security Domain) application interface during the card provisioning process.
|
|
(it is also possible to load JAVA-card applets in field via OTA-SMS, but that is beyond the scope of this guide). In
|
|
this guide we will go through the individual steps that are required to load JAVA-card applet onto an UICC card.
|
|
|
|
|
|
Preparation
|
|
~~~~~~~~~~~
|
|
|
|
In this example we will install the CAP file HelloSTK_09122024.cap [1] on an sysmoISIM-SJA2 card. Since the interface
|
|
is standardized, the exact card model does not matter.
|
|
|
|
The example applet makes use of the STK (Sim-Toolkit), so we must supply STK installation parameters. Those
|
|
parameters are supplied in the form of a hexstring and should be provided by the applet manufacturer. The available
|
|
parameters and their exact encoding is specified in ETSI TS 102 226, section 8.2.1.3.2.1. The installation of
|
|
HelloSTK_09122024.cap [1], will require the following STK installation parameters: "010001001505000000000000000000000000"
|
|
|
|
During the installation, we also have to set a memory quota for the volatile and for the non volatile card memory.
|
|
Those values also should be provided by the applet manufacturer. In this example, we will allow 255 bytes of volatile
|
|
memory and 255 bytes of non volatile memory to be consumed by the applet.
|
|
|
|
To install JAVA-card applets, one must be in the possession of the key material belonging to the card. The keys are
|
|
usually provided by the card manufacturer. The following example will use the following keyset:
|
|
|
|
+---------+----------------------------------+
|
|
| Keyname | Keyvalue |
|
|
+=========+==================================+
|
|
| DEK/KIK | 5524F4BECFE96FB63FC29D6BAAC6058B |
|
|
+---------+----------------------------------+
|
|
| ENC/KIC | 542C37A6043679F2F9F71116418B1CD5 |
|
|
+---------+----------------------------------+
|
|
| MAC/KID | 34F11BAC8E5390B57F4E601372339E3C |
|
|
+---------+----------------------------------+
|
|
|
|
[1] https://osmocom.org/projects/cellular-infrastructure/wiki/HelloSTK
|
|
|
|
|
|
Applet Installation
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
To prepare the installation, a secure channel to the ISD must be established first:
|
|
|
|
::
|
|
|
|
pySIM-shell (00:MF)> select ADF.ISD
|
|
{
|
|
"application_id": "a000000003000000",
|
|
"proprietary_data": {
|
|
"maximum_length_of_data_field_in_command_message": 255
|
|
}
|
|
}
|
|
pySIM-shell (00:MF/ADF.ISD)> establish_scp02 --key-dek 5524F4BECFE96FB63FC29D6BAAC6058B --key-enc 542C37A6043679F2F9F71116418B1CD5 --key-mac 34F11BAC8E5390B57F4E601372339E3C --security-level 1
|
|
Successfully established a SCP02[01] secure channel
|
|
|
|
.. warning:: In case you get an "EXCEPTION of type 'ValueError' occurred with message: card cryptogram doesn't match" error message, it is very likely that there is a problem with the key material. The card may lock the ISD access after a certain amount of failed tries. Carefully check the key material any try again.
|
|
|
|
|
|
When the secure channel is established, we are ready to install the applet. The installation normally is a multi step
|
|
procedure, where the loading of an executable load file is announced first, then loaded and then installed in a final
|
|
step. The pySim-shell command ``install_cap`` automatically takes care of those three steps.
|
|
|
|
::
|
|
|
|
pySIM-shell (SCP02[01]:00:MF/ADF.ISD)> install_cap /home/user/HelloSTK_09122024.cap --install-parameters-non-volatile-memory-quota 255 --install-parameters-volatile-memory-quota 255 --install-parameters-stk 010001001505000000000000000000000000
|
|
loading cap file: /home/user/HelloSTK_09122024.cap ...
|
|
parameters:
|
|
security-domain-aid: a000000003000000
|
|
load-file: 569 bytes
|
|
load-file-aid: d07002ca44
|
|
module-aid: d07002ca44900101
|
|
application-aid: d07002ca44900101
|
|
install-parameters: c900ef1cc80200ffc70200ffca12010001001505000000000000000000000000
|
|
step #1: install for load...
|
|
step #2: load...
|
|
Loaded a total of 573 bytes in 3 blocks. Don't forget install_for_install (and make selectable) now!
|
|
step #3: install_for_install (and make selectable)...
|
|
done.
|
|
|
|
The applet is now installed on the card. We can now quit pySim-shell and remove the card from the reader and test the
|
|
applet in a mobile phone. There should be a new STK application with one menu entry shown, that will greet the user
|
|
when pressed.
|
|
|
|
|
|
Applet Removal
|
|
~~~~~~~~~~~~~~
|
|
|
|
To remove the applet, we must establish a secure channel to the ISD (see above). Then we can delete the applet using the
|
|
``delete_card_content`` command.
|
|
|
|
::
|
|
|
|
pySIM-shell (SCP02[01]:00:MF/ADF.ISD)> delete_card_content D07002CA44 --delete-related-objects
|
|
|
|
The parameter "D07002CA44" is the load-file-AID of the applet. The load-file-AID is encoded in the .cap file and also
|
|
displayed during the installation process. It is also important to note that when the applet is installed, it cannot
|
|
be installed (under the same AID) again until it is removed.
|
|
|
|
|