From 022e67294eb6b39f8d2554abc178a1328e8b9cd5 Mon Sep 17 00:00:00 2001
From: Steve Holme <steve_holme@hotmail.com>
Date: Mon, 4 Feb 2013 23:51:36 +0000
Subject: email: Provided extra comments following recent pop3/imap fixes

Provided additional clarification about the logic of the authenticate()
functions following commit 6b6bdc83bd36 and b4270a9af1d0.
---
 lib/imap.c | 7 +++++--
 lib/pop3.c | 8 ++++++--
 lib/smtp.c | 9 ++++++---
 3 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/lib/imap.c b/lib/imap.c
index 50930f7a4..fd1d7e426 100644
--- a/lib/imap.c
+++ b/lib/imap.c
@@ -519,7 +519,7 @@ static CURLcode imap_authenticate(struct connectdata *conn)
   const char *mech = NULL;
   imapstate authstate = IMAP_STOP;
 
-  /* Check supported authentication mechanisms by decreasing order of
+  /* Calculate the supported authentication mechanism by decreasing order of
      security */
 #ifndef CURL_DISABLE_CRYPTO_AUTH
   if(imapc->authmechs & SASL_MECH_DIGEST_MD5) {
@@ -554,6 +554,7 @@ static CURLcode imap_authenticate(struct connectdata *conn)
   }
 
   if(mech) {
+    /* Perform SASL based authentication */
     const char *str = getcmdid(conn);
 
     result = imap_sendf(conn, str, "%s AUTHENTICATE %s", str, mech);
@@ -562,10 +563,12 @@ static CURLcode imap_authenticate(struct connectdata *conn)
       state(conn, authstate);
   }
   else if(!imapc->login_disabled)
+    /* Perform clear text authentication */
     result = imap_state_login(conn);
   else {
+    /* Other mechanisms not supported */
     infof(conn->data, "No known authentication mechanisms supported!\n");
-    result = CURLE_LOGIN_DENIED; /* Other mechanisms not supported */
+    result = CURLE_LOGIN_DENIED;
   }
 
   return result;
diff --git a/lib/pop3.c b/lib/pop3.c
index 395c39d21..e9eeb3a8a 100644
--- a/lib/pop3.c
+++ b/lib/pop3.c
@@ -458,7 +458,7 @@ static CURLcode pop3_authenticate(struct connectdata *conn)
   const char *mech = NULL;
   pop3state authstate = POP3_STOP;
 
-  /* Check supported authentication mechanisms by decreasing order of
+  /* Calculate the supported authentication mechanism by decreasing order of
      security */
   if(pop3c->authtypes & POP3_TYPE_SASL) {
 #ifndef CURL_DISABLE_CRYPTO_AUTH
@@ -495,6 +495,7 @@ static CURLcode pop3_authenticate(struct connectdata *conn)
   }
 
   if(mech) {
+    /* Perform SASL based authentication */
     result = Curl_pp_sendf(&pop3c->pp, "AUTH %s", mech);
 
     if(!result)
@@ -502,13 +503,16 @@ static CURLcode pop3_authenticate(struct connectdata *conn)
   }
 #ifndef CURL_DISABLE_CRYPTO_AUTH
   else if(pop3c->authtypes & POP3_TYPE_APOP)
+    /* Perform APOP authentication */
     result = pop3_state_apop(conn);
 #endif
   else if(pop3c->authtypes & POP3_TYPE_CLEARTEXT)
+    /* Perform clear text authentication */
     result = pop3_state_user(conn);
   else {
+    /* Other mechanisms not supported */
     infof(conn->data, "No known authentication mechanisms supported!\n");
-    result = CURLE_LOGIN_DENIED; /* Other mechanisms not supported */
+    result = CURLE_LOGIN_DENIED;
   }
 
   return result;
diff --git a/lib/smtp.c b/lib/smtp.c
index 6204de0e8..02048b05d 100644
--- a/lib/smtp.c
+++ b/lib/smtp.c
@@ -373,8 +373,8 @@ static CURLcode smtp_authenticate(struct connectdata *conn)
     return result;
   }
 
-  /* Check supported authentication mechanisms by decreasing order of
-     security */
+  /* Calculate the supported authentication mechanism, by decreasing order of
+     security, as well as the initial response where appropriate */
 #ifndef CURL_DISABLE_CRYPTO_AUTH
   if(smtpc->authmechs & SASL_MECH_DIGEST_MD5) {
     mech = "DIGEST-MD5";
@@ -417,11 +417,13 @@ static CURLcode smtp_authenticate(struct connectdata *conn)
                                             conn->passwd, &initresp, &len);
   }
   else {
+    /* Other mechanisms not supported */
     infof(conn->data, "No known authentication mechanisms supported!\n");
-    result = CURLE_LOGIN_DENIED; /* Other mechanisms not supported */
+    result = CURLE_LOGIN_DENIED;
   }
 
   if(!result) {
+    /* Perform SASL based authentication */
     if(initresp &&
        strlen(mech) + len <= 512 - 8) { /* AUTH <mech> ...<crlf> */
        result = Curl_pp_sendf(&smtpc->pp, "AUTH %s %s", mech, initresp);
@@ -435,6 +437,7 @@ static CURLcode smtp_authenticate(struct connectdata *conn)
       if(!result)
         state(conn, state1);
     }
+
     Curl_safefree(initresp);
   }
 
-- 
cgit v1.2.3