dcap-qvl 0.5.2

Python bindings for DCAP (Data Center Attestation Primitives) quote verification library

Python Bindings for DCAP-QVL

Python bindings for parsing and verifying Intel SGX/TDX DCAP (Data Center Attestation Primitives) quotes. Built on a Rust implementation for use in TEE (Trusted Execution Environment) remote attestation workflows.

Quick Start

# Install from PyPI
pip install dcap-qvl

# Basic usage
python -c "
import dcap_qvl
print('DCAP-QVL Python bindings successfully installed!')
print(f'Available functions: {dcap_qvl.__all__}')
"

Features

• Parse and inspect SGX/TDX quotes (headers, reports, embedded certificates)
• Extract PCK certificate extension fields (FMSPC, PPID, CPU SVN, etc.) or look up arbitrary OIDs
• Verify SGX and TDX quotes against collateral data
• Handle quote collateral data (serialize/deserialize JSON)
• Asynchronous collateral fetching from PCCS/PCS with async/await support
• Pure Rust implementation with Python bindings
• Cross-platform compatibility (Linux, macOS, Windows)
• Compatible with Python 3.8+

Installation

From PyPI (recommended)

pip install dcap-qvl

Using uv

uv add dcap-qvl

Usage

Parsing Quotes

import dcap_qvl

raw = open("quote.bin", "rb").read()
quote = dcap_qvl.parse_quote(raw)

# Quote type
print(quote.quote_type())  # "SGX" or "TDX"
print(quote.fmspc())       # e.g. "B0C06F000000"

# Header fields
hdr = quote.header
print(hdr.version, hdr.tee_type, hdr.attestation_key_type)

# Report body (TdReport10, TdReport15, or SgxEnclaveReport)
report = quote.report
if quote.is_tdx():
    print(report.mr_td.hex())
    print(report.rt_mr0.hex())
else:
    print(report.mr_enclave.hex())
    print(report.mr_signer.hex())
print(report.report_data.hex())

# Embedded PEM certificate chain
pem = quote.cert_chain_pem_bytes()  # bytes or None

PCK Extension Parsing

# From a parsed quote
ext = quote.pck_extension()  # PckExtension or None
if ext:
    print(ext.fmspc.hex())   # 6-byte FMSPC
    print(ext.ppid.hex())    # PPID
    print(ext.cpu_svn.hex()) # CPU SVN
    print(ext.pce_svn)       # PCE SVN (int)
    print(ext.pce_id.hex())  # PCE ID
    print(ext.sgx_type)      # SGX type (int)

# From a PEM certificate chain directly
ext = dcap_qvl.parse_pck_extension_from_pem(pem_bytes)
print(ext.fmspc.hex())

# Look up any OID in the Intel SGX extension (recursive search)
value = ext.get_value("1.2.840.113741.1.13.1.2.17")  # PCESVN
if value is not None:
    print(value.hex())

Basic Quote Verification

import dcap_qvl
import json
import time

# Load quote data (binary)
with open("path/to/quote", "rb") as f:
    quote_data = f.read()

# Load collateral data (JSON)
with open("path/to/collateral.json", "r") as f:
    collateral_json = json.load(f)

# Create collateral object
collateral = dcap_qvl.QuoteCollateralV3.from_json(json.dumps(collateral_json))

# Verify the quote
now = int(time.time())
try:
    result = dcap_qvl.verify(quote_data, collateral, now)
    print(f"Verification successful! Status: {result.status}")
    print(f"Advisory IDs: {result.advisory_ids}")
except ValueError as e:
    print(f"Verification failed: {e}")

Working with Collateral Data

# Create collateral manually
collateral = dcap_qvl.QuoteCollateralV3(
    pck_crl_issuer_chain="...",
    root_ca_crl=b"...",  # bytes
    pck_crl=b"...",      # bytes
    tcb_info_issuer_chain="...",
    tcb_info="...",      # JSON string
    tcb_info_signature=b"...",  # bytes
    qe_identity_issuer_chain="...",
    qe_identity="...",   # JSON string
    qe_identity_signature=b"...",  # bytes
)

# Serialize to JSON
json_str = collateral.to_json()

# Deserialize from JSON
collateral = dcap_qvl.QuoteCollateralV3.from_json(json_str)

API Reference

Async Collateral Functions

All collateral functions are asynchronous and must be awaited. They use the Rust async runtime for optimal performance.

async get_collateral(pccs_url: str, raw_quote: bytes) -> QuoteCollateralV3

Fetch full collateral (PCK cert chain, TCB info, QE identity, CRLs) for a raw DCAP quote from the given PCCS / PCS URL. Handles every supported certification data type (including cert_type 2 / 3 where the PCK cert is retrieved from PCCS via encrypted PPID).

Parameters:

• pccs_url: PCCS URL (e.g., "https://api.trustedservices.intel.com")
• raw_quote: Raw quote data as bytes

Returns:

• QuoteCollateralV3: Quote collateral data (with PCK certificate chain attached)

Raises:

• ValueError: If the quote is invalid, the HTTP client can't be built, or the PCCS / PCS fetch fails

Example:

import asyncio
import dcap_qvl

async def main():
    pccs_url = "https://api.trustedservices.intel.com"
    quote_data = open("quote.bin", "rb").read()
    collateral = await dcap_qvl.get_collateral(pccs_url, quote_data)
    print(f"Got collateral: {len(collateral.tcb_info)} chars")

asyncio.run(main())

async get_collateral_from_pcs(raw_quote: bytes) -> QuoteCollateralV3

Get collateral from Intel's PCS (default).

Parameters:

• raw_quote: Raw quote data as bytes

Returns:

• QuoteCollateralV3: Quote collateral data

Raises:

• ValueError: If quote is invalid or FMSPC cannot be extracted
• RuntimeError: If network request fails

Example:

import asyncio
import dcap_qvl

async def main():
    quote_data = open("quote.bin", "rb").read()
    collateral = await dcap_qvl.get_collateral_from_pcs(quote_data)
    print(f"Got collateral from Intel PCS")

asyncio.run(main())

async get_collateral_and_verify(raw_quote: bytes, pccs_url: Optional[str] = None) -> VerifiedReport

Get collateral and verify quote in one step.

Parameters:

• raw_quote: Raw quote data as bytes
• pccs_url: Optional PCCS URL (uses Intel PCS if None)

Returns:

• VerifiedReport: Verification results

Raises:

• ValueError: If quote is invalid or verification fails
• RuntimeError: If network request fails

Example:

import asyncio
import dcap_qvl

async def main():
    quote_data = open("quote.bin", "rb").read()
    result = await dcap_qvl.get_collateral_and_verify(quote_data)
    print(f"Status: {result.status}")
    print(f"Advisory IDs: {result.advisory_ids}")

asyncio.run(main())

Classes

QuoteCollateralV3

Represents quote collateral data required for verification.

Constructor:

QuoteCollateralV3(
    pck_crl_issuer_chain: str,
    root_ca_crl: bytes,
    pck_crl: bytes,
    tcb_info_issuer_chain: str,
    tcb_info: str,
    tcb_info_signature: bytes,
    qe_identity_issuer_chain: str,
    qe_identity: str,
    qe_identity_signature: bytes,
)

Methods:

• to_json() -> str: Serialize to JSON string
• from_json(json_str: str) -> QuoteCollateralV3: Create from JSON string (static method)

Properties:

• pck_crl_issuer_chain: str
• root_ca_crl: bytes
• pck_crl: bytes
• tcb_info_issuer_chain: str
• tcb_info: str
• tcb_info_signature: bytes
• qe_identity_issuer_chain: str
• qe_identity: str
• qe_identity_signature: bytes

VerifiedReport

Contains the results of quote verification.

Properties:

• status: str: Verification status (e.g., "OK", "SW_HARDENING_NEEDED", "CONFIGURATION_NEEDED", "OUT_OF_DATE", "REVOKED")
• advisory_ids: List[str]: List of Intel security advisory IDs (e.g., "INTEL-SA-00334")
• ppid: bytes: Platform PPID parsed from the PCK certificate

Methods:

• to_json() -> str: Serialize to JSON string

Quote

Represents a parsed SGX or TDX quote. Created via parse_quote() or Quote.parse().

Properties:

• header: QuoteHeader: Parsed quote header
• report: Union[TdReport10, TdReport15, SgxEnclaveReport]: Parsed report body

Methods:

• parse(raw_quote: bytes) -> Quote: Parse from raw bytes (static method)
• fmspc() -> str: FMSPC as uppercase hex string
• ca() -> str: Certificate Authority identifier
• is_sgx() -> bool / is_tdx() -> bool: Check quote type
• quote_type() -> str: Returns "SGX" or "TDX"
• cert_chain_pem_bytes() -> Optional[bytes]: Embedded PEM certificate chain
• pck_extension() -> Optional[PckExtension]: Parse Intel SGX extension from leaf PCK cert

QuoteHeader

Properties:

• version: int, attestation_key_type: int, tee_type: int
• qe_svn: int, pce_svn: int
• qe_vendor_id: bytes (16 bytes), user_data: bytes (20 bytes)

TdReport10 / TdReport15

TDX TDREPORT structures. TdReport15 extends TdReport10 with tee_tcb_svn2 and mr_service_td.

Properties (TdReport10):

• tee_tcb_svn: bytes, mr_seam: bytes, mr_signer_seam: bytes, seam_attributes: bytes
• td_attributes: bytes, xfam: bytes, mr_td: bytes, mr_config_id: bytes
• mr_owner: bytes, mr_owner_config: bytes
• rt_mr0: bytes, rt_mr1: bytes, rt_mr2: bytes, rt_mr3: bytes
• report_data: bytes

SgxEnclaveReport

Properties:

• cpu_svn: bytes, attributes: bytes
• mr_enclave: bytes, mr_signer: bytes
• report_data: bytes

PckExtension

Parsed values from the Intel SGX extension in the PCK leaf certificate.

Properties:

• ppid: bytes, cpu_svn: bytes, pce_svn: int, pce_id: bytes
• fmspc: bytes (6 bytes), sgx_type: int
• platform_instance_id: Optional[bytes]

Methods:

• get_value(oid: str) -> Optional[bytes]: Look up any OID in the Intel SGX extension by dotted-decimal string. Returns raw DER value bytes, or None if not found.

Functions

parse_quote(raw_quote: bytes) -> Quote

Parse a raw SGX or TDX quote from bytes.

parse_pck_extension_from_pem(pem_bytes: bytes) -> PckExtension

Parse the Intel SGX extension from a PEM-encoded certificate chain (uses the first/leaf certificate).

verify(raw_quote: bytes, collateral: QuoteCollateralV3, now_secs: int) -> VerifiedReport

Verify a quote with the provided collateral data.

Parameters:

• raw_quote: Raw quote data as bytes
• collateral: Quote collateral data
• now_secs: Current timestamp in seconds since Unix epoch

Returns:

• VerifiedReport: Verification results

Raises:

• ValueError: If verification fails

verify_with_root_ca(raw_quote: bytes, collateral: QuoteCollateralV3, root_ca_der: bytes, now_secs: int) -> VerifiedReport

Verify a quote with a custom root CA certificate (DER format) instead of the built-in Intel root CA.

Development

Building from Source

If you want to build from source or contribute to development:

# Clone the repository
git clone https://github.com/Phala-Network/dcap-qvl.git
cd dcap-qvl/python-bindings

# Install development dependencies (including maturin)
uv sync

# Build and install the Python extension in development mode
uv run maturin develop --features python

# Run tests
uv run pytest tests/ -v

Note: maturin is only required for building from source. Regular users installing from PyPI don't need maturin.

Running Examples

After installing the package, you can run the examples:

# Download the examples from the repository
git clone https://github.com/Phala-Network/dcap-qvl.git
cd dcap-qvl/python-bindings

# Basic functionality test
python examples/basic_test.py

# Full example (requires sample data files)
python examples/python_example.py

Or if you're using uv for development:

# Basic functionality test
uv run python examples/basic_test.py

# Full example (requires sample data files)
uv run python examples/python_example.py

Testing Across Python Versions

The project includes comprehensive testing across all supported Python versions:

# Quick test across all Python versions
make test_python_versions

# Test current Python version only
make test_python

See PYTHON_TESTING.md for detailed information about Python version compatibility testing.

Requirements

For regular usage (installing from PyPI):

• Python 3.8+

For development (building from source):

• Python 3.8+
• Rust toolchain (rustc, cargo)
• maturin (automatically installed with uv sync)

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.