[Docs] Add remote attestation terminology #1927
Conversation
dimakuv
force-pushed
the
dimakuv/docs-add-remote-attestation-terms
branch
from
aca0f48 to
df82737
Compare
There was a problem hiding this comment.
Reviewed 2 of 2 files at r1, all commit messages.
Reviewable status: all files reviewed, 15 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (1 more required, approved so far: Intel) (waiting on @dimakuv)
a discussion (no related file):
TODO for myself: check the rendered final version
Documentation/sgx-intro.rst line 193 at r1 (raw file):
Attestation result The result of appraisal of the :term:`evidence` that was generated by the
We should IMO use simpler English, so that it's easier to read for more people (as long as the meaning stays the same).
Suggestion:
The result of evaluation of the :term:`evidence`Documentation/sgx-intro.rst line 195 at r1 (raw file):
The result of appraisal of the :term:`evidence` that was generated by the :term:`verifier`. The attestation result is typically in the form of a token (e.g., a JSON Web Token), and typically includes information about
a token -> a signed token (it is actually signed, right?)
Documentation/sgx-intro.rst line 200 at r1 (raw file):
As a particular example, :term:`Intel Attestation Service` generates the attestation result as a custom-formatted JSON report. Other examples
What does formatting have to do with anything?
Code quote:
a custom-formatted JSON reportDocumentation/sgx-intro.rst line 207 at r1 (raw file):
The evidence contains claims that prove the attester's integrity
It's not the claims that prove it? It's the hardware signature which is proving the claims.
Documentation/sgx-intro.rst line 212 at r1 (raw file):
As a particular example, the attester is the Gramine SGX enclave. It generates the evidence (SGX quote plus additional claims) and sends it to the verifier (e.g., :term:`IAS`).
Isn't it the verifier, not the enclave, which sends it to IAS?
Documentation/sgx-intro.rst line 218 at r1 (raw file):
that has trustworthiness properties
What does this mean?
Documentation/sgx-intro.rst line 220 at r1 (raw file):
:term:`attester` that has trustworthiness properties, attributes or identifiers that can be included in :term:`evidence`, :term:`endorsement` or :term:`attestation result`.
Please add an example, e.g. a hash of TEE's initial state.
Documentation/sgx-intro.rst line 270 at r1 (raw file):
examples of endorsements are Certificate Revocation Lists (CRLs), minimum allowed TCB date, reference MRENCLAVE/MRSIGNER of the :term:`Quoting Enclave`, etc.
Am I missing something? I don't see what this list has in common with the meaning of the "endorsement" word in English... I'm really confused by this term and this description didn't help.
Documentation/sgx-intro.rst line 275 at r1 (raw file):
In :term:`attestation`, the endorser creates, provisions, or transfers an :term:`endorsement` to the :term:`verifier`.
So, it's kind of a database of expected TEE attributes? Can you write it more like that, or add an example?
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Attestation evidence Set of claims asserted by an attester about the :term:`Trusted Execution
That's weird, shouldn't it only cover the signature / proof? The definition doesn't seem to match the meaning of "evidence".
Code quote:
Set of claimsDocumentation/sgx-intro.rst line 538 at r1 (raw file):
Relying Party In :term:`attestation`, the relying party accepts the :term:`attestation
accepts?
Documentation/sgx-intro.rst line 671 at r1 (raw file):
the verifier receives the evidence from the attester
In IAS definition you said that it receives it from the relying party ;)
Documentation/sgx-intro.rst line 673 at r1 (raw file):
the :term:`attester`, as well as the :term:`endorsement` from the :term:`endorser`, and sends the :term:`attestation result` to the :term:`relying party`. The verifier appraises the evidence to determine
simpler English please, it's already really confusing even without this
Code quote:
appraisesDocumentation/sgx-intro.rst line 676 at r1 (raw file):
attester's trustworthiness. As a particular example, :term:`Intel Attestation Service` is the
But IAS doesn't verify the claims (maybe except the microcode version against known bugs), it only re-signs the quote so that it can be checked by non-Intel parties (because only Intel has the matching keys to the ones fused in the CPU).
There was a problem hiding this comment.
Reviewable status: 1 of 2 files reviewed, 15 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @mkow)
Documentation/sgx-intro.rst line 193 at r1 (raw file):
We should IMO use simpler English
You will not like the TCG DICE Attestation document then :)
Documentation/sgx-intro.rst line 195 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
a token->a signed token(it is actually signed, right?)
Done. Yes, of course the token is signed. Any "attestation result" must be signed.
Documentation/sgx-intro.rst line 200 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
What does formatting have to do with anything?
Done, removed that phrase. I wanted to contrast that IAS uses its own ad-hoc format for Attestation evidence, whereas more modern MAA and ITA use a standard JWT (developed specifically for such purposes).
Documentation/sgx-intro.rst line 207 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
The evidence contains claims that prove the attester's integrity
It's not the claims that prove it? It's the hardware signature which is proving the claims.
Done.
Nits: it's not necessarily a "hardware" signature, it's just some signature of a party that you trust. I mean, this definition gives a very broad explanation, not tied to Intel SGX or some other hardware TEE.
Documentation/sgx-intro.rst line 212 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
Isn't it the verifier, not the enclave, which sends it to IAS?
Done.
Yes, I forgot to add more details. Well, now I need to explain the Passport model vs Background check model :(
By the way, a really nice document on Passport vs Background check is found here, with diagrams: https://docs.trustauthority.intel.com/main/articles/concept-patterns.html
Documentation/sgx-intro.rst line 218 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
that has trustworthiness properties
What does this mean?
Done. What about this human-friendly speak?
Documentation/sgx-intro.rst line 220 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
Please add an example, e.g. a hash of TEE's initial state.
Done.
Documentation/sgx-intro.rst line 270 at r1 (raw file):
From TCG DICE:
Endorsements are the possible values that the Verifier expects to find in Evidence. Endorsements are obtained from manufacturers, vendors, and other supply chain entities called Endorsers.
I'm not the one who came up with this terminology... I actually think that "Endorsement" comes from the 90s, from the TPM world.
You can think of it like this:
- Attestation evidence is a set of (possibly malicious) claims coming from the TEE
- Attestation endorsement is a set of expected-values claims coming from vendors (e.g., a hash of the Linux kernel coming from Linus Torvalds)
- Claims from attestation evidence are compared against claims in all attestation endorsements, and a new set of claims is generated -- attestation result
Documentation/sgx-intro.rst line 275 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
So, it's kind of a database of expected TEE attributes? Can you write it more like that, or add an example?
Done.
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
That's weird, shouldn't it only cover the signature / proof? The definition doesn't seem to match the meaning of "evidence".
Done.
I'm not sure what exactly you meant by the comment, but I added the part about the signature.
Documentation/sgx-intro.rst line 538 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
accepts?
Done.
Documentation/sgx-intro.rst line 671 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
the verifier receives the evidence from the attester
In IAS definition you said that it receives it from the relying party ;)
Done.
Documentation/sgx-intro.rst line 673 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
simpler English please, it's already really confusing even without this
Done.
Documentation/sgx-intro.rst line 676 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
But IAS doesn't verify the claims (maybe except the microcode version against known bugs), it only re-signs the quote so that it can be checked by non-Intel parties (because only Intel has the matching keys to the ones fused in the CPU).
Done.
There was a problem hiding this comment.
Reviewed 1 of 1 files at r2, all commit messages.
Reviewable status: all files reviewed, 8 unresolved discussions, not enough approvals from maintainers (2 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv)
a discussion (no related file):
@donporter: Would you maybe have some time to go over this, try to understand it and suggest some ways to simplify the descriptions and naming? It was really confusing and non-intuitive to me.
Documentation/sgx-intro.rst line 193 at r1 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
We should IMO use simpler English
You will not like the TCG DICE Attestation document then :)
I thoroughly enjoyed it.
Documentation/sgx-intro.rst line 218 at r1 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Done. What about this human-friendly speak?
Much better now!
Documentation/sgx-intro.rst line 270 at r1 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
From TCG DICE:
Endorsements are the possible values that the Verifier expects to find in Evidence. Endorsements are obtained from manufacturers, vendors, and other supply chain entities called Endorsers.
I'm not the one who came up with this terminology... I actually think that "Endorsement" comes from the 90s, from the TPM world.
You can think of it like this:
- Attestation evidence is a set of (possibly malicious) claims coming from the TEE
- Attestation endorsement is a set of expected-values claims coming from vendors (e.g., a hash of the Linux kernel coming from Linus Torvalds)
- Claims from attestation evidence are compared against claims in all attestation endorsements, and a new set of claims is generated -- attestation result
But why is a "credential" on the list? Doesn't "credentials" in IT context mean authentication data? (e.g. login+password)
I really hate this TCG DICE terminology, it's really confusing and non-intuitive... Could you try to reword this description to make it less TCG-DICE-ey and more understandable?
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Evidence proves claims. But here you say that claims are the evidence, which seems like mistaking a theorem with its proof?
I'm not sure what exactly you meant by the comment, but I added the part about the signature.
That's weird, shouldn't it only cover the signature / proof?
Documentation/sgx-intro.rst line 217 at r2 (raw file):
generates the evidence (SGX quote plus additional claims) and sends it either directly to the verifier or to the relying party, which then will forward it to the verifier (see :term:`IAS` for more details).
IAS is EPID-only, right? Does it make sense to link to it here, knowing that it will be deprecated in a few months? The rest of the example doesn't seem to rely on the attestation being EPID.
Code quote:
(see :term:`IAS` for more details).Documentation/sgx-intro.rst line 310 at r2 (raw file):
As a particular example, :term:`Intel Provisioning Certification Service` is the endorser.
Suggestion:
is an endorser.Documentation/sgx-intro.rst line 567 at r2 (raw file):
Intel Attestation Service, another Internet service. Policy
Please remove it, it's too general without context. Actually, could you do the same for other glossary entries added here which are too generic? (e.g. "claim" - I'd only leave "attestation claim")
Documentation/sgx-intro.rst line 739 at r2 (raw file):
determine attester's trustworthiness. As a particular example, :term:`Intel Attestation Service` is the verifier
Suggestion:
is a verifier
There was a problem hiding this comment.
Reviewable status: 1 of 2 files reviewed, 8 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @mkow)
Documentation/sgx-intro.rst line 270 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
But why is a "credential" on the list? Doesn't "credentials" in IT context mean authentication data? (e.g. login+password)
I really hate this TCG DICE terminology, it's really confusing and non-intuitive... Could you try to reword this description to make it less TCG-DICE-ey and more understandable?
Done, I removed the word "credential" (I copied pasted from TCG DICE).
What else in the description is not understandable? To me, it reads ok.
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Evidence proves claims.
Says English dictionary? Unfortunately, TCG DICE has terminology that seems to contradict the English meanings of words. I'm not a native speaker, and I don't know the history of TPMs and TCG DICE well enough to explain what's going on here.
In TCG DICE terminology, these things are pretty clear:
- Attestation claim is a "this property has this value" atom
- Attestation evidence is a set of attestation claims, that describes the attester
- Attester generates this evidence (set of claims) and sends it to other parties
Here are relevant snippets from the TCG DICE Attestation spec:
The Attesting Environment collects assertions, called Claims, about the trustworthiness properties of the Target Environment. Claims are packaged as Evidence by the Attesting Environment, integrity protected and authenticated. The Attesting Environment may also supply additional claims that attest the freshness and recentness of collected claims
Evidence is a role message containing assertions, i.e., Claims, from the Attester. Evidence should contain freshness and recentness Claims that help establish Evidence relevance. For example, a Verifier supplies a nonce that can be included with the Evidence supplied by the Attester. Evidence typically describes the state of the device or entity. Normally, Evidence is collected in response to a request, i.e., challenge. Evidence may also describe historical device states, e.g., the state of the Attester during initial boot. It may also describe operational states that are dynamic and likely to change from one request to the next.
Documentation/sgx-intro.rst line 217 at r2 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
IAS is EPID-only, right? Does it make sense to link to it here, knowing that it will be deprecated in a few months? The rest of the example doesn't seem to rely on the attestation being EPID.
Done.
Now I introduced MAA and ITA, and always refer to them first. I still keep IAS around -- we'll remove the mentions in one go, once it's completely removed.
Documentation/sgx-intro.rst line 310 at r2 (raw file):
As a particular example, :term:`Intel Provisioning Certification Service` is the endorser.
Done.
Documentation/sgx-intro.rst line 567 at r2 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
Please remove it, it's too general without context. Actually, could you do the same for other glossary entries added here which are too generic? (e.g. "claim" - I'd only leave "attestation claim")
Done.
Documentation/sgx-intro.rst line 739 at r2 (raw file):
determine attester's trustworthiness. As a particular example, :term:`Intel Attestation Service` is the verifier
Done.
There was a problem hiding this comment.
Reviewed 1 of 1 files at r3, all commit messages.
Reviewable status: all files reviewed, 11 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv and @donporter)
Documentation/sgx-intro.rst line 270 at r1 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Done, I removed the word "credential" (I copied pasted from TCG DICE).
What else in the description is not understandable? To me, it reads ok.
See my proposals/questions above.
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Evidence proves claims.
Says English dictionary? Unfortunately, TCG DICE has terminology that seems to contradict the English meanings of words. I'm not a native speaker, and I don't know the history of TPMs and TCG DICE well enough to explain what's going on here.
In TCG DICE terminology, these things are pretty clear:
- Attestation claim is a "this property has this value" atom
- Attestation evidence is a set of attestation claims, that describes the attester
- Attester generates this evidence (set of claims) and sends it to other parties
Here are relevant snippets from the TCG DICE Attestation spec:
The Attesting Environment collects assertions, called Claims, about the trustworthiness properties of the Target Environment. Claims are packaged as Evidence by the Attesting Environment, integrity protected and authenticated. The Attesting Environment may also supply additional claims that attest the freshness and recentness of collected claims
Evidence is a role message containing assertions, i.e., Claims, from the Attester. Evidence should contain freshness and recentness Claims that help establish Evidence relevance. For example, a Verifier supplies a nonce that can be included with the Evidence supplied by the Attester. Evidence typically describes the state of the device or entity. Normally, Evidence is collected in response to a request, i.e., challenge. Evidence may also describe historical device states, e.g., the state of the Attester during initial boot. It may also describe operational states that are dynamic and likely to change from one request to the next.
/summon @donporter
@dimakuv: Do we have to use this term in Gramine? How widespread and "the standard" is TCG DICE? This particular name seems really bad and confusing to me.
Documentation/sgx-intro.rst line 217 at r2 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Done.
Now I introduced MAA and ITA, and always refer to them first. I still keep IAS around -- we'll remove the mentions in one go, once it's completely removed.
But in this entry (i.e. the entry for "Attester") the only example is EPID and it doesn't even mention that there are other ways than using IAS. Why not either removing that "(see :term:IAS for more details)" or describing a DCAP based scenario? If we keep the current example then we'll need to change it right away.
Documentation/sgx-intro.rst line 230 at r3 (raw file):
As a particular example, an Intel SGX quote (attestation evidence) contains an attestation claim ``MRENCLAVE = <SHA256 hash of initial enclave state>``. Similarly, an :term:`attestation policy` installed in
Suggestion:
``. SimilarlyDocumentation/sgx-intro.rst line 293 at r3 (raw file):
Attestation endorsement A reference value (e.g., expected hash) that authenticates the
Suggestion:
describesDocumentation/sgx-intro.rst line 294 at r3 (raw file):
A reference value (e.g., expected hash) that authenticates the :term:`attester`'s identity (e.g., device identity certificate). Other
Suggestion:
expected :term:`attester`'s identityDocumentation/sgx-intro.rst line 294 at r3 (raw file):
A reference value (e.g., expected hash) that authenticates the :term:`attester`'s identity (e.g., device identity certificate). Other
What is a "device identity certificate"? I never heard this term before.
Code quote:
(e.g., device identity certificate)Documentation/sgx-intro.rst line 596 at r3 (raw file):
party` that specifies how the :term:`attestation evidence` is evaluated by the :term:`verifier` against :term:`attestation endorsements<endorsement>`. The attestation policy also specifies the
Suggestion:
>`. Documentation/sgx-intro.rst line 765 at r3 (raw file):
As a particular example, :term:`Microsoft Azure Attestation` and :term:`Intel Trust Authority` are verifiers: they evaluate both the hardware and the software trustworthiness. Another example would be
Only partially I think? They can't know whether a specific version of user software is good or bad.
Code quote:
the software trustworthiness
There was a problem hiding this comment.
Reviewable status: all files reviewed, 11 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @donporter and @mkow)
Documentation/sgx-intro.rst line 270 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
See my proposals/questions above.
Done with the proposals above.
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
/summon @donporter
@dimakuv: Do we have to use this term in Gramine? How widespread and "the standard" is TCG DICE? This particular name seems really bad and confusing to me.
The same terminology is used in another standard called RATS: https://datatracker.ietf.org/doc/rfc9334/
I think at this point the terms are settled by the "attestation" community, and I see no point in inventing our own terminology.
Documentation/sgx-intro.rst line 217 at r2 (raw file):
Done, I removed that part.
describing a DCAP based scenario
I don't like to refer to Intel DCAP because it's not a proper end-user software. DCAP libraries/reference implementations from Intel are only a small part of the stack, and users (datacenter admins, CSPs) are supposed to write their own complete attestation solutions.
Documentation/sgx-intro.rst line 230 at r3 (raw file):
As a particular example, an Intel SGX quote (attestation evidence) contains an attestation claim ``MRENCLAVE = <SHA256 hash of initial enclave state>``. Similarly, an :term:`attestation policy` installed in
Done.
Documentation/sgx-intro.rst line 293 at r3 (raw file):
Attestation endorsement A reference value (e.g., expected hash) that authenticates the
Done.
Documentation/sgx-intro.rst line 294 at r3 (raw file):
A reference value (e.g., expected hash) that authenticates the :term:`attester`'s identity (e.g., device identity certificate). Other
Done.
Documentation/sgx-intro.rst line 294 at r3 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
What is a "device identity certificate"? I never heard this term before.
Just removed it, but it's a term used in TCG DICE to refer to certificates issued for each device. Just like DCAP issues certificates for each Intel CPU, just like NVidia issues certificates for each of its GPUs, etc. Is there any other term for this?
Documentation/sgx-intro.rst line 596 at r3 (raw file):
party` that specifies how the :term:`attestation evidence` is evaluated by the :term:`verifier` against :term:`attestation endorsements<endorsement>`. The attestation policy also specifies the
Done.
Documentation/sgx-intro.rst line 765 at r3 (raw file):
They can't know whether a specific version of user software is good or bad.
What do you mean by this exactly? Both MAA and ITA have the ability to install user-specified policies. The users are supposed to specify "golden values" for the software. So I would consider this "a specific version of user software known to be good". Do you mean something else by your comment?
User specified policies in MAA and ITA:
There was a problem hiding this comment.
Reviewed all commit messages.
Reviewable status: 1 of 2 files reviewed, 12 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv, @donporter, and @mkow)
Documentation/sgx-intro.rst line 204 at r3 (raw file):
Service` generates the attestation result as a JSON report. Attester
This needs to be defined in term of "the object that we ensure integrity" by the means of attestation. Starting with the story that it's the object that sends "attestation evidence" is going into implementation details.
Also please explain why this stuff is not named "attestee", because AFAIK the common English suffixes are reversed in this case. You can say that CoCo did it this way probably to avoid confusion.
While DICE and CoCoCo "confidential terminology" are authoritative in defining nomenclature, we still can't rely on their wording, we need to explain it to people who are starting with SGX and CoCo in the first place, not for people who are up to date with SIG mailing list.
There was a problem hiding this comment.
Reviewed 1 of 2 files at r1, all commit messages.
Reviewable status: 1 of 2 files reviewed, 24 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv and @mkow)
a discussion (no related file):
One higher-level suggestion: maybe group these terms by topic rather than alphabetically? In the case of attestation, a figure with an example protocol and roles might really help, but I also understand that is more than the original goal of this PR.
Documentation/glossary.rst line 36 at r4 (raw file):
library automatically supports *Interoperable RA-TLS*, a specification that modifies the original RA-TLS format for interoperability between different TEE frameworks. For example, Gramine applications can establish
Consider reworking: For example, without Interoperable RA-TLS, an application running in Gramine would need to be using the same cryptographic libraries in order to establish a secure connection with an application on a framework such as Occlum or OpenEnclave. With the addition of Interoperable RA-TLS in version 1.8, applications in Gramine can now establish secure connections to applications in Occlum and OpenEnclave.
Documentation/sgx-intro.rst line 270 at r1 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Done with the proposals above.
I think endorsement is a term of art going back to the information flow literature of the 70s.
Here's my understanding from the literature, which I think is consistent with this DICE document (but help me out if I'm off):
I think the key difference between evidence and endorsement is that endorsement asserts a logical implication from the evidence. For instance, in code with a machine checkable proof, the proof is the evidence, but the proof checker issues an endorsement that the code satisfies the specification.
In the context of Gramine, an attestation service might take in evidence such as the firmware version on the CPU and issue an endorsement that it did not include known exploits X, Y, and Z.
What is more explicit here is that there is a trust relationship on the verifier, who interprets the evidence upon which you are now relying.
Are we on the same page? If this text is more intuitive, steal any of it y'all are comfortable with.
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Evidence proves claims. But here you say that claims are the evidence, which seems like mistaking a theorem with its proof?
Would 'assertion' be more intuitive? I think the term 'claim' is trying to capture similar connotation here. Using 'claim' in the context of, say a signature, implies that one doesn't know the absolute truth of the claim. If a system is asserting that the hash of the TEE contents is X, I don't actually know whether that assertion is true in the absolute sense, only whether I trust the person making the assertion (claim).
In the context of a mathematical proof, in my mind assertions and claims are like lemmas: once they are proved, they are both theorems or can be steps in a chain of implications from an axiom to a different theorem.
Does this make sense?
Documentation/sgx-intro.rst line 194 at r4 (raw file):
The result of evaluation of the :term:`attestation evidence` that was generated by the :term:`verifier`. The attestation result is typically in
It could help to avoid passive voice, and give a bit more context explicitly. Maybe something like:
In the context of remote attestation, the :term:verifier issues an :term:attestation result after evaluating the :term:attestation evidence issued by the enclave CPU. The resulting evidence is typically a signed token (e.g., a JSON Web Token) with a public key signature that the client can check locally. The specific contents of the result vary by attestation protocol, but typically include...
Documentation/sgx-intro.rst line 206 at r4 (raw file):
Attester In :term:`attestation`, the attester transfers the :term:`attestation
I would just start with a definition of the role, which is apparently poorly defined. :(
Maybe:
In :term:attestation, the :term:attester collects the :term:attestation evidence and relays it to the :term:verifier (either directly or indirectly). The evidence contains ... Different protocols specify different recipients for the attestation evidence: the :term:passport model has the attester present the attestation evidence directly to the verifier, whereas in the :term:background check model the evidence is given to the :term:relying party, which then forwards the attestation evidence to the verifier.
Documentation/sgx-intro.rst line 214 at r4 (raw file):
trustworthiness, as well as the signature that proves the claims. As a particular example, the attester is the Gramine SGX enclave. It
Rather than giving an example, I would explicitly map these terms onto the Gramine architecture. For instance:
In Gramine, the Gramine SGX enclave serves the role of attester. The enclave generates...
Documentation/sgx-intro.rst line 222 at r4 (raw file):
In :term:`attestation`, the attestation claim is a machine-readable assertion about an :term:`attester` that describes security-relevant
, which
Documentation/sgx-intro.rst line 225 at r4 (raw file):
properties, attributes or identifiers that can be included in :term:`attestation evidence`, :term:`attestation endorsement` or :term:`attestation result`.
Suggest:
Common examples of attestation claims might include the hash of an SGX enclave's address space contents at the start of execution, or the firmware version installed on the CPU at execution time.
Documentation/sgx-intro.rst line 238 at r4 (raw file):
Background check attestation model In :term:`attestation`, background check model refers to an attestation
Here, I might just give the larger context as the opening sentence (and copy+reorder this text for passport model):
:term:Attestation protocols can be grouped by which party the :term:attester relays :term:attestation evidence from the TEE to; in all protocols, the attestation evidence eventually finds its way to the :term:verifier. In the :term:background check model, the attester sends attestation evidence to the :term:relying party, which then forwards the attestation evidence to the verifier.
In contrast, in the :term:passport model, the attester sends attestation evidence directly to the verifier.
Gramine supports the background check model.
Documentation/sgx-intro.rst line 306 at r4 (raw file):
In :term:`attestation`, the endorser creates, provisions, or transfers an :term:`attestation endorsement` to the :term:`verifier`.
I might merge this entry with the one above, if possible.
Documentation/sgx-intro.rst line 598 at r4 (raw file):
the :term:`attestation result`. For example, :term:`Microsoft Azure Attestation` and :term:`Intel Trust
None of these policy examples are that concrete. Could you say something like disallow any firmware or software versions with specific known vulnerabilities? Ideally connecting the evidence to the outcome, and why a third party needs to do it.
Documentation/sgx-intro.rst line 621 at r4 (raw file):
Relying Party In :term:`attestation`, the relying party receives the :term:`attestation
This could be improved by removing passive voice
Documentation/sgx-intro.rst line 627 at r4 (raw file):
on the analysis of the attestation result. Another term for relying party is remote trusted party.
What is a bit unclear here is that you are typically talking about a client. Can you make this more explicit?
There was a problem hiding this comment.
Reviewable status: 1 of 2 files reviewed, 27 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv and @mkow)
Documentation/sgx-intro.rst line 765 at r3 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
They can't know whether a specific version of user software is good or bad.
What do you mean by this exactly? Both MAA and ITA have the ability to install user-specified policies. The users are supposed to specify "golden values" for the software. So I would consider this "a specific version of user software known to be good". Do you mean something else by your comment?
User specified policies in MAA and ITA:
My reading of the DICE document is that the verifier's job is to determine whether the evidence is convincing, such as whether a signature could have been generated by a given key. As a potentially separate step, the relying party takes the evidence that passes verification and applies a policy to decide whether to trust the hardware/software.
I would avoid the phrase "determines trustworthiness", since this is really more of an implicit concept, and rarely absolute. You never really know for certain the other endpoint is trustworthy (or a meaningful risk percentage); you have some evidence and you decide to either trust it or not, based on your assessment of the evidence at hand.
Are we on the same page?
Documentation/sgx-intro.rst line 622 at r4 (raw file):
In :term:`attestation`, the relying party receives the :term:`attestation result` from the :term:`verifier`. The relying party typically manages
This sentence is a bit convoluted. Maybe something like this (what I might say when teaching this to newbies):
In Gramine's use of attestation, the relying party is typically the end-user's client that trusts a separate attestation service. In the literature, the term is more general, and applies to any system that trusts a verifier.
In a typical execution flow, the relying party might send a TEE an encrypted input, and after receiving attestation results from the verifier, the relying party may then decide to trust the TEE and offer access to the input data by sending a decryption key to the TEE.
Another term for relying party ...
Documentation/sgx-intro.rst line 753 at r4 (raw file):
Verifier In :term:`attestation`, the verifier receives the :term:`attestation
I would flip the order of these concepts - say what the verifier does first, then explain how the input is routed to the verifier (or just give a link to the relevant term).
Documentation/sgx-intro.rst line 763 at r4 (raw file):
As a particular example, :term:`Microsoft Azure Attestation` and :term:`Intel Trust Authority` are verifiers: they evaluate both the hardware and the software trustworthiness. Another example would be
suggestions: ...evaluate ...trustworthiness based on evidence reported by the CPU or architectural enclaves, such as the version of the firmware on the system or a cryptographically signed report that the CPU was made by a given vendor.
There was a problem hiding this comment.
Reviewed 1 of 1 files at r4.
Reviewable status: all files reviewed, 27 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv and @mkow)
There was a problem hiding this comment.
Reviewable status: 1 of 2 files reviewed, 26 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @donporter, @mkow, and @woju)
a discussion (no related file):
One higher-level suggestion: maybe group these terms by topic rather than alphabetically?
That's a glossary, so I think topics must be ordered alphabetically.
In the case of attestation, a figure with an example protocol and roles might really help, but I also understand that is more than the original goal of this PR.
I'm losing the point of what we're doing. The original ask from @mkow was to add explanations to some terminology used in Microsoft Azure Attestation and Intel Trust Authority plug-ins to our glossary in the documentation. There's a lot of documentation on MAA and ITA, as well as documentation on attestation generally, so my preferred way would be to point to that documentation.
Documentation/glossary.rst line 36 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
Consider reworking: For example, without Interoperable RA-TLS, an application running in Gramine would need to be using the same cryptographic libraries in order to establish a secure connection with an application on a framework such as Occlum or OpenEnclave. With the addition of Interoperable RA-TLS in version 1.8, applications in Gramine can now establish secure connections to applications in Occlum and OpenEnclave.
Sorry, this suggestion doesn't make sense to me:
- What do you mean by "using the same cryptographic libraries"? The only library that we care about is the RA-TLS library, and this one is tightly integrated with Gramine, and has its own ad-hoc format for the embedded SGX Quote. There is no ability to inter-operate with Occlum or OpenEnclave currently: RA-TLS lib cannot be used with Occlum or OpenEnclave because of its tight integration to Gramine internals, and Occlum's or OpenEnclave's similar libraries cannot communicate with Gramine's RA-TLS because the formats are different.
- If you meant e.g. OpenSSL or mbedTLS or WolfSSL by "same cryptographic libraries", then no, this is wrong. The problem of interoperability is not at the level of crypto, but at the level of how X.509 certificates are generated and how they embed the SGX Quote.
So currently I'll keep the text as is.
Documentation/sgx-intro.rst line 270 at r1 (raw file):
Previously, donporter (Don Porter) wrote…
I think endorsement is a term of art going back to the information flow literature of the 70s.
Here's my understanding from the literature, which I think is consistent with this DICE document (but help me out if I'm off):
I think the key difference between evidence and endorsement is that endorsement asserts a logical implication from the evidence. For instance, in code with a machine checkable proof, the proof is the evidence, but the proof checker issues an endorsement that the code satisfies the specification.
In the context of Gramine, an attestation service might take in evidence such as the firmware version on the CPU and issue an endorsement that it did not include known exploits X, Y, and Z.
What is more explicit here is that there is a trust relationship on the verifier, who interprets the evidence upon which you are now relying.
Are we on the same page? If this text is more intuitive, steal any of it y'all are comfortable with.
Done. I used some other definitions (mostly taken from https://datatracker.ietf.org/doc/rfc9334/), but Don is right (and my initial description of Endorsements was off).
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Previously, donporter (Don Porter) wrote…
Evidence proves claims. But here you say that claims are the evidence, which seems like mistaking a theorem with its proof?
Would 'assertion' be more intuitive? I think the term 'claim' is trying to capture similar connotation here. Using 'claim' in the context of, say a signature, implies that one doesn't know the absolute truth of the claim. If a system is asserting that the hash of the TEE contents is X, I don't actually know whether that assertion is true in the absolute sense, only whether I trust the person making the assertion (claim).
In the context of a mathematical proof, in my mind assertions and claims are like lemmas: once they are proved, they are both theorems or can be steps in a chain of implications from an axiom to a different theorem.
Does this make sense?
From Don's description, I still like to keep using "claims".
Documentation/sgx-intro.rst line 204 at r3 (raw file):
This needs to be defined in term of "the object that we ensure integrity" by the means of attestation. Starting with the story that it's the object that sends "attestation evidence" is going into implementation details.
Done, hopefully good enough.
Also please explain why this stuff is not named "attestee", because AFAIK the common English suffixes are reversed in this case. You can say that CoCo did it this way probably to avoid confusion.
Googling for "attestee dictionary" gives me no results. I don't think "attestee" is a real word? It's used by some blogs/papers, but I don't believe it to be a real word.
"Attester" has a reasonable meaning: One who attests, i.e., to certify by signature or oath. See https://en.wiktionary.org/wiki/attester. So, "attester" is the entity that certifies smth (its own properties). So I like "attester".
Documentation/sgx-intro.rst line 765 at r3 (raw file):
Previously, donporter (Don Porter) wrote…
My reading of the DICE document is that the verifier's job is to determine whether the evidence is convincing, such as whether a signature could have been generated by a given key. As a potentially separate step, the relying party takes the evidence that passes verification and applies a policy to decide whether to trust the hardware/software.
I would avoid the phrase "determines trustworthiness", since this is really more of an implicit concept, and rarely absolute. You never really know for certain the other endpoint is trustworthy (or a meaningful risk percentage); you have some evidence and you decide to either trust it or not, based on your assessment of the evidence at hand.
Are we on the same page?
I don't use the phrase "determines trustworthiness", I use the phrase "evaluates trustworthiness", which I think solves your "uncertainty" issue?
Documentation/sgx-intro.rst line 194 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
It could help to avoid passive voice, and give a bit more context explicitly. Maybe something like:
In the context of remote attestation, the :term:
verifierissues an :term:attestation resultafter evaluating the :term:attestation evidenceissued by the enclave CPU. The resulting evidence is typically a signed token (e.g., a JSON Web Token) with a public key signature that the client can check locally. The specific contents of the result vary by attestation protocol, but typically include...
Done.
Documentation/sgx-intro.rst line 206 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
I would just start with a definition of the role, which is apparently poorly defined. :(
Maybe:
In :term:
attestation, the :term:attestercollects the :term:attestation evidenceand relays it to the :term:verifier(either directly or indirectly). The evidence contains ... Different protocols specify different recipients for the attestation evidence: the :term:passport modelhas the attester present the attestation evidence directly to the verifier, whereas in the :term:background check modelthe evidence is given to the :term:relying party, which then forwards the attestation evidence to the verifier.
Done.
Documentation/sgx-intro.rst line 214 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
Rather than giving an example, I would explicitly map these terms onto the Gramine architecture. For instance:
In Gramine, the Gramine SGX enclave serves the role of attester. The enclave generates...
Done.
Documentation/sgx-intro.rst line 222 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
, which
Done.
Documentation/sgx-intro.rst line 225 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
Suggest:
Common examples of attestation claims might include the hash of an SGX enclave's address space contents at the start of execution, or the firmware version installed on the CPU at execution time.
Done.
Documentation/sgx-intro.rst line 238 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
Here, I might just give the larger context as the opening sentence (and copy+reorder this text for passport model):
:term:
Attestationprotocols can be grouped by which party the :term:attesterrelays :term:attestation evidencefrom the TEE to; in all protocols, the attestation evidence eventually finds its way to the :term:verifier. In the :term:background check model, the attester sends attestation evidence to the :term:relying party, which then forwards the attestation evidence to the verifier.In contrast, in the :term:
passport model, the attester sends attestation evidence directly to the verifier.Gramine supports the background check model.
Done.
Documentation/sgx-intro.rst line 306 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
I might merge this entry with the one above, if possible.
But why? This is a glossary.
Documentation/sgx-intro.rst line 598 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
None of these policy examples are that concrete. Could you say something like disallow any firmware or software versions with specific known vulnerabilities? Ideally connecting the evidence to the outcome, and why a third party needs to do it.
Done.
Documentation/sgx-intro.rst line 621 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
This could be improved by removing passive voice
Done
Documentation/sgx-intro.rst line 622 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
This sentence is a bit convoluted. Maybe something like this (what I might say when teaching this to newbies):
In Gramine's use of attestation, the relying party is typically the end-user's client that trusts a separate attestation service. In the literature, the term is more general, and applies to any system that trusts a verifier.
In a typical execution flow, the relying party might send a TEE an encrypted input, and after receiving attestation results from the verifier, the relying party may then decide to trust the TEE and offer access to the input data by sending a decryption key to the TEE.
Another term for relying party ...
Done.
Documentation/sgx-intro.rst line 627 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
What is a bit unclear here is that you are typically talking about a client. Can you make this more explicit?
Done.
Documentation/sgx-intro.rst line 753 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
I would flip the order of these concepts - say what the verifier does first, then explain how the input is routed to the verifier (or just give a link to the relevant term).
Done.
Documentation/sgx-intro.rst line 763 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
suggestions: ...evaluate ...trustworthiness based on evidence reported by the CPU or architectural enclaves, such as the version of the firmware on the system or a cryptographically signed report that the CPU was made by a given vendor.
Done.
There was a problem hiding this comment.
Reviewable status: 1 of 2 files reviewed, 26 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv, @donporter, and @mkow)
Documentation/sgx-intro.rst line 204 at r3 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
This needs to be defined in term of "the object that we ensure integrity" by the means of attestation. Starting with the story that it's the object that sends "attestation evidence" is going into implementation details.
Done, hopefully good enough.
Also please explain why this stuff is not named "attestee", because AFAIK the common English suffixes are reversed in this case. You can say that CoCo did it this way probably to avoid confusion.
Googling for "attestee dictionary" gives me no results. I don't think "attestee" is a real word? It's used by some blogs/papers, but I don't believe it to be a real word.
"Attester" has a reasonable meaning: One who attests, i.e., to certify by signature or oath. See https://en.wiktionary.org/wiki/attester. So, "attester" is the entity that certifies smth (its own properties). So I like "attester".
Good enough for me, thanks.
Documentation/sgx-intro.rst line 256 at r5 (raw file):
:term:`Attestation` protocols can be grouped by which party the :term:`attester` relays :term:`attestation evidence` from the TEE to; in
:term:`TEE`
There was a problem hiding this comment.
Reviewable status: 1 of 2 files reviewed, 26 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @donporter, @mkow, and @woju)
Documentation/sgx-intro.rst line 256 at r5 (raw file):
Previously, woju (Wojtek Porczyk) wrote…
:term:`TEE`
Done.
There was a problem hiding this comment.
Reviewed 1 of 1 files at r6, all commit messages.
Reviewable status: all files reviewed, 22 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv, @donporter, and @woju)
a discussion (no related file):
That's a glossary, so I think topics must be ordered alphabetically.
I agree. If we'd like to split this into categories, then I'd create separate pages for each and sort inside each ("sub-glossaries").
I'm losing the point of what we're doing. The original ask from @mkow was to add explanations to some terminology used in Microsoft Azure Attestation and Intel Trust Authority plug-ins to our glossary in the documentation. There's a lot of documentation on MAA and ITA, as well as documentation on attestation generally, so my preferred way would be to point to that documentation.
+1
Documentation/glossary.rst line 36 at r4 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Sorry, this suggestion doesn't make sense to me:
- What do you mean by "using the same cryptographic libraries"? The only library that we care about is the RA-TLS library, and this one is tightly integrated with Gramine, and has its own ad-hoc format for the embedded SGX Quote. There is no ability to inter-operate with Occlum or OpenEnclave currently: RA-TLS lib cannot be used with Occlum or OpenEnclave because of its tight integration to Gramine internals, and Occlum's or OpenEnclave's similar libraries cannot communicate with Gramine's RA-TLS because the formats are different.
- If you meant e.g. OpenSSL or mbedTLS or WolfSSL by "same cryptographic libraries", then no, this is wrong. The problem of interoperability is not at the level of crypto, but at the level of how X.509 certificates are generated and how they embed the SGX Quote.
So currently I'll keep the text as is.
+1 to what Dmitrii said, the difference is on a different level (and crypto libraries actually can be substituted in the current RA-TLS).
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
From Don's description, I still like to keep using "claims".
I don't have a problem with "claim", but with "evidence" used as a synonym of "claim". I don't know if I'm missing either some understanding or English meaning / possible connotations of "evidence", but it seems like here it's used with a very different meaning than the one I know.
Documentation/sgx-intro.rst line 294 at r3 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Just removed it, but it's a term used in TCG DICE to refer to certificates issued for each device. Just like DCAP issues certificates for each Intel CPU, just like NVidia issues certificates for each of its GPUs, etc. Is there any other term for this?
What is this certificate, exactly? I know what's a certificate in the context of TLS, but it doesn't seem to mean something analogous here.
Documentation/sgx-intro.rst line 765 at r3 (raw file):
Both MAA and ITA have the ability to install user-specified policies.
Ah, I thought they are evaluated by the user.
Documentation/sgx-intro.rst line 196 at r6 (raw file):
attestation result after evaluating the :term:`attestation evidence` issued by the :term:`TEE`. The resulting evidence is typically a signed token (e.g., a JSON Web Token) with a public key signature that the
ditto for the whole PR, you add these doublespaces all the time ;)
Suggestion:
Token) withDocumentation/sgx-intro.rst line 315 at r6 (raw file):
:term:`attester`'s various capabilities. Endorsements might describe the ways in which the attester resists attacks, protects secrets, and measures Target Environments. One example of an endorsement is a manufacturer
Why is this capitalized?
Code quote:
Target EnvironmentsDocumentation/sgx-intro.rst line 317 at r6 (raw file):
Target Environments. One example of an endorsement is a manufacturer certificate that signs a public key whose corresponding private key is only known inside the device's hardware.
Does this ever happens in any TEE? In SGX the public keys for the hardware private keys are AFAIR not known publicly.
Documentation/sgx-intro.rst line 801 at r6 (raw file):
check model` has the attester transfer the evidence to the :term:`relying party` which then forwards it to the :term:`verifier` for verification (the relying party performs a "background check" on the attester).
We have these flows (background-check vs passport) already described in the relevant entries, they don't seem too relevant here?
There was a problem hiding this comment.
Reviewable status: 1 of 2 files reviewed, 22 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @donporter, @mkow, and @woju)
a discussion (no related file):
Previously, mkow (Michał Kowalczyk) wrote…
That's a glossary, so I think topics must be ordered alphabetically.
I agree. If we'd like to split this into categories, then I'd create separate pages for each and sort inside each ("sub-glossaries").
I'm losing the point of what we're doing. The original ask from @mkow was to add explanations to some terminology used in Microsoft Azure Attestation and Intel Trust Authority plug-ins to our glossary in the documentation. There's a lot of documentation on MAA and ITA, as well as documentation on attestation generally, so my preferred way would be to point to that documentation.
+1
Done from my side (in the sense, nothing to be done)
Documentation/glossary.rst line 36 at r4 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
+1 to what Dmitrii said, the difference is on a different level (and crypto libraries actually can be substituted in the current RA-TLS).
Done.
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
I don't have a problem with "claim", but with "evidence" used as a synonym of "claim". I don't know if I'm missing either some understanding or English meaning / possible connotations of "evidence", but it seems like here it's used with a very different meaning than the one I know.
I don't know what my next action should be now. Any idea how to move forward? @mkow
Documentation/sgx-intro.rst line 294 at r3 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
What is this certificate, exactly? I know what's a certificate in the context of TLS, but it doesn't seem to mean something analogous here.
At least for Intel, there is an Intel Provisioning Certification Service: https://api.portal.trustedservices.intel.com/provisioning-certification. You can see that it talks about normal X.509 certificates.
You can skim through this official docs: https://api.trustedservices.intel.com/documents/Intel_SGX_PCK_Certificate_CRL_Spec-1.5.pdf. It contains enough details to assure you that these are the classic X.509 certificate chains (with some SGX magic values sprinkled around). The same applies to Intel TDX afaik.
Documentation/sgx-intro.rst line 196 at r6 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
ditto for the whole PR, you add these doublespaces all the time ;)
Done. That's Vim auto-indent, and I still didn't master how to instruct vim not to do this...
Documentation/sgx-intro.rst line 315 at r6 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
Why is this capitalized?
Done. Oops, I wanted to say Trusted Execution Environment.
Documentation/sgx-intro.rst line 317 at r6 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
Target Environments. One example of an endorsement is a manufacturer certificate that signs a public key whose corresponding private key is only known inside the device's hardware.
Does this ever happens in any TEE? In SGX the public keys for the hardware private keys are AFAIR not known publicly.
Well, yes, the reality is more like there's a special protocol (provisioning) in Intel SGX/TDX, where the new platform first talks to a special Intel service, and by the Intel service produces the certificate that proves the identity/genuineness of this device.
Documentation/sgx-intro.rst line 801 at r6 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
We have these flows (background-check vs passport) already described in the relevant entries, they don't seem too relevant here?
Done.
There was a problem hiding this comment.
Reviewed 1 of 1 files at r7, all commit messages.
Reviewable status: all files reviewed, 12 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv, @mkow, and @woju)
a discussion (no related file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Done from my side (in the sense, nothing to be done)
That's fine. The context helps.
Documentation/glossary.rst line 36 at r4 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Done.
My suggestion is really to unpack what the first sentence means by "not interoperable", perhaps with an example. My attempts to do this are incorrect -- that is fine. So add a sentence showing what this incompatibility means in a practical sense.
My secondary suggestion is to make this positive. Start with the feature Gramine does have, and then talk about the deficiency in older versions.
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
I don't know what my next action should be now. Any idea how to move forward? @mkow
In the technical terms (e.g., this DICE nomenclature): are "evidence" and "claims" equivalent terms.
I see mkow's point: in conversational English, evidence supports a claim. A claim is the higher-level take-away (this code is not vulnerable to buffer overflows), the evidence supports this claim (the code is written in a memory safe and type safe language, compiled with toolchain X, etc).
What if we replace "claim" with "statements"? Since ultimately, this is all operating on cryptographically signed statements. The definition of "attestation claims" uses "assertions".
Door number 3 (my attempted rewrite):
In the context of remote attestation, the attester creates and signs a set of of attestation claims about the TEE that must be transferred to the verifier. The attestation claims serve as evidence that the TEE meets certain security requirements, which are then validated or rejected by the verifier. For instance, attestation claims might include a statement that the TEE is running on specific hardware, and a cryptographic signature that could only be generated by
that hardware's vendor. The verifier in this example would validate this signature, or reject statements when cryptographic checks fail.
Documentation/sgx-intro.rst line 306 at r4 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
But why? This is a glossary.
I suppose just because it might be easier to explain both terms together than separately. But feel free not to take this one.
Documentation/sgx-intro.rst line 200 at r7 (raw file):
attestation protocol, but typically include information about the :term:`attester` (TEE) such as the hash of the public key generated by the attester, its identity measurements, etc.
Nit: You don't need "such as" and "etc". Choose one - I recommend "such as"
Documentation/sgx-intro.rst line 772 at r7 (raw file):
The document most relevant to the Gramine project is the "DICE Attestation Architecture" specification. It describes the requirements and flows for
Do we want to link to this term or the organization for the interested reader? Or let them use google like the rest of us :)
There was a problem hiding this comment.
Reviewable status: 0 of 2 files reviewed, 10 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @donporter, @mkow, and @woju)
Documentation/glossary.rst line 36 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
My suggestion is really to unpack what the first sentence means by "not interoperable", perhaps with an example. My attempts to do this are incorrect -- that is fine. So add a sentence showing what this incompatibility means in a practical sense.
My secondary suggestion is to make this positive. Start with the feature Gramine does have, and then talk about the deficiency in older versions.
Done. Reformulated.
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Again, we seem to be discussing Common English Meanings vs TCG DICE/RATS Standards Meanings. To quote TCG DICE:
Claims are packaged as Evidence by the Attesting Environment, integrity protected and authenticated.
I think this sentence captures very well that Evidence is a set of Claims. That's not exactly "equivalent terms", but the evidence is just a bunch of claims collected together and hashed/signed. Evidence is a struct, Claims are struct fields.
While I agree that in Common English the meaning is different (evidence are atoms that prove/support claims), but in the language of the TCG DICE and RATS standards it's the other meaning. The question is: do we want to follow the TCG DICE meaning? My answer is yes, because that was the original purpose of this PR and the original ask: while working on the MAA and ITA plugins for RA-TLS, @mkow wanted to learn the terminology used by these frameworks.
I added a sentence now that this meaning may differ from "conversational English", but that we stick to the TCG DICE definitions for the sake of standard conformity.
Documentation/sgx-intro.rst line 306 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
I suppose just because it might be easier to explain both terms together than separately. But feel free not to take this one.
Yes, I understand the motivation, but on the other hand it's a glossary, it's not a "description" document. We want to list all the terms separately.
Documentation/sgx-intro.rst line 200 at r7 (raw file):
Previously, donporter (Don Porter) wrote…
Nit: You don't need "such as" and "etc". Choose one - I recommend "such as"
Done
Documentation/sgx-intro.rst line 772 at r7 (raw file):
Previously, donporter (Don Porter) wrote…
Do we want to link to this term or the organization for the interested reader? Or let them use google like the rest of us :)
Done
There was a problem hiding this comment.
Reviewed 2 of 2 files at r8, all commit messages.
Reviewable status: all files reviewed, 9 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv, @mkow, and @woju)
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Again, we seem to be discussing Common English Meanings vs TCG DICE/RATS Standards Meanings. To quote TCG DICE:
Claims are packaged as Evidence by the Attesting Environment, integrity protected and authenticated.
I think this sentence captures very well that Evidence is a set of Claims. That's not exactly "equivalent terms", but the evidence is just a bunch of claims collected together and hashed/signed. Evidence is a struct, Claims are struct fields.
While I agree that in Common English the meaning is different (evidence are atoms that prove/support claims), but in the language of the TCG DICE and RATS standards it's the other meaning. The question is: do we want to follow the TCG DICE meaning? My answer is yes, because that was the original purpose of this PR and the original ask: while working on the MAA and ITA plugins for RA-TLS, @mkow wanted to learn the terminology used by these frameworks.
I added a sentence now that this meaning may differ from "conversational English", but that we stick to the TCG DICE definitions for the sake of standard conformity.
Maybe add a clarifying sentence like: In the TCG DICE nomenclature, the distinction between evidence and claims is that evidence is a set of signed claims.
I'm fine with using this nomenclature. Repeating this clarification confirms to the reader that they understand this relationship correctly.
Documentation/sgx-intro.rst line 206 at r4 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Done.
Did you commit? I don't see any edits.
There was a problem hiding this comment.
Reviewed 2 of 2 files at r8, all commit messages.
Reviewable status: all files reviewed, 4 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv, @donporter, and @woju)
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Maybe add a clarifying sentence like: In the TCG DICE nomenclature, the distinction between evidence and claims is that evidence is a set of signed claims.
+1
There was a problem hiding this comment.
Reviewable status: 1 of 2 files reviewed, 4 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @donporter, @mkow, and @woju)
Documentation/sgx-intro.rst line 334 at r1 (raw file):
Previously, mkow (Michał Kowalczyk) wrote…
Maybe add a clarifying sentence like: In the TCG DICE nomenclature, the distinction between evidence and claims is that evidence is a set of signed claims.
+1
Done.
Documentation/sgx-intro.rst line 206 at r4 (raw file):
Previously, donporter (Don Porter) wrote…
Did you commit? I don't see any edits.
Yes, this was done several days ago, see r4..r8 commit range. I slightly modified your proposal, but kept the gist of it.
There was a problem hiding this comment.
Reviewed 1 of 1 files at r9, all commit messages.
Reviewable status: all files reviewed, 3 unresolved discussions, "fixup! " found in commit messages' one-liners (waiting on @dimakuv, @mkow, and @woju)
There was a problem hiding this comment.
Reviewed 1 of 1 files at r9, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion, "fixup! " found in commit messages' one-liners (waiting on @woju)
a discussion (no related file):
Previously, mkow (Michał Kowalczyk) wrote…
TODO for myself: check the rendered final version
Done.
There was a problem hiding this comment.
Reviewed 1 of 2 files at r8, 1 of 1 files at r9, all commit messages.
Reviewable status: all files reviewed, 6 unresolved discussions, "fixup! " found in commit messages' one-liners (waiting on @dimakuv and @woju)
Documentation/glossary.rst line 33 at r9 (raw file):
Starting from v1.8, Gramine's RA-TLS library supports *Interoperable RA-TLS*, a specification that modifies the original RA-TLS format for
Should we put a link to the specifications here, e.g., https://github.com/CCC-Attestation/interoperable-ra-tls/tree/main/docs?
Code quote:
Starting from v1.8, Gramine's RA-TLS library supports *Interoperable
RA-TLS*, a specification that modifies the original RA-TLS format forDocumentation/sgx-intro.rst line 231 at r9 (raw file):
security-relevant properties, attributes or identifiers that can be included in :term:`attestation evidence`, :term:`attestation endorsement` or :term:`attestation result`.
what about attestation policies?
Code quote:
included in :term:`attestation evidence`, :term:`attestation endorsement`
or :term:`attestation result`.Documentation/sgx-intro.rst line 302 at r9 (raw file):
changing memory permissions and type. Attestation endorsement
I think (most of) these terms are basically formalized (though slightly differently) in IETF RATS (RFC 9334) (well, we are disucssing the flow of RATS in some sense), maybe we want to put a link somewhere?
Code quote:
Attestation endorsementDocumentation/sgx-intro.rst line 774 at r9 (raw file):
TCG DICE is an industry standard developed by the Trusted Computing Group organization. The DICE standard (ppreviously called RIoT) mandates
-> previously
Code quote:
ppreviouslyDocumentation/sgx-intro.rst line 806 at r9 (raw file):
a given vendor. Another example would be :term:`Intel Attestation Service`, though it only evaluates that the hardware is genuine and up-to-date.
- Is this true? Platform TCB would also contain architectural enclaves?
- Should we mention the plan of EOL: https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/resources/sgx-ias-using-epid-eol-timeline.html?
Code quote:
Service`, though it only evaluates that the hardware is genuine and
up-to-date.
There was a problem hiding this comment.
Reviewable status: 0 of 2 files reviewed, 6 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @donporter, @kailun-qin, @mkow, and @woju)
Documentation/glossary.rst line 33 at r9 (raw file):
Previously, kailun-qin (Kailun Qin) wrote…
Should we put a link to the specifications here, e.g., https://github.com/CCC-Attestation/interoperable-ra-tls/tree/main/docs?
Done.
Documentation/sgx-intro.rst line 231 at r9 (raw file):
Previously, kailun-qin (Kailun Qin) wrote…
what about attestation policies?
Done.
Documentation/sgx-intro.rst line 302 at r9 (raw file):
Previously, kailun-qin (Kailun Qin) wrote…
I think (most of) these terms are basically formalized (though slightly differently) in IETF RATS (RFC 9334) (well, we are disucssing the flow of RATS in some sense), maybe we want to put a link somewhere?
Done. Wasn't sure where to add this link (I don't want to mention two standards all the time), so added a "see also" note under TCG DICE
Documentation/sgx-intro.rst line 774 at r9 (raw file):
Previously, kailun-qin (Kailun Qin) wrote…
-> previously
Done.
Documentation/sgx-intro.rst line 806 at r9 (raw file):
Previously, kailun-qin (Kailun Qin) wrote…
- Is this true? Platform TCB would also contain architectural enclaves?
- Should we mention the plan of EOL: https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/resources/sgx-ias-using-epid-eol-timeline.html?
Done. To avoid confusion, I simply removed the IAS mention.
dimakuv
force-pushed
the
dimakuv/docs-add-remote-attestation-terms
branch
from
754ee07 to
fb7c676
Compare
There was a problem hiding this comment.
Reviewed 2 of 2 files at r10, all commit messages.
Reviewable status: all files reviewed, 2 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @dimakuv and @woju)
Documentation/sgx-intro.rst line 806 at r9 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Done. To avoid confusion, I simply removed the IAS mention.
We have similar descriptions here:
gramine/Documentation/sgx-intro.rst
Lines 628 to 631 in fb7c676
There was a problem hiding this comment.
Reviewed 2 of 2 files at r10, all commit messages.
Reviewable status: all files reviewed, 2 unresolved discussions, "fixup! " found in commit messages' one-liners (waiting on @dimakuv and @woju)
There was a problem hiding this comment.
Reviewable status: 1 of 2 files reviewed, 2 unresolved discussions, not enough approvals from maintainers (1 more required), not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @donporter, @kailun-qin, and @woju)
Documentation/sgx-intro.rst line 806 at r9 (raw file):
Previously, kailun-qin (Kailun Qin) wrote…
We have similar descriptions here:
, do we want to also remove this?gramine/Documentation/sgx-intro.rst
Lines 628 to 631 in fb7c676
Done.
There was a problem hiding this comment.
Reviewed 1 of 1 files at r11, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion, not enough approvals from different teams (1 more required, approved so far: Intel), "fixup! " found in commit messages' one-liners (waiting on @woju)
There was a problem hiding this comment.
Reviewed 1 of 2 files at r10, 1 of 1 files at r11, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion, "fixup! " found in commit messages' one-liners (waiting on @woju)
In particular, the terminology follows TCG DICE Attestation. Signed-off-by: Dmitrii Kuvaiskii <[email protected]>
There was a problem hiding this comment.
Dismissed @woju from a discussion.
Reviewable status: all files reviewed, all discussions resolved, "fixup! " found in commit messages' one-liners
Documentation/sgx-intro.rst line 256 at r5 (raw file):
Previously, dimakuv (Dmitrii Kuvaiskii) wrote…
Done.
Dismissing @woju from this discussion as he is currently unavailable and he allowed to dismiss him in a private conversation.
dimakuv
force-pushed
the
dimakuv/docs-add-remote-attestation-terms
branch
from
c1adb2c to
35d8528
Compare
dimakuv
dismissed
woju’s stale review
Dismissing @woju as he is currently unavailable and he allowed to dismiss him in a private conversation.
There was a problem hiding this comment.
Reviewed all commit messages.
Reviewable status:complete! all files reviewed, all discussions resolved
There was a problem hiding this comment.
Reviewed all commit messages.
Reviewable status:
Description of the changes
In particular, the terminology follows TCG DICE Attestation.
Extracted from #1039.
How to test this PR?
Check the RTD pages:
This change is