TLS Certificate Pinning

Relevant source files

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

• README.md
• attestation/attestation.go
• attestation/cert.go
• client/client.go
• examples/verifier/main.go
• wasm/main.go

TLS Certificate Pinning in the Tinfoil Verifier project is a security mechanism that binds hardware-rooted remote attestation to a TLS connection. Instead of relying solely on Traditional Certificate Authorities (CAs), the system verifies that the TLS certificate presented by an enclave-backed service matches the public key fingerprint cryptographically signed by the hardware (AMD SEV-SNP or Intel TDX).

This ensures that the client is communicating with a specific, verified enclave instance and prevents Man-in-the-Middle (MITM) attacks, even if a CA is compromised. The pinning logic is integrated into a secure http.Client that performs attestation transparently and pins the enclave-generated certificate fingerprint for the duration of the session.

Sources: README.md:5-10, README.md:46-50, client/client.go

Architecture and Flow

The pinning process relies on extracting a public key fingerprint from a hardware-signed attestation report and comparing it against the live TLS certificate used during the handshake.

Verification and Pinning Sequence

The following diagram illustrates how the client verifies the enclave and establishes the certificate pin.

Key Components and Logic

Fingerprint Extraction

The system calculates fingerprints using the SHA-256 hash of the ECDSA public key. This fingerprint is the "ground truth" used for pinning.

Component	Function / Field	Description
Key Fingerprint	KeyFP(publicKey *ecdsa.PublicKey)	Computes SHA-256 hash of the PKIX public key.
Cert Fingerprint	CertPubkeyFP(cert *x509.Certificate)	Extracts the public key from an X.509 cert and hashes it.
Connection FP	ConnectionCertFP(c tls.ConnectionState)	Retrieves the peer certificate from a live TLS state and returns the FP.

Sources: attestation/attestation.go:248-273

Verification Logic

The Verify() method in the attestation package handles the core logic of extracting the expected fingerprint from the hardware report.

1. AMD SEV-SNP: The fingerprint is extracted from the ReportData field of the SNP report.
2. Intel TDX: The fingerprint is extracted from the ReportData of the TDX Quote.

The extracted fingerprint is then compared against the live connection:

if verification.TLSPublicKeyFP != tlsPublicKey {
    log.Fatalf("TLS public key fingerprint mismatch: expected %s, got %s", tlsPublicKey, verification.TLSPublicKeyFP)
}

Sources: attestation/tdx.go:266-270, attestation/sev.go:148-152, examples/verifier/main.go:121-124

Enclave Certificate Verification

Beyond simple fingerprint matching, the project supports a more complex verification of enclave TLS certificates that encode data within Subject Alternative Names (SANs).

Certificate SAN Encoding

Enclaves can encode the HPKE public key and the attestation hash into DNS SANs using a specific format:
NN<base32-chunk>.<prefix>.<domain>

Prefix	Content	Description
.hpke.	HPKE Key	Base32 encoded chunks of the HPKE public key.
.hatt.	Attestation Hash	Base32 encoded chunks of the attestation document hash.

Sources: attestation/cert.go:101-110

SAN Decoding Flow

The decoding logic reconstructs the data from multiple SAN entries:

Implementation in WebAssembly (WASM)

The pinning and verification logic is also exposed to browser environments via WebAssembly. The verifyEnclave function in the WASM module provides the certificate fingerprint to the JavaScript environment.

result := map[string]interface{}{
    "tls_public_key":  verification.TLSPublicKeyFP,
    "hpke_public_key": verification.HPKEPublicKey,
    "certificate":     verification.TLSPublicKeyFP, // For compatibility
    "measurement":     string(jsonMeasurement),
}

Sources: wasm/main.go:116-121

Summary

TLS Certificate Pinning in Tinfoil Verifier creates a cryptographically secure link between the hardware identity of an enclave and its network identity. By extracting the public key fingerprint directly from hardware attestation reports and enforcing a match during the TLS handshake, the system eliminates reliance on external trust authorities for enclave communication.

Sources: README.md:5-15, attestation/attestation.go:275-285