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 to send a 500 error message to the
client. The connection to the server is closed so there's no chance that any
client data is sent to the (possible) evil server. The invalide certificate is
also 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).