Merge pull request #18 from scs/brenzi-private-tx

M5 doc and docker

DockerfileM5

@@ -0,0 +1,136 @@
+# BSD License
+#
+# Copyright (C) 2017-2018 Baidu, Inc. All Rights Reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+#   * Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#   * Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in
+#     the documentation and/or other materials provided with the
+#     distribution.
+#   * Neither the name of Baidu, Inc., nor the names of its
+#     contributors may be used to endorse or promote products derived
+#     from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# Copyright 2019 Supercomputing Systems AG
+
+FROM ubuntu:18.04
+MAINTAINER Yu Ding
+
+ENV sdk_bin https://download.01.org/intel-sgx/linux-2.5/ubuntu18.04-server/sgx_linux_x64_sdk_2.5.100.49891.bin
+ENV psw_deb https://download.01.org/intel-sgx/linux-2.5/ubuntu18.04-server/libsgx-enclave-common_2.5.101.50123-bionic1_amd64.deb
+ENV psw_dev_deb https://download.01.org/intel-sgx/linux-2.5/ubuntu18.04-server/libsgx-enclave-common-dev_2.5.101.50123-bionic1_amd64.deb
+ENV psw_dbgsym_deb https://download.01.org/intel-sgx/linux-2.5/ubuntu18.04-server/libsgx-enclave-common-dbgsym_2.5.101.50123-bionic1_amd64.ddeb
+ENV substratee_node https://github.com/scs/substraTEE-node/archive/M5.zip
+ENV substratee_worker https://github.com/scs/substraTEE-worker/archive/M5.zip
+ENV rust_toolchain nightly
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TERM xterm
+
+SHELL ["/bin/bash", "-c"]
+
+# prepare the linux system
+RUN apt-get update && \
+    apt-get install -y build-essential ocaml ocamlbuild automake autoconf \
+    libtool wget python libssl-dev libcurl4-openssl-dev protobuf-compiler \
+    libprotobuf-dev sudo kmod vim curl git-core libprotobuf-c0-dev \
+    libboost-thread-dev libboost-system-dev liblog4cpp5-dev libjsoncpp-dev \
+    alien uuid-dev libxml2-dev cmake pkg-config expect systemd-sysv gdb unzip \
+    clang libclang-dev rsync && \
+    rm -rf /var/lib/apt/lists/* && \
+    rm -rf /var/cache/apt/archives/*
+
+# install the Intel SGX PSW and SDK
+RUN mkdir /root/sgx && \
+    mkdir /etc/init && \
+    wget -O /root/sgx/psw.deb ${psw_deb} && \
+    wget -O /root/sgx/psw_dev.deb ${psw_dev_deb} && \
+    wget -O /root/sgx/psw_dbgsym.deb ${psw_dbgsym_deb} && \
+    wget -O /root/sgx/sdk.bin ${sdk_bin} && \
+    cd /root/sgx && \
+    dpkg -i /root/sgx/psw.deb && \
+    dpkg -i /root/sgx/psw_dev.deb && \
+    dpkg -i /root/sgx/psw_dbgsym.deb && \
+    chmod +x /root/sgx/sdk.bin && \
+    echo -e 'no\n/opt' | /root/sgx/sdk.bin && \
+    echo 'source /opt/sgxsdk/environment' >> /root/.bashrc && \
+    rm -rf /root/sgx/*
+
+# installing rust-sgx-sdk
+RUN wget 'https://static.rust-lang.org/rustup/dist/x86_64-unknown-linux-gnu/rustup-init' -O /root/rustup-init && \
+    chmod +x /root/rustup-init && \
+    echo '1' | /root/rustup-init --default-toolchain ${rust_toolchain} && \
+    echo 'source /root/.cargo/env' >> /root/.bashrc && \
+    /root/.cargo/bin/rustup component add rust-src && \
+    /root/.cargo/bin/cargo install xargo && \
+    rm -rf /root/.cargo/registry && rm -rf /root/.cargo/git
+
+# downloading and extracting the substraTEE components
+RUN mkdir /substraTEE && \
+    wget -O /substraTEE/substraTEE-node.zip ${substratee_node} && \
+    wget -O /substraTEE/substraTEE-worker.zip ${substratee_worker} && \
+    cd /substraTEE && \
+    unzip substraTEE-node.zip && \
+    mv substraTEE-node-M5 substraTEE-node && \
+    unzip substraTEE-worker.zip && \
+    mv substraTEE-worker-M5 substraTEE-worker && \
+    rm substraTEE-*.zip
+
+# install the needed nightly version of rust and the wasm32 for the default toolchain
+# FIXME: synchronize and fix the used version (see below)
+RUN /root/.cargo/bin/rustup install nightly-2019-08-01 && \
+    /root/.cargo/bin/rustup default nightly-2019-08-01 && \
+    /root/.cargo/bin/rustup target add wasm32-unknown-unknown
+
+# init the rust environment
+RUN source /opt/sgxsdk/environment && \
+    source /root/.cargo/env && \
+    /substraTEE/substraTEE-node/scripts/init.sh
+
+# build the substraTEE-node
+RUN source /opt/sgxsdk/environment && \
+    source /root/.cargo/env && \
+    cd /substraTEE/substraTEE-node && \
+    cargo build --release
+
+# build the substraTEE-worker
+# the substratee-worker (or more precisly, the rust-sgx-sdk compiles only with nightly-2019-08-01)
+RUN source /opt/sgxsdk/environment && \
+    source /root/.cargo/env && \
+    /root/.cargo/bin/rustup default nightly && \
+    /root/.cargo/bin/rustup target add wasm32-unknown-unknown && \
+    cd /substraTEE/substraTEE-worker && \
+    /root/.cargo/bin/rustup override set nightly-2019-08-01 && \
+    make
+
+# copy the shell scripts to the docker to launch to node and the workers
+COPY scriptsM5/* /substraTEE/
+
+# copy the certificates for the RA
+COPY intel_cert/* /substraTEE/substraTEE-worker/bin/
+
+# install ipfs
+RUN mkdir /ipfs && \
+    cd ipfs && \
+    wget -O go-ipfs.tar.gz https://dist.ipfs.io/go-ipfs/v0.4.21/go-ipfs_v0.4.21_linux-amd64.tar.gz && \
+    tar xvfz go-ipfs.tar.gz && \
+    cd go-ipfs && \
+    ./install.sh
+
+WORKDIR /substraTEE

M1_DEMO.md

@@ -0,0 +1,174 @@
+### M1 PoC1: single-TEE confidential state transition function
+The following requirements are needed to run the M1 demo:
+* Docker installed
+* Active internet connection
+
+To build and execute the code, follow these instructions:
+1. Clone the [substraTEE](https://github.com/scs/substraTEE) repository to your favorite location:
+   ```
+   $ git clone https://github.com/scs/substraTEE.git
+   ```
+2. Build the docker image:
+   ```
+   $ docker build -t substratee -f DockerfileM1 .
+   ```
+   This may take some time (~2h on a recent MacBook), so grab a cup of :coffee: or :tea: - or two.
+3. Start the docker image and get an interactive shell:
+   ```
+   $ docker run -v $(pwd):/substraTEE/backup -ti substratee
+   ```
+   The `-v $(pwd):/substraTEE/backup` is used to save the files generated by the enclave for later use and can also be omitted.
+
+   If you are in a PowerShell on Windows, replace the `$(pwd)` with `${PWD}`.
+4. Start the development substraTEE-node in the background and log the output in a file:
+   ```
+   root@<DOCKERID>:/substraTEE# /substraTEE/substraTEE-node-M1/target/release/substratee-node --dev > node.log 2>&1 &
+   ```
+   The node now runs in the background and the output can be inspected by calling: `tail -f /substraTEE/node.log`.
+5. Start the substraTEE-worker and generate the keys:
+   ```
+   root@<DOCKERID>:/substraTEE# cd /substraTEE/substraTEE-worker-M1
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M1# ./bin/substratee_worker getpublickey
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M1# ./bin/substratee_worker getsignkey
+   ```
+   This will generate the sealed (= encrypted) RSA3072 keypair (`./bin/rsa3072_key_sealed.bin`), the sealed ED25519 keypair (`./bin/ed25519_key_sealed.bin`) and the unencrypted public keys (`./bin/rsa_pubkey.txt` and `./bin/ecc_pubkey.txt`). The sealed keypairs can only be decrypted by your specific SGX enclave.
+6. Start the substraTEE-worker in the background and log the output in a file:
+   ```
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M1# ./bin/substratee_worker worker > /substraTEE/worker.log 2>&1 &
+   ```
+   The worker now runs in the background and the output can be inspected by calling: `tail -f /substraTEE/worker.log`.
+7. Start the substraTEE-client to send an extrinsic to the substraTEE-node that is then forwarded and processed by the substraTEE-worker (incrementing a counter):
+   ```
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M1# ./bin/substratee_client | tee /substraTEE/client.log
+   ```
+   The output of the client is also logged to the file `/substraTEE/client.log` and can be inspected by `less /substraTEE/client.log`.
+
+   You will see on the last lines of the output the two hashes of the transaction (expected and actual). These should match indicating that all commands were processed successfully.
+   ```
+   Expected Hash: [...]
+   Actual Hash:   [...]
+   ```
+8. Query the counter from the substraTEE-worker:
+   ```
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M1# ./bin/substratee_client getcounter | tee /substraTEE/counter.log
+   ```
+
+Whenever you perform the steps 7. and 8., you will see the counter incrementing.
+
+#### IMPORTANT
+If you exit the container (`exit`), you will loose the sealed counter state and the generated keys.
+
+To backup the files:
+```
+root@<DOCKERID>:/substraTEE# cp /substraTEE/substraTEE-worker-M1/bin/*.txt /substraTEE/backup/
+root@<DOCKERID>:/substraTEE# cp /substraTEE/substraTEE-worker-M1/bin/*.bin /substraTEE/backup/
+```
+
+To restore the files:
+```
+root@<DOCKERID>:/substraTEE# cp /substraTEE/backup/*.txt /substraTEE/substraTEE-worker-M1/bin/
+root@<DOCKERID>:/substraTEE# cp /substraTEE/backup/*.bin /substraTEE/substraTEE-worker-M1/bin/
+```
+
+#### Enabling Debug output
+To enable debug output, call the substraTEE-worker or the substraTEE-client with the following command, respectivly: `RUST_LOG=debug ./bin/substratee_client`.
+
+### M2 PoC2: single-TEE confidential state transition function in WASM
+The following requirements are needed to run the M2 demo:
+* Docker installed
+* Active internet connection
+
+The main principle is the same as M1. The big difference is that the code that implements the business logic (in our case, incrementing a counter) is stored as WASM code. When starting the client (step 8), we tell the worker the SHA256 hash of the WASM that we want to execute. If the desired and the computed hashes don't match, the STF must not be executed. This ensures that we know which code was executed in the SGX enclave.
+
+To build and execute the code, follow these instructions:
+1. Clone the [substraTEE](https://github.com/scs/substraTEE) repository to your favorite location:
+   ```shell
+   $ git clone https://github.com/scs/substraTEE.git
+   ```
+
+2. Build the docker image:
+   ```shell
+   $ docker build -t substratee -f DockerfileM2 .
+   ```
+   This may take some time (~2h on a recent MacBook), so grab a cup of :coffee: or :tea: - or two.
+
+3. Start the docker image and get an interactive shell:
+   ```shell
+   $ docker run -v $(pwd):/substraTEE/backup -ti substratee
+   ```
+   The `-v $(pwd):/substraTEE/backup` is used to save the files generated by the enclave for later use and can also be omitted.
+
+   If you are in a PowerShell on Windows, replace the `$(pwd)` with `${PWD}`.
+
+4. Start the development substraTEE-node in the background and log the output in a file:
+   ```shell
+   root@<DOCKERID>:/substraTEE# /substraTEE/substraTEE-node-M1/target/release/substratee-node --dev > node.log 2>&1 &
+   ```
+   The node now runs in the background and the output can be inspected by calling: `tail -f /substraTEE/node.log`.
+
+5. Start the substraTEE-worker and generate the keys:
+   ```shell
+   root@<DOCKERID>:/substraTEE# cd /substraTEE/substraTEE-worker-M2
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M2# ./bin/substratee_worker getpublickey
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M2# ./bin/substratee_worker getsignkey
+   ```
+   This will generate the sealed (= encrypted) RSA3072 keypair (`./bin/rsa3072_key_sealed.bin`), the sealed ED25519 keypair (`./bin/ed25519_key_sealed.bin`) and the unencrypted public keys (`./bin/rsa_pubkey.txt` and `./bin/ecc_pubkey.txt`). The sealed keypairs can only be decrypted by your specific SGX enclave.
+
+6. Start the substraTEE-worker in the background and log the output in a file:
+   ```shell
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M2# ./bin/substratee_worker worker > /substraTEE/worker.log 2>&1 &
+   ```
+   The worker now runs in the background and the output can be inspected by calling: `tail -f /substraTEE/worker.log`.
+
+7. Get the SHA256 hash of the WASM module:
+   ```shell
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M2# sha256sum ./bin/worker_enclave.compact.wasm
+   ```
+   This will output something like the following, where the actual values may be different:
+   ```shell
+   d7331d5344a99696a8135212475e2c6b605cea88e9edd594773181205dda1531  ./bin/worker_enclave.compact.wasm
+   ```
+   The first long number is the SHA256 hash of the WASM code. Copy this value (in the example case `d733...1531`) into the clipboard (Control-C).
+
+8. Start the substraTEE-client to send an extrinsic to the substraTEE-node that is then forwarded and processed by the substraTEE-worker. The code to increment the counter comes from the WASM file (`bin/worker_enclave.compact.wasm`). The user provides the hash of the code he wants to execute.
+   ```shell
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M2# ./bin/substratee_client --sha256wasm <COPIED_CONTENT_FROM_STEP_7> | tee /substraTEE/client.log
+   ```
+   The output of the client is also logged to the file `/substraTEE/client.log` and can be inspected by `less /substraTEE/client.log`.
+
+   You will see on the last lines of the output the two hashes of the transaction (expected and actual). These should match indicating that all commands were processed successfully.
+   ```shell
+   Expected Hash: [...]
+   Actual Hash:   [...]
+   ```
+
+9. Query the counter from the substraTEE-worker:
+   ```shell
+   root@<DOCKERID>:/substraTEE/substraTEE-worker-M2# ./bin/substratee_client getcounter | tee /substraTEE/counter.log
+   ```
+   After the first iteration, the counter of Alice will have the value 52. This is correct as the following code is executed in the WASMI in the enclave: `new = old + increment + 10` (see `substraTEE-worker/enclave/wasm/src/lib.rs`).
+
+10. Check the output of the substraTEE-worker by calling `less /substraTEE/worker.log`. The most important section is (near the end)
+    ```
+    [>] Decrypt and process the payload
+        ...
+        [Enclave] SHA256 of WASM code identical
+        ...
+    [<] Message decoded and processed in the enclave
+    ```
+    which indicates that the SHA256 hash passed by the client matches the calculated hash of the code that should be executed.
+
+11. When sending a different hash from the substraTEE-client to the substraTEE-worker, the code will not be executed and the counter therefore not updated.
+
+     The client will wait infinitely for the callConfirmed event which will never be sent by the worker as the code was not executed. The client must be killed (Control-C) and the log file of the worker can be inspected with `less /substraTEE/worker.log`. At the end of the log file there is a different output than before
+     ```
+     [>] Decrypt and process the payload
+         ...
+         [Enclave] SHA256 of WASM code not matching
+         [Enclave]   Wanted by client    : [...]
+         [Enclave]   Calculated by worker: [...]
+         [Enclave] Returning ERROR_UNEXPECTED and not updating STF
+     ```
+     which indicates that the SHA256 hash passed by the client **DOES NOT** match the calculated hash of the code that should be executed.
+
+Whenever you perform the steps 8. and 9., you will see the counter incrementing.