X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=README.SSL;h=930da8bb5ace9f3db4e2a21ada3f7810453686e3;hb=87bcf29364c4640edb87cc2186b965d1a564d70c;hp=8f6c2a6206da978606522ac0c9d0a5c04aea45de;hpb=73e0c50cb8b3ed77c5e168288c36e04c960e8d8d;p=~andy%2Ffetchmail diff --git a/README.SSL b/README.SSL index 8f6c2a62..930da8bb 100644 --- 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. -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 -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. -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. -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. -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). -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. -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. -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). -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 + - Matthias Andree