Add comments about usage of TLS/SSL in connection establishment

All new code of the whole pull request, including one or several files
that are either new files or modified ones, are contributed under the
BSD-new license. I am contributing on behalf of my employer Amazon Web
Services, Inc.

libmariadb/mariadb_lib.c

@@ -1951,6 +1951,17 @@ MYSQL *mthd_my_real_connect(MYSQL *mysql, const char *host, const char *user,
 
   mysql->client_flag= client_flag;
 
+  /* Until run_plugin_auth has completed, the connection
+   * cannot have been secured with TLS/SSL.
+   *
+   * This means that any client which expects to use a
+   * TLS/SSL-secured connection SHOULD NOT trust any
+   * communication received from the server prior to this
+   * point as being genuine; nor should either the client
+   * or the server send any confidential information up
+   * to this point.
+   */
+
   if (run_plugin_auth(mysql, scramble_data, scramble_len,
                              scramble_plugin, db))
     goto error;

plugins/auth/my_auth.c

@@ -321,8 +321,19 @@ static int send_client_reply_packet(MCPVIO_EXT *mpvio,
       (mysql->client_flag & CLIENT_SSL))
   {
     /*
-      Send mysql->client_flag, max_packet_size - unencrypted otherwise
-      the server does not know we want to do SSL
+      Send UNENCRYPTED "Login Request" packet with mysql->client_flag
+      and max_packet_size, but no username; without this, the server
+      does not know we want to switch to SSL/TLS
+
+      FIXME: Sending this packet is a very very VERY bad idea. It
+      contains the client's preferred charset and flags in plaintext;
+      this can be used for fingerprinting the client software version,
+      and probable geographic location.
+
+      This offers a glaring opportunity for pervasive attackers to
+      easily target, intercept, and exploit the client-server
+      connection (e.g. "MITM all connections from known-vulnerable
+      client versions originating from countries X, Y, and Z").
     */
     if (ma_net_write(net, (unsigned char *)buff, (size_t) (end-buff)) || ma_net_flush(net))
     {
@@ -332,6 +343,9 @@ static int send_client_reply_packet(MCPVIO_EXT *mpvio,
                           errno);
       goto error;
     }
+    /* This is where the socket is actually converted from a plain
+     * TCP/IP socket to a TLS/SSL-wrapped socket.
+     */
     if (ma_pvio_start_ssl(mysql->net.pvio))
       goto error;
   }