--- title: Privacy Proxy description: Privacy Proxy is a managed proxy service that runs on Cloudflare's global network. It uses the MASQUE protocol suite to proxy TCP and UDP traffic via HTTP CONNECT and CONNECT-UDP methods over HTTP/2 and HTTP/3. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/privacy-proxy/index.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Privacy Proxy A MASQUE-based forward proxy that protects user privacy while preserving geolocation accuracy. Enterprise-only Privacy Proxy is a managed proxy service that runs on Cloudflare's global network. It uses the [MASQUE ↗](https://datatracker.ietf.org/wg/masque/about/) protocol suite to proxy TCP and UDP traffic via HTTP CONNECT and CONNECT-UDP methods over HTTP/2 and HTTP/3. Privacy Proxy separates user identity from user activity. Users authenticate to the proxy without revealing which destinations they visit, and destination servers see requests from Cloudflare IP addresses without learning who made them. Privacy Proxy powers services like [Microsoft Edge Secure Network ↗](https://blog.cloudflare.com/cloudflare-now-powering-microsoft-edge-secure-network/) and serves as a second-hop relay for [iCloud Private Relay ↗](https://blog.cloudflare.com/icloud-private-relay/). --- ## Features ### Single-hop deployment Deploy Privacy Proxy as a standalone proxy where Cloudflare handles authentication, proxying, and egress. [ Use Single-hop deployment ](https://developers.cloudflare.com/privacy-proxy/concepts/deployment-models/#single-hop) ### Double-hop deployment Operate your own first-hop proxy to authenticate users, then relay traffic through Cloudflare for additional privacy separation. [ Use Double-hop deployment ](https://developers.cloudflare.com/privacy-proxy/concepts/deployment-models/#double-hop) ### Geolocation preservation Maintain accurate geolocation for users without exposing their real IP addresses, ensuring location-relevant content and services work correctly. [ Use Geolocation preservation ](https://developers.cloudflare.com/privacy-proxy/concepts/geolocation/) ### Privacy Pass authentication Authenticate users with Privacy Pass tokens for production deployments, ensuring privacy-preserving access control. [ Use Privacy Pass authentication ](https://developers.cloudflare.com/privacy-proxy/concepts/authentication/) --- ## Related products **[Privacy Gateway](https://developers.cloudflare.com/privacy-gateway/)** Implements the Oblivious HTTP (OHTTP) standard for request-level privacy, hiding client IP addresses from application backends. **[WARP Client](https://developers.cloudflare.com/warp-client/)** Cloudflare's consumer VPN application that uses similar privacy-preserving proxy technology. --- ## Availability Privacy Proxy is available as a managed service for Enterprise customers. [Contact us ↗](https://www.cloudflare.com/lp/privacy-edge/) to discuss your use case and get started. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/privacy-proxy/","name":"Privacy Proxy"}}]} ``` --- --- title: Get started description: This guide walks you through connecting to Privacy Proxy and verifying that traffic is proxied correctly. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/privacy-proxy/get-started.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Get started This guide walks you through connecting to Privacy Proxy and verifying that traffic is proxied correctly. ## Before you begin Privacy Proxy is a managed service. Before you can connect, Cloudflare will provision an endpoint and provide you with: * **Proxy endpoint URL**: The hostname for your Privacy Proxy instance (for example, `https://your-proxy.example.com`). * **Pre-shared key (PSK)**: A secret key for proof-of-concept authentication. * **Egress IP ranges**: The IP addresses that destination servers will see for proxied traffic. [Contact us ↗](https://www.cloudflare.com/lp/privacy-edge/) to request access and receive your configuration details. --- ## 1\. Configure your client Privacy Proxy accepts connections over HTTP/2 and HTTP/3 using the HTTP CONNECT method. Because Privacy Proxy requires authentication headers, you cannot configure browsers to connect directly. Instead, use one of the following approaches: ### Use curl for testing locally For quick tests, use curl with the `--proxy` and `--proxy-header` flags to pass authentication directly: Terminal window ``` curl -v \ --proxy https://your-proxy.example.com \ --proxy-header "Proxy-Authorization: Preshared " \ https://example.com ``` ### Use Chaussette [Chaussette](https://developers.cloudflare.com/privacy-proxy/reference/client-libraries/#chaussette) is a local SOCKS5 proxy that handles authentication and forwards requests to Privacy Proxy. 1. Start Chaussette with your PSK and proxy endpoint: Terminal window ``` MASQUE_PRESHARED_KEY= chaussette \ --listen 127.0.0.1:1987 \ --proxy https://your-proxy.example.com:443 ``` 2. Configure your browser to use the local SOCKS5 proxy: Terminal window ``` google-chrome --proxy-server="socks5://127.0.0.1:1987" ``` --- ## 2\. Verify the connection To confirm that traffic is routing through Privacy Proxy, check your apparent IP address: Terminal window ``` curl -v \ --proxy https://your-proxy.example.com \ --proxy-header "Proxy-Authorization: Preshared " \ https://cloudflare.com/cdn-cgi/trace ``` The response includes connection metadata. Look for the `ip` field, which should show a Cloudflare egress IP address rather than your real IP. Example response ``` fl=123f456 h=cloudflare.com ip=162.159.xxx.xxx ts=1234567890.123 visit_scheme=https uag=curl/8.0.0 colo=SJC http=http/2 loc=US tls=TLSv1.3 ``` The `ip` value confirms the egress IP address used by the proxy. --- ## 3\. (Optional) Test geolocation Privacy Proxy preserves user geolocation by selecting egress IP addresses based on the client's location. You can specify a geohash to test this behavior: Terminal window ``` curl -v \ --proxy https://your-proxy.example.com \ --proxy-header "Proxy-Authorization: Preshared " \ --proxy-header "sec-ch-geohash: xn76c-JP" \ https://cloudflare.com/cdn-cgi/trace ``` The `sec-ch-geohash` header provides a [geohash ↗](https://en.wikipedia.org/wiki/Geohash) that the proxy uses to select an appropriate egress IP. The format is `-`. The response should show a `loc` value corresponding to the geohash region. --- ## Next steps * Learn about [deployment models](https://developers.cloudflare.com/privacy-proxy/concepts/deployment-models/) to understand single-hop versus double-hop architectures. * Review [authentication methods](https://developers.cloudflare.com/privacy-proxy/concepts/authentication/) for production deployments using Privacy Pass. * Configure [observability](https://developers.cloudflare.com/privacy-proxy/reference/observability/) to monitor proxy traffic with OpenTelemetry. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/privacy-proxy/","name":"Privacy Proxy"}},{"@type":"ListItem","position":3,"item":{"@id":"/privacy-proxy/get-started/","name":"Get started"}}]} ``` --- --- title: Authentication description: Privacy Proxy requires clients to authenticate before proxying traffic. This page explains the supported authentication methods and when to use them. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/privacy-proxy/concepts/authentication.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Authentication Privacy Proxy requires clients to authenticate before proxying traffic. This page explains the supported authentication methods and when to use them. ## Authentication methods Privacy Proxy supports three authentication methods: | Method | Use case | Privacy level | | -------------------- | ------------------------- | ------------- | | Pre-shared key (PSK) | Proof of concept, testing | Lower | | Privacy Pass tokens | Client to server | High | | mTLS | Server to server | Higher | --- ## Pre-shared key (PSK) Pre-shared keys provide a simple way to authenticate during development and proof-of-concept testing. Cloudflare provides a secret key that clients include in each request. ### How it works Include the PSK in the `Proxy-Authorization` header: ``` CONNECT example.com:443 HTTP/2 Host: example.com Proxy-Authorization: Preshared ``` The proxy validates the key and allows the connection if it matches. ### Limitations PSK authentication has limitations that make it unsuitable for production. * **Shared secret**: All clients use the same key, so you cannot revoke access for individual users. * **No rate limiting per user**: You cannot enforce per-user quotas or limits. * **Linkability**: The proxy can link all requests using the same PSK, which reduces user privacy. Use PSK only for testing. For production deployments, use [Privacy Pass tokens](#privacy-pass-tokens). --- ## Privacy Pass tokens [Privacy Pass ↗](https://datatracker.ietf.org/wg/privacypass/about/) is a protocol that allows clients to authenticate without revealing their identity. Tokens are cryptographically unlinkable, meaning the proxy cannot correlate different requests from the same user. ### How it works Privacy Pass uses a three-party architecture: * **Attester**: Verifies that the Client is a legitimate user (for example, has a valid account) and forwards token requests to the Issuer. * **Issuer**: Signs blinded tokens without learning which Client requested them. * **Origin (Privacy Proxy)**: Accepts tokens as proof of authorization. ### Token issuance ``` ┌──────────┐ 1. Attestation request ┌──────────┐ │ │ ──────────────────────────▶ │ │ │ Client │ │ Attester │ │ │ ◀────────────────────────── │ │ └──────────┘ 2. Attestation OK └──────────┘ │ │ 3. Blinded token request ▼ ┌──────────┐ 4. Forward request ┌──────────┐ │ │ ──────────────────────────▶ │ │ │ Attester │ │ Issuer │ │ │ ◀────────────────────────── │ │ └──────────┘ 5. Signed blinded token └──────────┘ │ │ 6. Return to Client ▼ ┌──────────┐ │ Client │ (unblinds and stores token) └──────────┘ ``` The Client sends the token request through the Attester to maintain unlinkability. This ensures the Issuer cannot correlate token requests with specific attestation events or Client identities. ### Token redemption ``` ┌──────────┐ 1. Present token ┌──────────┐ │ │ ──────────────────────────▶ │ │ │ Client │ │ Privacy │ │ │ ◀────────────────────────── │ Proxy │ └──────────┘ 2. Connection OK └──────────┘ ``` The Privacy Proxy validates the token using the Issuer's public key. The proxy learns only that the token is valid, not who it was issued to. The token issuance process: 1. The client proves their identity to the attester (for example, by signing in with an account). 2. The attester confirms the client is valid. 3. The client generates blinded tokens and sends them to the issuer. 4. The issuer signs the blinded tokens and returns them. 5. The client unblinds the tokens and stores them. When making a request: 1. The client includes a token in the `Proxy-Authorization` header. 2. The proxy verifies the token signature with the issuer's public key. 3. The proxy allows the connection if the token is valid. Because tokens are blinded during issuance, the issuer cannot link tokens to specific issuance requests. The proxy sees only that a token is valid, not who it was issued to. ### Token format Privacy Pass tokens are included in the `Proxy-Authorization` header using the `PrivateToken` scheme: ``` CONNECT example.com:443 HTTP/2 Host: example.com Proxy-Authorization: PrivateToken token= ``` ### Set up Privacy Pass For production deployments using Privacy Pass: 1. Choose an issuer. Cloudflare can operate a token issuer, or you can integrate with a third-party issuer. 2. Configure attestation to define how clients prove their identity before receiving tokens. 3. Distribute issuer configuration. Clients need the issuer's public key and endpoint to request tokens. [Contact us ↗](https://www.cloudflare.com/lp/privacy-edge/) to configure Privacy Pass for your deployment. --- ## Mutual TLS (mTLS) [Mutual TLS (mTLS) authentication ↗](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) ensures that traffic is both secure and trusted in both directions. The client presents a certificate to the proxy, and the proxy validates it before allowing the connection. ### How it works The client includes a TLS client certificate during the TLS handshake. The proxy validates the certificate against a configured certificate authority (CA) and allows the connection if the certificate is trusted. ### Limitations You must provision and manage certificates for each client or service. mTLS is designed for server-to-server communication, not for authenticating individual users. The proxy can identify the client by its certificate, which reduces privacy compared to Privacy Pass. Use mTLS for server-to-server integrations where both parties are trusted services. --- ## Authentication in double-hop deployments In [double-hop deployments](https://developers.cloudflare.com/privacy-proxy/concepts/deployment-models/#double-hop), authentication occurs at two levels: ### User to Proxy A Proxy A (which you operate) authenticates users. Common methods include: * Account credentials (username/password, SSO) * Privacy Pass tokens issued by your infrastructure * Client certificates (mTLS) ### Proxy A to Proxy B Proxy B authenticates itself to Proxy A using TLS. Depending on your configuration, this can use: * Standard TLS certificates * Raw Public Key (RPK) TLS extension for reduced certificate overhead --- ## Related resources * [Privacy Pass Working Group ↗](https://datatracker.ietf.org/wg/privacypass/about/) \- IETF working group developing the Privacy Pass protocol. * [Supporting the latest version of the Privacy Pass protocol ↗](https://blog.cloudflare.com/supporting-the-latest-version-of-the-privacy-pass-protocol/) \- Cloudflare blog post on Privacy Pass implementation. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/privacy-proxy/","name":"Privacy Proxy"}},{"@type":"ListItem","position":3,"item":{"@id":"/privacy-proxy/concepts/","name":"Concepts"}},{"@type":"ListItem","position":4,"item":{"@id":"/privacy-proxy/concepts/authentication/","name":"Authentication"}}]} ``` --- --- title: Deployment models description: Privacy Proxy supports two deployment architectures: single-hop and double-hop. The right choice depends on your privacy requirements and operational preferences. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/privacy-proxy/concepts/deployment-models.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Deployment models Privacy Proxy supports two deployment architectures: single-hop and double-hop. The right choice depends on your privacy requirements and operational preferences. ## Single-hop In a single-hop deployment, Cloudflare operates the entire proxy infrastructure. Clients connect directly to Cloudflare's Privacy Proxy, which handles authentication, proxying, and egress. ``` ┌────────┐ ┌─────────────────┐ ┌─────────────┐ │ Client │ ───▶ │ Privacy Proxy │ ───▶ │ Destination │ │ │ │ (Cloudflare) │ │ Server │ └────────┘ └─────────────────┘ └─────────────┘ ``` ### How it works 1. The client establishes an HTTP/2 or HTTP/3 connection to the Cloudflare proxy endpoint. 2. The client authenticates using Privacy Pass tokens or a pre-shared key. 3. The client sends CONNECT requests to establish tunnels to destination servers. 4. Cloudflare proxies traffic and selects egress IP addresses based on client geolocation. ### Use cases Single-hop deployment works well when: * You want Cloudflare to manage the complete proxy infrastructure. * Your privacy model requires hiding client IP addresses from destinations, but not from the proxy operator. * You need a straightforward integration with minimal client-side changes. #### Example: Microsoft Edge Secure Network [Microsoft Edge Secure Network ↗](https://blog.cloudflare.com/cloudflare-now-powering-microsoft-edge-secure-network/) uses single-hop deployment. The Edge browser connects directly to Cloudflare's Privacy Proxy, which handles authentication via Privacy Pass and proxies traffic to destination servers. Users get protection from network observers and destination servers without needing to configure additional infrastructure. --- ## Double-hop In a double-hop deployment, you operate the first proxy (Proxy A), and Cloudflare operates the second proxy (Proxy B). This creates stronger privacy separation because no single party sees both user identity and destination. ``` ┌────────┐ ┌─────────────┐ ┌─────────────────┐ ┌─────────────┐ │ Client │ ───▶ │ Proxy A │ ───▶ │ Proxy B │ ───▶ │ Destination │ │ │ │ (You) │ │ (Cloudflare) │ │ Server │ └────────┘ └─────────────┘ └─────────────────┘ └─────────────┘ ``` ### How it works 1. The client connects to Proxy A, which you operate. 2. Proxy A authenticates the user and verifies they can use the service. 3. Proxy A establishes a tunnel to Cloudflare's Proxy B, forwarding the client's CONNECT request. 4. Proxy B connects to the destination and proxies traffic. 5. Proxy B selects egress IPs based on geolocation provided by Proxy A. ### Privacy separation The double-hop architecture ensures: | Information | Proxy A (you) | Proxy B (Cloudflare) | | ------------------ | ------------- | -------------------- | | Client IP address | Yes | No | | User account | Yes | No | | Destination server | Encrypted | Yes | | Request content | Encrypted | Encrypted | Proxy A knows who the user is but cannot see where they are going (the destination is encrypted). Proxy B knows the destination but not who is making the request. Neither party has the complete picture. ### Use cases Double-hop deployment works well when: * You need stronger privacy guarantees where no single operator sees both identity and destination. * You want to maintain control over user authentication and account management. * Regulatory or compliance requirements mandate separation of user data. #### Example: iCloud Private Relay [iCloud Private Relay ↗](https://blog.cloudflare.com/icloud-private-relay/) uses double-hop deployment. Apple operates the first-hop proxy, which authenticates users with their Apple ID and encrypts the destination. Cloudflare operates the second-hop proxy, which decrypts the destination and connects to the server. Apple knows who the user is but not where they browse. Cloudflare knows the destinations but not who is browsing. --- ## Comparison | Aspect | Single-hop | Double-hop | | ---------------------- | --------------------------------- | -------------------------- | | Infrastructure | Cloudflare only | You + Cloudflare | | Privacy separation | Proxy sees identity + destination | Split across two parties | | Operational complexity | Lower | Higher | | Authentication | Cloudflare-managed | You manage first-hop auth | | Use case | Browser VPNs, simple privacy | Maximum privacy separation | --- ## Choose a deployment model Consider these questions when selecting a deployment model: 1. Who should manage user authentication? If you want Cloudflare to handle authentication, use single-hop. If you need control over user accounts, use double-hop. 1. What are your privacy requirements? If your threat model requires that no single party sees both user identity and browsing activity, use double-hop. 1. What operational capacity do you have? Double-hop requires you to operate and maintain a proxy. If you prefer a fully managed solution, use single-hop. [Contact us ↗](https://www.cloudflare.com/lp/privacy-edge/) to discuss which deployment model fits your use case. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/privacy-proxy/","name":"Privacy Proxy"}},{"@type":"ListItem","position":3,"item":{"@id":"/privacy-proxy/concepts/","name":"Concepts"}},{"@type":"ListItem","position":4,"item":{"@id":"/privacy-proxy/concepts/deployment-models/","name":"Deployment models"}}]} ``` --- --- title: Geolocation description: Privacy Proxy preserves user geolocation without exposing real IP addresses. This ensures location-based services work correctly while maintaining privacy. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/privacy-proxy/concepts/geolocation.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Geolocation Privacy Proxy preserves user geolocation without exposing real IP addresses. This ensures location-based services work correctly while maintaining privacy. ## Why geolocation matters Many online services use IP addresses to determine user location: * Search engines return locally relevant results. * Content providers enforce regional licensing restrictions. * E-commerce sites show local pricing and shipping options. * News sites display region-specific content. Traditional VPNs and proxies often break these services because traffic exits from data centers far from the user's actual location. Privacy Proxy solves this by selecting egress IP addresses that match the user's geographic region. ## How geolocation works Privacy Proxy uses geohashes to preserve location without revealing precise coordinates. ### Geohash encoding A [geohash ↗](https://en.wikipedia.org/wiki/Geohash) is a compact representation of latitude and longitude. Geohashes use a hierarchical encoding where longer strings represent more precise locations: | Geohash length | Approximate area | | -------------- | ---------------- | | 1 character | \~5,000 km | | 2 characters | \~1,250 km | | 3 characters | \~150 km | | 4 characters | \~40 km | | 5 characters | \~5 km | Privacy Proxy uses reduced-precision geohashes (typically four to five characters) to locate users to a city or region without pinpointing their exact location. ### Egress IP selection When a client connects to Privacy Proxy: 1. The client (or first-hop proxy in double-hop deployments) determines the user's approximate location. 2. The client sends a geohash in the `sec-ch-geohash` header. 3. Privacy Proxy validates the geohash and selects an egress IP address from a pool registered to that geographic area. 4. Destination servers see the egress IP and geolocate the user to the correct region. ### Geohash header format The `sec-ch-geohash` header includes the geohash and country code: ``` sec-ch-geohash: xn76c-JP ``` The format is `-`. The country code helps resolve edge cases where geohashes span country borders. ## Geolocation accuracy Cloudflare maintains egress IP pools in hundreds of cities worldwide. When you register egress IPs with geolocation databases, they map to specific locations. Privacy Proxy achieves: * **City-level accuracy** by default, so users get locally relevant search results. * **Country-level accuracy** as a fallback if city-level is not available. Users can opt for coarser geolocation (country and timezone only) if they prefer less precise location sharing. ### The pizza test A simple way to verify geolocation accuracy is to search for "pizza near me" through the proxy. If results show pizza places in the user's actual city rather than a distant data center, geolocation is working correctly. ## IPv6 and geolocation precision Privacy Proxy achieves better geolocation precision over IPv6\. If your origin servers support IPv6 (AAAA DNS records), the proxy prefers IPv6 egress addresses, which are registered with greater geographic precision than IPv4 equivalents. To maximize geolocation accuracy for your users, ensure your services are reachable over IPv6. ## Geolocation in double-hop deployments In [double-hop deployments](https://developers.cloudflare.com/privacy-proxy/concepts/deployment-models/#double-hop), Proxy A (which you operate) is responsible for determining and forwarding the geohash: 1. Proxy A geolocates the client's IP address. 2. Proxy A converts the location to a geohash with appropriate precision. 3. Proxy A includes the geohash in the forwarded CONNECT request to Proxy B. 4. Proxy B (Cloudflare) selects an egress IP based on the geohash. The geohash is cryptographically protected to prevent clients from spoofing their location. ## Related resources * [Geo-egress: Improving WARP user experience on a larger network ↗](https://blog.cloudflare.com/geoexit-improving-warp-user-experience-larger-network/) \- How Cloudflare implements geolocation-aware egress. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/privacy-proxy/","name":"Privacy Proxy"}},{"@type":"ListItem","position":3,"item":{"@id":"/privacy-proxy/concepts/","name":"Concepts"}},{"@type":"ListItem","position":4,"item":{"@id":"/privacy-proxy/concepts/geolocation/","name":"Geolocation"}}]} ``` --- --- title: How Privacy Proxy works description: Privacy Proxy uses the MASQUE protocol suite to create encrypted tunnels between clients and destination servers. This page explains the protocol mechanics and how privacy is preserved. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/privacy-proxy/concepts/how-it-works.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # How Privacy Proxy works Privacy Proxy uses the MASQUE protocol suite to create encrypted tunnels between clients and destination servers. This page explains the protocol mechanics and how privacy is preserved. ## Traffic flow ``` ┌──────────┐ 1. Connect + Auth ┌──────────┐ 4. Connect ┌─────────────┐ │ │ ──────────────────────────▶ │ │ ────────────────────▶ │ │ │ Client │ 2. CONNECT request │ Privacy │ (Egress IP) │ Destination │ │ │ ──────────────────────────▶ │ Proxy │ │ Server │ │ │ │ │ ◀──────────────────── │ │ │ │ 3. 200 OK │ │ 5. Connected │ │ │ │ ◀────────────────────────── │ │ │ │ │ │ │ │ │ │ │ │ ◀───── 6. Encrypted data tunnel ─────▶ ◀─────────────────────▶│ │ └──────────┘ └──────────┘ └─────────────┘ │◀──── Client IP hidden ────▶│◀──── Cloudflare Egress IP visible ──────────▶│ ``` 1. The client establishes an HTTP/2 or HTTP/3 connection to Privacy Proxy and presents credentials (PSK or Privacy Pass token) in the `Proxy-Authorization` header. 2. The client sends a CONNECT request specifying the destination hostname and port. 3. The proxy responds with `200 OK` to confirm the tunnel is ready. 4. The proxy opens a connection to the destination using an egress IP address selected based on the client's geolocation. 5. The client sends encrypted data through the tunnel. The proxy forwards bytes without inspection. Throughout this process, the proxy learns the destination but not the content. The destination learns the egress IP address but not the client's real IP. ## MASQUE protocols [MASQUE ↗](https://datatracker.ietf.org/wg/masque/about/) (Multiplexed Application Substrate over QUIC Encryption) defines methods for proxying traffic over HTTP. Privacy Proxy supports two MASQUE methods: | Method | Transport | Use case | | ------------ | --------- | ------------------------------------------ | | HTTP CONNECT | TCP | Traditional HTTPS traffic | | CONNECT-UDP | UDP | QUIC-based traffic, real-time applications | Both methods create encrypted tunnels where the proxy forwards traffic without inspecting the content. The proxy sees only the destination hostname and port, not the actual requests, paths, or data exchanged. Privacy Proxy accepts connections over HTTP/2 (TLS over TCP) and HTTP/3 (QUIC), selecting the appropriate protocol based on client capabilities. For a technical deep dive into how these protocols work, refer to our [blog post ↗](https://blog.cloudflare.com/a-primer-on-proxies/). ## Privacy separation Privacy Proxy creates a privacy boundary between user identity and user activity: | Information | Who knows it | | ----------------------------------- | ------------------------------------------------------------- | | User identity (IP address, account) | Authentication service, first-hop proxy (if using double-hop) | | Destination server | Privacy Proxy, destination server | | Request content | Client, destination server only | The proxy authenticates users to verify they have permission to use the service, but authentication happens separately from proxying. Once authenticated, the proxy forwards traffic without linking individual requests to specific users. ## Related resources * [A Primer on Proxies ↗](https://blog.cloudflare.com/a-primer-on-proxies/) \- Technical deep dive into HTTP CONNECT and MASQUE protocols. * [MASQUE Working Group ↗](https://datatracker.ietf.org/wg/masque/about/) \- IETF working group developing proxy protocol standards. * [RFC 9298 ↗](https://datatracker.ietf.org/doc/html/rfc9298) \- CONNECT-UDP specification for proxying UDP over HTTP. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/privacy-proxy/","name":"Privacy Proxy"}},{"@type":"ListItem","position":3,"item":{"@id":"/privacy-proxy/concepts/","name":"Concepts"}},{"@type":"ListItem","position":4,"item":{"@id":"/privacy-proxy/concepts/how-it-works/","name":"How Privacy Proxy works"}}]} ``` --- --- title: Client libraries description: This page lists open source libraries and tools you can use to connect to Privacy Proxy. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/privacy-proxy/reference/client-libraries.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Client libraries This page lists open source libraries and tools you can use to connect to Privacy Proxy. ## tokio-quiche [tokio-quiche ↗](https://github.com/cloudflare/quiche/tree/master/tokio-quiche) is Cloudflare's open source async QUIC and HTTP/3 library for Rust. It combines the [quiche ↗](https://github.com/cloudflare/quiche) QUIC implementation with the [Tokio ↗](https://tokio.rs/) async runtime. tokio-quiche powers Privacy Proxy infrastructure, including Proxy B for iCloud Private Relay and Cloudflare's Oxy-based proxies. It handles millions of HTTP/3 requests per second in production. ### Features * Async QUIC client and server * HTTP/3 support via `H3Driver` * MASQUE CONNECT and CONNECT-UDP support * Battle-tested at scale on Cloudflare's network ### Installation Add tokio-quiche to your `Cargo.toml`: ``` [dependencies] tokio-quiche = "0.1" ``` ### Resources * [GitHub repository ↗](https://github.com/cloudflare/quiche/tree/master/tokio-quiche) * [crates.io ↗](https://crates.io/crates/tokio-quiche) * [Blog post: Async QUIC and HTTP/3 made easy ↗](https://blog.cloudflare.com/async-quic-and-http-3-made-easy-tokio-quiche-is-now-open-source/) --- ## quiche [quiche ↗](https://github.com/cloudflare/quiche) is Cloudflare's low-level QUIC and HTTP/3 implementation in Rust. It provides a sans-io design that can integrate into any application architecture. quiche is the foundation that tokio-quiche builds upon. Use quiche directly if you need fine-grained control over I/O or are integrating with a non-Tokio runtime. ### Resources * [GitHub repository ↗](https://github.com/cloudflare/quiche) * [Documentation ↗](https://docs.quic.tech/quiche/) * [crates.io ↗](https://crates.io/crates/quiche) --- ## Chaussette [Chaussette ↗](https://github.com/cloudflare/chaussette) is a SOCKS5-to-CONNECT proxy designed for Privacy Proxy. It accepts local SOCKS5 connections and forwards them as HTTP CONNECT requests to Privacy Proxy. Chaussette is useful for integrating applications that support SOCKS5 but not HTTP CONNECT proxying. ### Features * SOCKS5 to HTTP CONNECT conversion * Pre-shared key authentication * Geohash support for geolocation hints * Optional mTLS authentication ### Usage Terminal window ``` MASQUE_PRESHARED_KEY= chaussette \ --listen 127.0.0.1:1987 \ --proxy https://your-proxy.example.com:443 \ --geohash xn76c-JP ``` Then configure your application to use `socks5://127.0.0.1:1987` as its proxy. ### Resources * [GitHub repository ↗](https://github.com/cloudflare/chaussette) --- ## curl For basic testing over HTTP/2, standard curl supports CONNECT proxying: Terminal window ``` curl -v \ --proxy https://your-proxy.example.com \ --proxy-header "Proxy-Authorization: Preshared " \ https://example.com ``` curl can also be [built with quiche ↗](https://github.com/curl/curl/blob/master/docs/HTTP3.md#quiche-version) for HTTP/3 support. --- ## privacypass-ts [privacypass-ts ↗](https://github.com/cloudflare/privacypass-ts) is Cloudflare's TypeScript implementation of the Privacy Pass protocol. Use this library to issue and redeem Privacy Pass tokens for authenticating with Privacy Proxy. ### Features * Privacy Pass token issuance and redemption * Support for publicly verifiable and rate-limited token types * Compatible with browser and Node.js environments ### Installation Terminal window ``` npm install @cloudflare/privacypass-ts ``` ### Resources * [GitHub repository ↗](https://github.com/cloudflare/privacypass-ts) * [npm package ↗](https://www.npmjs.com/package/@cloudflare/privacypass-ts) ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/privacy-proxy/","name":"Privacy Proxy"}},{"@type":"ListItem","position":3,"item":{"@id":"/privacy-proxy/reference/","name":"Reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/privacy-proxy/reference/client-libraries/","name":"Client libraries"}}]} ``` --- --- title: HTTP headers description: This page documents the HTTP headers used by Privacy Proxy for authentication, geolocation, and observability. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/privacy-proxy/reference/http-headers.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # HTTP headers This page documents the HTTP headers used by Privacy Proxy for authentication, geolocation, and observability. ## Request headers Clients include the following headers when connecting to Privacy Proxy. ### `Proxy-Authorization` Authenticates the client to the proxy. Required for all requests. Pre-shared key format: ``` Proxy-Authorization: Preshared ``` Privacy Pass token format: ``` Proxy-Authorization: PrivateToken token= ``` | Parameter | Description | | ---------------------- | ----------------------------------------- | | | The pre-shared key provided by Cloudflare | | | A base64-encoded Privacy Pass token | ### `sec-ch-geohash` Specifies the client's geographic location for egress IP selection. Optional but recommended for accurate geolocation. ``` sec-ch-geohash: - ``` | Parameter | Description | | --------------- | -------------------------------------------------------------------------------------- | | | A [geohash ↗](https://en.wikipedia.org/wiki/Geohash) string (typically 4-8 characters) | | | ISO 3166-1 alpha-2 country code | Example ``` sec-ch-geohash: u4pruydqqvj-GB ``` This example specifies a location in the United Kingdom. --- ## Response headers Privacy Proxy includes the following headers in responses. ### `Server-Timing` Provides timing information about proxy processing. Use this to measure latency introduced by the proxy. ``` Server-Timing: proxy;dur= ``` | Parameter | Description | | -------------- | ------------------------------- | | | Processing time in milliseconds | Example ``` Server-Timing: proxy;dur=8.2 ``` --- ## `CONNECT` request format A complete `CONNECT` request to Privacy Proxy looks like this: ``` CONNECT example.com:443 HTTP/2 Host: example.com Proxy-Authorization: Preshared abc123xyz sec-ch-geohash: 9q8yy-US ``` The proxy responds with a status code indicating success or failure: | Status | Meaning | | ----------------------- | -------------------------------- | | 200 OK | Tunnel established successfully | | 403 Forbidden | Authentication failed | | 502 Bad Gateway | Could not connect to destination | | 503 Service Unavailable | Proxy temporarily unavailable | ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/privacy-proxy/","name":"Privacy Proxy"}},{"@type":"ListItem","position":3,"item":{"@id":"/privacy-proxy/reference/","name":"Reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/privacy-proxy/reference/http-headers/","name":"HTTP headers"}}]} ``` --- --- title: Observability description: Privacy Proxy supports OpenTelemetry for monitoring and observability. You can collect metrics and traces to understand proxy performance and usage. image: https://developers.cloudflare.com/dev-products-preview.png --- [Skip to content](#%5Ftop) Was this helpful? YesNo [ Edit page ](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/privacy-proxy/reference/observability.mdx) [ Report issue ](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) Copy page # Observability Privacy Proxy supports OpenTelemetry for monitoring and observability. You can collect metrics and traces to understand proxy performance and usage. ## OpenTelemetry integration Privacy Proxy exports telemetry data using the [OpenTelemetry Protocol (OTLP) ↗](https://opentelemetry.io/docs/specs/otlp/). You can configure an endpoint to receive this data and forward it to your observability platform. ### Configure telemetry export During onboarding, provide Cloudflare with your OpenTelemetry collector endpoint: * **Endpoint URL**: The HTTPS endpoint where telemetry data should be sent. * **Authentication**: Headers or credentials required to authenticate with your collector. Cloudflare configures your Privacy Proxy instance to export telemetry to this endpoint. ### Supported signals Privacy Proxy exports the following telemetry signals: | Signal | Description | | ------- | ----------------------------------------------------------------------------------------------------- | | Metrics | Connection counts, request rates, latency histograms, error rates | | Traces | Per-request traces showing proxy processing time. Traces are sampled at approximately 1% of requests. | ## Metrics Privacy Proxy exports metrics that help you understand usage patterns and performance. ### Connection metrics | Metric | Description | | ---------------------------------------------- | --------------------------------- | | privacy\_proxy\_connections\_total | Total number of proxy connections | | privacy\_proxy\_connections\_active | Currently active connections | | privacy\_proxy\_connections\_duration\_seconds | Connection duration histogram | ### Request metrics | Metric | Description | | -------------------------------------- | ---------------------------------------- | | privacy\_proxy\_requests\_total | Total CONNECT requests processed | | privacy\_proxy\_requests\_by\_status | Requests grouped by response status code | | privacy\_proxy\_bytes\_sent\_total | Total bytes sent to destinations | | privacy\_proxy\_bytes\_received\_total | Total bytes received from destinations | ### Latency metrics | Metric | Description | | --------------------------------------------- | ------------------------------------------- | | privacy\_proxy\_connect\_latency\_seconds | Time to establish connection to destination | | privacy\_proxy\_first\_byte\_latency\_seconds | Time to first byte from destination | ## `Server-Timing` header Privacy Proxy includes a `Server-Timing` header in responses to help measure processing latency from the client side. For full header format details, refer to [HTTP headers](https://developers.cloudflare.com/privacy-proxy/reference/http-headers/#server-timing). ``` Server-Timing: proxy;dur=12.5 ``` The `dur` value is the processing time in milliseconds introduced by the proxy. Use this header as a client-side SLI (Service Level Indicator) to monitor proxy performance. ### Example: Prometheus and Grafana To visualize Privacy Proxy metrics in Grafana: 1. Configure an OpenTelemetry collector to receive data from Privacy Proxy. 2. Export metrics from the collector to Prometheus. 3. Create Grafana dashboards using Prometheus as a data source. Example Prometheus queries ``` # Request rate over time rate(privacy_proxy_requests_total[5m]) # 95th percentile connection latency histogram_quantile(0.95, rate(privacy_proxy_connect_latency_seconds_bucket[5m])) # Error rate sum(rate(privacy_proxy_requests_by_status{status=~"5.."}[5m])) / sum(rate(privacy_proxy_requests_total[5m])) ``` ## Data privacy Telemetry data does not include: * User IP addresses * Request content or headers (beyond what is needed for metrics) * Destination URLs or hostnames (aggregated only) * Authentication tokens or credentials Cloudflare exports only operational metrics that help you monitor service health without compromising user privacy. ## Related resources * [OpenTelemetry documentation ↗](https://opentelemetry.io/docs/) \- Learn more about OpenTelemetry concepts and configuration. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/privacy-proxy/","name":"Privacy Proxy"}},{"@type":"ListItem","position":3,"item":{"@id":"/privacy-proxy/reference/","name":"Reference"}},{"@type":"ListItem","position":4,"item":{"@id":"/privacy-proxy/reference/observability/","name":"Observability"}}]} ```