Skip to content

Latest commit

 

History

History
174 lines (149 loc) · 9.56 KB

M1_DEMO.md

File metadata and controls

174 lines (149 loc) · 9.56 KB
Raw

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 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 ☕ 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-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 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.