Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 100 lines (67 sloc) 5.883 kb
c3675441 »
2012-06-22 first pass over readme
1 # SPDY Proxy
2
7d2f16f7 »
2012-06-25 moar better readme + link to StartSSL
3 Google Chrome comes with built-in support for SSL-based proxies, which means that we can give Chrome an HTTPS proxy URL, and the rest is taken care of: a TLS tunnel is first established to the proxy, and the proxied requests are sent over a secure link. No eavesdropping allowed! This is a huge improvement over regular HTTP proxies, which can also tunnel SSL, but in the process leak information about the site we're connecting to - [read more about Chrome and secure proxies][chrome-secure]. This allow a number of new and interesting use cases:
31d24865 »
2012-06-22 readme improvements
4
5 * End-to-end secure browsing for *all* sites (HTTP, HTTPS, SPDY) - no sniffing!
6 * Web VPN: secure access to internal servers and services without relying on heavy TCP VPN solutions
c3675441 »
2012-06-22 first pass over readme
7
25d3bd18 »
2012-06-24 add PAC examples
8 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][npn] ([RFC][npn-rfc]). If both sides support SPDY, then all communication between browser and proxy can be done over SPDY:
c3675441 »
2012-06-22 first pass over readme
9
7d2f16f7 »
2012-06-25 moar better readme + link to StartSSL
10 ![SPDY Proxy Diagram](http://www.igvita.com/posts/12/spdyproxy-diagram.png)
c3675441 »
2012-06-22 first pass over readme
11
31d24865 »
2012-06-22 readme improvements
12 * All browser <-> proxy communication is done over SSL
13 * SPDY Proxy and Chrome communicate via SPDY (v2)
c3675441 »
2012-06-22 first pass over readme
14 * Browser requests are routed via SPDY proxy to destination
15
31d24865 »
2012-06-22 readme improvements
16 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 - we're tunneling SSL over SSL!
c3675441 »
2012-06-22 first pass over readme
17
7d2f16f7 »
2012-06-25 moar better readme + link to StartSSL
18 Same logic applies for tunneling SPDY! We can establish a SPDY v2 tunnel to the proxy, and then tunnel SPDY v3 connections over it.
c3675441 »
2012-06-22 first pass over readme
19
20 ## Installation & Configuration
21
604ef0fb »
2012-06-25 woot, can use 0.8.0, no need for custom builds!
22 SPDY proxy requires node.js 0.8.x+. Grab the [package for your platform](http://nodejs.org/) from the node site. Once node.js is installed, you can use npm (node package manager) to install SPDY Proxy:
c3675441 »
2012-06-22 first pass over readme
23
24 ```bash
25 $> npm install -g spdyproxy
26 $> spdyproxy --help
27 ```
28
29 To run the proxy, you need to provide your SSL keys:
30
31 ```bash
d328d501 »
2012-06-24 add SSL key instructions + sample localhost keys
32 $> spdyproxy -k keys/mykey.pem -c keys/mycert.pem -p 44300
c3675441 »
2012-06-22 first pass over readme
33 ```
34
35 With that, you should have a SPDY proxy running on port 44300.
36
37 ## Configuring Google Chrome
38
39 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:
40
41 ```javascript
42 function FindProxyForURL(url, host) {
43 return "HTTPS proxy.example.com:8080; DIRECT";
44 }
45 ```
46
25d3bd18 »
2012-06-24 add PAC examples
47 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](https://github.com/igrigorik/node-spdyproxy/tree/master/pac) for examples.
c3675441 »
2012-06-22 first pass over readme
48
49 ## DIY demo setup
50
31d24865 »
2012-06-22 readme improvements
51 To do a quick local test, start the SPDY proxy on your machine, and start Chrome with the `--proxy-pac-url` flag:
c3675441 »
2012-06-22 first pass over readme
52
53 ```bash
d328d501 »
2012-06-24 add SSL key instructions + sample localhost keys
54 $> spdyproxy -k keys/mykey.pem -c keys/mycert.pem -p 44300 -v
25d3bd18 »
2012-06-24 add PAC examples
55 $> "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --proxy-pac-url=file:///path/to/config.pac --use-npn
c3675441 »
2012-06-22 first pass over readme
56 ```
57
ea4d63b0 »
2012-06-24 add images to readme
58 ![SPDY Proxy](http://www.igvita.com/posts/12/spdyproxy-demo.png)
59
c3675441 »
2012-06-22 first pass over readme
60 ## Securing the proxy
61
d328d501 »
2012-06-24 add SSL key instructions + sample localhost keys
62 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 client keychain - otherwise, the browser will terminate the connection. To create a self-signed certificate:
c3675441 »
2012-06-22 first pass over readme
63
64 ```bash
d328d501 »
2012-06-24 add SSL key instructions + sample localhost keys
65 $> openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.pem -out mycert.pem
66
67 # on OSX, you now need to manually add mycert.pem to your keychain (for local testing)
68 # -> lauch Keychain app, drag the key into the app, and mark it as accepted
c3675441 »
2012-06-22 first pass over readme
69 ```
70
7d2f16f7 »
2012-06-25 moar better readme + link to StartSSL
71 **Protip**: You can get a free, signed SSL certificate for your domain via [StartSSL](http://www.startssl.com/).
72
31d24865 »
2012-06-22 readme improvements
73 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 secure! 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.
c3675441 »
2012-06-22 first pass over readme
74
25d3bd18 »
2012-06-24 add PAC examples
75 ```bash
76 # pass in -U and -P flags to spdyproxy to set the Basic-Auth username and password
d328d501 »
2012-06-24 add SSL key instructions + sample localhost keys
77 $> spdyproxy -k keys/mykey.pem -c keys/mycert.pem -p 44300 -U user -P pass
25d3bd18 »
2012-06-24 add PAC examples
78 ```
c3675441 »
2012-06-22 first pass over readme
79
80 ### Other resources
81
7d2f16f7 »
2012-06-25 moar better readme + link to StartSSL
82 * [SPDY & Secure Proxy Support in Google Chrome][chrome-secure]
c3675441 »
2012-06-22 first pass over readme
83 * [Web VPN: Secure proxies with SPDY & Chrome][spdy-vpn]
84 * [SPDY proxy examples on chromium.org][spdy-examples]
604ef0fb »
2012-06-25 woot, can use 0.8.0, no need for custom builds!
85 * [Proxy Auto Configuration][pac]
d328d501 »
2012-06-24 add SSL key instructions + sample localhost keys
86 * [Creating an SSL Certificate Signing Request][csr]
87 * [Creating a Self-Signed SSL Certificate][self-signed]
c3675441 »
2012-06-22 first pass over readme
88
d328d501 »
2012-06-24 add SSL key instructions + sample localhost keys
89 ### License
90
91 (MIT License) - Copyright (c) 2012 Ilya Grigorik
c3675441 »
2012-06-22 first pass over readme
92
7d2f16f7 »
2012-06-25 moar better readme + link to StartSSL
93 [chrome-secure]: http://www.igvita.com/2012/06/25/spdy-and-secure-proxy-support-in-google-chrome/
c3675441 »
2012-06-22 first pass over readme
94 [spdy-vpn]: http://www.igvita.com/2011/12/01/web-vpn-secure-proxies-with-spdy-chrome/
25d3bd18 »
2012-06-24 add PAC examples
95 [npn]: https://technotes.googlecode.com/git/nextprotoneg.html
96 [npn-rfc]: http://tools.ietf.org/html/draft-agl-tls-nextprotoneg-00
c3675441 »
2012-06-22 first pass over readme
97 [pac]: http://en.wikipedia.org/wiki/Proxy_auto-config
98 [spdy-examples]: http://dev.chromium.org/spdy/spdy-proxy-examples
d328d501 »
2012-06-24 add SSL key instructions + sample localhost keys
99 [csr]: https://devcenter.heroku.com/articles/csr)
100 [self-signed]: https://devcenter.heroku.com/articles/ssl-certificate-self
Something went wrong with that request. Please try again.