From 105919d14de2fc05fca3b5a60d7b9892e4fde213 Mon Sep 17 00:00:00 2001 From: Prakash Narayana Moorthy Date: Mon, 4 Mar 2024 22:12:24 +0000 Subject: [PATCH 1/6] 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 --- ledgers/ccf/README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/ledgers/ccf/README.md b/ledgers/ccf/README.md index 1bd95af5..4b5af3b8 100644 --- a/ledgers/ccf/README.md +++ b/ledgers/ccf/README.md @@ -216,13 +216,9 @@ cd ${PDO_SOURCE_ROOT}/build make test ``` -## CCF TP TEE attestation 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. +## CCF TP TEE attestation verification policy +CCF TP provides two APIs to be used by the CCF Governance consortium to register attestation verification policy that must be satisfied by PDO contract enclaves. + +1. The first API `set_attestation_check_flag` is invoked as part of the TP start up scripts to specify whether PDO runs in SGX `HW` mode or SGX `SIM` mode. The flag can be set only once. There is no default value for the flag, and hence must be set explicitly before the TP can accept any `register_encalve` transactions. + +2. The second API `set_expected_sgx_measurements` is used whenever the `set_attestation_check_flag` specifies that PDO runs in SGX `HW` mode. In this case, the second API is used to the specify expected `MREnclave` value, and additionally `basename` and the `ias_public_key`. Note that PDO currently supports SGX `HW mode` with EPID attestation. The expected SGX measurements can be updated via the second API, subject to voting rules of the consortium. From 62955bb9adb39c82f2817519fbb2d5818245dfb3 Mon Sep 17 00:00:00 2001 From: Prakash Narayana Moorthy Date: Fri, 8 Mar 2024 19:46:35 +0000 Subject: [PATCH 2/6] Address feedback on PR Signed-off-by: Prakash Narayana Moorthy --- ledgers/ccf/README.md | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/ledgers/ccf/README.md b/ledgers/ccf/README.md index 4b5af3b8..2182b276 100644 --- a/ledgers/ccf/README.md +++ b/ledgers/ccf/README.md @@ -217,8 +217,32 @@ make test ``` ## CCF TP TEE attestation verification policy -CCF TP provides two APIs to be used by the CCF Governance consortium to register attestation verification policy that must be satisfied by PDO contract enclaves. - -1. The first API `set_attestation_check_flag` is invoked as part of the TP start up scripts to specify whether PDO runs in SGX `HW` mode or SGX `SIM` mode. The flag can be set only once. There is no default value for the flag, and hence must be set explicitly before the TP can accept any `register_encalve` transactions. - -2. The second API `set_expected_sgx_measurements` is used whenever the `set_attestation_check_flag` specifies that PDO runs in SGX `HW` mode. In this case, the second API is used to the specify expected `MREnclave` value, and additionally `basename` and the `ias_public_key`. Note that PDO currently supports SGX `HW mode` with EPID attestation. The expected SGX measurements can be updated via the second API, subject to voting rules of the consortium. +We briefly describe the attestation verification policy implemented by CCF TP. + +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 expected `MREnclave`, enclave `basename` and `ias_public_key`. +Further, the CCF TP governance consortium is permitted to change the +values of these parameters, subject to TP consoritum 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` is invoked as part of the TP start up +scripts to specify whether PDO runs in SGX `HW` mode or SGX `SIM` mode. + +2. The second API `set_expected_sgx_measurements` is used whenever the +`set_attestation_check_flag` specifies that PDO runs in SGX `HW` mode. +In this case, as noted above the second API is used to the specify expected +`MREnclave` value, and additionally `basename` and the `ias_public_key`. From fd4bb3449dec6fe75314d00193bb51e116bcd074 Mon Sep 17 00:00:00 2001 From: prakashngit Date: Mon, 11 Mar 2024 09:43:10 -0700 Subject: [PATCH 3/6] Update ledgers/ccf/README.md Co-authored-by: Bruno Vavala Signed-off-by: prakashngit --- ledgers/ccf/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ledgers/ccf/README.md b/ledgers/ccf/README.md index 2182b276..0421d4bf 100644 --- a/ledgers/ccf/README.md +++ b/ledgers/ccf/README.md @@ -233,7 +233,7 @@ 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 expected `MREnclave`, enclave `basename` and `ias_public_key`. Further, the CCF TP governance consortium is permitted to change the -values of these parameters, subject to TP consoritum governance rules. +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 From 5bea2b810096213427b0b9455260b0125cd83acf Mon Sep 17 00:00:00 2001 From: prakashngit Date: Tue, 12 Mar 2024 10:38:47 -0700 Subject: [PATCH 4/6] Update ledgers/ccf/README.md Co-authored-by: Bruno Vavala Signed-off-by: prakashngit --- ledgers/ccf/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/ledgers/ccf/README.md b/ledgers/ccf/README.md index 0421d4bf..bd1cb3c8 100644 --- a/ledgers/ccf/README.md +++ b/ledgers/ccf/README.md @@ -239,8 +239,11 @@ The TP provides two APIs `set_attestation_check_flag` and `set_expected_sgx_meas to program the various values required to implement the above attestation verification policy. -1. The first API `set_attestation_check_flag` is invoked as part of the TP start up -scripts to specify whether PDO runs in SGX `HW` mode or SGX `SIM` mode. +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` is used whenever the `set_attestation_check_flag` specifies that PDO runs in SGX `HW` mode. From 8ce49e8f1534d2d740cb71469c629b6b1f1f3f1d Mon Sep 17 00:00:00 2001 From: prakashngit Date: Tue, 12 Mar 2024 10:39:01 -0700 Subject: [PATCH 5/6] Update ledgers/ccf/README.md Co-authored-by: Bruno Vavala Signed-off-by: prakashngit --- ledgers/ccf/README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/ledgers/ccf/README.md b/ledgers/ccf/README.md index bd1cb3c8..2c971d3b 100644 --- a/ledgers/ccf/README.md +++ b/ledgers/ccf/README.md @@ -245,7 +245,8 @@ A convenience script `ccf_set_attestation_check_flag` is provided to invoke this 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` is used whenever the -`set_attestation_check_flag` specifies that PDO runs in SGX `HW` mode. -In this case, as noted above the second API is used to the specify expected -`MREnclave` value, and additionally `basename` and the `ias_public_key`. +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. From 9e460ff1b8b37791bc7a887cc53ff317f0f0a310 Mon Sep 17 00:00:00 2001 From: prakashngit Date: Thu, 14 Mar 2024 09:10:17 -0700 Subject: [PATCH 6/6] Update ledgers/ccf/README.md Co-authored-by: Bruno Vavala Signed-off-by: prakashngit --- ledgers/ccf/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/ledgers/ccf/README.md b/ledgers/ccf/README.md index 2c971d3b..bdc0a9a1 100644 --- a/ledgers/ccf/README.md +++ b/ledgers/ccf/README.md @@ -231,7 +231,11 @@ 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 expected `MREnclave`, enclave `basename` and `ias_public_key`. +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.