attestation-service

Attestation Service

The Attestation Service (AS or CoCo-AS) verifies hardware evidence. The AS was designed to be used with the KBS for Confidential Containers, but it can be used in a wide variety of situations. The AS can be used anytime TEE evidence needs to be validated.

Today, the AS can validate evidence from the following TEEs:

• Intel TDX
• Intel SGX
• AMD SEV-SNP
• ARM CCA
• Hygon CSV
• Intel TDX with vTPM on Azure
• AMD SEV-SNP with vTPM on Azure
• IBM Secure Execution (SE): Attestation Service with IBM SE
• NVIDIA

Overview

                                      ┌───────────────────────┐
┌───────────────────────┐ Evidence    │  Attestation Service  │
│                       ├────────────►│                       │
│ Verification Demander │             │ ┌────────┐ ┌──────────┴───────┐
│    (Such as KBS)      │             │ │ Policy │ │ Reference Value  │◄───Reference Value
│                       │◄────────────┤ │ Engine │ │ Provider Service │
└───────────────────────┘ Attestation │ └────────┘ └──────────┬───────┘
                        Results Token │                       │
                                      │ ┌───────────────────┐ │
                                      │ │  Verifier Drivers │ │
                                      │ └───────────────────┘ │
                                      │                       │
                                      └───────────────────────┘

The AS has a simple API. It receives attestation evidence and returns an attestation token containing the results of a two-step verification process. The AS can be consumed directly as a Rust crate (library) or built as a standalone service, exposing a REST or gRPC API. In Confidential Containers, the client of the AS is the KBS, but the evidence originates from the Attestation Agent inside the guest.

The AS has a two-step verification process.

1. Verify the format and provenance of evidence itself (i.e. check the signature of the evidence). This is done by verifier drivers.
2. Evaluate the claims presented by the evidence (i.e. check that measurements are what the client expects). This is done by policy engine and RVPS.

The first step is accomplished by one of the platform-specific Verifier Drivers. The second step is driven by the Policy Engine with help from the RVPS.

Quick Start

Please refer to

• Restful CoCo AS
• gRPC CoCo AS

Advanced Topics

Advanced topics for developers.

Library

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/trustee" }

Evidence format:

The attestation request must include attestation evidence. The format of the attestation evidence depends on the platform and the implementation of the verifier.

Please refer to the individual verifiers for the specific format of the evidence.

• Intel TDX: TdxEvidence
• Intel SGX: SgxEvidence
• AMD SNP: SnpEvidence
• Azure SNP vTPM: Evidence
• Azure TDX vTPM: Evidence
• Arm CCA: CcaEvidence
• Hygon CSV: CsvEvidence
• IBM Secure Execution (SE): SeEvidence
• NVIDIA: NvDeviceEvidence
• (v)TPM: TpmEvidence

Output

If the verification of TEE evidence does not fail, the AS will return an Attestation Results Token.

Attestation Results token is an EAT Attestation Results (EAR) in JSON Web Token format which contains the parsed evidence claims such as TCB status.

More information about the attestation token is available here.

The claims part of the typical EAR token JWT is here.

Architecture

Verifier Drivers

A verifier driver parses the HW-TEE specific attestation evidence, and performs the following tasks:

1. Verify HW-TEE hardware signature of the TEE quote/report in the evidence.

2. Resolve the 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.
• tdx: Verifier Driver for Intel Trust Domain Extention (Intel TDX).
• snp: Verifier Driver for AMD Secure Encrypted Virtualization-Secure Nested Paging (AMD SNP).
• sgx: Verifier Driver for Intel Software Guard Extensions (Intel SGX).
• az-snp-vtpm: Verifier Driver for Azure vTPM based on SNP (Azure SNP vTPM)
• cca: Verifier Driver for Confidential Compute Architecture (Arm CCA).
• csv: Verifier Driver for China Security Virtualization (Hygon CSV).
• hygon-dcu: Verifier Driver for Hygon Deep Computing Unit (DCU).
• se: Verifier Driver for IBM Secure Execution (SE).
• nvidia: Verifier Driver for NVIDIA Devices.
• tpm: Verifier Driver for Trusted Platform Module (TPM)

Warning

TPM Device Note: TPM devices (except Azure vTPM series) are not bound to TEE endorsement. When using TPM as a standalone attestation device (not integrated with Azure vTPM), you must ensure that you trust the TPM itself, as there is no cryptographic binding between the TPM and the underlying TEE hardware. This feature is mostly for development purposes.

Architecture-Specific Verifier Configurations

The AS supports a different set of verifier drivers based on the target architecture:

• x86_64: All verifier drivers are included via all-verifier
• aarch64: cca is included
• s390x: snp, nvidia and se are included

Policy Engine

OPA is a flexible policy engine. The AS allows users to define and upload their own OPA policy when performing evidence verification. The policy_ids field of the attestation request determines which policies are evaluated. The results of the policy evaluation will be reflected in the token.

Note: Please refer to the Policy Language documentation for more information about Rego.

If the policy is not updated, the AS will use the default policy.

Note

Only EAR token is supported, and Simple token is removed. If you were using Simple token earlier, you will need to change the attestation_token_broker part in the configuration file. Besides, original policies for Simple tokens might not work, you can refer to new .rego policies under the directory.

Concrete policy usages please refer to this guide.

Reference Value Provider Service

The Reference Value Provider Service (RVPS) is a module integrated into 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.

The Reference Value Provider Service supports different deployment modes, please refer to the doc for more details.