Updating CCF PDO/TP Documentation with details about recent API changes used to set PDO contract enclave attestation policy. #475
Conversation
cmickeyb
force-pushed
the
Prakash.PDOTP_Documentation_Update
branch
from
40ef5f2
to
fee1eb1
Compare
There was a problem hiding this comment.
Thanks @prakashngit ! I echo Bruno's and Mic's comments about separating the API description from the API usage, and adding details for newcomers. I will add more detailed comments in issue #264, but a separate question that we might want to address in this PR is: how does the intended user of this documentation actually interact with the TP? It sounds like its via the scripts, rather than the APIs directly. In that case, talking about the APIs first may not be the right level of abstraction for the user. I think it would be helpful to add a line or two describing the scripts first before you go on to talk about the APIs these scripts call.
ledgers/ccf/README.md
Outdated
| 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. |
There was a problem hiding this comment.
Two suggestions: 1) I would explain the TP acronym the first time it's used. 2) If you have a link to some documentation or website for the "CCF Governance consortium", that would be a helpful addition.
There was a problem hiding this comment.
thank you @marcelamelara for the feedback. 1. TP full form has already been provided earlier in the same document. 2. I have added a link to the CCF Governance consortium document.
ledgers/ccf/README.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
one more REQUIREMENT... line length 80.
There was a problem hiding this comment.
@cmickeyb thanks, pruned lines to length 80
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]>
prakashngit
force-pushed
the
Prakash.PDOTP_Documentation_Update
branch
from
fee1eb1
to
62955bb
Compare
ledgers/ccf/README.md
Outdated
| 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`. |
There was a problem hiding this comment.
A couple points worth clarifying: Which of these expected values is unique per contract enclave? What is the actual policy, do these three values need to match for a given contract enclave? And what does the TP do if one/any of these values doesn't match the expectation?
There was a problem hiding this comment.
thank you for the questions. While these are important questions to document, these must be covered as part of PDO/documentation on "how PDO enables HW mode". The TP is one piece of the whole "PDO HW mode flow". A lot of these questions are coming up because we lack documentation on "how PDO supports EPID attestation". I suggest that an issue be created on this topic of the need for extra documentation. otherwise, these are out of scope for this PR.
There was a problem hiding this comment.
these must be covered as part of PDO/documentation on "how PDO enables HW mode"
Not sure what you mean here. PDO does not enable HW mode. Rather, PDO uses SGX enclaves. The SIM mode is only for whoever wants to experiment on non-SGX platforms.
The TP is one piece of the whole "PDO HW mode flow"
I don't agree with this. The TP is an architectural component of PDO, and it's actually used in SIM mode too.
we lack documentation on "how PDO supports EPID attestation". I suggest that an issue be created on this topic of the need for extra documentation. otherwise, these are out of scope for this PR.
As I interpret Marcela's question, the focus is on the values and the policy. About the values, we would have mrenclave and manufacturer certificate even if we used DCAP, so only the basename turns out to have a specific meaning in EPID. Fortunately, we kept things simple, and this makes the answer simple -- I'll add that separately.
There was a problem hiding this comment.
My questions are related to EPID attestation verification, but more fundamentally about assumptions-- assumptions about how the system will be used and assumptions about what the reader does and doesn't need to know. This document is quite long and I think the audience is still mostly us, as in, we are documenting this to record our design decisions etc. Does a newcomer user really need all of these details?
Many assumptions also aren't documented explicitly, making this document pretty difficult to digest at times. I don't think addressing this should be part of this PR, but it would be good for us to take a step back, put ourselves in the position of a newcomer, and create separate "quickstart" documentation that covers only the most fundamental information and keep this as a longer "deep dive" document.
ledgers/ccf/README.md
Outdated
| Further, the CCF TP governance consortium is permitted to change the | ||
| values of these parameters, subject to TP consoritum governance rules. |
There was a problem hiding this comment.
Is this desirable behavior? This sentence seems to be implying that the governance consortium can change the expected MRENCLAVE, base name, or IAS key for an existing registered enclave. Why wouldn't a change in these values result in a new enclave registration? That is, a new MRENCLAVE, for all intents and purposes, represents a distinct enclave. Otherwise, wouldn't a verifier with an outdated policy fail upon such changes?
There was a problem hiding this comment.
thank you. same answer as above.
| 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. |
There was a problem hiding this comment.
This flag is set only once per TP instance? This might be helpful to note.
There was a problem hiding this comment.
thank you, yes, only once. again part of policy, must be covered as part of the documentation mentioned above.
| 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. |
There was a problem hiding this comment.
This description is very good, and it says "to program the values".
Below, however, the description suggests that these APIs are already/only used in scripts so nobody should care about "programming" anything. So it is not clear who this description is for.
I think we have 3 levels of abstraction here:
- the APIs themselves as implemented in the TP.
- the convenience scripts for (just) calling these APIs from the client side (i.e., the python scripts)
- additional convenience scripts which embed these calls at the right time during a deployment -- namely when the the CCF network starts up and when the eservice starts up
There was a problem hiding this comment.
the documentation only talks about APIs provided by PDO TP that are useful to implement PDO's attestation policy. How these APIs are used by PDO clients is out of scope of this PR. you can either use the scripts that PDO provides, or write your own scripts.
There was a problem hiding this comment.
you can either use the scripts that PDO provides
Precisely, and the scripts are available, and they are even installed ready to be used.
So, how can they be out of scope (particularly (2) which is the TP client)?
Co-authored-by: Bruno Vavala <[email protected]> Signed-off-by: prakashngit <[email protected]>
Co-authored-by: Bruno Vavala <[email protected]> Signed-off-by: prakashngit <[email protected]>
Co-authored-by: Bruno Vavala <[email protected]> Signed-off-by: prakashngit <[email protected]>
| 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. |
There was a problem hiding this comment.
you can either use the scripts that PDO provides
Precisely, and the scripts are available, and they are even installed ready to be used.
So, how can they be out of scope (particularly (2) which is the TP client)?
ledgers/ccf/README.md
Outdated
| 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`. |
There was a problem hiding this comment.
these must be covered as part of PDO/documentation on "how PDO enables HW mode"
Not sure what you mean here. PDO does not enable HW mode. Rather, PDO uses SGX enclaves. The SIM mode is only for whoever wants to experiment on non-SGX platforms.
The TP is one piece of the whole "PDO HW mode flow"
I don't agree with this. The TP is an architectural component of PDO, and it's actually used in SIM mode too.
we lack documentation on "how PDO supports EPID attestation". I suggest that an issue be created on this topic of the need for extra documentation. otherwise, these are out of scope for this PR.
As I interpret Marcela's question, the focus is on the values and the policy. About the values, we would have mrenclave and manufacturer certificate even if we used DCAP, so only the basename turns out to have a specific meaning in EPID. Fortunately, we kept things simple, and this makes the answer simple -- I'll add that separately.
Co-authored-by: Bruno Vavala <[email protected]> Signed-off-by: prakashngit <[email protected]>
There was a problem hiding this comment.
Thanks for the updates @prakashngit ! I'll accept the changes since I think we're good enough to close this out, but as I mentioned in a comment, it would be good for us to take a step back, put ourselves in the position of a new user, and create separate "quickstart" documentation that covers only the most fundamental information someone needs to get started, and keep this as a longer "deep dive" documentation.
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 policycontained within ledgers/ccf/README.md to reflect the new APIs introduced in PR 467.