corda/sgx-jvm/tools/sx/README.md

SGX Build Container and Utilities

Project Organisation

• Containers

  To pin down dependencies and simplify development and testing, we have a Docker image with all necessary compile- and run-time dependencies pre-installed. This image supports mounting of volumes for the user's home directory, code repository, and SGX SDK directory. It also exposes various ports for debuggable targets (JVM and native). To run SGX-enabled applications in hardware mode, the user must pass in a reference to the SGX kernel driver (which is done automagically if the sx command is used).

• Tools

  sx is a utility that simplifies running builds and tests inside the SGX container, and also provides some additional helper functions for things like generating tags databases, starting debug servers, etc.

Getting Started

To get started, run the following commands in sgx-jvm:

> source environment
> sx help

Yielding the following output:

usage: <variables> sx <command> <options>

<command>
  build                build project in container (<directory> <arguments>)
  containers           actions related to containers
  debug                actions related to debugging
  exec                 shorthand for `containers exec core`
  get-started          build containers and key components
  help                 show help information
  hsm                  actions related to the hsm simulator
  logs                 tail application logs
  reports              actions related to reports
  shell                show information about shell commands
  tags                 actions related to tag databases

<options>
  -c                   colours = on | off (-C)
  -d                   debug = on | off (-D)
  -f                   force operation
  -h                   hardware = on | off (-s)
  -r                   target = release | pre-release (-p)
  -s                   hsm profile = simulator | development hsm (-S) | production (-P)
  -t                   tty = on | off (-T)
  -v                   verbose output

<variables>
  LINES                number of lines to return from the end of the log files (default 50)
  PORT                 port number used for connecting to the ISV (default 9080)

The first command simply sets up an alias pointing to sgx-jvm/tools/sx/sx, and enables Bash auto-completion for the various command options. For example:

> sx b<tab> # will expand to "sx build"

The second command shows all the available sub-commands and options.

If this is your first time using sx, you will most likely have to build the Docker container used for building and running the various components of the SGX projects. To do that, run the command:

> sx get-started

This command will also set up default configuration for SGX-GDB, both inside and outside of the container, and Visual Studio Code configuration if you fancy running remote debugging sessions from an IDE.

Building Components

As an example, this section will go through the process of building the various components of the remote attestation project.

Enclave

To build the enclave and sign it with a self-signed OpenSSL certificate (for testing), run the following command:

> sx build remote-attestation/enclave clean all

This command runs make -C sgx-jvm/remote-attestation/enclave clean all inside the SGX container.

To build the enclave in hardware and pre-release mode, use the -h and -p switches like this:

> sx build -hp remote-attestation/enclave clean all

Host

Similarly, to build the host (JVM-layer), you can run the following command:

> sx build remote-attestation/host

This will run gradlew in the host/ directory, with the necessary paths and environment variables set.

JNI Library

This is a native library, so you can compile it either for use with software simulation or hardware.

> sx build remote-attestation/host/native       # simulation, debug mode
# or:
> sx build -hp remote-attestation/host/native   # hardware, pre-release mode

As part of the build, as seen in host/native/Makefile, we run javah on the NativeWrapper class to extract its JNI mapping. This mapping will be written to wrapper.hpp. This means that the JVM-layer needs building prior to this step.

Running and Debugging Components

Unit Tests

The unit tests are run through Gradle inside the SGX container, with the various paths set to necessary dependencies. For instance, we need to set the java.library.path and corda.sgx.enclave.path variables to point to the JNI library and the enclave shared object, respectively. This is all done for you by the Gradle build script, the container, and the sx tool.

Provided that you have built the aforementioned components, you can now run the unit tests with the following command:

> sx build remote-attestation/host unit-tests

You can open the output report by issuing the following command:

> sx reports unit-tests

Integration Tests

Similarly, you can run the integration tests with the following command:

> sx build remote-attestation/host integration-tests

This requires that the service provider (in the future challenger and IAS proxy) is running. Say that the service is running on port 12345, you can run the tests like this:

> PORT=12345 sx build remote-attestation/host integration-tests

You can open the output report by issuing the following command:

> sx reports integration-tests

If you want to explore the logs, you can use the logs command:

> LINES=100 sx logs

Test Flow

There is also a simple attestation flow which similarly to the integration test requires the service provider to run on a specific port. This flow can be run with the sx build command.

To run the simple flow without attaching a debugger, run:

> PORT=8080 sx build remote-attestation/host run

There are a few different debug targets depending on how you want to run your debugger:

• Local

  Runs gdb inside the Docker container (if you don't have gdb installed on your computer): run-local.

• Remote

  Runs gdbserver inside the Docker container so that you can attach to it from the host computer or another machine: run-remote.

• SGX

  Runs sgx-gdb inside the Docker container (if you don't have sgx-gdb installed on your computer): run-sgx. This lets you step through enclave-code, inspect stack traces in the trusted environment, etc. Obviously, this is only possible if the program has been compiled for debug and simulation mode.

For all of the above, and for the unit and integration tests, you can attach a Java debugger remotely as well, using JDWP.

Other Tools

CTags

For the C/C++ part of the project, you might wish to construct a tags file to easily jump back and forth between symbols. You can construct this either with or without the symbols from the Linux SGX SDK:

> sx tags lean remote-attestation # Remote Attestation project only
> sx tags full remote-attestation # Include symbols from the SGX SDK

Dependencies

• Intel SGX SDK – 01org/linux-sgx
• Intel SGX Driver – 01org/linux-sgx-driver