Document how to get CA certifcates.

2 files changed, 108 insertions, 19 deletions

diff --git a/NEWS b/NEWS
index 833ff6a..ac5a29e 100644
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,8 @@ News
 
   * CVS:
 
+    * Document how to get CA certificates.
+    
     * Corrections to the manpages (Reuben Thomas).
 
     * Tips for adding missing Date: headers in messages for local delivery
diff --git a/README b/README
index f85aea3..1a58f9a 100644
--- a/README
+++ b/README
@@ -3,7 +3,7 @@
                                      -----
                                   José Fonseca
                                       ---
-                                   July 2003
+                                   March 2006
                                      
 
 Introduction
@@ -175,16 +175,53 @@ defaults
   whichever value you use on your <<<~/.esmtprc>>>.
 
 
+Interfacing with particular mail servers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+* Gmail
+~~~~~~~
+
+  First edit your ~/.esmtprc according to
+  {{http://mail.google.com/support/bin/answer.py?answer=13287}}. It should look
+  like this:
+
+-------------------------------------
+identity username@gmail.com
+        hostname smtp.gmail.com:587
+        username "username@gmail.com"
+        password "password"
+        starttls required
+-------------------------------------
+
+  Since Gmail requires the use of the StartTLS extension, you'll need to add
+  the Cert-Authority (CA) root certificate which signed Gmail server certificate.
+
+  Gmail's server certificated is signed by Thawte. You can either follow the
+  instructions to use Mozilla's CA cert bundle, found elsewhere in this
+  document, or download directly the
+  {{{http://www.thawte.com/roots/index.html}Thawte Premium Server CA
+  certificate}}, as shown below:
+
+---------------------------------------
+mkdir ~/.authenticate
+chmod 0700 ~/.authenticate
+wget https://www.verisign.com/support/thawte-roots.zip
+unzip -p thawte-roots.zip 'Thawte Server Roots/ThawtePremiumServerCA.txt' > ~/.authenticate/ca.pem
+chmod 0600 ~/.authenticate/ca.pem
+---------------------------------------
+
+
 Using the StartTLS extension
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
   TLS support in <<libESMTP>> although usable is not yet as robust and
-  featureful as the rest of the library. At the moment to use the StarTLS
+  featureful as the rest of the library. At the moment to use the StartTLS
   extension you will need to:
   
-    [[1]] create a ~/.authenticate directory for the certificates. All files
-    and directories in ~/.authenticate (including itself) must be user-readable
-    only , i.e., they must have 0600 and 0700 permissions respectively.
+    [[1]] create a <<<~/.authenticate>>> directory for the certificates. All files
+    and directories in <<<~/.authenticate>>> (including itself) must be user-readable
+    only, i.e., they must have 0600 and 0700 permissions respectively.
 
     [[2]] put the certificate of the trusted Cert-Authority that signed the
     server certificate into <<<~/.authenticate/ca.pem>>>. 
@@ -204,19 +241,69 @@ Using the StartTLS extension
   In case of failure no error message will appear. Instead, <<libESMTP>> will
   terminate the SMTP connection right after issuing the STARTLS command.
   
-  For more information about TLS support in <<libEMSTP>> see (here in
-  cronological order, and roughly in reverse-order of importance):
+  For more information about TLS support in <<libEMSTP>> see the comments in
+  <<<smtp-tls.c>>> in the <<libESMTP>> source distribution.
 
-    * {{http://mail.gnome.org/archives/balsa-list/2002-February/thread.html#00225}}
-    
-    * {{http://mail.gnome.org/archives/balsa-list/2002-March/thread.html#00000}}
-    
-    * {{http://mail.gnome.org/archives/balsa-list/2003-September/thread.html#00011}}
-    
-    * {{http://mail.gnome.org/archives/balsa-list/2003-September/msg00023.html}}
 
-    * comments in smtp-tls.c in the <<libESMTP>> source distribution.
-  
-  Also of interest may be:
-  
-    * {{http://postfix.state-of-mind.de/patrick.koetter/smtpauth/postfix_tls_support.html}}
+* Using CA root certificates from mozilla.org
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Mozilla.org's browsers already ship with a bundle of CA root certificates. For most cases
+  this bundle should suffice. You can download the bundle a format suitable to esmtp from 
+  {{http://curl.haxx.se/docs/caextract.html}}, as
+
+---------------------------------------
+mkdir ~/.authenticate
+chmod 0700 ~/.authenticate
+wget http://curl.haxx.se/ca/cacert.pem
+mv cacert.pem ~/.authenticate/ca.pem
+chmod 0600 ~/.authenticate/ca.pem
+---------------------------------------
+
+
+
+* Using CA root certificates from debian
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  If you use Debian, you can also use the CA root certificates included in the
+  <ca-certificates> package:
+
+---------------------------------------
+mkdir ~/.authenticate
+chmod 0700 ~/.authenticate
+sudo apt-get install ca-certificates
+cp -a /etc/ssl/certs/ ~/.authenticate/ca
+chmod -R go-rwx ~/.authenticate/ca
+---------------------------------------
+
+
+* Determining determining the Cert-Authority certificate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  It may happen that the mail server certificate is signed by an unknown or
+  custom root certificate. If you think that may be your case you can try to
+  figure out which one is using <<openssl>>:
+
+-------------
+openssl s_client -connect hostname:port
+--------------
+
+  Depending on the SMTP mail server, you might need to play with the port number
+  or add '-starttls smtp' option.
+
+  Look for lines in the output which can provide clues for the certification
+  authority such as:
+
+---------------
+issuer=/C=ZA/ST=Western Cape/L=Cape Town/O=Thawte Consulting cc/OU=Certification Services Division/CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com
+---------------
+
+  Once you are in possession of the root certificate, you can check if it
+  validates the server certificate by passing it on the <<<-CAfile>>> option. It is
+  does then you'll get a line like:
+
+--------
+  Verify return code: 0 (ok)
+--------
+
+  See also http://curl.haxx.se/docs/sslcerts.html