Conclave Core Sdk Save

:warning: The Conclave SDK is discontinued and is no longer actively maintained. Feel free to fork this repo if you wish to continue making improvements. For any further queries, including use of the Key Derivation Service (KDS), please reach out to R3.

The Conclave Core SDK is an open source platform that lets you create SGX enclaves easily. You can write your enclave code in high-level languages such as Java, Kotlin, and JavaScript.

Enclaves are small pieces of software that are protected from attack by the owner of the computer on which they run. They are ideally suited to solving multi-party collaboration and privacy problems, but can also be used to secure your infrastructure against attack.

The Conclave Core SDK is developed by R3, and has been made available to the open source community.

How to use Conclave

If you want to learn how to use Conclave and build enclaves, take a look at the hello world example and tutorial. You can also refer to the Conclave documentation and API docs.

Building the SDK

If you want to build the SDK, you can do so both on Linux and macOS (Intel only) using a development Docker container.

:warning: **Building the SDK is currently not supported on Apple Silicon hardware.

In the instructions below we assume Ubuntu as the Linux distribution; in case you use a different one, you need to translate the instructions to your chosen distribution.

Getting the source code

To retrieve the source code you need to clone this repository:

git clone https://github.com/R3Conclave/conclave-core-sdk.git

Preparing the development container

We have created Docker containers to have an encapsulated and easy-to-use build environment, follow the instructions for your operating system.

macOS (Intel)

You can install Docker Desktop following Docker's instructions

:warning: On macOS you must increase your Docker RAM allocation. The default is 2GB but we have found out that it needs around 6GB of RAM to successfully build and run the tests.

Linux (Ubuntu)

You can get install Docker for Linux following Docker's instructions.

In either cases (Linux or macOS), make sure you can use Docker without root privileges by adding yourself to the docker UNIX group:

sudo groupadd docker            # Create the docker group. Don't worry if it already exists!
sudo usermod -aG docker $USER   # Add your user to the docker group.

This step is not configured out of the box on some Linux distributions like Ubuntu, and will break the development environment scripts (which you will need later).

Development is done inside a devenv container, which has access to your host disk and network. This is layered on top of the build container.

Building and entering into your development container

Once you have set up your container, you need to enter into it:

./scripts/devenv_shell.sh

After the container has been built and your terminal have printed out a lot of logging, you should see at the end a message similar to this:

Welcome to the Conclave development environment.

You are now in a shell inside a Docker container. 
Run ./gradlew build test to compile and run unit tests.
Browse to http://localhost:8000 to view the external docsite.

conclave master ~/conclave-core-sdk> 

Building the SDK and runnning tests

We use Gradle to build the SDK, which you can do with the following command:

./gradlew build

This is will also run the unit tests. To skip them run:

./gradlew build -x test

Due to the large number of native components, the build takes around 10 minutes the first time, then some elements of the build are cached and hence it should be sensibly quicker after that.

The integration tests reside as a separate Gradle project in integration-tests/. To run them you will first need to create a local Maven repository with the SDK artifacts:

./gradlew publishAllPublicationsToBuildRepository
cd integration-tests
./gradlew test

Note: if in your development you need to use sudo inside the container, then enter it using

docker exec --user root -it <container-id> /bin/bash

In this way you will be using the container as a root user.

Debug mode

As part of the build, Conclave uses a modified version of the Intel SGX SDK, together with other C/C++ code. By default, this code is built in Release mode. If you need to debug C/C++ code you need to set the Debug mode by adding -PnativeDebug to the parameters. e.g.

./gradlew build -PnativeDebug

If you want to debug C/C++ code inside the enclave, you can use the scripts conclave-gdb and conclave-gdb-attach (in the directory scripts/) to debug your code. These are just wrappers of gdb for Conclave.

IntelliJ and CLion inside the container (Linux only)

It is possible to install IntelliJ and CLion into the containers, but only on Linux.

Setting the environment variable CONCLAVE_DOCKER_IDE=1 will enable their automatic download/installation. Just add

export CONCLAVE_DOCKER_IDE_TEST=1

to the last row of shell initialization scripts (e.g. in ~/.bashrc), and restart the terminal.

For the download or update to happen, the container must not be running, so you need to stop it in that case (see below).

Downloads are accomplished using curl, so ensure that it is installed on your system:

sudo apt-get install curl

By default, the IDEs will be downloaded under the host's ~/.opt/ folder.

You can now use these commands to launch your IDE of choice:

cd <conclave-core-sdk's local repository>
./scripts/idea.sh      # starts IDEA in a container
./scripts/clion.sh     # starts CLion in a container

Stopping and restarting the container

If you exit the shell, the container will continue to run. You can see a list of running sdk-build containers and their IDs by running

docker ps -f label=sdk-build 

If necessary, a container can be shut down with

docker stop $(docker ps -f label=sdk-build -q)

If you stop the container, you can restart it and log back in by re-running the devenv_shell.sh script.

Gradle maintains various caches and such in the container in the /gradle directory (this won't appear on your host system). If your container gets messed up you can blow it away by stopping it and then using docker images to list the image, and docker rmi to delete the image. Then rerun devenv_shell.sh to re-download things fresh.

Exploring the codebase

The Conclave Core SDK consists of several technologies working together. Here is a description of the most important directories in this repo.

License

Copyright © 2022, R3 LLC, all rights reserved.

The Conclave Core SDK is distributed under the Apache License v2.0.

It incorporates components from third-party open source libraries. See the NOTICE file for more information.