add or update documentation for managing the sgx collateral required …

…by the pdo services; add documentation for building and deploying using sgx; add documentation for triggering the attestation policy registration step through a service container; align some docker scripts with the documentation

Signed-off-by: Bruno Vavala <[email protected]>

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

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.
+
 <!--- xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --->
 ## 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

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
 # -----------------------------------------------------------------

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=<your folder>`):
-* 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=<absolute path to enclave code signing key>
+```
+
 #### 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.

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)).
+
+# <a name="register-policy">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).
+
 # <a name="validating">Validate the Installation
 
 The easiest way to validate that your installation is correct is to run