Working with attestation reports¶

When a workflow is triggered with attestation reporting requested, OPAQUE generates cryptographic proof in the form of a token that the workflow executed inside a trusted, hardware-protected environment. The OPAQUE SDK automatically retrieves this proof—called an attestation report—and validates it to confirm that the environment, binaries, and request data all match trusted measurements.

Each attestation run generates two outputs that you can later verify or archive for audit:

• An attestation token (.jwt), the signed proof of secure execution issued by the trusted environment.
• An appraisal log (.log), the record of how the SDK verified that token.

This guide shows how to verify, re-appraise, and enforce policy on attestation artifacts created when a workflow author enables attestation in OPAQUE.

What you’ll work with¶

When a workflow is triggered with attestation reporting requested, the SDK saves the generated artifacts to the paths defined in the submission parameters (report_path and appraisal_path).

As a developer, you’ll typically access:

• .jwt tokens: Signed files representing the environment’s security claims.
• .log files: Detailed results of how the SDK appraised those reports.
• Optional endorsement data: Context from the original workflow request—such as the nonce, workflow ID, or portions of the request and response bodies—that can be provided to the SDK during appraisal to more tightly bind the attestation result to a specific execution.

These files form the cryptographic evidence of secure execution and can be used later for independent verification, audit, or compliance review.

Checking a saved report¶

You can verify a saved attestation report at any time using the OPAQUE SDK.

Under the hood, this process (called appraisal) evaluates one or more attestation results issued by trusted verifiers, checking that they collectively vouch for a trustworthy execution environment and still match expected platform measurements.

You can independently verify a saved attestation report at any time using the OPAQUE SDK:

from opaque.attestation.authority.appraiser import AttestationAuthorityAppraiser

# Example path to a saved attestation report (generated when attestation reporting was requested)
report_file = "/path/to/report/2025-10-07_20-31-04-UTC-report.jwt"

# Read the report into memory
with open(report_file, "rb") as f:
    report_bytes = f.read()

# Create an appraiser with default validation policies for supported runtimes
appraiser = AttestationAuthorityAppraiser.from_runtimes()

# Appraise the report
# If no endorsement data (nonce, workflow ID, request/response) available, pass an empty list
appraisal = appraiser.appraise(report_bytes, [])

# Print the appraisal result
print(appraisal)

This example assumes no endorsement data (nonce, workflow ID, request body, or response body) is available. If you have some of these items, you can pass them as a partial dictionary to appraise() in any order to strengthen verification.

All attestation reports include an expiry timestamp. If a report has expired but you still need to verify its contents, you can disable expiry checks while keeping all other validations intact:

# Create an appraiser that skips expiry checks but performs all other checks
appraiser = AttestationAuthorityAppraiser.from_runtimes(verify_exp=False)

A successful appraisal confirms that the report originated from a valid trusted execution environment and that its claims still match expected platform measurements.

Configuring a specific appraiser¶

If your appraisal requirements are stricter than the defaults, you can configure a specific appraiser to enforce tighter policies. For example, you might require that a workflow be verified as having run on an OPAQUE trusted computing base (O-TCB) node with a confidential GPU (cGPU) attached.

from opaque.attestation.authority.appraiser import AttestationAuthorityAppraiser
from opaque.attestation.azure.aas.otcb import OTCBAppraiser
from opaque.attestation.runtimes import Runtime
from opaque.workflow import WorkflowService

# Create an appraiser for O-TCB environments that require a confidential GPU
innerAppraiser = OTCBAppraiser(cgpu=True)

# Create an attestation authority appraiser that uses this specific inner appraiser
appraiser = AttestationAuthorityAppraiser.from_appraisers(
    {Runtime.AZURE_OAS_OPAQUE_CVM_CGPU: innerAppraiser}
)

# Create a workflow client using a given UUID and attach the configured appraiser
workflow_service = WorkflowService(
    workflow_uuid=uuid.UUID(WORKFLOW_SERVICE_UUID), appraiser=appraiser
)

With this setup, any appraisal (or workflow submission that uses this appraiser) will fail if the report doesn’t meet the defined runtime criteria. This is especially useful for regulated workloads or when your organization enforces environment-specific attestation policies.

Interpreting results¶

The attestation token (.jwt) contains the cryptographic proof of how and where the workflow executed. The appraisal log (.log) does not provide additional proof; it is a human-readable record of the checks the SDK performed while appraising the token.

The following examples show what to look for in attestation tokens if you review them manually.

AKS clusters with confidential node pools¶

For workflows running on Azure Kubernetes Service (AKS) with confidential node pools, the attestation token (.jwt) provides evidence that the workflow executed on trusted AMD SEV-SNP hardware using verified, unmodified Azure images. The token records the claims that Azure Attestation Service (AAS) verified as part of the confidential VM’s trust chain.

When you review an JWT token issued for AKS, look for claims that confirm the following:

• The workflow ran on AMD SEV-SNP–backed confidential nodes verified by the Azure Attestation Service (AAS).
• The execution environment met Azure’s confidential VM compliance requirements, including unmodified OS and Kubernetes builds and enforced memory encryption and isolation.
• The request and response were both processed within this trusted environment, and the proof was generated for this specific request

The following table shows some examples of the claims you’ll see in the token and what they represent. In particular, the x-ms-compliance-status claim is Azure Attestation Service’s assertion that the confidential VM meets all required security properties for confidential execution.

If any claim fails verification, the SDK raises a SecurityError and marks the report as unverified.

OPAQUE trusted computing base (O-TCB)¶

For workflows running on the OPAQUE trusted computing base (O-TCB), the token shows evidence that the workflow executed inside an OPAQUE-provisioned confidential virtual machine built on Azure SEV-SNP hardware. These reports include additional OPAQUE-specific verification steps that confirm the integrity of both the environment and the software stack.

When you review an O-TCB token, look for claims that confirm the following:

• The environment used a verified OPAQUE image and an immutable, OPAQUE-provided OS and Kubernetes distribution, as confirmed by OPAQUE’s attestation service.
• Memory encryption was enforced, and isolation was maintained during execution.
• All binaries matched OPAQUE-signed builds.
• If a confidential GPU (cGPU) was attached, it passed attestation through NVIDIA’s Remote Attestation Service (NRAS).
• The request and response were verified as bound to the same secure execution instance inside the trusted environment

The following table shows examples of the claims you’ll see in the appraisal log and what they represent.

If any of these claims fail appraisal or don’t match expected measurements, the SDK marks the report as unverified and raises a SecurityError.

Next steps¶

Attestation artifacts are your proof of secure workflow execution. Archive the attestation token (.jwt) as part of your audit trail so it can be independently re-appraised during future reviews or compliance checks.

Appraisal logs (.log) are optional and can be regenerated at any time by re-appraising the token using the SDK. You may choose to keep them for convenience or troubleshooting, but they are not required for verification.