From: Simon Ruderich Date: Fri, 11 Mar 2011 23:49:34 +0000 (+0100) Subject: README: Add. X-Git-Tag: 0.1~1 X-Git-Url: https://ruderich.org/simon/gitweb/?a=commitdiff_plain;h=1b01c652600d44ff64e49fdc379342fea0d83839;p=tlsproxy%2Ftlsproxy.git README: Add. --- diff --git a/README b/README new file mode 100644 index 0000000..31a4a56 --- /dev/null +++ b/README @@ -0,0 +1,55 @@ +README +====== + +tlsproxy is a TLS proxy for HTTPS which intercepts the connections and ensures +the server certificate doesn't change. Normally this isn't detected if a +trusted CA for the new server certificate is installed. + +tlsproxy is licensed under GPL 3 (or later). + + +REQUIREMENTS +------------ + +- GnuTLS library including development headers +- certtool (from by GnuTLS) to create TLS certificates + + +USAGE +----- + +To use tlsproxy you must first run `tlsproxy-setup` in an (empty) directory. +This creates the following files: + +- `proxy-ca.pem`: CA which is used for all connections to the client +- `proxy-ca-key.pem`: private key for the CA +- `proxy-key.pem`: private key for the server +- `proxy-invalid.pem`: special certificate used for invalid pages + +Then import the CA file `proxy-ca.pem` in your browser so it can validate the +pages sent by the proxy. + +For each page you want to visit securely you must first obtain its server +certificate (in PEM format) (for example with `gnutls-cli --print-cert server` +- you need the first certificate). The next step is to _validate_ it. The +proxy doesn't perform any validation thus it's important that you make sure +the server certificate is the correct one! + +Then run `tlsproxy-add hostname path-to-certificate` in the same directory as +above. This creates the following files: + +- `certificate-example.org-proxy.pem`: certificate used by the proxy for the + connection to the client +- `certificate-example.org-server.pem`: original server certificate, used to + check if the current server certificate changed + +If the validation is successful the proxy uses the `certificate-*-proxy.pem` +certificate to secure the connection to the client (signed by `proxy-ca.pem`). + +If an error occurs in the validation (missing `certificate-*.pem` files, +fingerprint changed, etc.) it's logged by the proxy (stdout) and the special +`proxy-invalid.pem` certificate is used. It's easy to spot in the browser +because it uses an invalid hostname ("invalid") and is self-signed. + +If an internal error occurs before the TLS connection can be established a 503 +Forwarding failure is sent to the client (unencrypted).