Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Privacy Gateway] onboarding guide #18646

Open
wants to merge 3 commits into
base: production
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion src/content/docs/privacy-gateway/get-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Get started
pcx_content_type: get-started
sidebar:
order: 3
order: 2

---

Expand Down
79 changes: 79 additions & 0 deletions src/content/docs/privacy-gateway/privacy-proxy-onboarding.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
title: Privacy Proxy Onboarding Guide
pcx_content_type: how-to
sidebar:
order: 3

---

## System overview

The Cloudflare Privacy Proxy consists of a generic HTTPS CONNECT (and CONNECT-UDP ) proxy.
These may be used to ensure that knowledge of sensitive user information leaked in web traffic is not only available to those that need it to function.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
These may be used to ensure that knowledge of sensitive user information leaked in web traffic is not only available to those that need it to function.
These proxies ensure sensitive user information in web traffic is only accessible to those requiring it for functionality.


A high level overview of the system is shown below. Control plane services are shown in orange, whereas dataplane services are shown in blue.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A high level overview of the system is shown below. Control plane services are shown in orange, whereas dataplane services are shown in blue.
A high-level overview of how the the Prixacy Proxy works is shown below. Control plane services are shown in orange. Dataplane services are shown in blue.


![Privacy Proxy system overview](~/assets/images/privacy-gateway/privacy-proxy-system-overview.png)

The following components comprise the Privacy Proxy system:

- **Client**: The end-user making HTTP requests via the Privacy Proxy from within a web browser and/or other supported client.
- **Attester**: The client-facing service that authenticates the validity of end-user accounts, validates entitlements, and requests a PAT from the issuer on behalf of the end-user. Not operated by Cloudflare.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Attester**: The client-facing service that authenticates the validity of end-user accounts, validates entitlements, and requests a PAT from the issuer on behalf of the end-user. Not operated by Cloudflare.
- **Attester**: The client-facing service that authenticates the validity of end-user accounts, validates entitlements, and requests a Private Access Token (PAT) from the issuer on behalf of the end user. Not operated by Cloudflare.

- **Privacy API**: Cloudflare service that issues PATs to the client for redemption against the Privacy Proxy service. This service mints Private Access Tokens (PATs) using the RSA blind signature protocol.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Privacy API**: Cloudflare service that issues PATs to the client for redemption against the Privacy Proxy service. This service mints Private Access Tokens (PATs) using the RSA blind signature protocol.
- **Privacy API**: Cloudflare service that issues PATs to the client for redemption against the Privacy Proxy service. Cloudflare Privacy Proxy mints Private Access Tokens (PATs) using the RSA blind signature protocol.

- **Privacy Proxy**: The HTTP CONNECT-based proxy service running on Cloudflare’s edge. This service validates the PAT passed by the client, enforces any double spend prevention necessary for the token. The service handles proxying of the wrapped HTTP request, as well as selection of the egress path and IP.
deadlypants1973 marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Privacy Proxy**: The HTTP CONNECT-based proxy service running on Cloudflares edge. This service validates the PAT passed by the client, enforces any double spend prevention necessary for the token. The service handles proxying of the wrapped HTTP request, as well as selection of the egress path and IP.
- **Privacy Proxy**: The HTTP CONNECT-based proxy service running on Cloudflare's edge. Privacy Proxy validates the PAT passed by the client, enforces any double spend prevention necessary for the token. Privacy Proxy handles proxying of the wrapped HTTP request, as well as selection of the egress path and IP.

@mari the second sentence seems incomplete, is there supposed to be an "and" after "client," and before "enforces"?

- **Origin**: The external (target) website for the end-user request.

DNS resolution uses [Cloudflare’s public resolver (1.1.1.1)](/1.1.1.1/) infrastructure for name resolution.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
DNS resolution uses [Cloudflares public resolver (1.1.1.1)](/1.1.1.1/) infrastructure for name resolution.
DNS resolution uses [Cloudflare's public resolver (1.1.1.1)](/1.1.1.1/) infrastructure for name resolution.

Issues:

  • Style Guide - (cloudflare.NonStandardQuotes-warning) Use standard single quotes or double quotes only. Do not use any of the following quote mark types: ‘ ’ “ ”. In the text, we found this character: ’

Fix Explanation:

The non-standard single quote ’ should be replaced with the standard single quote ' to comply with the style guide. This change ensures consistency and adherence to the style guidelines.


### System architecture
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mari Is the "system" in question here the "Privacy Proxy architecture"?


![System architecture](~/assets/images/privacy-gateway/system-architecture.png)

### Client initialization

A client requires configuration data (the region public key) to request tokens. The key is used to initialize the request for blinded tokens from the Privacy API.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A client requires configuration data (the region public key) to request tokens. The key is used to initialize the request for blinded tokens from the Privacy API.
A client requires configuration data (the region public key) to request tokens. The region public key is used to initialize the request for blinded tokens from the Privacy API.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mari are the tokens mentioned here "privacy access tokens"? or just "tokens"?


The client should periodically refresh this public key, especially after IP address changes, since Cloudflare will use the IP address to map to the region.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mari "periodically refresh this public key" or "periodically refresh the region public key"?


This key should be kept in the client session across multiple requests.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This key should be kept in the client session across multiple requests.
The region public key should be kept in the client session across multiple requests.


![Client initialization](~/assets/images/privacy-gateway/client-initialization.png)

### Token issuance

After the client is configured, it will need privacy tokens in order to make requests.

When the token pool is low/empty, the client can use the stored region public key to create a batch of new blinded token requests to send to the Privacy API through the Token Proxy.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When the token pool is low/empty, the client can use the stored region public key to create a batch of new blinded token requests to send to the Privacy API through the Token Proxy.
When the token pool is low/empty, the client can use the stored region public key to create a batch of new blinded token requests to send to the Privacy API through the Token Proxy.

@mari

  1. "token pool" or "privacy token pool"?


The Privacy API signs the tokens and returns them to the client, which can store them in a pool for later use.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mari "tokens" or "privacy tokens"?


![Token issuance](~/assets/images/privacy-gateway/token-issuance.png)

### Example client code

Cloudflare will provide access to a MASQUE client, which can be used in mobile client code to connect to the MASQUE proxy provided by Cloudflare. For example:

```sh
cargo run --bin quiche-client -- \
--no-verify \
--connect-to masque-relay.cloudflare.com \
--connect-type=HTTP \
https://example.com
```

### HTTP (Web) request flow

Once the client needs to make a connection to a new server, it can connect to the Cloudflare Proxy service and request a connection to the origin with a token in the ` Proxy-Authorization ` HTTP request header.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Once the client needs to make a connection to a new server, it can connect to the Cloudflare Proxy service and request a connection to the origin with a token in the ` Proxy-Authorization ` HTTP request header.
Once the client needs to make a connection to a new server, the client can connect to the Cloudflare Proxy service and request a connection to the origin with a token in the ` Proxy-Authorization ` HTTP request header.

@mari

  1. "Cloudflare Proxy service" or "Cloudflare Privacy Proxy service"?
  2. is this a specific kind of token (Private Access Token)? Or do we leave it as "token"?


This connection can be kept alive for multiple requests/responses from the server.

![HTTP request flow](~/assets/images/privacy-gateway/http-request-flow.png)

## Environments

Cloudflare will provide access to both development and production environments.
Credentials are shared across both environments.

| Environment | Endpoint | Description | |
|--------------------- | -------------- |-----------|
| | | |
Loading