Copyright (C) 2020

This software is licensed under the MIT license. See LICENSE file at the root folder of the project.

• Guillaume BOUFFARD (mailto:guillaume.bouffard@ssi.gouv.fr)

CHOUPI is a Java Card Virtual Machine security-oriented for small footprint device. Currently, this implementation provides a proof-of-concept of Java Card 3.0.5.

• ant

• maven

• The arm-none-eabi toolchain
• openocd
• rlwrap

• Boost is required for building the computer version
• CMake

To clone the repository and its dependency, you should execute the following command:

git clone --recurse-submodules https://github.com/orenskl/choupi 

Version 1.75 of Rust is required. To install it you should:

1. Install rustup:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Adding rust to your PATH file:

   source ~/.cargo/env

3. Install the version 1.75 of the rust compiler:

   rustup default 1.75

4. To build to ARM Cortex M4 board, you should run:

   rustup target add thumbv7em-none-eabi

The Java Card Virtual Machine has two main targets: computer and embedded board. The Java Card OS computer version emulates the MPU behavior. The MPU emulation on computer blocks the usage of a debugger (but debugging works on embedded version :).

mkdir -p build/pc cd build/pc cmake -DCHOUPI_TARGET_PC=ON -DCHOUPI_OS_DEBUG=ON -DCHOUPI_JCVM_DEBUG=ON ../../ make

To run the PC version of the JCVM, run choupi as:

./choupi -m flash

The flash file is the initial memory state generated by the rommask.

The other options are the following:

Options: -h [ --help ] Print help messages -m [ --memory ] MEMORY_FILENAME Flash Memory -s [ --save ] Save modifications on MEMORY_FILENAME

Note that for tests, it may be hard to debug some issues, like when the child in an emulation has an unexpected behaviour at runtime that is not a panic!, as it would require a debugger, which is not possible given the emulator is already a pseudo-debugger.

For this reason, sending SIGILL to the child process will make the emulator (ie. parent process) to make it dump core. The core dump can then be used to try to debug the issue.

Currently, the only target is a Nucleo board which embeds a STM32f401. The OS can easily be extended to support new target.

mkdir -p build/stm32 cd build/stm32 cmake -DCHOUPI_TARGET_STM32=ON -DCHOUPI_OS_DEBUG=ON -DCHOUPI_JCVM_DEBUG=OFF ../../ make

Due to a missing of flash memory space, the STM32f401 version cannot embeds JCVM debug output.

Currently, the only target is ST Nucleo STM32f401. To load firmware on board, we use rlwrap though OpenOCD.

1. start OpenOCD in a terminal:

   sudo make ocd

2. in another terminal, run rlwrap:

   sudo make load

   As indicate, to install the firmware, you should execute:

   reset halt; flash write_image erase loader.hex; flash write_image erase code.hex; flash write_image flash.hex; reset run

To see the debug message, in case of the OS is built in debug mode. The Makefile may be modified to built the OS in debug mode.

make screen

To running the OS on board though a debugger, arm-none-eabi-gdb must be install.

1. Starting openOCD in a terminal:

   sudo make ocd

2. Starting GDB in another terminal :

   make debug

3. Enjoy debugging

For the version 1.0, CHOUPI must implement:

• Java exceptions handling
• Input/Output buffer (like ISO7816 buffer)
• Object serialisation in Flash memory
• Shareable interface, implemented in OS but not yet implemented in the VM layout
• Transient objects
• Atomicity
• Implemented cryptographic functions