README

   1 README
   2 ======
   3
   4 tlsproxy is a TLS proxy for HTTPS which intercepts the connections and ensures
   5 the server certificate doesn't change. Normally this isn't detected if a
   6 trusted CA for the new server certificate is installed.
   7
   8 tlsproxy is licensed under GPL 3 (or later).
   9
  10
  11 REQUIREMENTS
  12 ------------
  13
  14 - GnuTLS library including development headers
  15 - certtool (from by GnuTLS) to create TLS certificates
  16
  17
  18 USAGE
  19 -----
  20
  21 To use tlsproxy you must first run `tlsproxy-setup` in an (empty) directory.
  22 This creates the following files:
  23
  24 - `proxy-ca.pem`:      CA which is used for all connections to the client
  25 - `proxy-ca-key.pem`:  private key for the CA
  26 - `proxy-key.pem`:     private key for the server
  27 - `proxy-invalid.pem`: special certificate used for invalid pages
  28
  29 Then import the CA file `proxy-ca.pem` in your browser so it can validate the
  30 pages sent by the proxy.
  31
  32 For each page you want to visit securely you must first obtain its server
  33 certificate (in PEM format) (for example with `gnutls-cli --print-cert server`
  34 - you need the first certificate). The next step is to _validate_ it. The
  35 proxy doesn't perform any validation thus it's important that you make sure
  36 the server certificate is the correct one!
  37
  38 Then run `tlsproxy-add hostname path-to-certificate` in the same directory as
  39 above. This creates the following files:
  40
  41 - `certificate-example.org-proxy.pem`: certificate used by the proxy for the
  42   connection to the client
  43 - `certificate-example.org-server.pem`: original server certificate, used to
  44   check if the current server certificate changed
  45
  46 If the validation is successful the proxy uses the `certificate-*-proxy.pem`
  47 certificate to secure the connection to the client (signed by `proxy-ca.pem`).
  48
  49 If an error occurs in the validation (missing `certificate-*.pem` files,
  50 fingerprint changed, etc.) it's logged by the proxy (stdout) and the special
  51 `proxy-invalid.pem` certificate is used. It's easy to spot in the browser
  52 because it uses an invalid hostname ("invalid") and is self-signed.
  53
  54 If an internal error occurs before the TLS connection can be established a 503
  55 Forwarding failure is sent to the client (unencrypted).