From: Timo Sirainen <timo.sirainen@open-xchange.com>
Date: Thu, 22 Dec 2022 12:04:11 +0000 (+0200)
Subject: login-common: Add comments
X-Git-Tag: 2.4.0~2905
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e460281ffd723ae361f8ab35abf04de7edc0d7a0;p=thirdparty%2Fdovecot%2Fcore.git

login-common: Add comments
---

diff --git a/src/login-common/client-common.c b/src/login-common/client-common.c
index 8194c144d1..6f576560e4 100644
--- a/src/login-common/client-common.c
+++ b/src/login-common/client-common.c
@@ -1139,6 +1139,11 @@ const char *client_get_extra_disconnect_reason(struct client *client)
 	if (client->auth_process_comm_fail)
 		return "auth process communication failure";
 
+	/* The reasons below are returned only when there is a single
+	   authentication attempt. The main reason is to avoid confusion in
+	   case the client sends tons of auth attempts and disconnection just
+	   happens to be on the last attempt. In that case it's more important
+	   to know the total number of auth attempts instead. */
 	if (client->auth_client_continue_pending && client->auth_attempts == 1) {
 		return t_strdup_printf("client didn't finish SASL auth, "
 				       "waited %u secs", auth_secs);
@@ -1154,10 +1159,16 @@ const char *client_get_extra_disconnect_reason(struct client *client)
 	if (client->auth_aborted_by_client && client->auth_attempts == 1)
 		return "auth aborted by client";
 
-	if (client->auth_nologin_referral)
+	if (client->auth_nologin_referral) {
+		/* Referral was sent to the connecting client, which is
+		   expected to be a trusted Dovecot proxy. There should be no
+		   further auth attempts. */
 		return "auth referral";
-	if (client->proxy_auth_failed)
+	}
+	if (client->proxy_auth_failed) {
+		/* Authentication to the next hop failed. */
 		return "proxy dest auth failed";
+	}
 	if (client->auth_successes > 0) {
 		return t_strdup_printf("internal failure, %u successful auths",
 				       client->auth_successes);
diff --git a/src/login-common/client-common.h b/src/login-common/client-common.h
index 0d4bda8557..048e51f7d0 100644
--- a/src/login-common/client-common.h
+++ b/src/login-common/client-common.h
@@ -197,6 +197,8 @@ struct client {
 
 	char *auth_mech_name;
 	enum sasl_server_auth_flags auth_flags;
+	/* Auth request set while the client is authenticating.
+	   During this time authenticating=TRUE also. */
 	struct auth_client_request *auth_request;
 	struct auth_client_request *reauth_request;
 	string_t *auth_response;
@@ -207,6 +209,9 @@ struct client {
 	struct anvil_request *anvil_request;
 
 	unsigned int master_auth_id;
+	/* Tag that can be used with login_client_request_abort() to abort
+	   sending client fd to mail process. authenticating is always TRUE
+	   while this is non-zero. */
 	unsigned int master_tag;
 	sasl_server_callback_t *sasl_callback;
 
@@ -257,6 +262,10 @@ struct client {
 	bool connection_trusted:1;
 	bool ssl_servername_settings_read:1;
 	bool banner_sent:1;
+	/* Authentication is going on. This is set a bit before auth_request is
+	   created, and it can fail early e.g. due to unknown SASL mechanism.
+	   Also this is still TRUE while the client fd is being sent to the
+	   mail process (master_tag != 0). */
 	bool authenticating:1;
 	/* SASL authentication is waiting for client to send a continuation */
 	bool auth_client_continue_pending:1;