teepot/crates/intel-dcap-api/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This crate (intel-dcap-api) is a Rust client library for Intel's Data Center Attestation Primitives (DCAP) API. It provides access to Intel's Trusted Services API for SGX and TDX attestation, including TCB info, PCK certificates, CRLs, and enclave identity verification.

Features

• Support for both API v3 and v4
• Async/await API using tokio
• Comprehensive error handling with Intel-specific error codes
• Type-safe request/response structures
• Support for SGX and TDX platforms
• Real data integration tests

Development Commands

# Build
cargo build
cargo build --no-default-features --features rustls  # Use rustls instead of default TLS

# Test
cargo test

# Lint
cargo clippy

# Examples
cargo run --example example            # Basic usage example
cargo run --example get_pck_crl       # Fetch certificate revocation lists
cargo run --example common_usage      # Common attestation verification patterns
cargo run --example integration_test  # Comprehensive test of most API endpoints
cargo run --example fetch_test_data   # Fetch real data from Intel API for tests

Architecture

Client Structure

• ApiClient (src/client/mod.rs): Main entry point supporting API v3/v4
  • Base URL: https://api.trustedservices.intel.com
  • Manages HTTP client and API version selection

Key Modules

• client/: API endpoint implementations
  • tcb_info: SGX/TDX TCB information retrieval
    • get_sgx_tcb_info(), get_tdx_tcb_info()
  • pck_cert: PCK certificate operations
    • get_pck_certificate_by_ppid(), get_pck_certificate_by_manifest()
    • get_pck_certificates_by_ppid(), get_pck_certificates_by_manifest()
    • get_pck_certificates_config_by_ppid(), get_pck_certificates_config_by_manifest()
  • pck_crl: Certificate revocation lists
    • get_pck_crl() - supports PEM and DER encoding
  • enclave_identity: SGX QE/QVE/QAE/TDQE identity
    • get_sgx_qe_identity(), get_sgx_qve_identity(), get_sgx_qae_identity(), get_tdx_qe_identity()
  • fmspc: FMSPC-related operations (V4 only)
    • get_fmspcs() - with optional platform filter
    • get_sgx_tcb_evaluation_data_numbers(), get_tdx_tcb_evaluation_data_numbers()
  • registration: Platform registration
    • register_platform(), add_package()

Core Types

• error.rs: IntelApiError for comprehensive error handling
  • Extracts error details from Error-Code and Error-Message headers
• types.rs: Enums (CaType, ApiVersion, UpdateType, etc.)
• requests.rs: Request structures
• responses.rs: Response structures with JSON and certificate data

API Pattern

All client methods follow this pattern:

1. Build request with query parameters
2. Send HTTP request with proper headers
3. Parse response (JSON + certificate chains)
4. Return typed response or error

Testing Strategy

• Mock Tests: Two test suites using mockito for HTTP mocking
  • tests/mock_api_tests.rs: Basic API functionality tests with simple data (11 tests)
  • tests/real_data_mock_tests.rs: Tests using real Intel API responses (25 tests)
• Test Data: Real responses stored in tests/test_data/ (JSON format)
  • Fetched using cargo run --example fetch_test_data
  • Includes TCB info, CRLs, enclave identities for both SGX and TDX
  • Covers V3 and V4 API variations, different update types, and evaluation data numbers
• Key Testing Considerations:
  • Headers with newlines must be URL-encoded for mockito (use percent_encode with NON_ALPHANUMERIC)
  • V3 vs V4 API use different header names:
    • V3: SGX-TCB-Info-Issuer-Chain
    • V4: TCB-Info-Issuer-Chain
  • Error responses include Error-Code and Error-Message headers
  • Examples use real Intel API endpoints
  • Test data (FMSPC, PPID) from Intel documentation
  • Async tests require tokio runtime

API Version Differences

V4-Only Features

• FMSPC listing (get_fmspcs())
• TCB Evaluation Data Numbers endpoints
• PPID encryption key type parameter
• TDX QE identity endpoint

Common Pitfalls

1. Mockito Header Encoding: Always URL-encode headers containing newlines/special characters
2. API Version Selection: Some endpoints are V4-only and will return errors on V3
3. Platform Filters: Only certain values are valid (All, Client, E3, E5)
4. Test Data: PCK certificate endpoints require valid platform data and often need subscription keys
5. Issuer Chain Validation: Always check that issuer_chain is non-empty - it's critical for signature verification

Security Considerations

• Certificate Chain Verification: The issuer_chain field contains the certificates needed to verify the signature of the response data
• Signature Validation: All JSON responses (TCB info, enclave identities) should have their signatures verified using the issuer chain
• CRL Verification: PCK CRLs must be signature-verified before being used for certificate revocation checking
• Empty Issuer Chains: Always validate that issuer chains are present and non-empty before trusting response data