Skip to content
Newer
Older
100644 109 lines (72 sloc) 5.76 KB
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
1 # SPDY Proxy
2
31d2486 @igrigorik readme improvements
authored Jun 22, 2012
3 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]). Use cases:
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
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
7
25d3bd1 @igrigorik add PAC examples
authored Jun 24, 2012
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:
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
9
ea4d63b @igrigorik add images to readme
authored Jun 24, 2012
10 ![SPDY Proxy Diagram](http://www.igvita.com/posts/12/spdyproxy-diagram.png)
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
11
31d2486 @igrigorik readme improvements
authored Jun 22, 2012
12 * All browser <-> proxy communication is done over SSL
13 * SPDY Proxy and Chrome communicate via SPDY (v2)
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
14 * Browser requests are routed via SPDY proxy to destination
15
31d2486 @igrigorik readme improvements
authored Jun 22, 2012
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!
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
17
18 Same logic applies for tunelling SPDY! We can establish a SPDY v2 tunnel to the proxy, and then tunnel SPDY v3 connections over it.
19
20 ## Installation & Configuration
21
22 SPDY proxy requires node.js 0.7.x+. To install:
23
24 ```bash
25 $> git clone git://github.com/joyent/node.git && cd node
26 $> ./configure --prefix=$HOME/.node/dev # <- or any other dir
27
28 $> make install -j4 # in -jN, N is number of CPU cores on your machine
29
30 # Add node's bin to PATH env variable
31 $> echo 'export PATH=$HOME/.node/dev/bin:$PATH' >> ~/.bashrc
32 ```
33
34 Once node.js is installed, you can use npm (node package manager) to install SPDY Proxy:
35
36 ```bash
37 $> npm install -g spdyproxy
38 $> spdyproxy --help
39 ```
40
41 To run the proxy, you need to provide your SSL keys:
42
43 ```bash
d328d50 @igrigorik add SSL key instructions + sample localhost keys
authored Jun 24, 2012
44 $> spdyproxy -k keys/mykey.pem -c keys/mycert.pem -p 44300
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
45 ```
46
47 With that, you should have a SPDY proxy running on port 44300.
48
49 ## Configuring Google Chrome
50
51 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:
52
53 ```javascript
54 function FindProxyForURL(url, host) {
55 return "HTTPS proxy.example.com:8080; DIRECT";
56 }
57 ```
58
25d3bd1 @igrigorik add PAC examples
authored Jun 24, 2012
59 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.
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
60
61 ## DIY demo setup
62
31d2486 @igrigorik readme improvements
authored Jun 22, 2012
63 To do a quick local test, start the SPDY proxy on your machine, and start Chrome with the `--proxy-pac-url` flag:
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
64
65 ```bash
d328d50 @igrigorik add SSL key instructions + sample localhost keys
authored Jun 24, 2012
66 $> spdyproxy -k keys/mykey.pem -c keys/mycert.pem -p 44300 -v
25d3bd1 @igrigorik add PAC examples
authored Jun 24, 2012
67 $> "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --proxy-pac-url=file:///path/to/config.pac --use-npn
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
68 ```
69
ea4d63b @igrigorik add images to readme
authored Jun 24, 2012
70 ![SPDY Proxy](http://www.igvita.com/posts/12/spdyproxy-demo.png)
71
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
72 ## Securing the proxy
73
d328d50 @igrigorik add SSL key instructions + sample localhost keys
authored Jun 24, 2012
74 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:
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
75
76 ```bash
d328d50 @igrigorik add SSL key instructions + sample localhost keys
authored Jun 24, 2012
77 $> openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.pem -out mycert.pem
78
79 # on OSX, you now need to manually add mycert.pem to your keychain (for local testing)
80 # -> lauch Keychain app, drag the key into the app, and mark it as accepted
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
81 ```
82
31d2486 @igrigorik readme improvements
authored Jun 22, 2012
83 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.
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
84
25d3bd1 @igrigorik add PAC examples
authored Jun 24, 2012
85 ```bash
86 # pass in -U and -P flags to spdyproxy to set the Basic-Auth username and password
d328d50 @igrigorik add SSL key instructions + sample localhost keys
authored Jun 24, 2012
87 $> spdyproxy -k keys/mykey.pem -c keys/mycert.pem -p 44300 -U user -P pass
25d3bd1 @igrigorik add PAC examples
authored Jun 24, 2012
88 ```
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
89
90 ### Other resources
91
92 * [Web VPN: Secure proxies with SPDY & Chrome][spdy-vpn]
93 * [SPDY proxy examples on chromium.org][spdy-examples]
94 * [PAC wikipedia page][pac]
d328d50 @igrigorik add SSL key instructions + sample localhost keys
authored Jun 24, 2012
95 * [Creating an SSL Certificate Signing Request][csr]
96 * [Creating a Self-Signed SSL Certificate][self-signed]
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
97
d328d50 @igrigorik add SSL key instructions + sample localhost keys
authored Jun 24, 2012
98 ### License
99
100 (MIT License) - Copyright (c) 2012 Ilya Grigorik
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
101
102 [spdy-vpn]: http://www.igvita.com/2011/12/01/web-vpn-secure-proxies-with-spdy-chrome/
25d3bd1 @igrigorik add PAC examples
authored Jun 24, 2012
103 [npn]: https://technotes.googlecode.com/git/nextprotoneg.html
104 [npn-rfc]: http://tools.ietf.org/html/draft-agl-tls-nextprotoneg-00
c367544 @igrigorik first pass over readme
authored Jun 22, 2012
105 [pac]: http://en.wikipedia.org/wiki/Proxy_auto-config
106 [spdy-examples]: http://dev.chromium.org/spdy/spdy-proxy-examples
d328d50 @igrigorik add SSL key instructions + sample localhost keys
authored Jun 24, 2012
107 [csr]: https://devcenter.heroku.com/articles/csr)
108 [self-signed]: https://devcenter.heroku.com/articles/ssl-certificate-self
Something went wrong with that request. Please try again.