Doxygen: documented the password validation service and the keyring service

Author: gkodinov

include/mysql/plugin_validate_password.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+/* Copyright (c) 2012, 2016, 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 as published by
@@ -24,26 +24,47 @@
 #include <mysql/plugin.h>
 #define MYSQL_VALIDATE_PASSWORD_INTERFACE_VERSION 0x0100
 
-/*  
-  The descriptor structure for the plugin, that is referred from
-  st_mysql_plugin.
-*/
-
 typedef void* mysql_string_handle;
 
+/**
+  This plugin type defines interface that the server uses to
+  enforce a password policy.
+
+  The policy is enfoced through st_mysql_validate_password::validate_password()
+  that answers the question of whether this password is good enough or not.
+
+  There's one auxilary functon
+  st_mysql_validate_password::get_password_strength() that can be used by
+  password changing UIs to display a password strength meter as the user enters
+  a password.
+
+  Since plugins may need that functionality there's a plugin service
+  @ref mysql_password_policy_service_st exposing
+  it to other plugins.
+
+  There also is a default password policy plugin
+  "validate_password" built into the server binary that
+  implements this plugin API.
+
+  @sa mysql_password_policy_service_st
+*/
 struct st_mysql_validate_password
 {
   int interface_version;
-  /*  
-    This function retuns TRUE for passwords which satisfy the password
-    policy (as choosen by plugin variable) and FALSE for all other
-    password
+  /**
+    Checks if a password is valid by the password policy
+
+    @param password  The password to validate
+    @retval TRUE   password meets the password validation plugin policy
+    @retval FALSE  password does not meet the validation policy
   */
   int (*validate_password)(mysql_string_handle password);
-  /*  
-    This function returns the password strength (0-100) depending
-    upon the policies
+  /**
+    Calculates the strength of a password in the scale of 0 to 100.
+
+    @param password The password to evaluate the strength of
+    @return  The strength of the password (0-100)
   */
   int (*get_password_strength)(mysql_string_handle password);
 };
-#endif
+#endif

include/mysql/service_mysql_keyring.h

@@ -16,17 +16,69 @@
 #ifndef MYSQL_SERVICE_MYSQL_PLUGIN_KEYRING_INCLUDED
 #define MYSQL_SERVICE_MYSQL_PLUGIN_KEYRING_INCLUDED
 
+/**
+  @file include/mysql/service_mysql_keyring.h
+*/
+
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+  @ingroup group_ext_plugin_services
+
+  This service allows plugins to interact with key store backends.
+
+  A key currently is a blob of binary data, defined by a string
+  key type, that's meanigfull to the relevant backend.
+  Typical key_type values include "AES", "DES", "DSA" etc.
+  There's no length in the type, since it's defined by the number of bytes
+  the key takes.
+
+  A key is uniquely identified by the key_id and the user_id values, i.e.
+  all keys are assigned to a particular user.
+  There's only one exception to that: a single category for instance keys
+  that are not associated with any particular user id. This is signified
+  to the APIs by supplying NULL for user_id.
+  Plugins would typically pass user accounts to the user_id parameter, or
+  NULL if there's no user account to associate the key with.
+
+  Not all backends must implement all of the functions defined
+  in this interface.
+
+  The plugin service is a "bridge service", i.e. facade with no
+  real functionality that just calls the actual keyring plugin APIs.
+  This is needed to allow other plugins to call into the keyring
+  plugins and thus overcome the limitation that only the server
+  can call plugins.
+
+  @sa st_mysql_keyring
+*/
 extern struct mysql_keyring_service_st
 {
+  /**
+    Stores a key into the keyring.
+    @sa my_key_store, st_mysql_keyring::mysql_key_store
+  */
   int (*my_key_store_func)(const char *, const char *, const char *,
                            const void *, size_t);
+  /**
+    Receives a key from the keyring.
+    @sa my_key_fetch, st_mysql_keyring::mysql_key_fetch
+  */
   int (*my_key_fetch_func)(const char *, char **, const char *, void **,
                            size_t *);
+
+  /**
+    Removes a key from the keyring.
+    @sa my_key_remove, st_mysql_keyring::mysql_key_remove
+  */
   int (*my_key_remove_func)(const char *, const char *);
+  /**
+    Generates a new key inside the keyring backend
+    @sa my_key_generate, st_mysql_keyring::mysql_key_generate
+  */
   int (*my_key_generate_func)(const char *, const char *, const char *,
                               size_t);
 } *mysql_keyring_service;

include/mysql/service_mysql_password_policy.h

@@ -1,4 +1,4 @@
-/* Copyright (c) 2014, 2015 Oracle and/or its affiliates. All rights reserved.
+/* Copyright (c) 2014, 2016 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 as published by
@@ -18,30 +18,39 @@
 
 /**
   @file include/mysql/service_mysql_password_policy.h
-  This service provides functions to validate password, check for strength
-  of password based on common policy.
-
-  SYNOPSIS
-  my_validate_password_policy()    - function to validate password
-                                     based on defined policy
-  const char*                        buffer holding the password value
-  unsigned int                       buffer length
-
-  my_calculate_password_strength() - function to calculate strength
-                                     of the password based on the policies defined.
-  const char*                        buffer holding the password value
-  unsigned int                       buffer length
-
-  Both the service function returns 0 on SUCCESS and 1 incase input password does not
-  match against the policy rules defined.
+
+  Definitions for the password validation service
 */
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+  @ingroup group_ext_plugin_services
+
+  This service allows plugins to validate passwords based on a common policy.
+
+  This is a "bridge service", i.e. facade with no
+  real functionality that just calls the actual password validation plugin
+  APIs. This serive is needed by other plugins to call into the password
+  validation plugins and thus overcome the limitation that only the server
+  can call plugins.
+
+  @sa st_mysql_validate_password
+*/
 extern struct mysql_password_policy_service_st {
+  /**
+    Validates a password.
+
+    @sa my_validate_password_policy, st_mysql_validate_password::validate_password
+  */
   int (*my_validate_password_policy_func)(const char *, unsigned int);
+  /**
+    Evaluates the strength of a password in a scale 0-100
+
+    @sa my_calculate_password_strength, st_mysql_validate_password::get_password_strength
+  */
   int (*my_calculate_password_strength_func)(const char *, unsigned int);
 } *mysql_password_policy_service;
 

sql/auth/password_policy_service.cc

@@ -1,4 +1,4 @@
-/*  Copyright (c) 2015 Oracle and/or its affiliates. All rights reserved.
+/*  Copyright (c) 2015, 2016 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 as
@@ -24,19 +24,32 @@
 #include "sql_plugin.h"
 
 
+/**
+  Static name of the built in plugin used by mysql_password_policy_service_st
+  for password validation.
+*/
 LEX_CSTRING validate_password_plugin= {
   C_STRING_WITH_LEN("validate_password")
 };
 
 /**
-  Validate the input password based on defined policies.
+  Invoke the plugin to validate the input password.
+
+  Implementation of a plugin service @ref mysql_password_policy_service_st
+  method.
+  Calls the @ref validate_password_plugin plugin's @ref
+  st_mysql_validate_password::validate_password method.
+  Constructs a temporary binary @ref String object out of the password
+  supplied.
 
   @param password        password which needs to be validated against the
                          defined policies
   @param password_len    length of password
 
-  @retval 0 ok
-  @retval 1 ERROR;
+  @retval 0 Password OK
+  @retval 1 Password incompatible with policy
+
+  @sa st_mysql_validate_password, mysql_password_policy_service_st::my_validate_password_policy_func
 */
 
 int my_validate_password_policy(const char *password, unsigned int password_len)
@@ -68,7 +81,25 @@ int my_validate_password_policy(const char *password, unsigned int password_len)
 }
 
 
-/* called when new user is created or exsisting password is changed */
+/**
+  Invoke the plugin to evalue the strength of a password.
+
+  Implementation of a plugin service @ref mysql_password_policy_service_st
+  method.
+  Typically called when new user is created or exsisting password is changed.
+  Calls the @ref validate_password_plugin plugin's @ref
+  st_mysql_validate_password::get_password_strength method.
+  Constructs a temporary binary @ref String object out of the password
+  supplied.
+
+  @param password        password which needs to be validated against the
+                         defined policies
+  @param password_len    length of password
+
+  @return password strength score (0-100)
+
+  @sa st_mysql_validate_password, mysql_password_policy_service_st::my_calculate_password_strength_func
+*/
 int my_calculate_password_strength(const char *password, unsigned int password_len)
 {
   int res= 0;

sql/keyring_service.cc

@@ -105,6 +105,12 @@ static my_bool key_generate(THD *thd, plugin_ref plugin, void *arg)
   return TRUE;
 }
 
+/**
+  Iterates over all active keyring plugins and calls the mysql_key_fetch API
+  for the first one found.
+
+  @sa st_mysql_keyring::mysql_key_fetch, mysql_keyring_service_st
+*/
 int my_key_fetch(const char *key_id, char **key_type, const char *user_id,
                  void **key, size_t *key_len)
 {
@@ -118,6 +124,13 @@ int my_key_fetch(const char *key_id, char **key_type, const char *user_id,
   return key_data.result;
 }
 
+
+/**
+  Iterates over all active keyring plugins calls the mysql_key_store API
+  for the first one found.
+
+  @sa st_mysql_keyring::mysql_key_store, mysql_keyring_service_st
+*/
 int my_key_store(const char *key_id, const char *key_type, const char *user_id,
                  const void *key, size_t key_len)
 {
@@ -131,6 +144,12 @@ int my_key_store(const char *key_id, const char *key_type, const char *user_id,
   return key_data.result;
 }
 
+/**
+  Iterates over all active keyring plugins and calls the mysql_key_remove API
+  for the first one found.
+
+  @sa st_mysql_keyring::mysql_key_remove, mysql_keyring_service_st
+*/
 int my_key_remove(const char *key_id, const char *user_id)
 {
   Key_data key_data;
@@ -140,6 +159,12 @@ int my_key_remove(const char *key_id, const char *user_id)
   return key_data.result;
 }
 
+/**
+  Iterates over all active keyring plugins and calls the mysql_key_generate API
+  for the first one found.
+
+  @sa st_mysql_keyring::mysql_key_generate, mysql_keyring_service_st
+*/
 int my_key_generate(const char *key_id, const char *key_type,
                     const char *user_id, size_t key_len)
 {