Commit | Line | Data |
---|---|---|
0756eb3c PH |
1 | $Cambridge: exim/src/src/auths/README,v 1.1 2004/10/07 13:10:00 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 | BAD64 bad base64 data received | |
62 | UNEXPECTED unexpected data received | |
63 | ||
64 | In the case of DEFER, auth_defer_msg should point to an error message. | |
65 | ||
66 | CLIENT AUTHENTICATION | |
67 | ||
68 | The third function performs authentication as a client. It receives a pointer | |
69 | to the instance block, and four further arguments: | |
70 | ||
71 | The smtp_inblock item for the connection to the remote host. | |
72 | ||
73 | The normal command-reading timeout value. | |
74 | ||
75 | A pointer to a buffer, to be used for receiving responses. It is done this | |
76 | way so that the buffer is available for logging etc. in the calling | |
77 | function in cases of error. | |
78 | ||
79 | The size of the buffer. | |
80 | ||
81 | The yield of a client authentication check must be one of: | |
82 | ||
83 | OK success | |
84 | FAIL_SEND error after writing a command; errno is set | |
85 | FAIL failed after reading a response; | |
86 | either errno is set (for timeouts, I/O failures) or | |
87 | the buffer contains the SMTP response line | |
88 | FORCEFAIL failed without reading a response (often "fail" in expansion) | |
89 | ERROR local problem (typically expansion error); message in buffer | |
90 | ||
91 | To communicate with the remote host the client should call | |
92 | smtp_write_command(). If this yields FALSE, the authenticator should return | |
93 | FAIL. After a successful write, the response is received by a call to | |
94 | smtp_read_response(), which should use the buffer handed to the client function | |
95 | as an argument. | |
96 | ||
97 | **** |