List:Commits« Previous MessageNext Message »
From:paul.dubois Date:June 10 2011 3:21pm
Subject:svn commit - mysqldoc@oter02: r26489 - in trunk: . refman-5.5 refman-5.6
View as plain text  
Author: pd221994
Date: 2011-06-10 17:21:20 +0200 (Fri, 10 Jun 2011)
New Revision: 26489

Log:
 r48839@dhcp-adc-twvpn-1-vpnpool-10-154-31-162:  paul | 2011-06-10 10:20:13 -0500
 Add instructions for writing authentication plugins


Modified:
   svk:merge
   trunk/refman-5.5/dba-user-management-core.xml
   trunk/refman-5.5/extending-mysql.xml
   trunk/refman-5.6/dba-user-management-core.xml
   trunk/refman-5.6/extending-mysql.xml

Property changes on: trunk
___________________________________________________________________

Modified: svk:merge
===================================================================


Changed blocks: 0, Lines Added: 0, Lines Deleted: 0; 1277 bytes


Modified: trunk/refman-5.5/dba-user-management-core.xml
===================================================================
--- trunk/refman-5.5/dba-user-management-core.xml	2011-06-10 15:21:12 UTC (rev 26488)
+++ trunk/refman-5.5/dba-user-management-core.xml	2011-06-10 15:21:20 UTC (rev 26489)
Changed blocks: 1, Lines Added: 7, Lines Deleted: 2; 1026 bytes

@@ -1393,8 +1393,13 @@
 
     <para>
       Several authentication plugins are available in MySQL. The
-      following sections provide details about specific plugins. The
-      remainder of this section provides general instructions for
+      following sections provide details about specific plugins. If you
+      are interested in writing your own authentication plugins, see
+      <xref linkend="writing-authentication-plugins"/>.
+    </para>
+
+    <para>
+      The remainder of this section provides general instructions for
       installing and using such plugins. The instructions use an an
       example authentication plugin included in MySQL distributions (see
       <xref linkend="test-authentication-plugin"/>). The plugin has


Modified: trunk/refman-5.5/extending-mysql.xml
===================================================================
--- trunk/refman-5.5/extending-mysql.xml	2011-06-10 15:21:12 UTC (rev 26488)
+++ trunk/refman-5.5/extending-mysql.xml	2011-06-10 15:21:20 UTC (rev 26489)
Changed blocks: 3, Lines Added: 436, Lines Deleted: 5; 18166 bytes

@@ -1108,6 +1108,11 @@
           have. See <xref linkend="proxy-users"/>.
         </para>
 
+        <para>
+          For more information about authentication plugins, see
+          <xref linkend="writing-authentication-plugins"/>.
+        </para>
+
       </section>
 
     </section>

@@ -2700,11 +2705,8 @@
             members following the common members. For example, for an
             authentication plugin, there is a function
             (<literal>my_auth_main()</literal> in the descriptor just
-            shown) that handles communication with the server.
-
-<!--
-See <xref linkend="writing-authentication-plugins"/>.
--->
+            shown) that handles communication with the server. See
+            <xref linkend="writing-authentication-plugins"/>.
           </para>
 
           <para>

@@ -4776,6 +4778,435 @@
 
       </section>
 
+      <section id="writing-authentication-plugins">
+
+        <title>Writing Authentication Plugins</title>
+
+        <para>
+          An authentication plugin can be written for the server side or
+          the client side. Server-side plugins use the same plugin API
+          that is used for the other server plugin types such as
+          full-text parser or audit plugins (although with a different
+          type-specific descriptor). Client-side plugins use the client
+          plugin API.
+        </para>
+
+        <para>
+          Several header files contain information relevent to
+          authentication plugins:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <filename>plugin.h</filename>: Defines the
+              <literal>MYSQL_AUTHENTICATION_PLUGIN</literal> server
+              plugin type.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <filename>client_plugin.h</filename>: Defines the API for
+              client plugins. This includes the client plugin descriptor
+              and function prototypes for client plugin C API calls (see
+              <xref linkend="c-api-plugin-functions"/>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <filename>plugin_auth.h</filename>: Defines the part of
+              the server plugin API specific to authentication plugins.
+              This includes the type-specific descriptor for server-side
+              authentication plugins and the
+              <literal>MYSQL_SERVER_AUTH_INFO</literal> structure.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <filename>plugin_auth_common.h</filename>: Contains common
+              elements of client and server authentication plugins. This
+              includes return value definitions and the
+              <literal>MYSQL_PLUGIN_VIO</literal> structure.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          To write an authentication plugin, include the following
+          header files in the plugin source file. Other MySQL or general
+          header files might also be needed.
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              For a source file that implements a server authentication
+              plugin, include this file:
+            </para>
+
+<programlisting>
+#include &lt;mysql/plugin_auth.h&gt;
+</programlisting>
+          </listitem>
+
+          <listitem>
+            <para>
+              For a source file that implements a client authentication
+              plugin, or both client and server plugins, include these
+              files:
+            </para>
+
+<programlisting>
+#include &lt;mysql/plugin_auth.h&gt;
+#include &lt;mysql/client_plugin.h&gt;
+#include &lt;mysql&gt;
+</programlisting>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          <filename>plugin_auth.h</filename> includes
+          <filename>plugin.h</filename> and
+          <filename>plugin_auth_common.h</filename>, so you need not
+          include the latter files explicitly.
+        </para>
+
+        <para>
+          This section describes how to write a pair of simple server
+          and client authentication plugins that work together. These
+          plugins accept any non-empty password. This is insecure, so
+          the plugins <emphasis>should not be used in production
+          environments.</emphasis>
+        </para>
+
+        <para>
+          The server-side and client-side plugins developed here both
+          are named <literal>auth_simple</literal>. As described in
+          <xref linkend="plugin-data-structures"/>, the plugin library
+          file must have the same basename as the client plugin, so the
+          source file name is <filename>auth_simple.c</filename> and
+          produces a library named <filename>auth_simple.so</filename>
+          (assuming that your system uses <filename>.so</filename> as
+          the extension for library files).
+        </para>
+
+        <para>
+          In MySQL source distributions, authentication plugin source is
+          located in the <filename>plugin/auth</filename> directory and
+          can be examined as a guide to writing other authentication
+          plugins. Also, to see how the built-in authentication plugins
+          are implemented, see <filename>sql/sql_acl.cc</filename> for
+          plugins that are built in to the MySQL server and
+          <filename>sql-common/client.c</filename> for plugins that are
+          built in to the <literal>libmysql</literal> client library.
+          (For the built-in client plugins, note that the
+          <literal>auth_plugin_t</literal> structures used there differ
+          from the structures used with the usual client plugin
+          declaration macros. In particular, the first two members are
+          provided explicitly, not by declaration macros.)
+        </para>
+
+        <section id="writing-authentication-plugins-server-side">
+
+          <title>Writing the Server-Side Authentication Plugin</title>
+
+          <para>
+            Declare the server-side plugin with the usual general
+            descriptor format that is used for all server plugin types
+            (see <xref linkend="server-plugin-descriptors"/>). For the
+            <literal>auth_simple</literal> plugin, the descriptor looks
+            like this:
+          </para>
+
+<programlisting>
+mysql_declare_plugin(auth_simple)
+{
+  MYSQL_AUTHENTICATION_PLUGIN,
+  &amp;auth_simple_handler,                 /* type-specific descriptor */
+  "auth_simple",                        /* plugin name */
+  "Author Name",                        /* author */
+  "Any-password authentication plugin", /* description */
+  PLUGIN_LICENSE_GPL,                   /* license type */
+  NULL,                                 /* no init function */
+  NULL,                                 /* no deinit function */
+  0x0100,                               /* version = 1.0 */
+  NULL,                                 /* no status variables */
+  NULL,                                 /* no system variables */
+  NULL                                  /* no reserved information */
+}
+mysql_declare_plugin_end;
+</programlisting>
+
+          <para>
+            The <literal>name</literal> member
+            (<literal>auth_simple</literal>) indicates the name to use
+            for references to the plugin in statements such as
+            <literal role="stmt">INSTALL PLUGIN</literal> or
+            <literal role="stmt">UNINSTALL PLUGIN</literal>. This is
+            also the name displayed by <literal role="stmt">SHOW
+            PLUGINS</literal> or
+            <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>.
+          </para>
+
+          <para>
+            The <literal>auth_simple_handler</literal> member of the
+            general descriptor points to the type-specific descriptor.
+            This is an instance of the <literal>st_mysql_auth</literal>
+            structure (defined in <filename>plugin_auth.h</filename>),
+            which has three members: The type-specific API version
+            number, the name of the required client plugin (or
+            <literal>NULL</literal> for <quote>any plugin</quote>), and
+            a pointer to the main plugin function that communicates with
+            the client:
+          </para>
+
+<programlisting>
+static struct st_mysql_auth auth_simple_handler =
+{
+  MYSQL_AUTHENTICATION_INTERFACE_VERSION,
+  "auth_simple",          /* required client-side plugin name */
+  auth_simple_server_main /* server-side plugin main function */
+};
+</programlisting>
+
+          <para>
+            The main function takes two arguments representing an I/O
+            structure and an authentication information structure. The
+            function reads the password (a null-terminated string) from
+            the client and succeeds if the password is nonempty (first
+            byte not null):
+          </para>
+
+<programlisting>
+static int auth_simple_server_main (MYSQL_PLUGIN_VIO *vio,
+                               MYSQL_SERVER_AUTH_INFO *info)
+{
+  unsigned char *pkt;
+  int pkt_len;
+
+  /* read the password as null-terminated string, fail on error */
+  if ((pkt_len= vio-&gt;read_packet(vio, &amp;pkt)) &lt; 0)
+    return CR_ERROR;
+  /* fail on empty password */
+  if (!pkt_len || *pkt == '\0')
+  {
+    info-&gt;password_used= PASSWORD_USED_NO;
+    return CR_ERROR;
+  }
+  /* succeed on nonempty password */
+  info-&gt;password_used= PASSWORD_USED_YES;
+  return CR_OK;
+}
+</programlisting>
+
+          <para>
+            The main function should return <literal>CR_OK</literal> for
+            success, <literal>CR_ERROR</literal> for an error, or
+            <literal>CR_OK_HANDSHAKE_COMPLETE</literal> to tell the
+            server not to send a status packet back to the client. (For
+            an example of how this handshake works, see the
+            <filename>plugin/auth/dialog.c</filename> source file.)
+          </para>
+
+          <para>
+            <literal>auth_simple_server_main()</literal> is so basic
+            that it does not use the authentication information
+            structure except to set the member that indicates whther a
+            password was received. For a description of this structure's
+            members and how to use them, see the
+            <filename>plugin_auth.h</filename> header file. For example,
+            a plugin that supports proxy users must return to the server
+            the name of the proxied user (the MySQL user whose
+            privileges the client user should get). To do this, the
+            plugin must set the
+            <literal>info-&gt;authenticated_as</literal> member to the
+            proxied user name. For information about proxying, see
+            <xref linkend="proxy-users"/>.
+          </para>
+
+        </section>
+
+        <section id="writing-authentication-plugins-client-side">
+
+          <title>Writing the Client-Side Authentication Plugin</title>
+
+          <para>
+            Declare the client-side plugin with the
+            <literal>mysql_declare_client_plugin()</literal> and
+            <literal>mysql_end_client_plugin</literal> macros (see
+            <xref linkend="client-plugin-descriptors"/>). For the
+            <literal>auth_simple</literal> plugin, the descriptor looks
+            like this:
+          </para>
+
+<programlisting>
+mysql_declare_client_plugin(AUTHENTICATION)
+  "auth_simple",                        /* plugin name */
+  "Author Name",                        /* author */
+  "Any-password authentication plugin", /* description */
+  {1,0,0},                              /* version = 1.0.0 */
+  "GPL",                                /* license type */
+  NULL,                                 /* for internal use */
+  NULL,                                 /* no init function */
+  NULL,                                 /* no deinit function */
+  NULL,                                 /* no option-handling function */
+  auth_simple_client_main               /* main function */
+mysql_end_client_plugin;
+</programlisting>
+
+          <para>
+            The descriptor members common to all client plugins are
+            <literal>auth_simple_client</literal> (the plugin name)
+            through the option-handling function. An authentication
+            plugin also has one extra member following the common
+            members. This is the <quote>main</quote> function, which
+            handles communication with the server. The function takes
+            two arguments representing an I/O structure and a connection
+            handler. For our simple any-password plugin, the main
+            function does nothing but write to the server the password
+            provided by the user:
+          </para>
+
+<programlisting>
+static int auth_simple_client_main (MYSQL_PLUGIN_VIO *vio, MYSQL *mysql)
+{
+  int res;
+
+  /* send password as null-terminated string in clear text */
+  res= vio-&gt;write_packet(vio, (const unsigned char *) mysql-&gt;passwd, 
+						 strlen(mysql-&gt;passwd) + 1);
+
+  return res ? CR_ERROR : CR_OK;
+}
+</programlisting>
+
+          <para>
+            The main function should return <literal>CR_OK</literal> for
+            success, <literal>CR_ERROR</literal> for an error, or
+            <literal>CR_OK_HANDSHAKE_COMPLETE</literal> to indicate that
+            the client has done its part successfully and has read the
+            last packet. A plugin may return the latter status if the
+            number of round trips in the authentication protocol is not
+            known in advance and the client plugin must read another
+            packet to determine whether authentication is finished.
+          </para>
+
+        </section>
+
+        <section id="writing-authentication-plugins-setup">
+
+          <title>Using the Authentication Plugins</title>
+
+          <para>
+            To compile and install a plugin library object file, see the
+            instructions in
+            <xref linkend="compiling-plugin-libraries"/>. To use the
+            library file, it must be installed in the plugin directory
+            (the directory named by the
+            <literal role="sysvar">plugin_dir</literal> system
+            variable).
+          </para>
+
+          <para>
+            Register the server-side plugin with the server. For
+            example, to load the plugin at server startup, use a
+            <option role="mysqld">--plugin-load=auth_simple.so</option>
+            option (change the library extension as necessary for your
+            system).
+          </para>
+
+          <para>
+            Create a user for whom the server will use the
+            <literal>auth_simple</literal> plugin for authentication:
+          </para>
+
+<programlisting>
+mysql&gt; <userinput>CREATE USER 'x'@'localhost'</userinput>
+    -&gt; <userinput>IDENTIFIED WITH auth_simple;</userinput>
+</programlisting>
+
+          <para>
+            Use a client program to connect to the server as user
+            <literal>x</literal>. The server-side
+            <literal>auth_simple</literal> plugin communicates with the
+            client program that it should use the client-side
+            <literal>auth_simple</literal> plugin, and the latter sends
+            the password to the server. The server plugin should reject
+            connections that send an empty password and accept
+            connections that send a nonempty password. Invoke the client
+            program each way to verify this:
+          </para>
+
+<programlisting>
+shell&gt; <userinput>mysql --user=x --skip-password</userinput>
+ERROR 1045 (28000): Access denied for user 'x'@'localhost' (using password: NO)
+
+shell&gt; <userinput>mysql --user=x --password=abc</userinput>
+mysql&gt;
+</programlisting>
+
+          <para>
+            Because the server plugin accepts any nonempty password, it
+            should be considered insecure. After testing the plugin to
+            verify that it works, restart the server without the
+            <option role="mysqld">--plugin-load</option> option so as
+            not to indavertently leave the server running with an
+            insecure authentication plugin loaded. Also, drop the user
+            with <literal role="stmt" condition="drop-user">DROP USER
+            'x'@'localhost'</literal>.
+          </para>
+
+          <para>
+            For additional information about loading and using
+            authentication plugins, see
+            <xref linkend="registering-plugins"/>, and
+            <xref linkend="pluggable-authentication"/>.
+          </para>
+
+          <para>
+            If you are writing a client program that supports the use of
+            authentication plugins, normally such a program causes a
+            plugin to be loaded by calling
+            <literal role="cfunc">mysql_options()</literal> to set the
+            <literal>MYSQL_DEFAULT_AUTH</literal> and
+            <literal>MYSQL_PLUGIN_DIR</literal> options:
+          </para>
+
+<programlisting>
+char *plugin_dir = "<replaceable>path_to_plugin_dir</replaceable>";
+char *default_auth = "<replaceable>plugin_name</replaceable>";
+
+/* ... process command-line options ... */
+
+mysql_options(&amp;mysql, MYSQL_PLUGIN_DIR, plugin_dir);
+mysql_options(&amp;mysql, MYSQL_DEFAULT_AUTH, default_auth);
+</programlisting>
+
+          <para>
+            Typically, the program will also accept
+            <option>--plugin-dir</option> and
+            <option>--default-auth</option> options that enable users to
+            override the default values.
+          </para>
+
+          <para>
+            Should a client program require lower-level plugin
+            management, the client library contains functions that take
+            an <literal>st_mysql_client_plugin</literal> argument. See
+            <xref linkend="c-api-plugin-functions"/>.
+          </para>
+
+        </section>
+
+      </section>
+
     </section>
 
     <section id="plugin-services">


Modified: trunk/refman-5.6/dba-user-management-core.xml
===================================================================
--- trunk/refman-5.6/dba-user-management-core.xml	2011-06-10 15:21:12 UTC (rev 26488)
+++ trunk/refman-5.6/dba-user-management-core.xml	2011-06-10 15:21:20 UTC (rev 26489)
Changed blocks: 1, Lines Added: 7, Lines Deleted: 2; 1026 bytes

@@ -1393,8 +1393,13 @@
 
     <para>
       Several authentication plugins are available in MySQL. The
-      following sections provide details about specific plugins. The
-      remainder of this section provides general instructions for
+      following sections provide details about specific plugins. If you
+      are interested in writing your own authentication plugins, see
+      <xref linkend="writing-authentication-plugins"/>.
+    </para>
+
+    <para>
+      The remainder of this section provides general instructions for
       installing and using such plugins. The instructions use an an
       example authentication plugin included in MySQL distributions (see
       <xref linkend="test-authentication-plugin"/>). The plugin has


Modified: trunk/refman-5.6/extending-mysql.xml
===================================================================
--- trunk/refman-5.6/extending-mysql.xml	2011-06-10 15:21:12 UTC (rev 26488)
+++ trunk/refman-5.6/extending-mysql.xml	2011-06-10 15:21:20 UTC (rev 26489)
Changed blocks: 3, Lines Added: 436, Lines Deleted: 5; 18166 bytes

@@ -1108,6 +1108,11 @@
           have. See <xref linkend="proxy-users"/>.
         </para>
 
+        <para>
+          For more information about authentication plugins, see
+          <xref linkend="writing-authentication-plugins"/>.
+        </para>
+
       </section>
 
     </section>

@@ -2700,11 +2705,8 @@
             members following the common members. For example, for an
             authentication plugin, there is a function
             (<literal>my_auth_main()</literal> in the descriptor just
-            shown) that handles communication with the server.
-
-<!--
-See <xref linkend="writing-authentication-plugins"/>.
--->
+            shown) that handles communication with the server. See
+            <xref linkend="writing-authentication-plugins"/>.
           </para>
 
           <para>

@@ -4711,6 +4713,435 @@
 
       </section>
 
+      <section id="writing-authentication-plugins">
+
+        <title>Writing Authentication Plugins</title>
+
+        <para>
+          An authentication plugin can be written for the server side or
+          the client side. Server-side plugins use the same plugin API
+          that is used for the other server plugin types such as
+          full-text parser or audit plugins (although with a different
+          type-specific descriptor). Client-side plugins use the client
+          plugin API.
+        </para>
+
+        <para>
+          Several header files contain information relevent to
+          authentication plugins:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              <filename>plugin.h</filename>: Defines the
+              <literal>MYSQL_AUTHENTICATION_PLUGIN</literal> server
+              plugin type.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <filename>client_plugin.h</filename>: Defines the API for
+              client plugins. This includes the client plugin descriptor
+              and function prototypes for client plugin C API calls (see
+              <xref linkend="c-api-plugin-functions"/>).
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <filename>plugin_auth.h</filename>: Defines the part of
+              the server plugin API specific to authentication plugins.
+              This includes the type-specific descriptor for server-side
+              authentication plugins and the
+              <literal>MYSQL_SERVER_AUTH_INFO</literal> structure.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              <filename>plugin_auth_common.h</filename>: Contains common
+              elements of client and server authentication plugins. This
+              includes return value definitions and the
+              <literal>MYSQL_PLUGIN_VIO</literal> structure.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          To write an authentication plugin, include the following
+          header files in the plugin source file. Other MySQL or general
+          header files might also be needed.
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              For a source file that implements a server authentication
+              plugin, include this file:
+            </para>
+
+<programlisting>
+#include &lt;mysql/plugin_auth.h&gt;
+</programlisting>
+          </listitem>
+
+          <listitem>
+            <para>
+              For a source file that implements a client authentication
+              plugin, or both client and server plugins, include these
+              files:
+            </para>
+
+<programlisting>
+#include &lt;mysql/plugin_auth.h&gt;
+#include &lt;mysql/client_plugin.h&gt;
+#include &lt;mysql&gt;
+</programlisting>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>
+          <filename>plugin_auth.h</filename> includes
+          <filename>plugin.h</filename> and
+          <filename>plugin_auth_common.h</filename>, so you need not
+          include the latter files explicitly.
+        </para>
+
+        <para>
+          This section describes how to write a pair of simple server
+          and client authentication plugins that work together. These
+          plugins accept any non-empty password. This is insecure, so
+          the plugins <emphasis>should not be used in production
+          environments.</emphasis>
+        </para>
+
+        <para>
+          The server-side and client-side plugins developed here both
+          are named <literal>auth_simple</literal>. As described in
+          <xref linkend="plugin-data-structures"/>, the plugin library
+          file must have the same basename as the client plugin, so the
+          source file name is <filename>auth_simple.c</filename> and
+          produces a library named <filename>auth_simple.so</filename>
+          (assuming that your system uses <filename>.so</filename> as
+          the extension for library files).
+        </para>
+
+        <para>
+          In MySQL source distributions, authentication plugin source is
+          located in the <filename>plugin/auth</filename> directory and
+          can be examined as a guide to writing other authentication
+          plugins. Also, to see how the built-in authentication plugins
+          are implemented, see <filename>sql/sql_acl.cc</filename> for
+          plugins that are built in to the MySQL server and
+          <filename>sql-common/client.c</filename> for plugins that are
+          built in to the <literal>libmysql</literal> client library.
+          (For the built-in client plugins, note that the
+          <literal>auth_plugin_t</literal> structures used there differ
+          from the structures used with the usual client plugin
+          declaration macros. In particular, the first two members are
+          provided explicitly, not by declaration macros.)
+        </para>
+
+        <section id="writing-authentication-plugins-server-side">
+
+          <title>Writing the Server-Side Authentication Plugin</title>
+
+          <para>
+            Declare the server-side plugin with the usual general
+            descriptor format that is used for all server plugin types
+            (see <xref linkend="server-plugin-descriptors"/>). For the
+            <literal>auth_simple</literal> plugin, the descriptor looks
+            like this:
+          </para>
+
+<programlisting>
+mysql_declare_plugin(auth_simple)
+{
+  MYSQL_AUTHENTICATION_PLUGIN,
+  &amp;auth_simple_handler,                 /* type-specific descriptor */
+  "auth_simple",                        /* plugin name */
+  "Author Name",                        /* author */
+  "Any-password authentication plugin", /* description */
+  PLUGIN_LICENSE_GPL,                   /* license type */
+  NULL,                                 /* no init function */
+  NULL,                                 /* no deinit function */
+  0x0100,                               /* version = 1.0 */
+  NULL,                                 /* no status variables */
+  NULL,                                 /* no system variables */
+  NULL                                  /* no reserved information */
+}
+mysql_declare_plugin_end;
+</programlisting>
+
+          <para>
+            The <literal>name</literal> member
+            (<literal>auth_simple</literal>) indicates the name to use
+            for references to the plugin in statements such as
+            <literal role="stmt">INSTALL PLUGIN</literal> or
+            <literal role="stmt">UNINSTALL PLUGIN</literal>. This is
+            also the name displayed by <literal role="stmt">SHOW
+            PLUGINS</literal> or
+            <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>.
+          </para>
+
+          <para>
+            The <literal>auth_simple_handler</literal> member of the
+            general descriptor points to the type-specific descriptor.
+            This is an instance of the <literal>st_mysql_auth</literal>
+            structure (defined in <filename>plugin_auth.h</filename>),
+            which has three members: The type-specific API version
+            number, the name of the required client plugin (or
+            <literal>NULL</literal> for <quote>any plugin</quote>), and
+            a pointer to the main plugin function that communicates with
+            the client:
+          </para>
+
+<programlisting>
+static struct st_mysql_auth auth_simple_handler =
+{
+  MYSQL_AUTHENTICATION_INTERFACE_VERSION,
+  "auth_simple",          /* required client-side plugin name */
+  auth_simple_server_main /* server-side plugin main function */
+};
+</programlisting>
+
+          <para>
+            The main function takes two arguments representing an I/O
+            structure and an authentication information structure. The
+            function reads the password (a null-terminated string) from
+            the client and succeeds if the password is nonempty (first
+            byte not null):
+          </para>
+
+<programlisting>
+static int auth_simple_server_main (MYSQL_PLUGIN_VIO *vio,
+                               MYSQL_SERVER_AUTH_INFO *info)
+{
+  unsigned char *pkt;
+  int pkt_len;
+
+  /* read the password as null-terminated string, fail on error */
+  if ((pkt_len= vio-&gt;read_packet(vio, &amp;pkt)) &lt; 0)
+    return CR_ERROR;
+  /* fail on empty password */
+  if (!pkt_len || *pkt == '\0')
+  {
+    info-&gt;password_used= PASSWORD_USED_NO;
+    return CR_ERROR;
+  }
+  /* succeed on nonempty password */
+  info-&gt;password_used= PASSWORD_USED_YES;
+  return CR_OK;
+}
+</programlisting>
+
+          <para>
+            The main function should return <literal>CR_OK</literal> for
+            success, <literal>CR_ERROR</literal> for an error, or
+            <literal>CR_OK_HANDSHAKE_COMPLETE</literal> to tell the
+            server not to send a status packet back to the client. (For
+            an example of how this handshake works, see the
+            <filename>plugin/auth/dialog.c</filename> source file.)
+          </para>
+
+          <para>
+            <literal>auth_simple_server_main()</literal> is so basic
+            that it does not use the authentication information
+            structure except to set the member that indicates whther a
+            password was received. For a description of this structure's
+            members and how to use them, see the
+            <filename>plugin_auth.h</filename> header file. For example,
+            a plugin that supports proxy users must return to the server
+            the name of the proxied user (the MySQL user whose
+            privileges the client user should get). To do this, the
+            plugin must set the
+            <literal>info-&gt;authenticated_as</literal> member to the
+            proxied user name. For information about proxying, see
+            <xref linkend="proxy-users"/>.
+          </para>
+
+        </section>
+
+        <section id="writing-authentication-plugins-client-side">
+
+          <title>Writing the Client-Side Authentication Plugin</title>
+
+          <para>
+            Declare the client-side plugin with the
+            <literal>mysql_declare_client_plugin()</literal> and
+            <literal>mysql_end_client_plugin</literal> macros (see
+            <xref linkend="client-plugin-descriptors"/>). For the
+            <literal>auth_simple</literal> plugin, the descriptor looks
+            like this:
+          </para>
+
+<programlisting>
+mysql_declare_client_plugin(AUTHENTICATION)
+  "auth_simple",                        /* plugin name */
+  "Author Name",                        /* author */
+  "Any-password authentication plugin", /* description */
+  {1,0,0},                              /* version = 1.0.0 */
+  "GPL",                                /* license type */
+  NULL,                                 /* for internal use */
+  NULL,                                 /* no init function */
+  NULL,                                 /* no deinit function */
+  NULL,                                 /* no option-handling function */
+  auth_simple_client_main               /* main function */
+mysql_end_client_plugin;
+</programlisting>
+
+          <para>
+            The descriptor members common to all client plugins are
+            <literal>auth_simple_client</literal> (the plugin name)
+            through the option-handling function. An authentication
+            plugin also has one extra member following the common
+            members. This is the <quote>main</quote> function, which
+            handles communication with the server. The function takes
+            two arguments representing an I/O structure and a connection
+            handler. For our simple any-password plugin, the main
+            function does nothing but write to the server the password
+            provided by the user:
+          </para>
+
+<programlisting>
+static int auth_simple_client_main (MYSQL_PLUGIN_VIO *vio, MYSQL *mysql)
+{
+  int res;
+
+  /* send password as null-terminated string in clear text */
+  res= vio-&gt;write_packet(vio, (const unsigned char *) mysql-&gt;passwd, 
+						 strlen(mysql-&gt;passwd) + 1);
+
+  return res ? CR_ERROR : CR_OK;
+}
+</programlisting>
+
+          <para>
+            The main function should return <literal>CR_OK</literal> for
+            success, <literal>CR_ERROR</literal> for an error, or
+            <literal>CR_OK_HANDSHAKE_COMPLETE</literal> to indicate that
+            the client has done its part successfully and has read the
+            last packet. A plugin may return the latter status if the
+            number of round trips in the authentication protocol is not
+            known in advance and the client plugin must read another
+            packet to determine whether authentication is finished.
+          </para>
+
+        </section>
+
+        <section id="writing-authentication-plugins-setup">
+
+          <title>Using the Authentication Plugins</title>
+
+          <para>
+            To compile and install a plugin library object file, see the
+            instructions in
+            <xref linkend="compiling-plugin-libraries"/>. To use the
+            library file, it must be installed in the plugin directory
+            (the directory named by the
+            <literal role="sysvar">plugin_dir</literal> system
+            variable).
+          </para>
+
+          <para>
+            Register the server-side plugin with the server. For
+            example, to load the plugin at server startup, use a
+            <option role="mysqld">--plugin-load=auth_simple.so</option>
+            option (change the library extension as necessary for your
+            system).
+          </para>
+
+          <para>
+            Create a user for whom the server will use the
+            <literal>auth_simple</literal> plugin for authentication:
+          </para>
+
+<programlisting>
+mysql&gt; <userinput>CREATE USER 'x'@'localhost'</userinput>
+    -&gt; <userinput>IDENTIFIED WITH auth_simple;</userinput>
+</programlisting>
+
+          <para>
+            Use a client program to connect to the server as user
+            <literal>x</literal>. The server-side
+            <literal>auth_simple</literal> plugin communicates with the
+            client program that it should use the client-side
+            <literal>auth_simple</literal> plugin, and the latter sends
+            the password to the server. The server plugin should reject
+            connections that send an empty password and accept
+            connections that send a nonempty password. Invoke the client
+            program each way to verify this:
+          </para>
+
+<programlisting>
+shell&gt; <userinput>mysql --user=x --skip-password</userinput>
+ERROR 1045 (28000): Access denied for user 'x'@'localhost' (using password: NO)
+
+shell&gt; <userinput>mysql --user=x --password=abc</userinput>
+mysql&gt;
+</programlisting>
+
+          <para>
+            Because the server plugin accepts any nonempty password, it
+            should be considered insecure. After testing the plugin to
+            verify that it works, restart the server without the
+            <option role="mysqld">--plugin-load</option> option so as
+            not to indavertently leave the server running with an
+            insecure authentication plugin loaded. Also, drop the user
+            with <literal role="stmt" condition="drop-user">DROP USER
+            'x'@'localhost'</literal>.
+          </para>
+
+          <para>
+            For additional information about loading and using
+            authentication plugins, see
+            <xref linkend="registering-plugins"/>, and
+            <xref linkend="pluggable-authentication"/>.
+          </para>
+
+          <para>
+            If you are writing a client program that supports the use of
+            authentication plugins, normally such a program causes a
+            plugin to be loaded by calling
+            <literal role="cfunc">mysql_options()</literal> to set the
+            <literal>MYSQL_DEFAULT_AUTH</literal> and
+            <literal>MYSQL_PLUGIN_DIR</literal> options:
+          </para>
+
+<programlisting>
+char *plugin_dir = "<replaceable>path_to_plugin_dir</replaceable>";
+char *default_auth = "<replaceable>plugin_name</replaceable>";
+
+/* ... process command-line options ... */
+
+mysql_options(&amp;mysql, MYSQL_PLUGIN_DIR, plugin_dir);
+mysql_options(&amp;mysql, MYSQL_DEFAULT_AUTH, default_auth);
+</programlisting>
+
+          <para>
+            Typically, the program will also accept
+            <option>--plugin-dir</option> and
+            <option>--default-auth</option> options that enable users to
+            override the default values.
+          </para>
+
+          <para>
+            Should a client program require lower-level plugin
+            management, the client library contains functions that take
+            an <literal>st_mysql_client_plugin</literal> argument. See
+            <xref linkend="c-api-plugin-functions"/>.
+          </para>
+
+        </section>
+
+      </section>
+
     </section>
 
     <section id="plugin-services">


Thread
svn commit - mysqldoc@oter02: r26489 - in trunk: . refman-5.5 refman-5.6paul.dubois11 Jun