M2_DEMO.md

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 repository to your favorite location:

   $ git clone https://github.com/scs/substraTEE.git

2. Build the docker image:

   $ docker build -t substratee -f DockerfileM2 .

   This may take some time (~2h on a recent MacBook), so grab a cup of ☕ or 🍵 - 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-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:

   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:

   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:

   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.

   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.

   Expected Hash: [...]
   Actual Hash:   [...]

9. Query the counter from the substraTEE-worker:

   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.