Metadata-Version: 2.4
Name: epsilon-attestation-verifier
Version: 1.0.0
Summary: Standalone tool to verify AWS Nitro Enclave attestation documents from Epsilon
Author: Epsilon Team
License: MIT
Project-URL: Homepage, https://github.com/Epsilon-Data/epsilon-attestation-verifier
Project-URL: Documentation, https://github.com/Epsilon-Data/epsilon-attestation-verifier#readme
Project-URL: Repository, https://github.com/Epsilon-Data/epsilon-attestation-verifier
Project-URL: Issues, https://github.com/Epsilon-Data/epsilon-attestation-verifier/issues
Keywords: aws,nitro,enclave,attestation,tee,verification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Security :: Cryptography
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cbor2>=5.4.0
Requires-Dist: cryptography>=3.4.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Dynamic: license-file

# Epsilon Attestation Verifier

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/Epsilon-Data/epsilon-attestation-verifier)](https://github.com/Epsilon-Data/epsilon-attestation-verifier/releases/latest)
[![Tests](https://github.com/Epsilon-Data/epsilon-attestation-verifier/actions/workflows/tests.yml/badge.svg)](https://github.com/Epsilon-Data/epsilon-attestation-verifier/actions/workflows/tests.yml)

Standalone tool to verify AWS Nitro Enclave attestation documents from Epsilon. **No AWS account or Nitro hardware required** - runs on any machine.

## What This Verifies

1. **AWS Signature** - Document is signed by genuine AWS Nitro hardware
2. **Certificate Chain** - Valid chain to AWS Nitro root certificate
3. **PCR Values** - Enclave ran the expected code (image hash)
4. **Output Integrity** - Output hash matches the actual output
5. **Timestamp** - When the execution occurred

## Installation

```bash
pip install epsilon-attestation-verifier
```

Or from source:

```bash
git clone https://github.com/Epsilon-Data/epsilon-attestation-verifier.git
cd epsilon-attestation-verifier
pip install -e .
```

## Quick Start

### Python API

```python
from epsilon_verifier import verify_attestation

result = verify_attestation(
    attestation_doc="<base64 attestation from Epsilon>",
    expected_output="Hello, World!",  # The output you received
    expected_pcr0="abc123..."          # Optional: verify specific enclave version
)

if result.valid:
    print("Attestation verified!")
    print(f"  PCR0: {result.pcr0}")
    print(f"  Output hash matches: {result.output_verified}")
    print(f"  Signed by AWS: {result.aws_signature_valid}")
else:
    print(f"Verification failed: {result.error}")
```

### CLI

```bash
# Verify an attestation file
epsilon-verify verify attestation.json --output output.txt

# Verify with expected PCR0
epsilon-verify verify attestation.json --pcr0 abc123...

# Verify with known Epsilon version
epsilon-verify verify attestation.json --version 1.0.0

# Output as JSON
epsilon-verify verify attestation.json --json

# Extract PCR values without full verification
epsilon-verify extract attestation.json

# List known enclave versions
epsilon-verify list-versions
```

### From Epsilon Job Response

```python
import json
from epsilon_verifier import verify_attestation

# Parse Epsilon job response
job_response = json.loads(response_data)

result = verify_attestation(
    attestation_doc=job_response['attestation']['attestation']['attestation_document'],
    expected_output=job_response['output'],
    expected_pcr0=PUBLISHED_PCR0  # From Epsilon's published values
)
```

## Verification Flow

```mermaid
flowchart TD
    A[Base64 attestation document] --> B[Parse COSE_Sign1 structure]
    B --> C{Validate fields\nmodule_id, digest, pcrs, etc.}
    C -->|Invalid| X[VERIFICATION FAILED]
    C -->|Valid| D{Verify certificate chain\nagainst AWS Nitro root cert}
    D -->|Fail| X
    D -->|Pass| E{Verify COSE signature\nusing leaf certificate}
    E -->|Fail| X
    E -->|Pass| F{Compare PCR values\nwith published hashes}
    F -->|Mismatch| X
    F -->|Match| G{Verify output hash\nSHA256 actual output}
    G -->|Mismatch| X
    G -->|Match| H[VERIFIED]
```

## What's Inside an Attestation

```
Attestation Document (CBOR + COSE_Sign1):
├── module_id      : Enclave instance identifier
├── timestamp      : Unix timestamp (ms)
├── digest         : Hash algorithm (SHA384)
├── pcrs           : Platform Configuration Registers
│   ├── PCR0       : Enclave image hash (48 bytes)
│   ├── PCR1       : Linux kernel + bootstrap
│   └── PCR2       : Application hash
├── certificate    : Enclave certificate (DER)
├── cabundle       : Certificate chain to AWS root
├── user_data      : Custom data (output hash, job_id, etc.)
├── nonce          : Replay protection
└── public_key     : Optional encryption key
```

## Trust Model

**You trust:**
- AWS Nitro Attestation PKI (hardware root of trust)
- Epsilon's published PCR0 value (open source, reproducible build)

**You verify:**
- AWS signature on attestation document
- PCR0 matches published value
- Output hash matches actual output

## Published PCR Values

Get expected PCR values for each Epsilon enclave version:

```python
from epsilon_verifier import get_published_pcrs

pcrs = get_published_pcrs("1.0.0")
print(pcrs.pcr0)  # Compare with attestation
```

Or check: [pcr-registry.json](https://github.com/Epsilon-Data/epsilon-enclave/blob/main/published/pcr-registry.json)

## AWS Nitro Root Certificate

The verifier automatically downloads and caches the AWS Nitro root certificate from:

```
https://aws-nitro-enclaves.amazonaws.com/AWS_NitroEnclaves_Root-G1.zip
```

The certificate fingerprint is verified against the known SHA256 hash before use.

To manually specify:

```python
result = verify_attestation(
    attestation_doc="...",
    aws_root_cert_path="/path/to/aws_root.pem"
)
```

## Architecture

```
src/epsilon_verifier/
├── __init__.py          # Public API exports
├── verifier.py          # Core verification engine (COSE, X.509, PCR)
├── cli.py               # Command-line interface
├── exceptions.py        # Custom exception hierarchy
├── aws_root_cert.py     # AWS root certificate download & caching
└── pcr_registry.py      # PCR value registry (built-in + GitHub fetch)
```

## Versioning

This project uses [release-please](https://github.com/googleapis/release-please) for automated versioning and changelog generation:

1. PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/) (enforced by CI)
2. PRs are squash-merged into `main`
3. `release-please` opens a release PR that bumps the version and updates `CHANGELOG.md`
4. Merging the release PR creates a GitHub Release

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, and PR process.

## Security

See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.

## License

[MIT](LICENSE)
