src/src/auths/README

   1 $Cambridge: exim/src/src/auths/README,v 1.2 2004/12/20 14:57:05 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 ****