From 16f6c417c9f877ccb6b40fc3dd87b831a7761797 Mon Sep 17 00:00:00 2001
From: José Fonseca <jrfonseca@users.sourceforge.net>
Date: Mon, 3 Nov 2003 17:03:48 +0000
Subject: Detailed documentation on how to use the StartTLS extension. Handle
 StarTLS events. Fixed some compiler warnings.

---
 README | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

(limited to 'README')

diff --git a/README b/README
index f2b9e12..8bb8796 100644
--- a/README
+++ b/README
@@ -157,3 +157,49 @@ defaults
   redundant step by simply replacing the value inside the quotes above by
   whichever value you use on your <<<~/.esmtprc>>>.
 
+
+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
+  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.
+
+    [[2]] put the certificate of the trusted Cert-Authority that signed the
+    server certificate into <<<~/.authenticate/ca.pem>>>. 
+
+    [[3]] if a client certificate is required by the server then put it
+    (including the private key) into
+    <<<~/.authenticate/private/smtp-starttls.pem>>> or
+    <<<~/.authenticate/host.name/private/smtp-starttls.pem>>>. If your client
+    certificate has a passphrase then it should be specificied with the
+    <certificate_passphrase> configuration.
+
+    [[4]] enable (or require) the StartTLS extension with the <starttls>
+    configuration option. Note that the value of the <hostname> configuration
+    option of the server you connect MUST match the name in the server
+    certificate, since it will be used to verify the server identity.
+
+  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):
+
+    * {{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}}
-- 
cgit v1.2.3-54-g00ecf