Skip to content

Commit 173bd86

Browse files
mgalicerclaudepatriciasantaanadanish-m-qureshi
authored
[Draft] Add documentation for Privacy Proxy (#27724)
* Add Privacy Proxy documentation Add developer documentation for Privacy Proxy, a MASQUE-based forward proxy service for enterprise customers. Documentation includes: - Overview and product landing page - Get started guide with Chaussette and curl examples - Concepts: how it works, deployment models, authentication, geolocation - Reference: HTTP headers, observability, client libraries Co-authored-by: Claude <noreply@anthropic.com> * Apply suggestions from code review * Apply suggestions from code review * Address reviewer feedback: add trace sampling note, privacypass-ts library, update related products * Revert Related Products to only Privacy Gateway and WARP * Apply suggestions from code review * Remove Privacy Pass protocol specification link --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Patricia Santa Ana <103445940+patriciasantaana@users.noreply.github.com> Co-authored-by: Danish Mujtaba Qureshi <s-dqureshi@ucp.pt>
1 parent d08ffb6 commit 173bd86

13 files changed

Lines changed: 967 additions & 0 deletions

File tree

‎src/content/docs/privacy-proxy/concepts/authentication.mdx‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: Authentication
3+
pcx_content_type: concept
4+
sidebar:
5+
order: 3
6+
---
7+
8+
Privacy Proxy requires clients to authenticate before proxying traffic. This page explains the supported authentication methods and when to use them.
9+
10+
## Authentication methods
11+
12+
Privacy Proxy supports two authentication methods:
13+
14+
| Method | Use case | Privacy level |
15+
| -------- | ---------- | --------------- |
16+
| Pre-shared key (PSK) | Proof of concept, testing | Lower |
17+
| Privacy Pass tokens | Production deployments | Higher |
18+
19+
---
20+
21+
## Pre-shared key (PSK)
22+
23+
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.
24+
25+
### How it works
26+
27+
Include the PSK in the `Proxy-Authorization` header:
28+
29+
```http
30+
CONNECT example.com:443 HTTP/2
31+
Host: example.com
32+
Proxy-Authorization: Preshared <YOUR_PSK>
33+
```
34+
35+
The proxy validates the key and allows the connection if it matches.
36+
37+
### Limitations
38+
39+
PSK authentication has limitations that make it unsuitable for production.
40+
41+
- **Shared secret**: All clients use the same key, so you cannot revoke access for individual users.
42+
- **No rate limiting per user**: You cannot enforce per-user quotas or limits.
43+
- **Linkability**: The proxy can link all requests using the same PSK, which reduces user privacy.
44+
45+
Use PSK only for testing. For production deployments, use [Privacy Pass tokens](#privacy-pass-tokens).
46+
47+
---
48+
49+
## Privacy Pass tokens
50+
51+
[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.
52+
53+
### How it works
54+
55+
Privacy Pass uses a three-party architecture:
56+
57+
- **Attester**: Verifies that the Client is a legitimate user (for example, has a valid account) and forwards token requests to the Issuer.
58+
- **Issuer**: Signs blinded tokens without learning which Client requested them.
59+
- **Origin (Privacy Proxy)**: Accepts tokens as proof of authorization.
60+
61+
### Token issuance
62+
63+
```
64+
┌──────────┐ 1. Attestation request ┌──────────┐
65+
│ │ ──────────────────────────▶ │ │
66+
│ Client │ │ Attester │
67+
│ │ ◀────────────────────────── │ │
68+
└──────────┘ 2. Attestation OK └──────────┘
69+
│
70+
│ 3. Blinded token request
71+
▼
72+
┌──────────┐ 4. Forward request ┌──────────┐
73+
│ │ ──────────────────────────▶ │ │
74+
│ Attester │ │ Issuer │
75+
│ │ ◀────────────────────────── │ │
76+
└──────────┘ 5. Signed blinded token └──────────┘
77+
│
78+
│ 6. Return to Client
79+
▼
80+
┌──────────┐
81+
│ Client │ (unblinds and stores token)
82+
└──────────┘
83+
```
84+
85+
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.
86+
87+
### Token redemption
88+
89+
```
90+
┌──────────┐ 1. Present token ┌──────────┐
91+
│ │ ──────────────────────────▶ │ │
92+
│ Client │ │ Privacy │
93+
│ │ ◀────────────────────────── │ Proxy │
94+
└──────────┘ 2. Connection OK └──────────┘
95+
```
96+
97+
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.
98+
99+
The token issuance process:
100+
101+
1. The client proves their identity to the attester (for example, by signing in with an account).
102+
2. The attester confirms the client is valid.
103+
3. The client generates blinded tokens and sends them to the issuer.
104+
4. The issuer signs the blinded tokens and returns them.
105+
5. The client unblinds the tokens and stores them.
106+
107+
When making a request:
108+
109+
1. The client includes a token in the `Proxy-Authorization` header.
110+
2. The proxy verifies the token signature with the issuer's public key.
111+
3. The proxy allows the connection if the token is valid.
112+
113+
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.
114+
115+
### Token format
116+
117+
Privacy Pass tokens are included in the `Proxy-Authorization` header using the `PrivateToken` scheme:
118+
119+
```http
120+
CONNECT example.com:443 HTTP/2
121+
Host: example.com
122+
Proxy-Authorization: PrivateToken token=<base64-encoded-token>
123+
```
124+
125+
### Set up Privacy Pass
126+
127+
For production deployments using Privacy Pass:
128+
129+
1. Choose an issuer. Cloudflare can operate a token issuer, or you can integrate with a third-party issuer.
130+
2. Configure attestation to define how clients prove their identity before receiving tokens.
131+
3. Distribute issuer configuration. Clients need the issuer's public key and endpoint to request tokens.
132+
133+
[Contact us](https://www.cloudflare.com/lp/privacy-edge/) to configure Privacy Pass for your deployment.
134+
135+
---
136+
137+
## Authentication in double-hop deployments
138+
139+
In [double-hop deployments](/privacy-proxy/concepts/deployment-models/#double-hop), authentication occurs at two levels:
140+
141+
### User to Proxy A
142+
143+
Proxy A (which you operate) authenticates users. Common methods include:
144+
145+
- Account credentials (username/password, SSO)
146+
- Privacy Pass tokens issued by your infrastructure
147+
- Client certificates (mTLS)
148+
149+
### Proxy A to Proxy B
150+
151+
Proxy B authenticates itself to Proxy A using TLS. Depending on your configuration, this can use:
152+
153+
- Standard TLS certificates
154+
- Raw Public Key (RPK) TLS extension for reduced certificate overhead
155+
156+
---
157+
158+
## Related resources
159+
160+
- [Privacy Pass Working Group](https://datatracker.ietf.org/wg/privacypass/about/) - IETF working group developing the Privacy Pass protocol.
161+
- [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.

‎src/content/docs/privacy-proxy/concepts/deployment-models.mdx‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: Deployment models
3+
pcx_content_type: concept
4+
sidebar:
5+
order: 2
6+
---
7+
8+
Privacy Proxy supports two deployment architectures: single-hop and double-hop. The right choice depends on your privacy requirements and operational preferences.
9+
10+
## Single-hop
11+
12+
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.
13+
14+
```
15+
┌────────┐ ┌─────────────────┐ ┌─────────────┐
16+
│ Client │ ───▶ │ Privacy Proxy │ ───▶ │ Destination │
17+
│ │ │ (Cloudflare) │ │ Server │
18+
└────────┘ └─────────────────┘ └─────────────┘
19+
```
20+
21+
### How it works
22+
23+
1. The client establishes an HTTP/2 or HTTP/3 connection to the Cloudflare proxy endpoint.
24+
2. The client authenticates using Privacy Pass tokens or a pre-shared key.
25+
3. The client sends CONNECT requests to establish tunnels to destination servers.
26+
4. Cloudflare proxies traffic and selects egress IP addresses based on client geolocation.
27+
28+
### Use cases
29+
30+
Single-hop deployment works well when:
31+
32+
- You want Cloudflare to manage the complete proxy infrastructure.
33+
- Your privacy model requires hiding client IP addresses from destinations, but not from the proxy operator.
34+
- You need a straightforward integration with minimal client-side changes.
35+
36+
#### Example: Microsoft Edge Secure Network
37+
38+
[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.
39+
40+
---
41+
42+
## Double-hop
43+
44+
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.
45+
46+
```
47+
┌────────┐ ┌─────────────┐ ┌─────────────────┐ ┌─────────────┐
48+
│ Client │ ───▶ │ Proxy A │ ───▶ │ Proxy B │ ───▶ │ Destination │
49+
│ │ │ (You) │ │ (Cloudflare) │ │ Server │
50+
└────────┘ └─────────────┘ └─────────────────┘ └─────────────┘
51+
```
52+
53+
### How it works
54+
55+
1. The client connects to Proxy A, which you operate.
56+
2. Proxy A authenticates the user and verifies they can use the service.
57+
3. Proxy A establishes a tunnel to Cloudflare's Proxy B, forwarding the client's CONNECT request.
58+
4. Proxy B connects to the destination and proxies traffic.
59+
5. Proxy B selects egress IPs based on geolocation provided by Proxy A.
60+
61+
### Privacy separation
62+
63+
The double-hop architecture ensures:
64+
65+
| Information | Proxy A (you) | Proxy B (Cloudflare) |
66+
| ------------- | --------------- | ---------------------- |
67+
| Client IP address | Yes | No |
68+
| User account | Yes | No |
69+
| Destination server | Encrypted | Yes |
70+
| Request content | Encrypted | Encrypted |
71+
72+
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.
73+
74+
### Use cases
75+
76+
Double-hop deployment works well when:
77+
78+
- You need stronger privacy guarantees where no single operator sees both identity and destination.
79+
- You want to maintain control over user authentication and account management.
80+
- Regulatory or compliance requirements mandate separation of user data.
81+
82+
#### Example: iCloud Private Relay
83+
84+
[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.
85+
86+
---
87+
88+
## Comparison
89+
90+
| Aspect | Single-hop | Double-hop |
91+
| -------- | ------------ | ------------ |
92+
| Infrastructure | Cloudflare only | You + Cloudflare |
93+
| Privacy separation | Proxy sees identity + destination | Split across two parties |
94+
| Operational complexity | Lower | Higher |
95+
| Authentication | Cloudflare-managed | You manage first-hop auth |
96+
| Use case | Browser VPNs, simple privacy | Maximum privacy separation |
97+
98+
---
99+
100+
## Choose a deployment model
101+
102+
Consider these questions when selecting a deployment model:
103+
104+
1. Who should manage user authentication?
105+
106+
If you want Cloudflare to handle authentication, use single-hop. If you need control over user accounts, use double-hop.
107+
108+
2. What are your privacy requirements?
109+
110+
If your threat model requires that no single party sees both user identity and browsing activity, use double-hop.
111+
112+
3. What operational capacity do you have?
113+
114+
Double-hop requires you to operate and maintain a proxy. If you prefer a fully managed solution, use single-hop.
115+
116+
[Contact us](https://www.cloudflare.com/lp/privacy-edge/) to discuss which deployment model fits your use case.

‎src/content/docs/privacy-proxy/concepts/geolocation.mdx‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: Geolocation
3+
pcx_content_type: concept
4+
sidebar:
5+
order: 4
6+
---
7+
8+
Privacy Proxy preserves user geolocation without exposing real IP addresses. This ensures location-based services work correctly while maintaining privacy.
9+
10+
## Why geolocation matters
11+
12+
Many online services use IP addresses to determine user location:
13+
14+
- Search engines return locally relevant results.
15+
- Content providers enforce regional licensing restrictions.
16+
- E-commerce sites show local pricing and shipping options.
17+
- News sites display region-specific content.
18+
19+
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.
20+
21+
## How geolocation works
22+
23+
Privacy Proxy uses geohashes to preserve location without revealing precise coordinates.
24+
25+
### Geohash encoding
26+
27+
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:
28+
29+
| Geohash length | Approximate area |
30+
| ---------------- | ------------------ |
31+
| 1 character | ~5,000 km |
32+
| 2 characters | ~1,250 km |
33+
| 3 characters | ~150 km |
34+
| 4 characters | ~40 km |
35+
| 5 characters | ~5 km |
36+
37+
Privacy Proxy uses reduced-precision geohashes (typically four to five characters) to locate users to a city or region without pinpointing their exact location.
38+
39+
### Egress IP selection
40+
41+
When a client connects to Privacy Proxy:
42+
43+
1. The client (or first-hop proxy in double-hop deployments) determines the user's approximate location.
44+
2. The client sends a geohash in the `sec-ch-geohash` header.
45+
3. Privacy Proxy validates the geohash and selects an egress IP address from a pool registered to that geographic area.
46+
4. Destination servers see the egress IP and geolocate the user to the correct region.
47+
48+
### Geohash header format
49+
50+
The `sec-ch-geohash` header includes the geohash and country code:
51+
52+
```http
53+
sec-ch-geohash: xn76c-JP
54+
```
55+
56+
The format is `<geohash>-<country_code>`. The country code helps resolve edge cases where geohashes span country borders.
57+
58+
## Geolocation accuracy
59+
60+
Cloudflare maintains egress IP pools in hundreds of cities worldwide. When you register egress IPs with geolocation databases, they map to specific locations.
61+
62+
Privacy Proxy achieves:
63+
64+
- **City-level accuracy** by default, so users get locally relevant search results.
65+
- **Country-level accuracy** as a fallback if city-level is not available.
66+
67+
Users can opt for coarser geolocation (country and timezone only) if they prefer less precise location sharing.
68+
69+
### The pizza test
70+
71+
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.
72+
73+
## IPv6 and geolocation precision
74+
75+
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.
76+
77+
To maximize geolocation accuracy for your users, ensure your services are reachable over IPv6.
78+
79+
## Geolocation in double-hop deployments
80+
81+
In [double-hop deployments](/privacy-proxy/concepts/deployment-models/#double-hop), Proxy A (which you operate) is responsible for determining and forwarding the geohash:
82+
83+
1. Proxy A geolocates the client's IP address.
84+
2. Proxy A converts the location to a geohash with appropriate precision.
85+
3. Proxy A includes the geohash in the forwarded CONNECT request to Proxy B.
86+
4. Proxy B (Cloudflare) selects an egress IP based on the geohash.
87+
88+
The geohash is cryptographically protected to prevent clients from spoofing their location.
89+
90+
## Related resources
91+
92+
- [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.

0 commit comments

Comments
 (0)