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. |