Skip to content

SYSTEM Cited by 1 source

GeoKey Manager

GeoKey Manager is Cloudflare's system for geographically restricting where a customer's private keys can be unwrapped on its global anycast network. It is the cornerstone of Cloudflare's Data Localization Suite (DLS): a customer picks a region (e.g. Germany, or the EU) and GeoKey Manager guarantees that their TLS/decryption keys are only ever unwrappable by Cloudflare edge servers physically located inside that region. Because TLS traffic can only be decrypted where its private key is available, GeoKey Manager is the primitive every other regional control (routing, tunnel termination, traffic inspection — all Regional Services) ultimately depends on. (Source: sources/2026-10-23-cloudflare-pq-geokey-manager)

What it controls — and what it doesn't

GeoKey Manager controls where wrapped private keys can be unwrapped and used on the data plane, and nothing else. It explicitly does not control where requests are forwarded/routed, where tunnels terminate, or where traffic inspection happens — those are Regional Services. The separation is deliberate: one system owns the key-unwrap-location invariant; others own topology.

Three generations

Year Design Mechanism
2017 Geo-restricted TLS keys Keys unwrappable only in a chosen fixed set of datacenters (e.g. "India only")
2022 Ciphertext-policy ABE Attribute-based encryption; geography expressed as attributes ("region = EU", "CA+US+MX"); newly-authorized servers get matching decryption capability without rewrapping every key
2026 PQ symmetric-root (this page) Per-region 256-bit symmetric root → derived hybrid-PQ HPKE key pair; simpler than ABE, post-quantum, easier to operate

The 2026 redesign dropped ABE because no production-ready post-quantum ABE scheme exists, and because customers need only a handful of regions — a simpler scheme meets the requirement and is easier to maintain. The trade is expressiveness (ABE's attribute expressions) for operability and PQ-readiness.

Key hierarchy

GeoKey Manager uses a two-level envelope-style hierarchy, but with a symmetric root and a derived asymmetric wrapping pair:

  1. Regional root key — a 256-bit symmetric secret tied to exactly one region. Never leaves its region. Stored by the provisioning service (backed by on-prem HashiCorp Vault) and, on authorized edge servers, in the Linux kernel keyring.
  2. Application-specific key pair — an HPKE key pair derived from the regional root key for a single (service context, regional boundary, epoch) triple. The public half wraps the customer's private key; the private half (recoverable only via the regional root key) unwraps it.
  3. Wrapped customer private key — the customer's key material sealed under the application key pair's public half, distributed globally with its metadata.

Every wrapped key carries metadata identifying its service context (the Cloudflare service using it — Tunnel, Gateway, Access, Cloudflare One client), its regional boundary (the approved datacenters), and its epoch (which generation of the regional root key it belongs to). Keys sharing all three reuse the same application key pair.

Blast radius of a compromise

The hierarchy makes the blast radius explicit and bounded:

  • Compromising the Tunnel-Germany application private key exposes every customer's Tunnel-Germany key for that epoch — but not their Gateway-Germany keys (different service context → different derived pair).
  • Compromising the Germany regional root key exposes every application key derived from it for that epoch across all services.

Cryptographic design

The Cloudflare One path uses HPKE (Hybrid Public Key Encryption, RFC 9180):

  • KEM — hybrid ML-KEM-768 (NIST FIPS 203, post-quantum) + X25519 (classical). Confidentiality holds as long as at least one component is unbroken — defence in depth on the algorithm axis, and the standard hybrid-over-replacement transition shape.
  • KDF — HKDF-SHA-256.
  • AEAD — AES-256-GCM.

This protects the long-lived private-key material against harvest-now-decrypt-later while preserving the regional key-use boundary.

Two distribution planes

GeoKey Manager separates the globally-distributed wrapped keys from the regionally-scoped root key needed to unwrap them:

  • Wrapped private keys + metadata → distributed to every POP by Quicksilver, Cloudflare's global config KV store. Global distribution is safe because a wrapped key is useless without its regional root key and service context.
  • Regional root keys → delivered only to authorized edge servers by a separate provisioning service (backed by on-prem HashiCorp Vault). Never via Quicksilver.

The trust boundary (everything that can touch a regional root key) is the key-management service, the provisioning service, and authorized edge key services. Quicksilver is deliberately outside it — it only ever sees wrapped keys and metadata.

Edge-server authorization

Before an edge server can receive a regional root key, the provisioning service evaluates three inputs:

  1. Trusted Platform Module (TPM) — proves the server holds a registered hardware identity (remote attestation).
  2. Zinc — Cloudflare's server-inventory system maps that hardware identity to a datacenter and physical location (also supports FIPS 140-3 compliance).
  3. Provisioning policy — determines which regional root keys that location may access.

The provisioning service then issues a scoped token the server uses to fetch only the roots authorized for its location. Authorized servers load those roots into the Linux kernel keyring (volatile memory), never persisting them to disk — so a reboot wipes them and forces re-attestation and re-provisioning. This trades operational complexity for a smaller persistent-key attack surface.

Fleet membership is dynamic: as Cloudflare adds/removes capacity or does maintenance, the definition of "Germany" changes in Zinc and is propagated through the network via Quicksilver several times per day — granting or revoking root-key access with no customer action. This is separate from key rotation.

Fail-closed by design

Failing closed is explicit and load-bearing (see concepts/fail-open-vs-fail-closed):

  • At startup, the edge key service loads every configured regional root key from the kernel keyring; a missing or malformed root prevents the service from initializing.
  • Per request, if the request's metadata names a regional root key not locally available, the request is rejected — a key for Germany cannot be unwrapped in Spain or France because neither holds Germany's root.

Failing open would mean unwrapping a customer's private key outside its allowed region; Cloudflare states it never does this. An edge server serves a region's requests only once its configuration and key provisioning are complete.

Key rotation

Two rotation modes, both epoch-based:

  • Soft rotation — create a new epoch for the regional root key while keeping controlled access to a bounded number of previous epochs. New customer keys wrap under the latest epoch; older wrapped keys remain usable during the transition. Analogy: a credit-card issuer letting a previous card keep working for recurring charges during reissue. The number of retained epochs bounds how many prior generations stay valid.
  • Hard rotation — rewrap affected customers' wrapped keys under a replacement epoch so access to the previous epoch can be fully removed. Analogy: the issuer refusing the old card entirely.

Status and roadmap

  • Closed beta (October 2026); GA targeted Q1 2027.
  • Positioned as the basis for an improved Regional Services offering for Cloudflare One (to be announced).
  • Older GeoKey Manager versions already geo-fence CDN certificate keys; bringing this PQ design to the CDN path is separate, in-progress work with no date.

Seen in

  • sources/2026-10-23-cloudflare-pq-geokey-manager — canonical wiki source and primary subject. The post-quantum redesign of GeoKey Manager: symmetric regional root → derived hybrid ML-KEM-768 + X25519 HPKE wrapping, Quicksilver-distributed wrapped keys with a separate Vault-backed provisioning plane for roots, TPM + Zinc edge authorization into the kernel keyring, strict fail-closed out-of-region enforcement, and soft/hard epoch rotation.
Last updated · 854 distilled / 2,448 read