More doxygen on the protocol auth methods

Author: gkodinov

Doxyfile

@@ -1,4 +1,4 @@
-# Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved.
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License, version 2.0,
@@ -478,7 +478,7 @@ TYPEDEF_HIDES_STRUCT   = NO
 # the optimal cache size from a speed point of view.
 # Minimum value: 0, maximum value: 9, default value: 0.
 
-LOOKUP_CACHE_SIZE      = 1
+LOOKUP_CACHE_SIZE      = 2
 
 #---------------------------------------------------------------------------
 # Build related configuration options
@@ -884,6 +884,7 @@ INPUT                  = ./client \
                          ./sql-common \
                          ./storage \
                          ./strings \
+                         ./libmysql \
                          ./vio
 
 # This tag can be used to specify the character encoding of the source files
@@ -948,8 +949,6 @@ EXCLUDE                = cmd-line-utils \
                          include/sql_state.h \
                          internal \
                          libevent \
-                         libmysql \
-                         libmysql_r \
                          plugin/innodb_memcached/daemon_memcached/include/memcached \
                          source_downloads \
                          sql/sql_hints.cc \

libmysql/authentication_win/handshake.cc

@@ -1,4 +1,4 @@
-/* Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+/* Copyright (c) 2011, 2018, Oracle and/or its affiliates. All rights reserved.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License, version 2.0,
@@ -85,15 +85,13 @@ Handshake::~Handshake()
 /**
   Read and process data packets from the other end of a connection.
 
-  @param[IN] con  a connection to read packets from
-
   Packets are read and processed until authentication handshake is 
   complete. It is assumed that the peer will send at least one packet. 
   Packets are processed with @c process_data() method. If new data is
   generated during packet processing, this data is sent to the peer and
   another round of packet exchange starts.
 
-  @return 0 on success.
+  @retval 0 on success.
 
   @note In case of error, appropriate error message is logged.
 */

libmysql/authentication_win/handshake.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2011, 2017, Oracle and/or its affiliates. All rights reserved.
+/* Copyright (c) 2011, 2018, Oracle and/or its affiliates. All rights reserved.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License, version 2.0,
@@ -162,7 +162,7 @@ class Handshake
     This method is used inside @c packet_processing_loop to process
     data packets received from the other end.
 
-    @param[IN]  data  data to be processed
+    @param  data  data to be processed
 
     @return A blob with data to be sent to the other end or null blob if
     no more data needs to be exchanged.

libmysql/authentication_win/handshake_client.cc

@@ -1,4 +1,4 @@
-/* Copyright (c) 2011, 2017, Oracle and/or its affiliates. All rights reserved.
+/* Copyright (c) 2011, 2018, Oracle and/or its affiliates. All rights reserved.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License, version 2.0,
@@ -62,6 +62,7 @@ class Handshake_client: public Handshake
   @param con     connection for communication with the peer 
   @param target  name of the target service with which we will authenticate
                  (can be NULL if not used)
+  @param len     length of target
 
   Some security packages (like Kerberos) require providing explicit name
   of the service with which a client wants to authenticate. The server-side
@@ -315,6 +316,66 @@ Blob Handshake_client::process_data(const Blob &data)
 
 /**********************************************************************/
 
+/**
+  @page page_protocol_connection_phase_authentication_methods_authentication_windows Windows Native Authentication
+
+  Authentication::WindowsAuth:
+
+  <ul>
+  <li>
+  The server name is *authentication_windows*
+  </li>
+  <li>
+  The client name is *authentication_windows_client*
+  </li>
+  </ul>
+
+  The Windows Native Authentication method is more complex than the other
+  methods and extends the auth protocol as it has to send more data forth
+  and back than the old handshake permitted.
+
+  Basically it wraps the output of the
+  [Negotiate SSP]("http://msdn.microsoft.com/en-us/library/windows/desktop/aa378748(v=VS.85).aspx")
+  in the Auth Phase protocol which either means
+  @ref sect_protocol_connection_phase_authentication_methods_authentication_windows_ntlm or
+  @ref sect_protocol_connection_phase_authentication_methods_authentication_windows_spnego
+  are used as underlying protocol.
+
+  Due to the implementation details the Windows Native Authentication method
+  doesn't use the fast path of the @ref page_protocol_connection_phase, but is
+  only triggered on request as part of the
+  @ref page_protocol_connection_phase_packets_protocol_auth_switch_request packet.
+
+
+  @note Due to implementation details (again) the first packet sent from the
+  client to the server is expected to be either
+  <ul><li>254 bytes long max or</li>
+  <li>send the first 254 bytes first, appended by 1 byte with a magic value
+  plus a 2nd packet with rest of the data</li></ul>
+  Also following windows authentication packets don't get split.
+
+  The client will send either a
+  @ref sect_protocol_connection_phase_authentication_methods_authentication_windows_spnego
+  or a @ref sect_protocol_connection_phase_authentication_methods_authentication_windows_ntlm
+  packet as a next packet.
+
+  To implement the protocol one can use several existing implementations:
+  <ul>
+  <li>MS Windows provides
+  [InitializeSecurityContextW]("http://msdn.microsoft.com/en-us/library/windows/desktop/aa375509(v=VS.85).aspx")
+  and [AcceptSecurityContext]("http://msdn.microsoft.com/en-us/library/aa374703.aspx")
+  </li>
+  <li>A open source implemenation of NTML, SPNEGO and Kerberos5 are provided by
+  [Heimdal]("http://www.h5l.org/")
+  </li>
+  <li>Java6 added SPNEGO support to
+  [JGSS]("http://download.oracle.com/javase/6/docs/technotes/guides/security/jgss/lab/part5.html#SPNEGO")
+  which also provides the NTLM and Kerberos5 support.
+  </li></ul>
+
+  @section sect_protocol_connection_phase_authentication_methods_authentication_windows_spnego SPNEGO
+  @section sect_protocol_connection_phase_authentication_methods_authentication_windows_ntlm NTLM
+*/
 
 /**
   Perform authentication handshake from client side.

sql-common/client.cc

@@ -6794,6 +6794,51 @@ static int native_password_auth_client(MYSQL_PLUGIN_VIO *vio, MYSQL *mysql)
   DBUG_RETURN(CR_OK);
 }
 
+/**
+  @page page_protocol_connection_phase_authentication_methods_clear_text_password Clear text client plugin
+
+  <ul>
+  <li>
+  This client side plugin is used by a number of server plugins:
+  LDAP (*authentication_ldap_simple*) and PAM (*authentication_pam*) to name a few.
+  </li>
+  <li>
+  The client name is *mysql_clear_password*
+  </li>
+  <li>
+  Client side requires nothing from the server. But the server generates
+  and sends a 20-byte
+  @ref page_protocol_connection_phase_authentication_methods_native_password_authentication
+  compatible scramble.
+  </li>
+  <li>
+  Client side sends the password in clear text to the server
+  </li>
+  </ul>
+
+  @startuml
+  Server->Client: 20 bytes of scramble to be ignored
+  Client->Server: The clear text password. null terminated.
+  @enduml
+
+  @note
+  Sending the scramble is not necessary for the clear text
+  method, but, since the server always initiates the exchange by
+  sending @ref page_protocol_connection_phase_packets_protocol_handshake
+  and that one has a placeholder for authentication plugin dependent data the
+  server does fill that space with a scramble should it come to pass that
+  it will back down to
+  @ref page_protocol_connection_phase_authentication_methods_native_password_authentication.
+  This is also why it's OK no to specifically read this in
+  @ref clear_password_auth_client since it's already read as a part of
+  the initial exchange.
+
+
+  @sa ::clear_password_auth_client, ::server_mpvio_write_packet,
+    ::send_server_handshake_packet
+ */
+
+
 /**
   The main function of the mysql_clear_password authentication plugin.
 */

sql/auth/sql_authentication.cc

@@ -598,7 +598,7 @@
    The server name is *mysql_old_password*
    </li>
    <li>
-   The client name is *mysql_old_password"
+   The client name is *mysql_old_password*
    </li>
    <li>
    Client side requires an 8-byte random challenge from server
@@ -624,6 +624,8 @@
 
    @subpage page_protocol_connection_phase_authentication_methods_native_password_authentication
    @subpage page_caching_sha2_authentication_exchanges
+   @subpage page_protocol_connection_phase_authentication_methods_clear_text_password
+   @subpage page_protocol_connection_phase_authentication_methods_authentication_windows
 */
 
 /**