dk-tee-attestation 0.6.0

TEE attestation library for AMD SEV-SNP and Intel TDX platforms

FHEnom TEE Attestation Library

A Python library for generating and verifying TEE (Trusted Execution Environment) attestation reports across different hardware platforms.

Features

• Multi-Platform Support: Intel TDX and AMD SEV-SNP
• Unified API: Single interface for all TEE platforms
• Cryptographic Verification: Full certificate chain validation
• Automatic Dependency Management: System build dependencies are installed automatically when building from source
• Production Ready: Used in FHEnom AI confidential computing platform

Supported Platforms

• Intel TDX (Trust Domain Extensions)
• AMD SEV-SNP (Secure Encrypted Virtualization - Secure Nested Paging)

Installation

pip install dk-tee-attestation

A virtual environment is recommended because Ubuntu 23.04+ and other modern distributions block system-wide pip installs (PEP 668).

On Linux pre-built wheel is available but if you need to rebuild for your Python version, the custom build backend automatically handles it and installs:

• Build tools: build-essential, python3-dev, pkg-config
• Intel TDX libraries: libtdx-attest, libtdx-attest-dev (via Intel SGX APT repository)
• Rust toolchain (via maturin's automatic download)

On Windows pre-built wheel is available, but if building from source, Visual Studio Build Tools and Rust are required.

Docker

ENV PIP_BREAK_SYSTEM_PACKAGES=1
RUN pip3 install dk-tee-attestation

In Docker containers there is no risk of breaking system packages, so PIP_BREAK_SYSTEM_PACKAGES=1 is safe and avoids the need for a virtual environment.

What works where

Capability	Linux	Windows
AMD SEV-SNP report generation	Yes (requires /dev/sev-guest)	No
AMD SEV-SNP report verification	Yes	Yes
Intel TDX quote generation	Yes (requires /dev/tdx_guest + libtdx_attest.so)	No
Intel TDX quote verification	Yes	Yes

Report generation requires running inside the corresponding TEE hardware. Verification is pure Python and works on any machine with network access.

Quick Start

Generate an Attestation Report (Inside TEE)

from dk_tee_attestation import AttestationEngineFactory, TeeNotDetectedError

# Auto-detect the TEE platform (recommended)
try:
    engine = AttestationEngineFactory.get()
except TeeNotDetectedError:
    raise RuntimeError("No supported TEE platform detected on this machine.")

# Generate report with nonce (must be 64 bytes)
nonce = b"your_nonce_here" + b"\x00" * (64 - len(b"your_nonce_here"))
report_bytes = engine.get_report(nonce)

# Save for verification
with open("attestation_report.bin", "wb") as f:
    f.write(report_bytes)

To explicitly select a platform instead of auto-detecting:

from dk_tee_attestation import AttestationEngineFactory, AttestationEngineType

engine = AttestationEngineFactory.get(AttestationEngineType.INTEL_TDX)
# or
engine = AttestationEngineFactory.get(AttestationEngineType.AMD_SEV_SNP)

Verify an Attestation Report (Verifier Side)

from dk_tee_attestation import AttestationEngineFactory, AttestationEngineType

# Create engine for the platform that generated the report
engine = AttestationEngineFactory.get(AttestationEngineType.INTEL_TDX)

# Load report
with open("attestation_report.bin", "rb") as f:
    report_bytes = f.read()

# Verify (raises exception on failure)
nonce = b"your_nonce_here" + b"\x00" * (64 - len(b"your_nonce_here"))
try:
    engine.verify_report(report_bytes, nonce)
    print("Attestation verified successfully!")
except Exception as e:
    print(f"Verification failed: {e}")

API Reference

AttestationEngineFactory

Factory for instantiating attestation engine implementations.

AttestationEngineFactory.get(engine_type=None) -> AttestationEngine

Instantiate and return an attestation engine.

Parameters

• engine_type (AttestationEngineType, optional): Platform selector. If omitted, the TEE platform is auto-detected by probing available firmware interfaces.

Returns

• An AttestationEngine instance for the detected or requested platform.

Raises

• TeeNotDetectedError: If auto-detection is used and no supported TEE platform is found.
• UnsupportedEngine: If an explicit engine_type is provided but not registered.

---

AttestationEngine

Base interface for TEE attestation engines.

get_report(report_data: bytes) -> bytes

Generate a TEE attestation report.

Parameters

• report_data (bytes): Nonce / challenge. Must be exactly 64 bytes.

Returns

• bytes: Raw attestation report.

Raises

• AttestationError: If report generation fails.
• TeeNotDetectedError: If AttestationEngineFactory.get() is called with no argument and no supported TEE platform is found.

---

verify_report(report_bytes: bytes, expected_report_data: bytes) -> None

Verify a TEE attestation report.

Parameters

• report_bytes (bytes): Raw attestation report to verify.
• expected_report_data (bytes): Expected nonce. Must be exactly 64 bytes.

Returns

• None: Verification succeeded.

Raises

• AttestationError: If verification fails.

Exception Hierarchy

All exceptions inherit from AttestationError, so you can catch it broadly or handle specific cases:

from dk_tee_attestation import AttestationError

try:
    engine.verify_report(report_bytes, nonce)
except AttestationError as e:
    print(f"Verification failed: {e}")

Key exception types:

• TeeNotDetectedError: No supported TEE platform found during auto-detection
• UnsupportedEngine: Explicit engine type is not registered
• ReportDataError: Nonce mismatch or invalid report data
• SignatureError: Report signature verification failed
• CertChainError: Certificate chain validation failed
• KdsFetchError: Failed to fetch certificates from AMD KDS or Intel PCS
• MetadataMismatchError: TCB or hardware ID mismatch
• FirmwareOpenErrorAmdSevSnp: Cannot open /dev/sev-guest
• FirmwareOpenErrorIntelTdx: Cannot open /dev/tdx_guest or libtdx_attest.so unavailable

Verification Process

Intel TDX Verification Steps

1. Parse Quote: Extract structured data from TDX Quote v4 bytes
2. Validate Nonce: Ensure report_data matches expected value
3. Verify PCK Chain: Validate the embedded PCK certificate chain up to Intel Root CA
4. Fetch TCB Info: Retrieve and verify TCB Info from Intel PCS
5. Check TCB Status: Ensure platform TCB is not revoked or out of date
6. Fetch QE Identity: Retrieve and verify QE Identity from Intel PCS
7. Verify QE Report: Validate PCK signature over the Quoting Enclave report
8. Verify Quote Signature: Validate attestation key signature over the TD Report Body

AMD SEV-SNP Verification Steps

1. Parse Report: Extract structured data from raw bytes
2. Validate Nonce: Ensure nonce matches expected value
3. Fetch Certificates: Retrieve ARK, ASK, and VCEK from AMD KDS
4. Verify Chain: Validate certificate chain signatures
5. Check Metadata: Ensure TCB and hardware ID match
6. Verify Signature: Validate report signature with VCEK

Platform-Specific Notes

Intel TDX

• Requires access to /dev/tdx_guest device and libtdx_attest.so for quote generation
• Fetches TCB Info and QE Identity from Intel Provisioning Certification Service (PCS)
• Verification is pure Python and works on any machine with network access

AMD SEV-SNP

• Requires access to /dev/sev-guest device for report generation
• Fetches certificates from AMD Key Distribution Service (KDS)
• Supports Milan, Genoa, and Turin processor families

Integration with FHEnom AI

This library is integrated into the FHEnom AI SDK:

# Install FHEnom AI with attestation support
pip install fhenomai

# Use via FHEnom AI client
from fhenomai import FHEnomClient

client = FHEnomClient.from_config()
result = client.admin.verify_attestation(report_bytes, nonce_hex)

Requirements

• Python >= 3.8
• cryptography >= 46.0.0
• requests >= 2.32.0

Use Cases

• Remote Attestation: Prove code runs in genuine TEE
• Zero-Trust Security: Establish trust before sensitive operations
• Compliance: Demonstrate hardware-backed security
• Confidential Computing: Verify encrypted model execution

License

TBD