Design
According to [RFC] Generic Key Broker Service (KBS) & Attestation Service high level architecture proposal, CC's general Attestation system relies on Attestation Service and KBS to verify the Attestation-Agent's running environment and distribute critical messages(such as KEK). The KBS is the role of RATS Relying Party
, it's hardware agnostically and focuses on vendor-specific requirements. The Attestation Service is an implementation of the RATS Verifier
role, it focuses on the verification of Evidence's identity and TCB status.
And the CC's Attestation Service is a general infrastructure service that mostly focuses on providing a Evidence verification service to KBS. So it needs to be compatible with all CC-supported HW-TEEs and should have excellent scalability to support potential new HW-TEE in the future. It also can be compatible with existing third-party attestation services with modularization.
To support the verification of TCB status, Attestation Service has the capability of parse the received Evidence to extract its corresponding TCB status. At the same time, it also includes the Policy Engine component which is an implementation of RATS Verifier Owner
, It relies on the reference data from Reference Value Provider
and the info extracted from Evidence to match the Attestation-Agent's running environment's TCB status dynamically. And generate the corresponding Attestation Results.
Attestation Service supports different deployment modes, as a service or as a library. One Attestation Service maybe needs to support several KBS services simultaneously when it is deployed as an infrastructure service. This will enhance the flexibility of the service's deployment.
Goals
- Define the format of Evidence and Attestation Results messages for SGX and TDX.
- Distribute the Attestation Service as a library or single service.
- It's a general infrastructure service that:
- It should compatible with various HW-TEEs and have good scalability.
- It should compatible with different third-party attestation Services.
- Support management API to set reference data by
Reference Value Provider
and set other configurations.
Non-Goals
- Define the format of Evidence and Attestation Results messages for SEV(-ES) and SEV-SNP.
- Proxy sub-modules that support existing third-party attestation services.
Architecture
The following diagram demonstrates the overall architecture and internal modules:
- Service: Provides interface that can be used to communicate with KBS. It receives Evidence from KBS and returns the Attestation Results.
- Attestation: The core module that implements Evidence's attestation.
- Verification Drivers: Includes HW-TEE sepcific sub-modules and policy module to verify Evidence identity and TCB status.
- TDX/SGX/SEV-SNP/SEV(-ES): Pluggable and HW-TEE specific sub-modules which invoke
Endorser
to verify Evidence's identity.
- Policy Engine: Act as RATS
Verifier Owner
to verify TCB status.
- Proxy: Includes pluggable proxy sub-modules that can invoke third-party attestation services to attest the Evidence.
- Management API: It provides APIs that are used by
Reference Value Provider
to set Verifier Owner
reference data and execute some other configurations.
Service Module
This module is used to communicate with external modules such as KBS, its mainly features are:
- Support the following two different running modes:
- As a Library: It can be integrated and invoked by KBS directly.
- As a Service: Running as a separate service.
- Receive the
Evidence
sent by KBS and return the corresponding Attestation Results
.
Evidence
Different types of HW-TEE Evidences are various, as example:
{
"tee" : "tdx",
"quote": <Base64 encoded quote>,
// The ehd's hash will be embeded in Quote->report_data.
"ehd":
{
"nonce" : "cdfunsas23445xd",
"public-key" : "xxxxxxxx"
},
"aad":
{
"tdelInfo" : <Base64 encoded eventlog's information>,
"tdelData" : <Base64 encoded eventlog's data>
}
}
{
"tee" : "sgx",
"quote": <Base64 encoded quote>,
//The ehd's hash will be embeded in Quote->report_data.
"ehd":
{
"nonce" : "cdfunsas23445xd",
"public-key" : "xxxxxxxx"
},
"aad":{}
}
Attestation Results
The Entity Attestation Token (EAT) format compliant Attestation Results of the Evidence. Its format should be:
{
"alg": "RS256",
"jku": "https://xxxxx.xxx/certs",
"kid": <self signed certificate reference to perform signature verification of attestation token,
"typ": "JWT"
}.{
"exp": 1568187398,
"iat": 1568158598,
"iss": "https://xxxxxx",
"attestation_results":{}
}.[Signature]
attestation_results
: The result of the Evidence's attestation.
Signature
(Optional): The value will be empty in the following scenario:
- Attestation Service is called as a Crate.
- The connection between Attestation Service and KBS is security and trusted.
The attestation_results
of different types of HW-TEE are various, as examples:
- TDX Evidence attestation results:
"attestation_results":
{
"tee": "TDX",
"attestation-type": "TDX",
"policy":
{
"allow": "true", //true/false: the verification state
"name": <>, //The name of the used evaluation policy file
"hash": <>, //The hash of the used evaluation policy file
"diagnose":"" //Diagnose message from Policy Engine
}
"tcb":
{
"collateral":
{
"qeidcertshash": <SHA256 value of QE Identity issuing certs>,
"qeidcrlhash": <SHA256 value of QE Identity issuing certs CRL list>,
"qeidhash": <SHA256 value of the QE Identity collateral>,
"quotehash": <SHA256 value of the evaluated quote>,
"tcbinfocertshash": <SHA256 value of the TCB Info issuing certs>,
"tcbinfocrlhash": <SHA256 value of the TCB Info issuing certs CRL list>,
"tcbinfohash": <SHA256 value of the TCB Info collateral>
},
"ehd": <>,
"is-debuggable": true,
"mrseam": "xxxxxx",
"mrseamsigner": "xxxxxx",
"mrtd": "xxxxxx",
"rtmr0": "xxxxxx",
"rtmr1": "xxxxxx",
"rtmr2": "xxxxxx",
"rtmr3": "xxxxxx",
"cpusvn": 1,
"svn": 1
}
}
- SGX Evidence attestation results:
"attestation_results":
{
"tee": "SGX",
"attestation-type": "SGX", //String value representing attestation type
"policy":
{
"allow": "true", //true/false: the verification state
"name": <>, //The name of the used evaluation policy file
"hash": <>, //The hash of the used evaluation policy file
"diagnose":"" //Diagnose message from Policy Engine
}
"tcb":
{
"collateral":
{
"qeidcertshash": <SHA256 value of QE Identity issuing certs>,
"qeidcrlhash": <SHA256 value of QE Identity issuing certs CRL list>,
"qeidhash": <SHA256 value of the QE Identity collateral>,
"quotehash": <SHA256 value of the evaluated quote>,
"tcbinfocertshash": <SHA256 value of the TCB Info issuing certs>,
"tcbinfocrlhash": <SHA256 value of the TCB Info issuing certs CRL list>,
"tcbinfohash": <SHA256 value of the TCB Info collateral>
},
"ehd": <>,
"is-debuggable": true,
"mrenclave": <SGX enclave mrenclave value>,
"mrsigner": <SGX enclave msrigner value>,
"product-id": 1,
"svn": 1
}
}
- SEV-SNP Evidence attestation results:
TODO
As a Library
The Attestation Service will provide the following interface:
pub fn attestation(evidence: String) -> Result<String, String> {}
attestation()
:
- Role: Verify the evidence and return the corresponding Attestation Results.
- Evidence(Input): Attestation-Agent generated Evidence. It's a JSON string that includes the target HW-TEE identity and TCB status information that needs to be verified.
- Attestation Results(Output): The Entity Attestation Token (EAT) format compliant Attestation Results of the Evidence.
As a Service
The Attestation Service can be extended to add a separate service application which also relies on the upper library. Its Cargo.toml
file example:
[[bin]]
name = "attestation_service"
path = "app/attestation_service/src/main.rs"
Note: The service can be connected with localhost:port
only in POC stage.
The POC will select the gRPC, so its proto
file should be:
syntax = "proto3";
package attestation;
message AttestationRequest {
bytes evidence = 1;
}
message AttestationResponse {
bytes results = 1;
}
service AttestationService {
rpc Attestation(AttestationRequest) returns (AttestationResponse) {};
}
Attestation Module
Its responsibility is to verify these various received Evidence. It includes the following two internal modules:
- Verification Drivers: It includes different HW-TEE specific modules and some common modules. The former verifies the Evidence's identity, the common modules verify the TCB status.
- Proxy: It includes proxy sub-modules that are compatible with third-party Attestation Service in order to use these services to attest Evidence directly.
It also defines a trait
that needs to be implemented by its internal modules.
trait Attestation{
fn attestation(&self, evidence : String) ->Result<String, String>;
}
Verification Drivers
It includes different HW-TEE specific pluggable verification modules and some common modules to verify the Evidence's identity and TCB status:
- TDX/SGX/SEV(-ES)/SEV-SNP (pluggable): HW-TEE specific modules.
- Eventlog-rs (common): Parse the TCG protocol compliant eventlog inside Evidence.
- Policy Engine (common): Verify TCB status via Develop Policy as Code mechanism.
TDX/SGX/SEV(-ES)/SEV-SNP
Its features:
- Each module corresponds to a specific HW-TEE type.
- Each module can be enabled/disabled by
feature
, such as #[cfg(feature = "tdx")]
.
- It can verify the received Evidence's identity.
- It can extract the TCB information inside the received Evidence.
Eventlog-rs
To verify all running programs' measurements inside TEE-based VM, the TCG protocol compliant eventlog will be included inside Evidence. So the eventlog-rs is used to parse that eventlog and extract the following components' measurements which will be sent to Policy Engine for final verification (as an example):
- Bootloader
- Kernel Parameters
- Kernel
- ...
Note: Only the TDX supports eventlog currently.
Policy Engine
It uses Open Policy Engine to reach Develop Policy as Code. And OPA relies on the following files to execute verification:
- OPA Input (JSON): These data need to be verified such as TCB status and running programs' measurement.
- OPA Data (JSON): The reference data that is provided by
Reference Value Provider
.
- OPA Policy (.rego): The judgment policy.rego file.
Policy.rego
The different HW-TEE TCB status's verification policy is various, as examples:
Policy.rego
used to check Bootloader, Kernel Parameters, and Kernel measurements extracted from eventlog:
package policy
import future.keywords.in
default allow = false
allow {
bootloader_is_granted
kernel_is_granted
kernelparameters_is_granted
}
bootloader_is_granted {
count(data.bootloader.hashes) == 0
}
bootloader_is_granted {
input.bootloader == data.bootloader.hashes[_]
}
kernel_is_granted {
count(data.kernel.hashes) == 0
}
kernel_is_granted {
input.kernel == data.kernel.hashes[_]
}
kernelparameters_is_granted {
count(data.parameters.hashes) == 0
}
kernelparameters_is_granted {
input.parameters == data.parameters.hashes[_]
}
Policy.rego
used to check SGX Evidence's TCB information:
package policy
# By default, deny requests.
default allow = false
allow {
mrEnclave_is_grant
mrSigner_is_grant
input.productId >= data.productId
input.svn >= data.svn
}
mrEnclave_is_grant {
count(data.mrEnclave) == 0
}
mrEnclave_is_grant {
count(data.mrEnclave) > 0
input.mrEnclave == data.mrEnclave[_]
}
mrSigner_is_grant {
count(data.mrSigner) == 0
}
mrSigner_is_grant {
count(data.mrSigner) > 0
input.mrSigner == data.mrSigner[_]
}
Proxy
It includes pluggable proxy sub-modules that are used to support third-party Attestation Services, such as:
- Microsoft Azure Attestation Service
- ISecL Attestation Service
Management API Module
Attestation Service
also enables a management API to provide the following functionalities:
- Set Policy Engine's reference data by
Reference Value Provider
.
- Set proxy sub-modules configurations.
So this module provides the following interfaces:
fn set_policy(request: &SetPolicyEnginePolicyRequest) -> Result<(), String> {};
fn export_policy(request: &ExportPolicyEnginePolicyRequest) -> Result<PolicyEnginePolicy, String> {};
fn set_reference(request: &SetPolicyEngineReferenceRequest) -> Result<(), String> {};
fn export_reference(request: &ExportPolicyEngineReferenceRequest) -> Result<PolicyEngineReference, String> {};
fn test(requets: &TestPolicyEngineRequest) -> Result<TestPolicyEngineResponse, String> {};
As a Service
If the Attestation Service is built as a service, it will provide these functions as GRPC services. So its proto
file should be:
syntax = "proto3";
package managementapi;
message SetPolicyEnginePolicyRequest {
bytes name = 1;
bytes content = 2;
}
message SetPolicyEnginePolicyResponse {
bytes status = 1;
}
message SetPolicyEngineReferenceRequest {
bytes name = 1;
bytes content = 2;
}
message SetPolicyEngineReferenceResponse {
bytes status = 1;
}
message ExportPolicyEnginePolicyRequest {
bytes name = 1;
}
message ExportPolicyEnginePolicyResponse {
bytes status = 1;
bytes content = 2;
}
message ExportPolicyEngineReferenceRequest {
bytes name = 1;
}
message ExportPolicyEngineReferenceResponse {
bytes status = 1;
bytes content = 2;
}
message TestPolicyEngineRequest {
bytes policyname = 1;
bytes policycontent = 2;
bool policylocal = 3;
bytes referencename = 4;
bytes referencecontent = 5;
bool referencelocal = 6;
bytes input = 7;
}
message TestPolicyEngineResponse {
bytes status = 1;
}
service PolicyEngineService {
rpc SetPolicy(SetPolicyEnginePolicyRequest) returns (SetPolicyEnginePolicyResponse) {};
rpc exportPolicy(ExportPolicyEnginePolicyRequest) returns (ExportPolicyEnginePolicyResponse) {};
rpc setReference(SetPolicyEngineReferenceRequest) returns (SetPolicyEngineReferenceResponse) {};
rpc exportReference(ExportPolicyEngineReferenceRequest) returns (ExportPolicyEngineReferenceResponse) {};
rpc Test(TestPolicyEngineRequest) returns (TestPolicyEngineResponse) {};
}
Opens
- Currently the Attestation Service only supports the runtime attestation (TDX/SEV-SNP/SGX), the pre-attestation (SEV(-ES)) is supported by simple-kbs.
Reference