Commit | Line | Data |
---|---|---|
4730f942 | 1 | $Cambridge: exim/src/src/auths/README,v 1.5 2006/02/23 12:41:22 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 | |
f78eb7c6 PH |
47 | variables according to its (old) specification and $auth<n> variables the |
48 | preferred ones nowadays; it should leave them set at the end so that they can | |
49 | be used for the expansion of the generic server_set_id option, which happens | |
50 | centrally. | |
0756eb3c PH |
51 | |
52 | This function has access to the SMTP input and output so that it can write | |
53 | intermediate responses and read more data if necessary. There is a packaged | |
54 | function in auth_get_data() which outputs a challenge and reads a response. | |
55 | ||
56 | The yield of a server authentication check must be one of: | |
57 | ||
58 | OK success | |
59 | DEFER couldn't complete the check | |
60 | FAIL authentication failed | |
b1206957 | 61 | CANCELLED authentication forced to fail by "*" response to challenge, |
8e669ac1 | 62 | or by a forced string expansion failure |
0756eb3c PH |
63 | BAD64 bad base64 data received |
64 | UNEXPECTED unexpected data received | |
65 | ||
66 | In the case of DEFER, auth_defer_msg should point to an error message. | |
67 | ||
68 | CLIENT AUTHENTICATION | |
69 | ||
70 | The third function performs authentication as a client. It receives a pointer | |
71 | to the instance block, and four further arguments: | |
72 | ||
73 | The smtp_inblock item for the connection to the remote host. | |
74 | ||
75 | The normal command-reading timeout value. | |
76 | ||
77 | A pointer to a buffer, to be used for receiving responses. It is done this | |
78 | way so that the buffer is available for logging etc. in the calling | |
79 | function in cases of error. | |
80 | ||
81 | The size of the buffer. | |
82 | ||
83 | The yield of a client authentication check must be one of: | |
84 | ||
85 | OK success | |
86 | FAIL_SEND error after writing a command; errno is set | |
87 | FAIL failed after reading a response; | |
88 | either errno is set (for timeouts, I/O failures) or | |
89 | the buffer contains the SMTP response line | |
4730f942 PH |
90 | CANCELLED the client cancelled authentication (often "fail" in expansion) |
91 | the buffer may contain a message; if not, *buffer = 0 | |
0756eb3c PH |
92 | ERROR local problem (typically expansion error); message in buffer |
93 | ||
94 | To communicate with the remote host the client should call | |
95 | smtp_write_command(). If this yields FALSE, the authenticator should return | |
96 | FAIL. After a successful write, the response is received by a call to | |
97 | smtp_read_response(), which should use the buffer handed to the client function | |
98 | as an argument. | |
99 | ||
100 | **** |