| a4b225ee |
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. |
projects / squirrelmail.git / blame