PerProxy is a HTTPS proxy that uses Perspectives [1] to monitor
SSL connections, detect and thwart SSL attempts using fradulent
certificates (e.g. [3,4]). It is not in any way intended to replace
the Perspectives Firefox extension [2], but to serve in instances when
the extension cannot be used (e.g. you are using another browser, a
version of Firefox that doesn't support the extension).

Note that PerProxy has only been tested with Firefox 4.x.

PerProxy acts as a SSL MITM, accepting SSL credentials from the
browser and making certificates on the fly to imitate the expected
server.

PerProxy is a proof of concept and is no longer being developed.

==INSTALLATION==

Prerequisites:

* M2Crypto: http://chandlerproject.org/Projects/MeTooCrypto

* argparse: https://code.google.com/p/argparse/  - comes with Python 2.7+

* pyPerspecties: https://github.com/von/pyPerspectives - python client
code for Perspectives. Version 0.2 or later required.

--------------------

To install, run:

sudo setup.py install

Which will install the perproxy into your local site-packages and the
PerProxy scipts into the appropriate python bin/ directory
(e.g. /Library/Frameworks/Python.framework/Versions/2.7/bin/)

The next step is to create a CA certificate for PerProxy to use:

 /Library/Frameworks/Python.framework/Versions/2.7/bin/perproxy-create-ca

This will create ~/.PerProxy/ca-cert.crt and ~/.PerProxy/ca-key.pem

Then you need to load the newly create CA certificate into your
browser. With FireFox, you just need to open the certificate, e.g. use
a URL such as:

file:///path/to/~/.PerProxy/ca-cert.crt

And you will be prompted and walked through the process.

Then you can fire up PerProxy (use '-d' for debug mode will probably
be most useful):

/Library/Frameworks/Python.framework/Versions/2.7/bin/PerProxy -d

Then configure your web browser to use port localhost:8080 as a HTTPS
proxy. With FireFox this is under Preferences, Advanced, Network,
Connection, Settings. Select "Manual proxy configuration" and for "SSL
Proxy" enter "localhost" and "8080". Click OK to save. (Using an
add-on such as QuickProxy will let you turn this setting on and off
easily.)

Now connect to an HTTPS website and watch the output from PerProxy.

Please report comments, issues, bugs, etc. at https://github.com/von/PerProxy

==DETAILS==

Here is how PerProxy currently works:

* It acts as an HTTPS proxy, receiving and parsing a CONNECT message
from the client browser to obtain the target hostname.

* It connects to the target server.

** If the target server's certificate is in the cache, it proceeds.

** If the target server's certificate is not in the cache, it queries
Perspectives notaries to validate the target server certificate. On
success it puts the certificate into the cache.

** On failure, an error is returned to the client browser (see Note
below) and the connection is closed.

* A SSL conection is established back to the client and all data is
passed through between the two.

Note: All error handling is very rudimentary right now. PerProxy will
logs errors and a HTML web page is returned to the client. The HTML
will be displayed only for primary pages though, if the request is for
an image or other element of a page, it likely gets swallowed by the
browser.

--------------------

This code is freely distributed under an MIT license [6].

--------------------

[1] http://www.networknotary.org/
[2] http://www.networknotary.org/firefox.html
[3] https://www.eff.org/deeplinks/2011/03/iranian-hackers-obtain-fraudulent-https
[4] http://crypto.stanford.edu/ssl-mitm/
[5] https://github.com/danwent/Perspectives-Server
[6] http://www.opensource.org/licenses/mit-license.php