]> ruderich.org/simon Gitweb - tlsproxy/tlsproxy.git/blob - README
tests: Fix tlsproxy_add() for `make distcheck`.
[tlsproxy/tlsproxy.git] / 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 - C89 compiler
15 - GnuTLS library including development headers
16 - certtool (from GnuTLS) to create TLS certificates
17
18
19 USAGE
20 -----
21
22 To use tlsproxy you must first run `tlsproxy-setup` in an (empty) directory.
23 This creates the following files:
24
25 - `proxy-ca.pem`:      CA which is used for all connections to the client
26 - `proxy-ca-key.pem`:  private key for the CA
27 - `proxy-key.pem`:     private key for the proxy
28 - `proxy-invalid.pem`: special certificate used for invalid pages
29
30 Then import the CA file `proxy-ca.pem` in your browser so it can validate the
31 pages sent by the proxy.
32
33 For each page you want to visit securely you must first obtain its server
34 certificate (in PEM format) (for example with `gnutls-cli --print-cert server`
35 - you need the first certificate). The next step is to _validate_ it. The
36 proxy doesn't perform any validation thus it's important that you make sure
37 the server certificate is the correct one!
38
39 Then run `tlsproxy-add hostname path-to-certificate` in the same directory as
40 above. This creates the following files:
41
42 - `certificate-example.org-proxy.pem`: certificate used by the proxy for the
43   connection to the client
44 - `certificate-example.org-server.pem`: original server certificate, used to
45   check if the current server certificate changed
46
47 If the validation is successful the proxy uses the `certificate-*-proxy.pem`
48 certificate to secure the connection to the client (signed by `proxy-ca.pem`).
49
50 If an error occurs in the validation (missing `certificate-*.pem` files,
51 fingerprint changed, etc.) it's logged by the proxy (stdout) and the special
52 `proxy-invalid.pem` certificate is used to send a 500 error message to the
53 client. The connection to the server is closed so there's no chance that any
54 client data is sent to the (possible) evil server. The invalid certificate is
55 also easy to spot in the browser because it uses an invalid hostname
56 ("invalid") and is self-signed.
57
58 If an internal error occurs before the TLS connection can be established a 503
59 Forwarding failure is sent to the client (unencrypted).
60
61
62 -u option
63 ~~~~~~~~~
64
65 The '-u' option passes through connections for hostnames with no stored
66 certificate (i.e. `certificate-*-server.pem` is missing or unreadable). In
67 this case the normal CA chain in your browser lets you validate the server
68 certificate. If the server certificate changes you're _not_ informed!
69
70 This option is useful if you often visit websites using HTTPS but you don't
71 use critical information (e.g. no passwords, etc.) on these websites.
72
73 For hostnames with a stored server certificate everything works as usual and a
74 certificate change is detected.
75
76 WARNING: The option might cause security problems if you're not careful:
77
78 For example you normally visit https://example.org/ and store the server
79 certificate in `certificate-example.org.server.pem`. Without '-u' everything
80 is fine.
81
82 But if you use '-u' and an attacker redirects you to e.g.
83 https://www.example.org/ - leading .www - (or https://whatever.org/) (for
84 example through a link on a different site) then the proxy just forwards the
85 TLS connection (because it doesn't know the fingerprint for
86 https://www.example.org/, that's how '-u' works) and you won't be aware that a
87 different server certificate might be used!
88
89 If you always verify the authentication of the connection this isn't a
90 problem, but if you only check if it's a HTTPS connection then this attack is
91 possible.
92
93
94 KNOWN ISSUES
95 ------------
96
97 - Firefox (at least Iceweasel 3.5.16 on Debian) fails to load the error page
98   sent with the "invalid" certificate once the certificate has been accepted.
99   As the user shouldn't accept the invalid certificate this is a minor issue.