Commit | Line | Data |
---|---|---|
8e669ac1 | 1 | $Cambridge: exim/src/src/auths/README,v 1.3 2005/02/17 11:58:27 ph10 Exp $ |
0756eb3c PH |
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 | |
b1206957 | 60 | CANCELLED authentication forced to fail by "*" response to challenge, |
8e669ac1 | 61 | or by a forced string expansion failure |
0756eb3c PH |
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 | **** |