Skip to content
This repository has been archived by the owner on Nov 21, 2023. It is now read-only.

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
Signed-off-by: Jiale Zhang <[email protected]>
  • Loading branch information
jialez0 committed Aug 7, 2023
1 parent e8b5f70 commit 3300eab
Showing 1 changed file with 23 additions and 13 deletions.
36 changes: 23 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Attestation Service (AS for short) is a general function set that can verify TEE
With Confidential Containers, the attestation service must run in an secure environment, outside of the guest node.

With remote attestation, Attesters (e.g. the [Attestation Agent](https://github.com/confidential-containers/attestation-agent)) running on the guest node will request a resource (e.g. a container image decryption key) from the [Key Broker Service (KBS)](https://github.com/confidential-containers/kbs)).
The KBS receives the attestation evidence from the attestation agent and forwards it to the Attestation Service (AS). The AS role is to verify the attestation evidence and provide Attestation Results back to the KBS. Verifying the evidence is a two steps process:
The KBS receives the attestation evidence from the client in TEE and forwards it to the Attestation Service (AS). The AS role is to verify the attestation evidence and provide Attestation Results token back to the KBS. Verifying the evidence is a two steps process:

1. Verify the evidence signature, and assess that it's been signed with a trusted key of TEE.
2. Verify that the TCB described by that evidence (including hardware status and software measurements) meets the guest owner expectations.
Expand Down Expand Up @@ -55,7 +55,7 @@ The main architecture of the Attestation Service is shown in the figure below:
│ (Such as KBS) │ │ │ Policy │ │ Reference Value │◄───Reference Value
│ │◄────────────┤ │ Engine │ │ Provider Service │
└───────────────────────┘ Attestation │ └────────┘ └──────────┬───────┘
Result │ │
Results Token │ │
│ ┌───────────────────┐ │
│ │ Verifier Drivers │ │
│ └───────────────────┘ │
Expand All @@ -77,7 +77,7 @@ The attestation evidence is included in a [KBS defined Attestation payload](http
}
```

- `tee-pubkey`: A JWK-formatted public key, generated by the KBC running in the HW-TEE.
- `tee-pubkey`: A JWK-formatted public key, generated by the client running in the HW-TEE.
For more details on the `tee-pubkey` format, see the [KBS protocol](https://github.com/confidential-containers/kbs/blob/main/docs/kbs_attestation_protocol.md#key-format).

- `tee-evidence`: The attestation evidence generated by the HW-TEE platform software and hardware in the AA's execution environment.
Expand All @@ -87,22 +87,32 @@ The tee-evidence formats depend on the TEE and are typically defined by the each
Hash of `nonce` and `tee-pubkey` should be embedded in report/quote in `tee-evidence`, so they can be signed by HW-TEE.
This mechanism ensures the freshness of Evidence and the authenticity of `tee-pubkey`.

### Attestation result format:
### Attestation Results Token:

If the verification of TEE evidence is successful, AS will return an Attestation Results Token.
Otherwise, AS will return an Error which contain verifier output or policy engine output.

Attestation results token is a [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519) which contains the parsed evidence claims such as TCB status.

Claims format of the attestation results token is:

```json
{
"tee": $tee_type,
"allow": true,
"output": {
"verifier_output": $verifier_output,
"policy_engine_output": $opa_output
},
"tcb_status": $tcb_status_claims
"iss": $issuer_name,
"jwk": $public_key,
"exp": $expire_timestamp,
"nbf": $notbefore_timestamp,
"tee-pubkey": $pubkey,
"tcb-status": $parsed_evidence
}
```

* `allow`: The verification results. `true` if verification succeeded, `false` otherwise.
* `output`: When verification fails, `output.verifier` describes the failure reasons. When verification succeeds, `output.policy_engine` may provide additional policy verification information, depending on the policy configuration.
* `iss`: Token issuer name, default is `CoCo-Attestation-Service`.
* `jwk`: Public key to verify token signature. Must be in format of [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517).
* `exp`: Token expire time in Unix timestamp format.
* `nbf`: Token effective time in Unix timestamp format.
* `tee-pubkey`: A JWK-formatted public key, generated by the client running in the HW-TEE.
For more details on the `tee-pubkey` format, see the [KBS protocol](https://github.com/confidential-containers/kbs/blob/main/docs/kbs_attestation_protocol.md#key-format).
* `tcb_status`: Contains HW-TEE informations and software measurements of AA's execution environment.

## Verifier Drivers
Expand Down

0 comments on commit 3300eab

Please sign in to comment.