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-dh.pem`:      Diffie-Hellman parameters for the proxy
  28 - `proxy-key.pem`:     private key for the proxy
  29 - `proxy-invalid.pem`: special certificate used for invalid pages
  30
  31 Then import the CA file `proxy-ca.pem` in your browser so it can validate the
  32 pages sent by the proxy.
  33
  34 For each page you want to visit securely you must first obtain its server
  35 certificate (in PEM format) (for example with `gnutls-cli --print-cert server`
  36 - you need the first certificate). The next step is to _validate_ it. The
  37 proxy doesn't perform any validation thus it's important that you make sure
  38 the server certificate is the correct one!
  39
  40 Then run `tlsproxy-add hostname path-to-certificate` in the same directory as
  41 above. This creates the following files:
  42
  43 - `certificate-example.org-proxy.pem`: certificate used by the proxy for the
  44   connection to the client
  45 - `certificate-example.org-server.pem`: original server certificate, used to
  46   check if the current server certificate changed
  47
  48 If the validation is successful the proxy uses the `certificate-*-proxy.pem`
  49 certificate to secure the connection to the client (signed by `proxy-ca.pem`).
  50
  51 If an error occurs in the validation (missing `certificate-*.pem` files,
  52 fingerprint changed, etc.) it's logged by the proxy (stderr) and the special
  53 `proxy-invalid.pem` certificate is used to send a 500 error message to the
  54 client. The connection to the server is closed so there's no chance that any
  55 client data is sent to the (possible) evil server. The invalid certificate is
  56 also easy to spot in the browser because it uses an invalid hostname
  57 ("invalid") and is self-signed.
  58
  59 If an internal error occurs before the TLS connection can be established a 503
  60 Forwarding failure is sent to the client (unencrypted).
  61
  62
  63 -u option
  64 ~~~~~~~~~
  65
  66 The '-u' option passes through connections for hostnames with no stored
  67 certificate (i.e. `certificate-*-server.pem` is missing or unreadable). In
  68 this case the normal CA chain in your browser lets you validate the server
  69 certificate. If the server certificate changes you're _not_ informed!
  70
  71 This option is useful if you often visit websites using HTTPS but you don't
  72 use critical information (e.g. no passwords, etc.) on these websites.
  73
  74 For hostnames with a stored server certificate everything works as usual and a
  75 certificate change is detected.
  76
  77 WARNING: The option might cause security problems if you're not careful:
  78
  79 For example you normally visit https://example.org/ and store the server
  80 certificate in `certificate-example.org.server.pem`. Without '-u' everything
  81 is fine.
  82
  83 But if you use '-u' and an attacker redirects you to e.g.
  84 https://www.example.org/ - leading .www - (or https://whatever.org/) (for
  85 example through a link on a different site) then the proxy just forwards the
  86 TLS connection (because it doesn't know the fingerprint for
  87 https://www.example.org/, that's how '-u' works) and you won't be aware that a
  88 different server certificate might be used!
  89
  90 If you always verify the authentication of the connection this isn't a
  91 problem, but if you only check if it's a HTTPS connection then this attack is
  92 possible.
  93
  94 Another issue is embedded active content, like JavaScript. If the website
  95 includes data from a different host (e.g. a different sub-domain), for which
  96 tlsproxy has no certificate, then an attacker can MITM that connection and
  97 inject JavaScript with unknown consequences into the browser.
  98
  99
 100 KNOWN ISSUES
 101 ------------
 102
 103 - Firefox (at least Iceweasel 3.5.16 on Debian) fails to load the error page
 104   sent with the "invalid" certificate once the certificate has been accepted.
 105   As the user shouldn't accept the invalid certificate this is a minor issue.
 106
 107
 108 AUTHORS
 109 -------
 110
 111 Written by Simon Ruderich <simon@ruderich.org>.
 112
 113
 114 LICENSE
 115 -------
 116
 117 tlsproxy is licensed under GPL version 3 or later.
 118
 119 Copyright (C) 2011-2013  Simon Ruderich
 120
 121 This program is free software: you can redistribute it and/or modify
 122 it under the terms of the GNU General Public License as published by
 123 the Free Software Foundation, either version 3 of the License, or
 124 (at your option) any later version.
 125
 126 This program is distributed in the hope that it will be useful,
 127 but WITHOUT ANY WARRANTY; without even the implied warranty of
 128 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 129 GNU General Public License for more details.
 130
 131 You should have received a copy of the GNU General Public License
 132 along with this program.  If not, see <http://www.gnu.org/licenses/>.