diff --git a/docker/Makefile b/docker/Makefile index 071cf235..4182c29b 100644 --- a/docker/Makefile +++ b/docker/Makefile @@ -165,7 +165,14 @@ test : clean_config clean_repository build_test stop_all sgx_build_test : repository build_sgx_services build_ccf build_client -sgx_test : clean_config clean_repository sgx_build_test stop_all +sgx_keys : + # test for key availability and make keys available to the container through xfer + test -f ${PDO_SGX_KEY_ROOT}/sgx_spid_api_key.txt + test -f ${PDO_SGX_KEY_ROOT}/sgx_spid.txt + test -f ${PDO_SGX_KEY_ROOT}/sgx_ias_key.pem + cp ${PDO_SGX_KEY_ROOT}/* '$(DOCKER_DIR)'/xfer/services/keys/sgx/ + +sgx_test : clean_config clean_repository sgx_build_test stop_all sgx_keys PDO_VERSION=$(PDO_VERSION) $(DOCKER_COMPOSE_SGX) $(TEST_SGX_FILES) up --abort-on-container-exit PDO_VERSION=$(PDO_VERSION) $(DOCKER_COMPOSE_SGX) $(TEST_SGX_FILES) down @@ -184,6 +191,7 @@ clean_images : $(addprefix clean_,$(IMAGES)) clean_config : rm -f '$(DOCKER_DIR)'/xfer/ccf/keys/*.pem '$(DOCKER_DIR)'/xfer/ccf/etc/*.toml rm -f '$(DOCKER_DIR)'/xfer/services/keys/*.pem '$(DOCKER_DIR)'/xfer/services/etc/*.toml + rm -f '$(DOCKER_DIR)'/xfer/services/keys/sgx/*.pem '$(DOCKER_DIR)'/xfer/services/keys/sgx/*.txt rm -f '$(DOCKER_DIR)'/xfer/services/etc/site.psh clean : clean_images clean_config clean_repository diff --git a/docker/README.md b/docker/README.md index dc532f52..059c48b3 100644 --- a/docker/README.md +++ b/docker/README.md @@ -79,6 +79,16 @@ as services in detached mode. The last for the client will run an interactive shell in the client container. See below for information on how to use the client container. +### Build for SGX ### + +For the contract enclave to run in SGX hardware mode, the `pdo_services` +image must be built using the following target: +```bash + make build_sgx_services +``` +Inside the `pdo_services` images, the `SGX_MODE` environment variable +can help distinguish the build type. + ## Pattern: Local Development in a Container ## @@ -246,6 +256,29 @@ with the PDO tool `pdo-configure-services`. --name ${USER}_services_container pdo_services --mode copy ``` +#### PDO Services Deployment Using SGX #### + +There are a few _additional_ considerations when using the services with SGX. + +Before starting the container, make sure that the SGX collateral is available +as described [here](../docs/install). + +Also, recall that the attestation policy on the ledger has to be set once by the +first eservice of a ledger consortium member. Hence, the first service container +that is deputed to perform such registration must be instructed to do so. +```bash + docker run -v $(SCRIPT_DIR)/xfer/:/project/pdo/xfer --network host \ + --name ${USER}_services_container pdo_services --register +``` +This updated command allows to trigger the registration step right before +starting the services. The policy registration must happen before enclaves are +registered (or any enclave registration will fail). + +Finally, the _same_ SGX collateral must be made available to all service containers. +At enclave registration time, this will allow the eservice to generate the right +quote (and attestation verification report) that meets the attestation policy +originally registered with the PDO Transaction Processor. + ### PDO Client Deployment ### The client image creates an interactive environment for connecting diff --git a/docker/tools/start_services.sh b/docker/tools/start_services.sh index f3c2e501..b161d19b 100755 --- a/docker/tools/start_services.sh +++ b/docker/tools/start_services.sh @@ -82,6 +82,20 @@ check_pdo_runtime_env export no_proxy=$PDO_HOSTNAME,$PDO_LEDGER_ADDRESS,$no_proxy export NO_PROXY=$PDO_HOSTNAME,$PDO_LEDGER_ADDRESS,$NO_PROXY +# ----------------------------------------------------------------- +yell copy sgx keys +# ----------------------------------------------------------------- +# this collateral *must* be copied before configuring the services +# as it will be included in the service/enclave toml files +[ -z "$(ls -A ${XFER_DIR}/services/keys/sgx/)" ] ||\ + cp ${XFER_DIR}/services/keys/sgx/* ${PDO_SGX_KEY_ROOT} +# refresh the environment variables (necessary for SGX-related ones) +source /project/pdo/tools/environment.sh + +# ----------------------------------------------------------------- +yell Register with ledger: ${F_REGISTER} +# ----------------------------------------------------------------- + # ----------------------------------------------------------------- # Handle the configuration of the services # ----------------------------------------------------------------- diff --git a/docs/install.md b/docs/install.md index 3943125b..25b577bc 100644 --- a/docs/install.md +++ b/docs/install.md @@ -115,13 +115,21 @@ to create the client authentication key. The key will be available from your profile page. Now organize your data as follows under the `${PDO_SGX_KEY_ROOT}` folder -(the default folder is `${PDO_SOURCE_ROOT}/build/keys/sgx_mode_${SGX_MODE,,}`, +(the default folder is `${PDO_SOURCE_ROOT}/build/keys/sgx_mode_hw`, or you can define yours with `export PDO_SGX_KEY_ROOT=`): -* save your SPID in `${PDO_SGX_KEY_ROOT}/sgx_spid_api_key.txt` +* save your SPID in `${PDO_SGX_KEY_ROOT}/sgx_spid.txt` * save your API key in `${PDO_SGX_KEY_ROOT}/sgx_spid_api_key.txt` * save the IAS root CA certificate in `${PDO_SGX_KEY_ROOT}/sgx_ias_key.pem` (`wget https://certificates.trustedservices.intel.com/Intel_SGX_Attestation_RootCA.pem -O ${PDO_SGX_KEY_ROOT}/sgx_ias_key.pem`) +#### (optional) Set the path to an existing enclave code signing key + +At build time, an enclave code signing key is required to sign the contract enclave. +If one such key is available, it can be used by configuring PDO as follows: +```bash +export PDO_ENCLAVE_CODE_SIGN_PEM= +``` + #### Install the SGX Kernel Driver (Hardware Support) SGX can run in either simulation or hardware mode. No kernel driver is @@ -178,7 +186,9 @@ To validate that your SGX HW installation & and corresponding PDO configuration is working properly, the easiest way is to install docker as discussed below and then run ```bash - make SGX_MODE=HW -C docker test +. build/common-config.sh + +make -C docker sgx_test ``` This will build PDO and automatically execute the tests described in the Section [Validate the Installation](usage.md#validating) in HW mode. diff --git a/docs/usage.md b/docs/usage.md index a97353b3..ec4a0595 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -62,6 +62,18 @@ Using PDO requires a running instance of a ledger. Documentation for building, installing and running [Microsoft CCF](../ledgers/ccf/README.md) is available. +PDO provides a script to start and configure the ledger (see `ledgers/ccf/scripts/start_ccf_network.sh`). +If `"${SGX_MODE}" == "SIM"`, the script configures the PDO TP to skip attestation checks. +If `"${SGX_MODE}" == "HW"`, the script configures the PDO TP to enforce attestation checks. +In this case, a policy must be registered (see [README](../ledgers/ccf/README.md)). + +# Register the attestation policy with the ledger + +The registration of the attestation policy is required if `"${SGX_MODE}" == "HW"`, and irrelevant otherwise. +PDO provides the `private-data-objects/eservice/bin/register-with-ledger.sh` script to automate this procedure. +The script is meant to be use by a member of the ledger consortium, at the eservice side, +once the contract enclave's MRENCLAVE is available (i.e., once enclave build is completed). + # Validate the Installation The easiest way to validate that your installation is correct is to run