plugins/change_password/API

   1     ******************************
   2     * Change Password plugin API *
   3     ******************************
   4
   5 Document should explain how to create change_password plugin backends and
   6 provide details about plugin structure.
   7
   8 Plugin uses standard SquirrelMail plugin architecture and implements backends
   9 with two hooks.
  10
  11 change_password_init hook
  12 -------------------------
  13 change_password_init hook is used to execute some code before displaying
  14 change password form. Plugin can use this hook to check if install has all
  15 required components, or to check if backend is configured correctly, or
  16 display some messages to end user. Maybe some background information about
  17 password security and how to choose good password. If backend detects some
  18 configuration errors that make backend unusable, it can stop execution of the
  19 script with PHP exit() call.
  20
  21 change_password_dochange hook
  22 -----------------------------
  23 change_password_dochange hook is used when user submits old and new passwords.
  24 Plugin checks if old password matches current session password and checks new
  25 password satisfies requirements set in plugin's configuration. All data is
  26 provided in array submitted via hook. 'username' key contains user's login
  27 name, 'curpw' contains current session password, 'newpw' contains new password.
  28 Function that is attached to plugin should return empty array or array filled
  29 with error messages. If array is empty - plugin assumes that password was
  30 changed and updates current session password.
  31
  32 common strings
  33 --------------
  34 Backends can use constants for some error messages. CPW_CURRENT_NOMATCH
  35 constant sets 'Your current password is not correct.' error. CPW_INVALID_PW
  36 constant sets 'Your new password contains invalid characters.' error.
  37
  38 Recommendations
  39 ---------------
  40 Backend should check, if current password matches stored password.
  41 Internal plugin functions only check if password matches the one that
  42 was used to login into SquirrelMail. Password is validated against IMAP
  43 server and not against used backend.
  44
  45 Backend should store only default configuration variables that don't
  46 have any information specific to developer's server or these variables
  47 should be set to sane default values.
  48
  49 Backend's configuration should be controlled with configuration overrides
  50 that are set config.php. It is recommended to use array with
  51 configuration overrides and make sure that array is set to empty value
  52 before loading plugin's configuration file.
  53
  54 Backend should not use generic function names. It is recommended to use
  55 'cpw_' prefix.
  56
  57 If backend must load other SquirrelMail functions, it must use SM_PATH
  58 constant in include_once() calls and make sure that SM_PATH is defined
  59 in any case when backend file is loaded. In most cases constant is
  60 already defined, but some unusual use of php files might cause php
  61 warnings, if constant is used inside backend functions and not defined
  62 in backend file.
  63
  64 Overrides used by backend and backend requirements must be documented
  65 in README file.