X-Git-Url: https://ruderich.org/simon/gitweb/?p=tlsproxy%2Ftlsproxy.git;a=blobdiff_plain;f=README;h=f72eca02910eb361426f9d2af293471039ac497e;hp=ebcb53fb201f0c111e20a2dc249d272e441f1f76;hb=HEAD;hpb=d3ee0e4a91df6a73d93db8f1b0e70d2c528fc7b8 diff --git a/README b/README index ebcb53f..f72eca0 100644 --- a/README +++ b/README @@ -11,8 +11,9 @@ tlsproxy is licensed under GPL 3 (or later). REQUIREMENTS ------------ +- C89 compiler - GnuTLS library including development headers -- certtool (from by GnuTLS) to create TLS certificates +- certtool (from GnuTLS) to create TLS certificates USAGE @@ -23,7 +24,8 @@ 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-dh.pem`: Diffie-Hellman parameters for the proxy +- `proxy-key.pem`: private key for the proxy - `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 @@ -47,12 +49,84 @@ 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 +fingerprint changed, etc.) it's logged by the proxy (stderr) 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 +client data is sent to the (possible) evil server. The invalid 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). + + +-u option +~~~~~~~~~ + +The '-u' option passes through connections for hostnames with no stored +certificate (i.e. `certificate-*-server.pem` is missing or unreadable). In +this case the normal CA chain in your browser lets you validate the server +certificate. If the server certificate changes you're _not_ informed! + +This option is useful if you often visit websites using HTTPS but you don't +use critical information (e.g. no passwords, etc.) on these websites. + +For hostnames with a stored server certificate everything works as usual and a +certificate change is detected. + +WARNING: The option might cause security problems if you're not careful: + +For example you normally visit https://example.org/ and store the server +certificate in `certificate-example.org.server.pem`. Without '-u' everything +is fine. + +But if you use '-u' and an attacker redirects you to e.g. +https://www.example.org/ - leading .www - (or https://whatever.org/) (for +example through a link on a different site) then the proxy just forwards the +TLS connection (because it doesn't know the fingerprint for +https://www.example.org/, that's how '-u' works) and you won't be aware that a +different server certificate might be used! + +If you always verify the authentication of the connection this isn't a +problem, but if you only check if it's a HTTPS connection then this attack is +possible. + +Another issue is embedded active content, like JavaScript. If the website +includes data from a different host (e.g. a different sub-domain), for which +tlsproxy has no certificate, then an attacker can MITM that connection and +inject JavaScript with unknown consequences into the browser. + + +KNOWN ISSUES +------------ + +- Firefox (at least Iceweasel 3.5.16 on Debian) fails to load the error page + sent with the "invalid" certificate once the certificate has been accepted. + As the user shouldn't accept the invalid certificate this is a minor issue. + + +AUTHORS +------- + +Written by Simon Ruderich . + + +LICENSE +------- + +tlsproxy is licensed under GPL version 3 or later. + +Copyright (C) 2011-2014 Simon Ruderich + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see .