Building and Running

This section builds and runs the security_demo demonstration application described in Architecture document. All the host machine and target platform requirements described previously in this developer kit documentation are assumed.

Building the Application

As usual, this assumes that the user is already running a Docker container within the build environment, where we can create a directory and clone the code and dependencies.

mkdir /host/security_demo
cd /host/security_demo

repo init -u https://github.com/sel4devkit/sel4devkit-maaxboard-camkes-manifest.git

repo sync

The application requires an IP address to be allocated to PicoServer. This should be substituted for xxx.xxx.xxx.xxx below. From the /host/security_demo directory, we execute the following commands:

Configure the python environment:

python -m venv pyenv
source pyenv/bin/activate
pip install sel4-deps camkes-deps "protobuf<=3.20.*"

Create build area:

mkdir build
cd build

Build application:

../init-build.sh -DCAMKES_APP=security_demo -DPLATFORM=maaxboard -DPICOSERVER_IP_ADDR=xxx.xxx.xxx.xxx

This command should be repeated as a workaround - see the implementation note below:

../init-build.sh -DCAMKES_APP=security_demo -DPLATFORM=maaxboard -DPICOSERVER_IP_ADDR=xxx.xxx.xxx.xxx

Then run ninja as usual:

ninja

Implementation note

There is a known race condition with the CMake configuration of picoserver, which, if only run once, results in fatal error: pico_device.h: No such file or directory. A workaround is to run the command twice, or run CMake again, by typing cmake . (see here).

Preparing to Run

A successful build will result in an executable file called capdl-loader-image-arm-maaxboard in the images subdirectory.

Running the security_demo application requires the following:

• Connect a keyboard to the USB socket¹ of the MaaXBoard;
• Establish an Ethernet connection between the MaaXBoard and the host machine, which can be direct or via a network, as outlined in an earlier section (e.g. it will already be in place if TFTP is being used to transfer executables).

If the user has experience of running the picoserver_uboot test application, then elements of the security_demo application will be familiar. For example, from a terminal window on the host machine, we will use the netcat (nc) command (native to Linux or macOS, or available as a download for Windows) to connect to the MaaXBoard, so this should be prepared.

Running the Application

The application invokes three instances of the U-Boot Driver Library, so various sets of diagnostic messages are repeated on the CoolTerm display as the application starts. We should not be unduly concerned with some of the individual messages, such as No ethernet found, since in this case only one of the library instances is configured to use Ethernet (i.e. the library invoked by the EthDriverUboot component), and amongst the other messages there should be confirmation that it was successful, e.g. Assigned ipv4 xxx.xxx.xxx.xxx to device eth0. There are also some clk_register: failed ... (parent ...) messages, which are harmless (a fault in U-Boot's clock driver for the MaaXBoard).

When the application's initialisation has completed, we should see:

run_uboot_command@uboot_wrapper.c:176 --- running command 'fatrm mmc 0:2 transmitter_log.txt' ---
Net:   transmitter_log.txt: doesn't exist
run_uboot_command@uboot_wrapper.c:181 --- command 'fatrm mmc 0:2 transmitter_log.txt' completed with return code 1 ---

Note that on subsequent runs, the log file will exist (unless the user has intentionally deleted it), and the output will instead read:

run_uboot_command@uboot_wrapper.c:176 --- running command 'fatrm mmc 0:2 transmitter_log.txt' ---
run_uboot_command@uboot_wrapper.c:181 --- command 'fatrm mmc 0:2 transmitter_log.txt' completed with return code 0 ---

In either scenario, this is housekeeping by the application to delete any previous Transmitter logfile from the SD card, before it starts writing new log data. The logfile is named transmitter_log.txt and is expected on the third partition of the SD card - see the FAT partition FILESYS established during the Partitioning the SD Card section.

Just as with the picoserver_uboot test application, the application may sporadically display No such port .... messages as it monitors traffic on the network. This is expected diagnostic behaviour that may be ignored; indeed, the lack of any such messages may indicate for example that the Ethernet driver has not initialised properly.

The application is now ready to perform various actions concurrently:

1. If a key is pressed, the plaintext character will be encrypted into a ciphertext character;
2. If a client requests an Ethernet connection on port 1234, the application will establish the connection and transmit ciphertext to the client, continuing to do so until the client closes the connection;
3. Every 30 seconds, if there are any ciphertext characters that it has not yet logged to file, the application will append them to the logfile on the SD card.

For item (2), from a terminal window on the host machine, start netcat with the command:

nc xxx.xxx.xxx.xxx 1234

where xxx.xxx.xxx.xxx is the IP address of the MaaXBoard, as previously specified in the init_build call, and 1234 is the port number that has been programmed into the application.

In the CoolTerm window, a message such as the following will signify a successful connection:

transmitter: Connection established with yyy.yyy.yyy.yyy on socket 1

where yyy.yyy.yyy.yyy is the IP address of the host machine.

If this connection is not established promptly, please refer to the previous implementation note relating to network connection delays.

If characters have been typed at the USB keyboard before making the netcat connection, then (ciphertext) characters will appear straightaway on the host machine, since the application stores characters in a buffer while they cannot be sent.

Plaintext messages may be typed on the keyboard (note that these are not displayed anywhere), for example:

Hello world, testing 123. We love seL4!

Within the host machine's netcat session, the corresponding ciphertext message should appear:

Uryyb jbeyq, grfgvat 123. Jr ybir frY4!

Periodically, the CoolTerm window will show diagnostic messages concerning the logfile, such as:

run_uboot_command@uboot_wrapper.c:176 --- running command 'fatwrite mmc 0:2 0x55b010 transmitter_log.txt 26 1' ---
38 bytes written in 5 ms (6.8 KiB/s)
run_uboot_command@uboot_wrapper.c:181 --- command 'fatwrite mmc 0:2 0x55b010 transmitter_log.txt 26 1' completed with return code 0 ---

The application will continue indefinitely. netcat sessions on the host machine may be terminated (Ctrl-C) and restarted, whereupon the application will establish a new connection (buffering output in the meantime).

If the MaaXBoard is powered off and its SD card removed and transferred to the host machine, the transmitter_log.txt can be accessed from the FILESYS partition as one would expect.

To reduce the risk of corrupting the SD card, it is advisable to avoid powering off the MaaXBoard during a write operation of the logfile. As this operation lasts in the order of 10 ms and only occurs every 30 seconds (and only then if there are any ciphertext characters that have not yet been logged to file), the risk is both remote and avoidable (e.g. power off soon after a fatwrite command message, or wait for >30 seconds after the last fatwrite command message).