Go
Rust

• Oasis Core is in active development so all APIs, protocols and data structures are subject to change.
• The code has not yet been fully audited. For security issues and other security-related topics, see Security.

See our Contributing Guidelines.

Read our Security document.

Prerequisites:

• Linux (if you are not on Linux, you will need to either set up a VM with the proper environment or, if Docker is available for your platform, use the provided Docker image which does this for you, see below).

• System packages:

  • Bubblewrap (at least version 0.3.3).
  • GCC (including C++ subpackage).
  • Protobuf compiler.
  • GNU Make.
  • CMake.
  • OpenSSL development package.
  • libseccomp development package.

  On Fedora 29+, you can install all the above with:

  sudo dnf install bubblewrap gcc gcc-c++ protobuf-compiler make cmake openssl-devel libseccomp-devel
  

  On Ubuntu 18.10+ (18.04 LTS provides overly-old bubblewrap), you can install all the above with:

  sudo apt install bubblewrap gcc g++ protobuf-compiler make cmake libssl-dev libseccomp-dev
  

• Go (at least version 1.13).

  If your distribution provides a new-enough version of Go, just use that.

  Otherwise:

  • install the Go version provided by your distribution,

  • ensure $GOPATH/bin is in your PATH,

  • install the desired version of Go, e.g. 1.13, with:

    go get golang.org/dl/go1.13
    go1.13 download
    

  • instruct the build system to use this particular version of Go by setting the OASIS_GO environment variable in your ~/.bashrc:

    export OASIS_GO=go1.13
    

• Rust and the nightly toolchain.

  Once you have rustup installed, install the nightly with:

  rustup install nightly
  

  Then make it the default version with:

  rustup default nightly
  

• Fortanix Rust SGX target.

  Install it by running:

  rustup target add x86_64-fortanix-unknown-sgx
  

  Install its utilities by running:

  cargo install fortanix-sgx-tools sgxs-tools
  

• (OPTIONAL) protoc-gen-go.

  Download and install it with:

  ${OASIS_GO:-go} get github.com/golang/protobuf/protoc-gen-go
  

  NOTE: If you didn't/can't add $GOPATH/bin to your PATH, you can install protoc-gen-go to /usr/local/bin (which is in $PATH) with:

  sudo GOBIN=/usr/local/bin ${OASIS_GO:-go} install github.com/golang/protobuf/protoc-gen-go
  

  NOTE: The repository has the most up-to-date files generated by protoc-gen-go committed for convenience. Installing protoc-gen-go is only required if you are a developer making changes to protobuf definitions used by Go.

In the following instructions, the top-level directory is the directory where the code has been checked out.

If for some reason you don't want or can't install the specified prerequisites on the host system, you can use our development Docker image. This requires that you have a recent version of Docker installed.

Oasis development environment with all the dependencies preinstalled is available in the oasislabs/development:0.3.0 image. To run a container, do the following in the top-level directory:

make docker-shell

If you are curious, this target will internally run the following command:

docker run -t -i \
  --name oasis-core \
  --security-opt apparmor:unconfined \
  --security-opt seccomp=unconfined \
  -v $(pwd):/code \
  -w /code \
  oasislabs/development:0.3.0 \
  bash

All the following commands can then be used from inside the container. See the Docker documentation for detailed instructions on working with Docker containers.

To build everything required for running an Oasis node locally, simply execute in the top-level directory:

export OASIS_UNSAFE_SKIP_AVR_VERIFY="1"
export OASIS_UNSAFE_SKIP_KM_POLICY="1"
make

This will build all the required parts (build tools, Oasis node, runtime libraries, runtime loader, key manager and test runtimes). The AVR and KM flags are supported on production SGX systems only and these features must be disabled in our environment.

Next we specify how to run a simple network for development purposes. To start a simple Oasis network as defined by the default network fixture running the simple-keyvalue test runtime, do:

./go/oasis-net-runner/oasis-net-runner \
  --net.node.binary go/oasis-node/oasis-node \
  --net.runtime.binary target/default/debug/simple-keyvalue \
  --net.runtime.loader target/default/debug/oasis-core-runtime-loader \
  --net.keymanager.binary target/default/debug/oasis-core-keymanager-runtime

Wait for the network to start, there should be messages about nodes being started and at the end the following message should appear:

level=info module=oasis/net-runner caller=oasis.go:319 ts=2019-10-03T10:47:30.776566482Z msg="network started"
level=info module=net-runner caller=root.go:145 ts=2019-10-03T10:47:30.77662061Z msg="client node socket available" path=/tmp/oasis-net-runner530668299/net-runner/network/client-0/internal.sock

The simple-keyvalue runtime implements a key-value hash map in the enclave and supports reading, writing, and fetching string values associated with the given key. To learn how to create your own runtime, see the sources of the example here.

Finally, to test Oasis node, we will run a test client written specifically for the simple-keyvalue runtime. The client sends a few keys with associated values and fetches them back over RPC defined in the runtime's API. Execute the client as follows (substituting the socket path from your log output) in a different terminal:

./target/debug/simple-keyvalue-client \
  --runtime-id 0000000000000000000000000000000000000000000000000000000000000000 \
  --node-address unix:/tmp/oasis-net-runner530668299/net-runner/network/client-0/internal.sock

By default, Oasis node is configured with a 30-second epoch, so you may initially need to wait for the first epoch to pass before the test client will make any progress. For more information on writing your own client, see the simple-keyvalue client sources here.

Compilation procedure under SGX environment is similar to the non-SGX with slightly different environmental variables set:

export OASIS_UNSAFE_SKIP_AVR_VERIFY="1"
export OASIS_UNSAFE_KM_POLICY_KEYS="1"
export OASIS_UNSAFE_ALLOW_DEBUG_ENCLAVES="1"
export OASIS_TEE_HARDWARE=intel-sgx
make

The AVR flag is there because we are running a node in a local development environment and we will not do any attestation with Intel's remote servers. The KM policy keys flag allows testing keys to be used while verifying the security policy of the node. TEE hardware flag denotes the trusted execution environment engine for running the Oasis node and the tests below.

To run an Oasis node under SGX make sure:

• Your hardware has SGX support.

• You either explicitly enabled SGX in BIOS or made a sgx_cap_enable_device() system call, if SGX is in software controlled state.

• You installed Intel's SGX driver (check that /dev/isgx exists).

• You have the AESM daemon running. The easiest way is to just run it in a Docker container by doing (this will keep the container running and it will be automatically started on boot):

  docker run \
    --detach \
    --restart always \
    --device /dev/isgx \
    --volume /var/run/aesmd:/var/run/aesmd \
    --name aesmd \
    fortanix/aesmd
  

Run sgx-detect (part of fortanix rust tools) to verify that everything is configured correctly.

Finally, to run an Oasis node under SGX follow the same steps as for non-SGX, except the oasis-net-runner invocation:

./go/oasis-net-runner/oasis-net-runner \
  --net.node.binary go/oasis-node/oasis-node \
  --net.runtime.binary target/sgx/x86_64-fortanix-unknown-sgx/debug/simple-keyvalue.sgxs \
  --net.runtime.loader target/default/debug/oasis-core-runtime-loader \
  --net.keymanager.binary target/sgx/x86_64-fortanix-unknown-sgx/debug/oasis-core-keymanager-runtime.sgxs

After you built everything, you can use the following commands to run tests.

To run all unit tests:

make test-unit

To run end-to-end tests locally:

make test-e2e

To run all tests:

make test

Do not forget to set OASIS_TEE_HARDWARE flag (see above), if you want to execute tests under SGX.

Check the console output for mentions of a path of the form /tmp/oasis-test-runnerXXXXXXXXX (where each X is a digit). That's the log directory. Start with coarsest-level debug output in console.log files:

cat $(find /tmp/oasis-test-runnerXXXXXXXXX -name console.log) | less

For even more output, check the other *.log files.

• client: Client library for talking with the runtimes.
• docker: Docker environment definitions.
• go: Oasis node.
• keymanager-client: Client crate for the key manager.
• keymanager-runtime: (INSECURE) key manager implementation.
• runtime: The runtime library that simplifies writing SGX and non-SGX runtimes.
• runtime-loader: The SGX and non-SGX runtime loader process.
• scripts: Bash scripts for development.
• tests: Runtimes, clients and resources used for E2E tests.
• tools: Build tools.