Permalink
Browse files

first pass over readme

  • Loading branch information...
1 parent 172db67 commit c36754413a4521d145f2f811b6f9404c040e699a @igrigorik committed Jun 22, 2012
Showing with 105 additions and 0 deletions.
  1. +1 −0 .gitignore
  2. +92 −0 README.md
  3. +12 −0 pac/secure.pac
View
@@ -1,2 +1,3 @@
misc
+node_modules
keys
View
@@ -0,0 +1,92 @@
+# SPDY Proxy
+
+Google Chrome supports SPDY/HTTPS as a forward proxy type, which allow us to use Chrome in a number of use cases where HTTP proxies could not have been used before. When using an HTTPS proxy in Chrome, instead of sending a `CONNECT` request in cleartext and then creating the SSL tunnel (hence leaking information about the site we're connecting to), the browser and the proxy first negotiate an SSL session, and then the browser sends the proxy request. Hence, all communication is always encrypted over SSL, and nobody can listen in on what your browser is requesting - [read more][spdy-vpn].
+
+Where does SPDY fit in here? When the SSL handshake is done, the browser and the server can agree to establish a SPDY session by using [SSL NPN][ssl-npn]. If both sides support SPDY, then all communication between browser and proxy can be done over SPDY:
+
+[IMG]
+
+* All browser <> proxy communication is done over SSL
+* SPDY Proxy and Chrome communicate via SPDY
+* Browser requests are routed via SPDY proxy to destination
+
+Notice that we can route both HTTP and HTTPS requests through the SPDY tunnel. To establish an HTTPS session, the browser sends a `CONNECT` request to the proxy with the hostname of the secure server (ex, https://google.com), the proxy establishes the TCP connection and then simply transfers the encrypted bytes between the streams - the proxy only knows that you wanted to connect to Google, but cannot see any of your actual traffic.
+
+Same logic applies for tunelling SPDY! We can establish a SPDY v2 tunnel to the proxy, and then tunnel SPDY v3 connections over it.
+
+## Installation & Configuration
+
+SPDY proxy requires node.js 0.7.x+. To install:
+
+```bash
+$> git clone git://github.com/joyent/node.git && cd node
+$> ./configure --prefix=$HOME/.node/dev # <- or any other dir
+
+$> make install -j4 # in -jN, N is number of CPU cores on your machine
+
+# Add node's bin to PATH env variable
+$> echo 'export PATH=$HOME/.node/dev/bin:$PATH' >> ~/.bashrc
+```
+
+Once node.js is installed, you can use npm (node package manager) to install SPDY Proxy:
+
+```bash
+$> npm install -g spdyproxy
+$> spdyproxy --help
+```
+
+To run the proxy, you need to provide your SSL keys:
+
+```bash
+$> spdyproxy -k keys/mykey.pem -c keys/mycert.pem -a keys/mycsr.pem -p 44300
+```
+
+With that, you should have a SPDY proxy running on port 44300.
+
+## Configuring Google Chrome
+
+Google Chrome uses PAC (proxy auto-config) files to choose the appropriate proxy server for fetching any URL. The PAC file itself, is just a simple JavaScript function:
+
+```javascript
+function FindProxyForURL(url, host) {
+ return "HTTPS proxy.example.com:8080; DIRECT";
+}
+```
+
+The above file tells the browser to proxy all requests via a secure proxy on port 8080, and if the proxy fails, then try to connect directly to the host. However, the PAC file allows us to create *much* more interesting scenarios: proxy specific URLs or hostnames, proxy rules based on DNS resolution results, and more. See PAC directory for examples.
+
+## DIY demo setup
+
+To do a quick local test, start the SPDY proxy on your machine, and start Chrome with the `--proxy-pac-url` file:
+
+```bash
+$> spdyproxy -k keys/mykey.pem -c keys/mycert.pem -a keys/mycsr.pem -p 44300 -v
+$> "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome Canary" --proxy-pac-url=file:///path/to/config.pac --use-npn
+```
+
+## Securing the proxy
+
+To run a secure (SPDY) proxy your will need a valid SSL certificate on the server, and also make sure that your client will accept this certificate without any errors. If you're generating a self-signed certificate, then you will need to manually import it into your keychain on the client - otherwise, the browser will terminate the connection. If you don't have a set of existing certificates you can use, follow these steps:
+
+```bash
+$> TODO
+```
+
+Once the proxy server is running, it is accessible by any client that wants to use it. To restrict access, you can use regular firewall rules, IP blacklists, etc. Alternatively, SPDY proxy supports `Basic Auth` proxy authentication. Recall that all communication between client and server is done over SSL, hence all auth data is hidden! The first time your browser connects to the proxy, it will ask for a login and password. After that, the browser will automatically append the authentication headers.
+
+
+### Other resources
+
+* [Web VPN: Secure proxies with SPDY & Chrome][spdy-vpn]
+* [SPDY proxy examples on chromium.org][spdy-examples]
+* [PAC wikipedia page][pac]
+
+
+[spdy-vpn]: http://www.igvita.com/2011/12/01/web-vpn-secure-proxies-with-spdy-chrome/
+[ssl-npn]: http://tools.ietf.org/html/draft-agl-tls-nextprotoneg-00
+[pac]: http://en.wikipedia.org/wiki/Proxy_auto-config
+[spdy-examples]: http://dev.chromium.org/spdy/spdy-proxy-examples
+
+
+
+
View
@@ -0,0 +1,12 @@
+//
+// Route all requests through local SPDY proxy
+//
+
+function FindProxyForURL(url, host) {
+ // - no fallback mechanism
+ // - if proxy supports SPDY then SPDY tunnel will be negotiated
+ return "HTTPS localhost:44300";
+
+ // if proxy fails, connect directly
+ //return "HTTPS localhost:44300; DIRECT";
+}

0 comments on commit c367544

Please sign in to comment.