Java Card Implementation of Offline CBDC

Prerequisites

• Windows OS (We used Windows 11)
• Java Card Development Kit Tools and Simulator
• JDK 17 (64 bit version) or newer (although only tested on JDK 17)
• JDK 21 fails. It requires "source value" to be 8, instead of 7.
• GlobalPlatformPro executable
• Text editor or IDE of your choice (we used Visual Studio Code)

Development Environment Setup

• Start from here for instructions on how to install the Development Kit Tools.

• Start from here for instructions on how to install the Development Kit Simulator.

  • Before running the simulator for the first time, it must be initialized as described here.
  • After simulator is installed, copy libcrypto-3.dll and libssl-3.dll provided under prebuilt_bin/ directory to the simulator runtime directory i.e. JC_HOME_SIMULATOR/runtime/bin/, for example:
  

Compilation

To get started, the first step is to compile the prototype project files.

In a Command Prompt, first set working directory to the parent directory of this repo plutus then do:

cd prototype
build.bat

Check output to see that there were no errors in compiling applet, converting applet to CAP file, or compiling the client. Common errors we encountered during setup were path issues (e.g. JAVA_HOME, JC_HOME_TOOLS, or JC_HOME_SIMULATOR environment variables not set correctly)

If code is modified, the code must be recompiled to reflect any new changes and we also recommend running clean.bat before recompiling the project again to delete all bin files generated during previous compilation.

Installing / Deploying CAP file

This step must be done after compilation before any code can be run.

For testing on simulator, the installation and deployment of the converted applet (CAP) file is handled within the testscripts themselves. As the testscripts written under prototype were originally based on the simulator samples provided by Oracle, we recommend modifying the testscripts and observing changes as a starting point.

For hardware testing execute the following in a command prompt with gp.exe from GlobalPlatformPro:

gp.exe -v -install <path to repository>\prototype\applet\deliverables\plutus\plutus\javacard\plutus.cap

If multiple card readers are connected to the host computer, there is an optional -r flag that can be used to select the reader by name. See accompanying image:

Note: running this step should take a while (~1 minute), and if success, the console should output a message of the form <path to CAP file> loaded: <package name> <CAP AID>, for example:

C:\Users\linus\Documents\plutus\prototype\applet\deliverables\plutus\plutus\javacard\plutus.cap loaded: plutus 000102030405060708090A0B0C0D0E

• Note: the package name and application identifier (AID) are specified in the configuration file at prototype\applet\configurations\plutus\plutus.conf which was used by the converter when generating the CAP file

If running this command fails, typically it is either the CAP file was not generated properly (i.e. failed during conversion) or the applet instance is already on the card. In the former case, the user should check the output when running build.bat for any converter errors. For the latter case, the user should run the following testscript to undeploy the CAP file from the card: run testscript.TestUndeploy -sim=0 -v=0.

Testing on Simulator

1. Start the simulator in one command prompt (jcsw.exe)
2. In another command prompt cd plutus\prototype

For tests involving one simulator instance:

3. run.bat testscript.<Name of Test> -sim=1 -v=0 (e.g. to run TestInit do run.bat testscript.TestInit -sim=1 -v=0)

Arguments:

• -sim indicates to the testscript whether a simulator (set to 1) or a physical card (set to 0) at a connected card reader is listening
• -v indicates to the testscript whether to output APDU log to the console (set to 1 to turn on, 0 to turn off) i.e. allows toggling of viewing command and response APDUs between active and secure element

For tests involving two simulator instances:

4. run.bat testscript.<Name of Test> -sim1=1 -sim2=1 -v=0

Arguments:

• -sim1 indicates whether SE1 is simulator or physical card
• -sim2 indicates whether SE2 is simulator or physical card
• -v indicates whether to output APDU log to console

Note: all arguments are required

Example console output of running a testscript and corresponding simulator output:

The user has the option of printing debug, user, and performance statements to the console by changing the DEBUG_PRINTS, USER_PRINTS, and PERF_PRINTS flags respectively in .\prototype\client\src\terminal\TerminalUtil.java. The picture above is an example with only USER_PRINTS enabled.

Video of setting up and running testscript on simulator: https://youtu.be/nOPloBNoB4g

Testing on Hardware

For hardware testing, we used the ACOSJ 95K dual interface Java Card with the SCR3310v2.0 USB Contact Smart Card Reader. Additionally we also used the ACR39U reader which works in most cases however, we were only able to install the .cap file using the SCR reader.

Prior to using the card readers, install their respective drivers available at the provided links. The .cap files should also already be installed on the card(s) being tested. If not yet installed, please see installing cap file section

The steps are the same as testing on simulator except set the sim arguments to 0.

E.g. for tests involving one card:

3. run.bat testscript.Test_E2E_AE_SE -sim=0 -v=0

and for tests involving two cards:

4. run.bat testscript.Test_E2E_SE_SE -sim1=0 -sim2=0 -v=0

When running hardware tests, the user should monitor the console output for prompts to remove or insert the card into the card reader.

See image below for example of running a testscript involving two cards:

Video of installing cap file and running demo on hardware: https://youtu.be/YKpw-nOluuI

Video of undeploying cap file and running testscript on hardware: https://youtu.be/YEboElOGi5I

List of TestScripts

For running the testscripts, a successful run will be indicated with the line Test Complete at the end of the console standard output. If there are any issues, the aforementioned DEBUG_PRINTS flag should be set and testscripts should be run using the -v=1 argument to turn on printing of APDUs. The testscripts use a java.util.logging.Logger for logging APDU-related print statements. When -v=1 argument is added, an output file named .\prototype\client\bin\testscript.<Test Name>.log will be generated which the user should examine for unexpected APDU and SW values.

The following are a list of testscripts located under .\prototype\client\src\testscript\ for testing of applet functionality.

• TestInit
  • Simple program to test install/deploy of CAP file, initialization of card-side parameters, and uninstall/undeploy of the applet
• TestUndeploy
  • Only undeploys applet instance from card/simulator, assumes applet instance is currently on card/simulator
• TestPinTerminal
  • Tests PinTerminal functionality (PIN and PUK)
• Test_E2E_AE_SE
  • Tests AE to SE mutual authentication and basic functionality of encryption/decryption of APDU payload
• Test_E2E_Bank_SE
  • Tests BankTerminal functionality (withdraw, deposit, check balance)
• Test_E2E_SE_SE
  • Tests SE to SE mutual authentication and end-to-end transfer capability
• Test_E2E_SE_SE_Override_Transfer
  • Tests Test_E2E_SE_SE but overrides transaction logs that did not complete
• Test_E2E_SE_SE_Retransfer
  • Tests Test_E2E_SE_SE but receiving SE loses power resulting in testing of the end-to-end retransfer capability
• Test_E2E_SE_SE_sync_balance
  • Tests Test_E2E_SE_SE with multiple transactions then synchronizes to the online bank using balance tracking
• Test_E2E_SE_SE_sync_transaction
  • Tests Test_E2E_SE_SE with multiple transactions then synchronizes to the online bank using transaction tracking
• Test_Perf_Bank_SE
  • Measures AE to SE mutual authentication and withdraw timing (latency)
• Test_Perf_SE_SE
  • Measures SE to SE transfer (end to end) timing
• Test_Perf_SE_SE_2
  • An all-inclusive test to measure timing of all protocol operations