Bitcoin PIR

Attestation

The five privacy invariants talk about the wire shape. Attestation answers a different question: is the server I'm talking to actually running the binary the operator published?

Without attestation, a wallet that's careful about wire-shape leakage is still trusting whoever runs the server not to swap the binary out for a logging one. On a TEE host, attestation closes that gap by binding the WebSocket session to a signed, hardware-attested measurement of the software stack. On a host without one, it pins the binary the server reports and binds the session to the operator's signed identity instead.

The two-server split

The reference deployment uses two servers with different roles:

ServerRoleSEV-SNPWhy
wss://weikeng1.bitcoinpir.orgHintNo (Hetzner)Sees only the hint blob — never query traffic.
wss://bitcoin-pir-weikeng-laptop.chenweikeng.comQueryNo (MacBook)Sees the per-query traffic.

The query server is the one whose binary a wallet really wants to pin. Hint traffic alone reveals nothing about what the user is querying (an attacker who runs only the hint server can't replay queries — the secret-shared sketch lives in the query server's state).

No TEE on the query server since 2026-10-02

The query server used to be a VPSBG AMD SEV-SNP host (Tier 3, below) at wss://weikeng2.bitcoinpir.org. That host was retired on 2026-10-02. The pir2 roles now run on a MacBook without a TEE (server id pir2-macbook-v1), so both live servers are checked the same way: a binary pin plus the operator-signed identity. Direct ORAM needs a TEE: since 2026-10-03 it runs on its own VPSBG SEV-SNP host (AMD Milan) at wss://weikeng2.bitcoinpir.org.

What "Tier 3" means

No live server runs Tier 3 today; this is the shape a TEE host uses (pir2 until 2026-10-02, and Direct ORAM's next host).

Tier 3 is a deployment shape: the entire software stack — kernel, initramfs, command line, server binary — is packed into a single Unified Kernel Image (UKI) that the AMD SEV-SNP firmware measures at boot. AMD's Platform Security Processor signs a report binding:

  • The launch MEASUREMENT (the 48-byte hash of OVMF + UKI bytes).
  • Per-chip identity (VCEK certificate chain rooted at AMD's ARK).
  • A REPORT_DATA field the server uses for session binding.

Compare this to Slice 2 (the recovery mode) — same hardware, but boots a normal rootfs with sshd enabled. Useful for operator recovery, but unsuitable for production because the boot path is not measured.

The full verification flow

Neither live server has a TEE, so a wallet compares each server's binary with its pin and checks each server's operator-signed identity. The checks report; what to do with a mismatch is the wallet's choice:

import {
  gateOperatorIdentity,
  PIR1_PROVIDER,  // pir1: endpoint, PIR1_PIN, operator key
  PIR2_PROVIDER,  // pir2: endpoint, PIR2_MACBOOK_PIN, operator key
} from 'bitcoin-pir-web';
import { pinAcceptsBinary } from 'bitcoin-pir-web/attest-pin';
 
const attest0 = await client.attest(0);  // hint server
const attest1 = await client.attest(1);  // query server
 
// --- Step 1: compare with the operator's published binaries. Both
// servers report `noSevHost`: the hash is self-reported, so it catches
// drift from the published build but no hardware vouches for it. ---
const pinOk = [
  pinAcceptsBinary(PIR1_PROVIDER.serverPin, attest0.binarySha256Hex),
  pinAcceptsBinary(PIR2_PROVIDER.serverPin, attest1.binarySha256Hex),
];
 
// --- Step 2: upgrade to the AEAD-sealed channel ---
await client.upgradeToSecureChannel(
  attest0.serverStaticPub,
  attest1.serverStaticPub,
);
 
// --- Step 3: check the operator-signed identity of each server.
// Without a TEE this is what ties the channel key to the operator. ---
const now = BigInt(Math.floor(Date.now() / 1000));
const identities = [];
for (const [i, p, att] of [[0, PIR1_PROVIDER, attest0], [1, PIR2_PROVIDER, attest1]] as const) {
  const v = await client.announce(i);
  identities.push(gateOperatorIdentity(v, p.operatorPubkey, att.serverStaticPub, now));
  v.free();
}
// `pinOk` and `identities[i].state` ('verified', 'unverified', ...) are
// the verdicts.

The TypeScript adapters run the same checks on connect and report each outcome (attestation, operatorIdentity); they do not refuse to query.

On a TEE host

A server inside an AMD SEV-SNP guest (pir2 until 2026-10-02; the Direct ORAM host since 2026-10-03) adds hardware evidence before the channel upgrade, where pin is that host's ServerAttestPin from attest-pin.ts:

import { AMD_MILAN_ARK_FINGERPRINT } from 'bitcoin-pir-web/attest-pin';
 
if (attest.sevStatus !== 'reportDataMatch') {
  throw new Error(`SEV-SNP report did not bind: ${attest.sevStatus}`);
}
attest.verifyVcekChain(AMD_MILAN_ARK_FINGERPRINT);
// The SEV-SNP report is signed by a real AMD Milan chip whose ARK
// matches the operator's pin (use the ARK of the host's generation).
if (attest.launchMeasurementHex !== pin.measurementHex) {
  throw new Error('Server is running a different MEASUREMENT than expected');
}

What's actually being verified

verifyVcekChain

A one-shot validator that:

  1. Hashes the ARK PEM the server bundled and compares to your pinned fingerprint. (This is the crucial step — without a pinned root, a malicious server could substitute a forged self-signed "ARK" that doesn't actually belong to AMD.)
  2. Confirms ARK self-signs (RSA-PSS-SHA384).
  3. Confirms ARK signs the ASK.
  4. Confirms ASK signs the VCEK.
  5. Confirms the SEV-SNP report's ECDSA-P384-SHA384 signature verifies against the VCEK's pubkey.

On success: the report is cryptographically authentic and your client has cryptographically established that the chip generating it is a real AMD SEV-SNP processor of the pinned generation (Milan for the ORAM host). The adapters also hold every report chained to the Milan ARK to AMD_MILAN_SEV_SNP_FLOOR: a minimum TCB per component, the ALIAS_CHECK_COMPLETE platform bit and mitigation-vector bit 1, so a host on firmware without AMD's published Milan fixes is refused.

launchMeasurementHex

The 48-byte hash AMD's PSP signs into every SEV-SNP report. For Tier 3 it covers OVMF + the loaded UKI bytes — kernel, initramfs, cmdline. Any change to the server binary inside the initramfs flips this value.

A wallet that pins this value detects:

  • A server upgrade the operator made without publishing a new pin.
  • A boot of the recovery (Slice 2) image instead of the Tier 3 UKI.
  • Any binary substitution by anyone with access to the hardware.

binarySha256Hex

The SHA-256 of the running unified_server binary, server-self-reported. For Tier 3, this transitively follows from MEASUREMENT (the binary lives inside the initramfs, which is part of the UKI, which is part of MEASUREMENT). For Slice 2, the binary hash is server-self-reported and the operator publishes it via a separate channel.

The binarySha256Hex is also pinnable independently — the only pin for a host without SEV (both live servers today). While the operator switches such a host to a new build, its pin also carries the running build as transitionBinarySha256Hex; compare with pinAcceptsBinary(pin, reported), which accepts either, rather than with ===.

sevStatus

A string enum: noSevHost, reportDataMatch, reportDataMismatch, malformedReport. Any value other than reportDataMatch means no hardware vouches for the self-reported fields. noSevHost is expected on both live servers; there the operator-signed identity has to carry the binding instead.

gateOperatorIdentity

Checks a server's announce() bundle (REQ_ANNOUNCE) against the pinned operator key: the operator's key certified a server identity key for a server id, and that identity key signed a bundle naming the channel key and the binary hash. It returns state: 'verified' only when the certificate is signed by your pinned operator key and inside its validity window, the bundle's channel key equals the attested one, and the bundle is not future-dated. Compare serverId and binarySha256Hex with the provider's pins yourself, as in the flow above.

Operator pins

The reference operator publishes pins in web/src/attest-pin.ts. For wallets shipping with the reference deployment, bake those values into your bundle at build time and resync whenever the operator redeploys (the values rotate with every binary). The pins as of 2026-10-03:

PinServerPins
PIR1_PINpir1 (Hetzner, no SEV)binary SHA-256
PIR2_MACBOOK_PINpir2 (MacBook, no TEE)binary SHA-256
PIR2_TIER3_PINthe Direct ORAM host (VPSBG, AMD Milan)binary SHA-256 + SEV-SNP MEASUREMENT
AMD_MILAN_ARK_FINGERPRINTthe Direct ORAM hostAMD's Milan root key; its reports must also meet AMD_MILAN_SEV_SNP_FLOOR
AMD_TURIN_ARK_FINGERPRINTTurin SEV-SNP hostsAMD's Turin root key

PIR1_PROVIDER and PIR2_PROVIDER (production-providers.ts) pair each binary pin with the endpoint, the expected server id and the operator key the identity check needs. ORAM_PROVIDER does the same for the Direct ORAM host (server id pir2-oram-v1) and adds its ARK pin (Milan).

These values rotate on every operator redeploy

A wallet baking these into its bundle will refuse to connect after the operator publishes a new binary. Either resync from vendor/bitcoinpir-web/attest-pin.ts on every release, or fetch the current pins from a signed manifest you control. The playground itself reads from the vendored file, not from this doc.

The two servers run different builds (pir1 on Linux x86-64, pir2 on macOS arm64), so PIR1_PIN and PIR2_MACBOOK_PIN differ. pir2 runs --serve-queries only (no hint pool, no OnionPIR); pir1 runs the hint role.

What happens after the channel is upgraded

upgradeToSecureChannel wraps both WebSocket connections in an AEAD frame layer (ChaCha20-Poly1305). After this:

  • Every PIR request and response is sealed end-to-end with a key derived from the X25519 ECDH between the client's ephemeral key and the server's static key.
  • Cloudflared (the operator's TLS terminator), an ISP-level observer, or any other middlebox sees only ciphertext + framing metadata.
  • A future re-key requires a new attest() round trip.

This is defense in depth on top of TLS — TLS already encrypts in transit, but its certificate identity comes from a CA, not from hardware attestation. The AEAD layer binds the session to the server's channel key: on a TEE host the hardware report vouches for that key, and on the live servers (no TEE) the operator-signed identity does.

Skipping attestation

For development against the live server, you can skip attestation — the wire still uses WSS, and the SDK still enforces the four privacy invariants. What you lose is the binding to a specific known binary. Use this only for local prototyping; production wallets should pin.

Rotating pins

When the operator deploys a new binary:

  1. The operator runs bpir-admin attest <endpoint> against the new deployment to capture the new binary_sha256 (and, on a TEE host, the new MEASUREMENT).
  2. The pin file is updated in the reference repo (this is web/src/attest-pin.ts).
  3. Wallets ship a new bundle.

Wallets that don't update will refuse the new server — which is the correct behaviour from a security perspective. The operator must either coordinate a rolling rollout with bundled wallets, or maintain multiple acceptable pins during a transition (the SDK doesn't provide multi-pin acceptance out of the box; the wallet wraps it).

Where to go next