| 1 | $Cambridge: exim/src/src/auths/README,v 1.3 2005/02/17 11:58:27 ph10 Exp $ |
| 2 | |
| 3 | AUTHS |
| 4 | |
| 5 | The modules in this directory are in support of various authentication |
| 6 | functions. Some of them, such as the base64 encoding/decoding and MD5 |
| 7 | computation, are just functions that might be used by several authentication |
| 8 | mechanisms. Others are the SMTP AUTH mechanisms themselves, included in the |
| 9 | final binary if the relevant AUTH_XXX value is set in Local/Makefile. The |
| 10 | general functions are in separate modules so that they get included in the |
| 11 | final binary only if they are actually called from somewhere. |
| 12 | |
| 13 | GENERAL FUNCTIONS |
| 14 | |
| 15 | The API for each of these functions is documented with the function's code. |
| 16 | |
| 17 | auth_b64encode encode in base 64 |
| 18 | auth_b64decode decode from base 64 |
| 19 | auth_call_pam do PAM authentication (if build with SUPPORT_PAM) |
| 20 | auth_get_data issue SMTP AUTH challenge and read response |
| 21 | auth_xtextencode encode as xtext |
| 22 | auth_xtextdecode decode from xtext |
| 23 | |
| 24 | INTERFACE TO SMTP AUTHENTICATION MECHANISMS |
| 25 | |
| 26 | These are general SSL mechanisms, adapted for use with SMTP. Each |
| 27 | authentication mechanism has three functions, for initialization, server |
| 28 | authentication, and client authentication. |
| 29 | |
| 30 | INITIALIZATION |
| 31 | |
| 32 | The initialization function is called when the configuration is read, and can |
| 33 | check for incomplete or illegal settings. It has one argument, a pointer to the |
| 34 | instance block for this configured mechanism. It must set the flags called |
| 35 | "server" and "client" in the generic auth_instance block to indicate whether |
| 36 | the server and/or client functions are available for this authenticator. |
| 37 | Typically this depends on whether server or client configuration options have |
| 38 | been set, but it is also possible to have an authenticator that has only one of |
| 39 | the server or client functions. |
| 40 | |
| 41 | SERVER AUTHENTICATION |
| 42 | |
| 43 | The second function performs authentication as a server. It receives a pointer |
| 44 | to the instance block, and its second argument is the remainder of the data |
| 45 | from the AUTH command. The numeric variable maximum setting (expand_nmax) is |
| 46 | set to zero, with $0 initialized as unset. The authenticator may set up numeric |
| 47 | variables according to its specification; it should leave expand_nmax set at |
| 48 | the end so that they can be used for the expansion of the generic server_set_id |
| 49 | option, which happens centrally. |
| 50 | |
| 51 | This function has access to the SMTP input and output so that it can write |
| 52 | intermediate responses and read more data if necessary. There is a packaged |
| 53 | function in auth_get_data() which outputs a challenge and reads a response. |
| 54 | |
| 55 | The yield of a server authentication check must be one of: |
| 56 | |
| 57 | OK success |
| 58 | DEFER couldn't complete the check |
| 59 | FAIL authentication failed |
| 60 | CANCELLED authentication forced to fail by "*" response to challenge, |
| 61 | or by a forced string expansion failure |
| 62 | BAD64 bad base64 data received |
| 63 | UNEXPECTED unexpected data received |
| 64 | |
| 65 | In the case of DEFER, auth_defer_msg should point to an error message. |
| 66 | |
| 67 | CLIENT AUTHENTICATION |
| 68 | |
| 69 | The third function performs authentication as a client. It receives a pointer |
| 70 | to the instance block, and four further arguments: |
| 71 | |
| 72 | The smtp_inblock item for the connection to the remote host. |
| 73 | |
| 74 | The normal command-reading timeout value. |
| 75 | |
| 76 | A pointer to a buffer, to be used for receiving responses. It is done this |
| 77 | way so that the buffer is available for logging etc. in the calling |
| 78 | function in cases of error. |
| 79 | |
| 80 | The size of the buffer. |
| 81 | |
| 82 | The yield of a client authentication check must be one of: |
| 83 | |
| 84 | OK success |
| 85 | FAIL_SEND error after writing a command; errno is set |
| 86 | FAIL failed after reading a response; |
| 87 | either errno is set (for timeouts, I/O failures) or |
| 88 | the buffer contains the SMTP response line |
| 89 | FORCEFAIL failed without reading a response (often "fail" in expansion) |
| 90 | ERROR local problem (typically expansion error); message in buffer |
| 91 | |
| 92 | To communicate with the remote host the client should call |
| 93 | smtp_write_command(). If this yields FALSE, the authenticator should return |
| 94 | FAIL. After a successful write, the response is received by a call to |
| 95 | smtp_read_response(), which should use the buffer handed to the client function |
| 96 | as an argument. |
| 97 | |
| 98 | **** |