From: Simon Ruderich <simon@ruderich.org>
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).