Metadata-Version: 2.4
Name: dk-tee-attestation
Version: 0.6.3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Hardware
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Requires-Dist: cryptography>=46.0.0
Requires-Dist: requests>=2.32.0
Summary: TEE attestation library for AMD SEV-SNP and Intel TDX platforms
Keywords: tee,attestation,sev-snp,tdx,confidential-computing,amd,intel
Author: DataKrypto
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://docs.datakrypto.ai
Project-URL: Homepage, https://datakrypto.ai
Project-URL: Repository, https://devops.datakrypto.com/DataKrypto/_git/fhenom_tee_attestation

# 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

```bash
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, **Ubuntu only**)
- Rust toolchain (via maturin's automatic download)

> **Note:** Intel TDX quote generation requires **Ubuntu**.

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

### Docker

```dockerfile
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 | Ubuntu Linux | Other Linux | Windows |
|---|---|---|---|
| AMD SEV-SNP report generation | Yes (requires `/dev/sev-guest`) | Yes (requires `/dev/sev-guest`) | No |
| AMD SEV-SNP report verification | Yes | Yes | Yes |
| Intel TDX quote generation | Yes (requires `/dev/tdx_guest` + `libtdx_attest.so`) | No (Ubuntu required for `libtdx-attest`) | No |
| Intel TDX quote verification | Yes | 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)

```python
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:

```python
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)

```python
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_type() -> str`

Return the engine type identifier for this engine instance.

**Returns**
- `str`: The `AttestationEngineType` value (e.g. `"intel_tdx"` or `"amd_sev_snp"`).

**Example**
```python
engine = AttestationEngineFactory.get()
print(engine.get_type())  # "intel_tdx" or "amd_sev_snp"
```

---

### `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:

```python
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](https://pypi.org/project/fhenomai/):

```bash
# 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, engine_type)
```

## 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

