Detailed documentation on how to use the StartTLS extension.

Handle StarTLS events.
Fixed some compiler warnings.

7 files changed, 133 insertions, 19 deletions

diff --git a/AUTHORS b/AUTHORS
index 497c316..2f48b76 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1 +1 @@
-José Fonseca <j_r_fonseca@yahoo.co.uk>
+José Fonseca <jrfonseca@users.sourceforge.net>
diff --git a/NEWS b/NEWS
index 68f715e..8c15dc8 100644
--- a/NEWS
+++ b/NEWS
@@ -2,7 +2,10 @@ News
 ~~~~
 
   * Version 0.4.2 (under development):
-  
+
+    * Detailed documentation on how to use the StartTLS extension. More
+    verbosity on StarTLS error messages.
+    
     * New 'preconnect' keyword to execute a command prior to opening an SMTP
     connection (Daniel Richard G.).
     
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}}
diff --git a/TODO b/TODO
index 83a2645..b17f226 100644
--- a/TODO
+++ b/TODO
@@ -6,6 +6,8 @@ To do
 
   Here is a list of what can still be done:
 
-  * Alias expansion.
+    * Alias expansion.
+
+    * Include simple scripts to queue emails for dial-up connections.
 
 
diff --git a/autogen.sh b/autogen.sh
index 8a25f54..dab68d0 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -3,5 +3,5 @@
 aclocal \
 && automake --gnu --add-missing \
 && autoconf \
-&& ./configure --enable-maintainer-mode
+&& CFLAGS="-Wall -pedantic -g" ./configure --enable-maintainer-mode
 
diff --git a/message.c b/message.c
index 0162bca..a167b65 100644
--- a/message.c
+++ b/message.c
@@ -151,7 +151,6 @@ static char *message_buffer_readline(message_t *message)
 static void message_buffer_fill(message_t *message)
 {
 	FILE *fp = message->fp ? message->fp : stdin;
-	size_t n;
 
 	message->buffer_stop += fread(message->buffer + message->buffer_stop, 1, message->buffer_size - message->buffer_stop, fp);
 	
diff --git a/smtp.c b/smtp.c
index f536cec..f111ea4 100644
--- a/smtp.c
+++ b/smtp.c
@@ -131,7 +131,6 @@ void identities_cleanup(void)
 static const char * message_cb (void **buf, int *len, void *arg)
 {
 	message_t *message = (message_t *)arg;
-	int octets;
 
 	if (len == NULL)
 	{
@@ -154,10 +153,6 @@ static const char * message_cb (void **buf, int *len, void *arg)
 static void event_cb (smtp_session_t session, int event_no, void *arg, ...)
 {
 	va_list ap;
-	const char *mailbox;
-	smtp_message_t message;
-	smtp_recipient_t recipient;
-	const smtp_status_t *status;
 
 	va_start (ap, arg);
 		
@@ -165,12 +160,56 @@ static void event_cb (smtp_session_t session, int event_no, void *arg, ...)
 		case SMTP_EV_EXTNA_DSN:
 			fprintf(stderr, "Delivery Status Notification extension not supported by MTA\n");
 			break;
+
 		case SMTP_EV_EXTNA_8BITMIME:
 			fprintf(stderr, "8bit-MIME extension not supported by MTA\n");
 			break;
+			
 		case SMTP_EV_EXTNA_STARTTLS:
 			fprintf(stderr, "StartTLS extension not supported by MTA\n");
 			break;
+
+		case SMTP_EV_WEAK_CIPHER:
+		{
+			int bits = va_arg (ap, int);
+			int *ok = va_arg (ap, int *);
+
+			fprintf(stderr, "Weak cipher (%d bits)\n", bits);
+
+			*ok = 0;
+			break;
+		}
+
+		case SMTP_EV_INVALID_PEER_CERTIFICATE:
+		{
+			long result = va_arg (ap, long);
+			int *ok = va_arg (ap, int *);
+
+			fprintf(stderr, "Invalid peer certificate (error %ld)\n", result);
+
+			*ok = 0;
+			break;
+		}
+
+		case SMTP_EV_NO_PEER_CERTIFICATE:
+		{
+			int *ok = va_arg (ap, int *);
+			
+			fprintf(stderr, "No peer certificate\n");
+
+			*ok = 0;
+			break;
+		}
+
+		case SMTP_EV_WRONG_PEER_CERTIFICATE:
+		{
+			int *ok = va_arg (ap, int *);
+
+			fprintf(stderr, "Wrong peer certificate\n");
+
+			*ok = 0;
+			break;
+		}
 	}
 	
 	if (verbose)
@@ -189,21 +228,28 @@ static void event_cb (smtp_session_t session, int event_no, void *arg, ...)
 				break;
 				
 			case SMTP_EV_MAILSTATUS:
-				mailbox = va_arg (ap, const char *);
-				message = va_arg (ap, smtp_message_t);
-				status = smtp_reverse_path_status (message);
+			{
+				const char *mailbox = va_arg (ap, const char *);
+				smtp_message_t message = message = va_arg (ap, smtp_message_t);
+				const smtp_status_t *status = smtp_reverse_path_status (message);
+				
 				fprintf (stdout, "From %s: %d %s", mailbox, status->code, status->text);
 				break;
+			}
 
 			case SMTP_EV_RCPTSTATUS:
-				mailbox = va_arg (ap, const char *);
-				recipient = va_arg (ap, smtp_recipient_t);
-				status = smtp_recipient_status (recipient);
+			{
+				const char *mailbox = va_arg (ap, const char *);
+				smtp_recipient_t recipient = va_arg (ap, smtp_recipient_t);
+				const smtp_status_t *status = smtp_recipient_status (recipient);
+				
 				fprintf (stdout, "To %s: %d %s", mailbox, status->code, status->text);
 				break;
+			}
 				
 			case SMTP_EV_MESSAGEDATA:
-				message = va_arg (ap, smtp_message_t);
+			{
+				smtp_message_t message = message = va_arg (ap, smtp_message_t);
 				if (!sizeticking)
 				{
 					fputs("Message data: ", stdout);
@@ -217,16 +263,34 @@ static void event_cb (smtp_session_t session, int event_no, void *arg, ...)
 					sizeticker -= SIZETICKER;
 				}
 				break;
+			}
 
 			case SMTP_EV_MESSAGESENT:
-				message = va_arg (ap, smtp_message_t);
-				status = smtp_message_transfer_status (message);
+			{
+				smtp_message_t message = va_arg (ap, smtp_message_t);
+				const smtp_status_t *status = smtp_message_transfer_status (message);
+				
 				fprintf (stdout, "Message sent: %d %s", status->code, status->text);
 				break;
+			}
 				
 			case SMTP_EV_DISCONNECT:
 				fputs("Disconnected to MTA\n", stdout);
 				break;
+
+			case SMTP_EV_STARTTLS_OK:
+			{
+				void *ssl = va_arg(ap, void *);
+				void *cipher = va_arg(ap, void *);
+				int bits = va_arg(ap, int);
+				
+				(void) ssl;
+				(void) cipher;
+
+				fprintf(stdout, "StartTLS OK (%d bits)\n", bits);
+				break;
+			}
+
 		}
 	}