Merge branch 'legacy_63'

[~andy/fetchmail] / README.SSL

diff --git a/README.SSL b/README.SSL
index 8f6c2a6206da978606522ac0c9d0a5c04aea45de..930da8bb5ace9f3db4e2a21ada3f7810453686e3 100644 (file)
--- a/README.SSL
+++ b/README.SSL
@@ -1,104 +1,137 @@
-Fetchmail SSL support
-=====================
+Fetchmail client-side SSL support
+=================================

 
 

-Note: there is a separate document describing the server-side
-requirements for proper SSL support. It has checklist-style and not
+Preface
+-------
+
+Note: there is a separate document "README.SSL-SERVER" describing the server- 
+side requirements for proper SSL support.  It has checklist-style and is not 

 specific to fetchmail.
 
 specific to fetchmail.
 

-In case of troubles, mail it to your ISP and have them check it.
+In case of troubles, mail the README.SSL-SERVER file to your ISP and 
+have them check their server configuration against it.
+
+Unfortunately, fetchmail confuses SSL/TLS protocol levels with whether 
+a service needs to use in-band negotiation (STLS/STARTTLS for POP3/IMAP4) or is 
+totally SSL-wrapped on a separate port.  For compatibility reasons, this cannot 
+be fixed in a bugfix release.

 
        -- Matthias Andree, 2009-05-09
 
 
 
        -- Matthias Andree, 2009-05-09
 
 

-Fetchmail's client-side SSL support
------------------------------------
+Quickstart
+----------
+
+For use of SSL or TLS with in-band negotiation on the regular service's port, 
+i. e. with STLS or STARTTLS, use these command line options
+
+    --sslproto tls1 --sslcertck
+
+or these options in the rcfile (after the respective "user"... options)
+
+      sslproto tls1   sslcertck
+

 
 

-NOTE: This text is maybe not explanatory enough, so a little knowledge about
-public-key-cryptography and associated topics is required.
+For use of SSL or TLS on a separate port, if the whole TCP connection is 
+SSL-encrypted from the very beginning, use these command line options (in the 
+rcfile, omit all leading "--"):

 
 

-Using the fetchmail ssl option, you can have the data transferred between you
-and the server in an encrypted form, so that eavesdropping should become
+    --ssl --sslproto ssl3 --sslcertck
+
+or these options in the rcfile (after the respective "user"... options)
+
+      ssl   sslproto ssl3   sslcertck
+
+
+Background and use (long version :-))
+------------------
+
+Using fetchmail's "ssl" option, you can have the data transferred between you 
+and the server in an encrypted form, so that eavesdropping should become 

 practically impossible.
 
 practically impossible.
 

-This works as following: the server has a key pair (a secret and a public key),
-and it sends the client it's public key. Messages encrypted with the public key
+This works as follows: the server has a key pair (a secret and a public key), 
+and it sends the client its public key. Messages encrypted with the public key 

 can be decrypted using the private one and vice versa.
 can be decrypted using the private one and vice versa.

-A symmetric session key (symmetric means that the same key is used for
-encryption and decryption) can now be agreed upon by the two parties using
-the secure channel the key pair builds. The session key is now used to encrypt
-the traffic.

 
 

-In the fetchmail case, the client can now authenticate itself to the server by
+A symmetric session key (symmetric means that the same key is used for 
+encryption and decryption) can now be agreed upon by the two parties using the 
+secure channel the key pair builds. The session key is now used to encrypt the 
+traffic.
+
+In the fetchmail case, the client can now authenticate itself to the server by 

 using the usual POP/IMAP/whatever authentication mechanisms.
 
 using the usual POP/IMAP/whatever authentication mechanisms.
 

-However, so called man-in-the-middle attacks are still possible: in such a
-setting, an attacker imposes the server, and thus can e.g. get your
-authentication information if you don't use a challenge based authentication
-mechanism (because he is thought to be the real server, fetchmail will try to
+However, so called man-in-the-middle attacks are still possible: in such 
+a setting, an attacker pretends to be the server, and thus can e.g. get your 
+authentication information if you do not use a challenge based authentication 
+mechanism (because it is thought to be the real server, fetchmail will try to 

 authenticate against it by telling it your password).
 
 authenticate against it by telling it your password).
 

-So, not only you need to prove your identity to the server, the server likewise
-needs to prove it's to you.
-In the standard setting, the server has a certificate (the client can have a
-certificate too to prove its identity, but this is not covered by this
-document). This certificate contains the server's public key, some data about
+So, not only do you need to prove your identity to the server, the
+server likewise needs to prove (authenticate) its identity to you.
+  In the standard setting, the server has a certificate (the client can have 
+a certificate too to prove its identity, but this is not covered by this 
+document). This certificate contains the server's public key, some data about 

 the server, and a digital signature and data about the signer.
 the server, and a digital signature and data about the signer.

-Digital signatures can also be made using a key pair as described earlier.
-
-To check this certificate, you may use the new option sslcertck. When it is
-specified, the signature of server certificate is checked against local trusted
-certificates to see whether the owner of one of the ceritificates has signed
-that server certificate, and if so, whether the signature is valid.
-So, if the server certificate is signed by a Certification Authority (CA),
-you put the CA's certificate into a directory where you keep trusted
-certificates, and point fetchmail to it. Fetchmail will then accept certificates
-signed by the owner of that certificate with the private key belonging to the
-public key in the certificate.
-You can specifiy this path using the sslcertpath option.
-The idea is that the CA only gives certificates to entities of which it has
-checked and verified the identity of (and in this case, that the server name you
-specify does belong to it). So, if you chose the intentions and the thoroughness
-of a CA, you can be reasonably sure that if a certificate is signed by the CA,
-it really belongs to the server and owner that it claims to.
-
-Certificates are only valid in a certain time window, so your system clock
+  Digital signatures can also be made using a key pair as described earlier.
+
+To check this certificate, you should use the new option "sslcertck". When it 
+is specified, the signature of the server certificate is checked against local 
+trusted certificates to see whether the owner of one of the certificates has 
+signed that server certificate, and if so, whether the signature is valid.
+  So, if the server certificate is signed by a Certification Authority (CA), 
+you put the CA's certificate into a directory where you keep trusted 
+certificates, and point fetchmail to it. Fetchmail will then accept 
+certificates signed by the owner of that certificate with the private key 
+belonging to the public key in the certificate.
+You can specify this path using the "sslcertpath" option if it is 
+different from the one OpenSSL uses by default.
+
+The idea is that the CA only gives certificates to entities whose identity it 
+has checked and verified (and in this case, that the server name you specify 
+does belong to it). So, if you trust the CA's verification process, you can be 
+reasonably sure that if a certificate is signed by the CA, it really belongs to 
+the server and owner that it claims to.
+
+Certificates are only valid in a certain time window, so your system clock 

 should be reasonably accurate when checking certificates.
 
 should be reasonably accurate when checking certificates.
 

-Additionally, CAs keep Certificate Revocation Lists (CRLs) in which they note
-the certificates that are to be treated as invalid (e.g. because the server
-name has changed, another ceritifcate was granted, or even because the
+Additionally, CAs keep Certificate Revocation Lists (CRLs) in which they note 
+the certificates that are to be treated as invalid (e.g. because the server 
+name has changed, another certificate was granted, or even because the 

 certificate was not granted to the rightful owner).
 
 certificate was not granted to the rightful owner).
 

-The really paranoid (who chose to not trust a CA) can check the fingerprint of
-the public key that is used by the server. The fingerprint is a hash of that
-key that (hopefully) has few collisions and is hard to attack using a "birthday
-attack", i.e. nobody can generate a second key that hashes to the same value
-of the original key in reasonable time. So, if the fingerprint matches, you
-can be reasonable sure that you talk to the original server, because only that
-knows the secret key, and it is very hard to generate a matching secret key from
-the public key. If it doesn't, it might be an attack, but keep in mind that the
-server key may also have changed legitimately before panicing ;)
-
-fetchmail will present the fingerprint to you. Another mode, that strictly
-checks the fingerprint, is available (using the sslfingerprint option, and
-giving the desired fingerprint as an argument). If you want to check finger-
-prints, you should use that option, because otherwise, it may be too late
-to cancel if you see the fingerprint (your password may already have been
-transmitted)!
-
-The certificate directory must be hashed in a way OpenSSL expects it: each
-time you modify a file in that directory or add a file to it, you need
-to use the c_rehash perl script that comes with OpenSSL (in the tools/
-subdirectory, in case that it isn't installed). Additionally, you might
-need to convert the ceriticates to different formats (the PEM format is expected
-and usually is available, DER is another one; you can convert between
-both using the openssl(1) utility).
-
-The fingerprints fetchmail uses are MD5 sums. You can generate them e.g. useing
-the openssl(1) "x509 -fingerprint" command. The format is a hexadecimal string
-with a ":" separating two byes (i.e. a ":" every two hex "digits"). The letter
-hex digits must be in upper case!
-
-*CAVEAT*: OpenSSL seems to be unable to check CRLs at the moment!
+The certificate directory must be hashed in a way OpenSSL expects it: each time 
+you modify a file in that directory or add a file to it, you need to use the 
+"c_rehash" perl script that comes with OpenSSL (in the tools/ subdirectory, in 
+case that it is not installed). Additionally, you might need to convert the 
+certificates to different formats (the PEM format is expected and usually is 
+available, DER is another one; you can convert between both using the 
+openssl(1) utility's x509 sub-mode).
+
+The really paranoid (who chose to not trust a CA) can check the fingerprint of 
+the public key that is used by the server. The fingerprint is a hash of that 
+key that (hopefully) has few collisions and is hard to attack using a "birthday 
+attack", i.e. nobody can generate a second key that hashes to the same value of 
+the original key in reasonable time. So, if the fingerprint matches, you can be 
+reasonably sure that you are talking to the original server, because 
+only that server knows the secret key, and it is very hard to generate a 
+matching secret key from the public key. If the fingerprint does not 
+match, there might be an attack, but, before panicking, keep in mind 
+that the server key may also have changed legitimately.
+
+Fetchmail will present the fingerprint to you in verbose mode. You can have 
+fetchmail check the fingerprint (using the "sslfingerprint" option, and giving 
+the desired fingerprint as an argument).
+
+The fingerprints fetchmail uses are MD5 sums. You can generate them e.g. using
+openssl(1)'s "x509 -fingerprint" command. The format is a hexadecimal string 
+with a ":" separating two bytes (i.e. a ":" between every two hex "digits"). The 
+match is case insensitive since release 6.3.10 (upper-case digits A to F were 
+required up to and including release 6.3.9).
+
+*CAVEAT*: OpenSSL must be at least version 0.9.7 to be able to check CRLs.

 
        - Thomas Moestl <tmoestl@gmx.net>
 
        - Thomas Moestl <tmoestl@gmx.net>

+       - Matthias Andree