Example Implementations

Relevant source files

The following files were used as context for generating this wiki page:

• examples/client/main.go
• examples/verifier/main.go
• client/integration_test.go
• wasm/index.html
• wasm/main.go
• README.md

The Tinfoil Verifier project provides multiple reference implementations demonstrating how to integrate hardware-rooted remote attestation into various application environments. These examples cover high-level automated clients, manual verification CLI tools, browser-based WASM integrations, and integration testing frameworks.

The primary goal of these implementations is to showcase the binding of hardware integrity (AMD SEV-SNP or Intel TDX) to TLS connections, ensuring that requests are only processed by verified, unmodified enclaves.

Sources: README.md:5-15, examples/client/main.go:1-12

Secure HTTP Client Integration

The high-level client package implementation demonstrates a "drop-in" replacement for standard HTTP operations. It abstracts the complexity of fetching attestation documents and verifying measurements behind a simplified API.

Workflow

1. Initialization: A NewSecureClient or NewDefaultClient is instantiated with the target enclave hostname and the expected GitHub repository for code provenance.
2. Transparent Attestation: The first HTTP request (e.g., Post or Get) triggers an automatic attestation gate.
3. TLS Pinning: Upon successful verification, the enclave-generated certificate fingerprint is pinned for the duration of the session to prevent Man-in-the-Middle (MITM) attacks.

The diagram shows the logic flow where attestation occurs automatically before the first network request is fulfilled.
Sources: README.md:27-55, examples/client/main.go:13-35

Implementation Details

Feature	Implementation Component	Description
Client Creation	client.NewDefaultClient()	Creates a client using default configuration for predefined enclaves.
Secure Requests	tinfoilClient.Post(path, headers, body)	Performs an HTTP POST where attestation happens transparently.
Manual Exposure	tinfoilClient.Verify()	Manually triggers verification to access TLSPublicKey and HPKEPublicKey.

Sources: README.md:43-60, examples/client/main.go:13-20

Manual Verifier CLI

The examples/verifier implementation provides a more granular approach, allowing developers to manually inspect every step of the verification process, including hardware measurements and Sigstore code provenance.

Component Interaction

This implementation uses concurrent goroutines to fetch data from disparate sources:

• Sigstore/GitHub: Fetches the latest release digest and Sigstore attestation bundle for the specified repository.
• Enclave Runtime: Fetches the live attestation document (AMD SEV-SNP or Intel TDX) from the enclave's /.well-known/tinfoil-attestation endpoint.

The sequence diagram illustrates the parallel fetching of "Ground Truth" (from Sigstore) and "Runtime State" (from the enclave) for comparison.
Sources: examples/verifier/main.go:42-100, README.md:120-130

Comparison Logic

The CLI performs an explicit check between the measurements provided by the source (Sigstore) and the actual registers reported by the hardware.

• Measurement Equality: Uses codeMeasurements.EqualsDisplay(verification.Measurement) to show differences in registers like MRTD or RTMR.
• Hardware Verification: For Intel TDX, it specifically validates the hardware TCB (Trusted Computing Base) using sigstoreClient.LatestHardwareMeasurements().

Sources: examples/verifier/main.go:115-145, attestation/attestation.go:94-150

WebAssembly (WASM) Implementation

The project includes a WASM build that allows the Go-based verification logic to run natively in browser environments. This is implemented through a Go-to-JavaScript bridge using syscall/js.

WASM Bridge Functions

The wasm/main.go file exports several global functions to the JavaScript environment:

Function	Purpose
verify(enclave, repo)	The primary entry point for end-to-end verification in the browser.
verifyEnclave(hostname)	Specifically fetches and verifies the hardware attestation document.
verifyCode(repo, digest)	Verifies the Sigstore attestation bundle for code provenance.

Sources: wasm/main.go:120-135, wasm/index.html:298-315

Browser Integration Example

The HTML implementation utilizes a Go runtime wrapper (wasm_exec.js) to load the verifier and provides a UI for users to input enclave hostnames and repositories.

// Example of browser-side invocation
const result = await window.verify(enclave, repo);
const groundTruth = JSON.parse(result);
console.log("TLS Cert Fingerprint:", groundTruth.tls_public_key);

Sources: wasm/index.html:310-330, README.md:165-185

Integration Testing Reference

The client/integration_test.go file serves as a reference for programmatic verification within CI/CD pipelines. It demonstrates how to use environment variables to configure sensitive parameters like API keys and enclave addresses.

Key Test Pattern

func TestBasicChatCompletion(t *testing.T) {
    enclave, repo, apiKey := skipIfMissingEnvVars(t)
    client := NewSecureClient(enclave, repo)
    
    // The request body is typical for OpenAI-compatible APIs
    request := ChatCompletionRequest{
        Model: "gpt-oss-120b-free",
        Messages: []Message{{Role: "user", Content: "Hi"}},
    }
    
    headers := map[string]string{"Authorization": "Bearer " + apiKey}
    resp, err := client.Post("/v1/chat/completions", headers, requestBody)
    // ... validation logic
}

Sources: client/integration_test.go:57-85

Summary of Implementation Tools

The following table summarizes the different ways to execute the verifier as shown in the examples:

Method	Component	Target Audience	Primary Use Case
Go Library	client package	Backend Developers	Secure service-to-service communication.
CLI Tool	examples/verifier	Security Auditors	Manual inspection of enclave integrity.
Web UI	wasm/index.html	End Users	Client-side verification in a browser.
Automated Tests	integration_test.go	DevOps/SRE	Verifying deployments in CI/CD.

Sources: README.md:20-80, wasm/index.html:10-50

The provided examples demonstrate that the Tinfoil Verifier can be integrated at multiple levels of the stack, from low-level hardware register auditing to high-level transparent HTTP clients, ensuring that enclave-backed services maintain a verifiable chain of trust.