Updating CCF PDO/TP Documentation with details about recent API chang…

…es used to set PDO contract enclave attestation policy. (#475)

* Updating CCF PDO/TP Documentation with details about recent API changes
used to set PDO contract enclave attestation policy. The API changes are
part of PR 467 (https://github.com/hyperledger-labs/private-data-objects/pull/467/files#)

This PR updates the subsection `CCF TP TEE attestation verification policy` contained
within ledgers/ccf/README.md to reflect the new APIs introduced in PR 467.

Signed-off-by: Prakash Narayana Moorthy <[email protected]>

---------

Signed-off-by: Prakash Narayana Moorthy <[email protected]>
Signed-off-by: prakashngit <[email protected]>
Co-authored-by: Bruno Vavala <[email protected]>

ledgers/ccf/README.md

@@ -216,13 +216,41 @@ cd ${PDO_SOURCE_ROOT}/build
 make test
 ```
 
-## CCF TP TEE attestation policy
+## CCF TP TEE attestation verification policy
 We briefly describe the attestation verification policy implemented by CCF TP.
-- CCF Governance consortium  registers attestation policy after TP is deployed.
-- Currently, TP supports two policies:
-    - No attestation verification: This policy is used while using PDO enclaves in SGX SIM mode.
-    - Check EPID attestation verification reports generated by IAS: This policy is used while using PDO enclaves in SGX HW mode.
-- One of the two policies must necessarily have been registered by the CCF consortium before any PDO enclave can be registered. There is no default policy.
-CCF TP provides a member-rpc that can be used for registering one of the above two policies. For the second policy above, the consortium
-gets to specify expected MREnclave, basename and IAS public key via the member-rpc.
-- The policy (including expected value of MREnclave) can be changed anytime by the CCF Governance consortium, subject to voting rules of the consortium.
+
+1. The TP contains a programmable flag that specifies whether the TP will check
+for PDO contract enclaves' attestation when eservices attempt registering
+PDO enclaves with TP. The CCF TP governance consortium
+(see https://microsoft.github.io/CCF/release/4.x/governance/index.html)
+gets to set the flag after the TP is started. The flag can be set only once.
+
+2. If the flag described above is set, then it is expected that the CCF TP
+governance consortium further programs the TP with expected values required to
+verify enclave attestation reports. We note that PDO currently supports EPID
+attestation verification, and while running in SGX HW mode, the eservice submits
+IAS attestation report to the TP as part of contract enclave
+registration with TP. To help the TP verify the IAS attestation report, the TP
+must be programmed with the following SGX-defined expected values:
+* `MREnclave`, a unique identifier of the contract enclave code;
+* `basename`, which contains (and is directly derived from) the SPID in EPID attestations;
+* `ias_public_key`, which is the IAS public key for verifying attestation reports.
+At contract enclave registration time, the TP verifies that an attestation report is correctly signed by IAS and includes the expected values.
+Further, the CCF TP governance consortium is permitted to change the
+values of these parameters, subject to TP consortium governance rules.
+
+The TP provides two APIs `set_attestation_check_flag` and `set_expected_sgx_measurements`
+to program the various values required to implement the above attestation
+verification policy.
+
+1. The first API `set_attestation_check_flag` accepts as input a boolean value (indicating whether to check attestation reports or not). It is meant to be called when the CCF network starts up. It _must_ be called before enclave registrations and before the second API and only once.
+
+A convenience script `ccf_set_attestation_check_flag` is provided to invoke this API. The script requires a CCF endpoint and the `--attestation` or `--no-attestation` argument.
+
+The script for starting the CCF network in PDO automates the call to the script above, setting the check-attestation-flag based on whether PDO runs in SGX `HW` mode or SGX `SIM` mode.
+
+2. The second API `set_expected_sgx_measurements` accepts as input the MREnclave, the basename and the IAS public key values. It is meant to be called by the first eservice who will register enclaves. If the previous API was called to require attestation checks, then this API _must_ be called; otherwise, it may, or may not, be called.
+
+A convenience script `ccf_set_expected_sgx_measurements` is provided to invoke this API. The script requires a CCF endpoint and the `--mrenclave`, `--basename` and `--ias-public-key` arguments.
+
+The script for starting services in PDO contains an optional argument (`--register`) which automates the call to the script above. This allows an eservice running in SGX `HW` mode to register/set the policy/arguments with the PDO TP.