Commit | Line | Data |
---|---|---|
0756eb3c PH |
1 | AUTHS |
2 | ||
3 | The modules in this directory are in support of various authentication | |
4 | functions. Some of them, such as the base64 encoding/decoding and MD5 | |
5 | computation, are just functions that might be used by several authentication | |
6 | mechanisms. Others are the SMTP AUTH mechanisms themselves, included in the | |
7 | final binary if the relevant AUTH_XXX value is set in Local/Makefile. The | |
8 | general functions are in separate modules so that they get included in the | |
9 | final binary only if they are actually called from somewhere. | |
10 | ||
11 | GENERAL FUNCTIONS | |
12 | ||
13 | The API for each of these functions is documented with the function's code. | |
14 | ||
15 | auth_b64encode encode in base 64 | |
16 | auth_b64decode decode from base 64 | |
17 | auth_call_pam do PAM authentication (if build with SUPPORT_PAM) | |
18 | auth_get_data issue SMTP AUTH challenge and read response | |
19 | auth_xtextencode encode as xtext | |
20 | auth_xtextdecode decode from xtext | |
21 | ||
22 | INTERFACE TO SMTP AUTHENTICATION MECHANISMS | |
23 | ||
24 | These are general SSL mechanisms, adapted for use with SMTP. Each | |
25 | authentication mechanism has three functions, for initialization, server | |
26 | authentication, and client authentication. | |
27 | ||
28 | INITIALIZATION | |
29 | ||
30 | The initialization function is called when the configuration is read, and can | |
31 | check for incomplete or illegal settings. It has one argument, a pointer to the | |
32 | instance block for this configured mechanism. It must set the flags called | |
33 | "server" and "client" in the generic auth_instance block to indicate whether | |
34 | the server and/or client functions are available for this authenticator. | |
35 | Typically this depends on whether server or client configuration options have | |
36 | been set, but it is also possible to have an authenticator that has only one of | |
37 | the server or client functions. | |
38 | ||
39 | SERVER AUTHENTICATION | |
40 | ||
41 | The second function performs authentication as a server. It receives a pointer | |
42 | to the instance block, and its second argument is the remainder of the data | |
43 | from the AUTH command. The numeric variable maximum setting (expand_nmax) is | |
44 | set to zero, with $0 initialized as unset. The authenticator may set up numeric | |
f78eb7c6 PH |
45 | variables according to its (old) specification and $auth<n> variables the |
46 | preferred ones nowadays; it should leave them set at the end so that they can | |
47 | be used for the expansion of the generic server_set_id option, which happens | |
48 | centrally. | |
0756eb3c PH |
49 | |
50 | This function has access to the SMTP input and output so that it can write | |
51 | intermediate responses and read more data if necessary. There is a packaged | |
52 | function in auth_get_data() which outputs a challenge and reads a response. | |
53 | ||
54 | The yield of a server authentication check must be one of: | |
55 | ||
56 | OK success | |
57 | DEFER couldn't complete the check | |
58 | FAIL authentication failed | |
b1206957 | 59 | CANCELLED authentication forced to fail by "*" response to challenge, |
16ff981e | 60 | or by certain forced string expansion failures |
0756eb3c PH |
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 | |
4730f942 PH |
88 | CANCELLED the client cancelled authentication (often "fail" in expansion) |
89 | the buffer may contain a message; if not, *buffer = 0 | |
0756eb3c PH |
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 | **** |