Attestation Service (AS for short) is a general function set that can verify TEE evidence. 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) running on the guest node will request a resource (e.g. a container image decryption key) from the Key Broker Service (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:
- Verify the evidence signature, and assess that it's been signed with a trusted key of TEE.
- Verify that the TCB described by that evidence (including hardware status and software measurements) meets the guest owner expectations.
Those two steps are accomplished by respectively one of the Verifier Drivers and the AS Policy Engine. The policy engine can be customized with different policy configurations.
The AS can be built as a library (i.e. a Rust crate) by other confidential computing resources providers, like for example the KBS. It can also run as a standalone binary, in which case its API is exposed through a set of gRPC endpoints.
The AS can be built and imported as a Rust crate into any project providing attestation services.
As the AS API is not yet fully stable, the AS crate needs to be imported from GitHub directly:
attestation-service = { git = "https://github.com/confidential-containers/attestation-service" branch = "main" }
This project provides the Attestation Service binary program that can be run as an independent server:
grpc-as
: Provide AS APIs based on gRPC protocol.
Build and install AS components:
git clone https://github.com/confidential-containers/attestation-service
cd attestation-service
make && make install
grpc-as
will be installed into /usr/local/bin
.
The main architecture of the Attestation Service is shown in the figure below:
┌──────────────────────┐ Evidence ┌─────────────────────────────┐
│ ├──────────────────────> Attestation Service │
│Verification Demander │ │ │
│ (Such as KBS) <──────────────────────┤┌──────────┐┌───────────────┐│
│ │ Attestation Result ││ Policy ││Reference Value││
└──────────────────────┘ ││ Engine ││ Povider ││
│└──────────┘└───────────────┘│
│┌───────────────────────────┐│
││ Verifier Drivers ││
│└───────────────────────────┘│
└─────────────────────────────┘
The attestation evidence is included in a KBS defined Attestation payload:
{
"tee-pubkey": $pubkey,
"tee-evidence": {}
}
-
tee-pubkey
: A JWK-formatted public key, generated by the KBC running in the HW-TEE. For more details on thetee-pubkey
format, see the KBS protocol. -
tee-evidence
: The attestation evidence generated by the HW-TEE platform software and hardware in the AA's execution environment. The tee-evidence formats depend on the TEE and are typically defined by the each TEE verifier driver of AS.
Note: Verification Demander needs to specify the TEE type and pass nonce
to Attestation-Service together with Evidence,
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
.
{
"tee": $tee_type,
"allow": true,
"output": {
"verifier_output": $verifier_output,
"policy_engine_output": $opa_output
},
"tcb_status": $tcb_status_claims
}
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.tcb_status
: Contains HW-TEE informations and software measurements of AA's execution environment.
A verifier driver parse the HW-TEE specific tee-evidence
data from the received attestation evidence, and performs the following tasks:
-
Verify HW-TEE hardware signature of the TEE quote/report in
tee-evidence
. -
Resolve
tee-evidence
, and organize the TCB status into JSON claims to return.
Supported Verifier Drivers:
sample
: A dummy TEE verifier driver which is used to test/demo the AS's functionalities.amd-sev-snp
: TODO.intel-tdx
: TODO.
The AS supports modular policy engine, which can be specified through the AS configuration. The currently supported policy engines are:
OPA is a very flexible and powerful policy engine, AS allows users to define and upload their own policy when performing evidence verification.
Note: Please refer to the Policy Language documentation for more information about the .rego
.
If the user does not need to customize his own policy, AS will use the default policy.
Reference Value Provider Service (RVPS for short) is a module integrated in the AS to verify, store and provide reference values. RVPS receives and verifies the provenance input from the software supply chain, stores the measurement values, and generates reference value claims for the AS according to the evidence content when the AS verifies the evidence.