external/ibm-public/postfix/dist/src/xsasl/README

   1 Purpose of this document
   2 ========================
   3
   4 This document describes how to add your own SASL implementation to
   5 Postfix.  You don't have to provide both the server and client side.
   6 You can provide just one and omit the other. The examples below
   7 assume you do both.
   8
   9 The plug-in API is described in cyrus_server.c and cyrus_client.c.
  10 It was unavoidably contaminated^h^h^h^h^h^h^h^h^h^h^h^hinfluenced
  11 by Cyrus SASL and may need revision as other implementations are
  12 added.
  13
  14 For an example of how the plug-in interface is implemented, have a
  15 look at the xsasl/xsasl_cyrus_client.c and xsasl/xsasl_cyrus_server.c.
  16
  17 Configuration features
  18 ======================
  19
  20 There are two configuration parameters that allow you to pass
  21 information from main.cf into the plug_in:
  22
  23     smtpd_sasl_path, smtpd_sasl_security_options
  24     smtp_sasl_path, smtp_sasl_security_options
  25     lmtp_sasl_path, lmtp_sasl_security_options
  26
  27 As usual, newline characters are removed from multi-line parameter
  28 values, and $name is expanded recursively.  The parameter values
  29 are passed to the plug-in without any further processing. The
  30 following restrictions are imposed by the main.cf file parser:
  31
  32 - parameter values never contain newlines,
  33
  34 - parameter values never start or end with whitespace characters.
  35
  36 The _path parameter value is passed only once during process
  37 initialization (i.e. it is a class variable). The path typically
  38 specifies the location of a configuration file or rendez-vous point.
  39 The _security_options parameter value is passed each time SASL is
  40 turned on for a connection (i.e. it is an instance variable).  The
  41 options may depend on whether or not TLS encryption is turned on.
  42 Remember that one Postfix process may perform up to 100 mail
  43 transactions during its life time. Things that happen in one
  44 transaction must not affect later transactions.
  45
  46 Adding Postfix support for your own SASL implementation
  47 =======================================================
  48
  49 To add your own SASL implementation, say, FOOBAR:
  50
  51 - Copy xsasl/xsasl_cyrus.h to xsasl/xsasl_foobar.h and replace
  52   CYRUS by FOOBAR:
  53
  54  #if defined(USE_SASL_AUTH) && defined(USE_FOOBAR_SASL)
  55   /*
  56    * SASL protocol interface
  57    */
  58  #define XSASL_TYPE_FOOBAR "foobar"
  59  extern XSASL_SERVER_IMPL *xsasl_foobar_server_init(const char *, const char *);
  60  extern XSASL_CLIENT_IMPL *xsasl_foobar_client_init(const char *, const char *);
  61  #endif
  62
  63 - Edit xsasl/xsasl_server.c, add your #include <xsasl_foobar.h> line
  64   under #include <xsasl_cyrus.h> at the top, and add your initialization
  65   function in the table at the bottom as shown below:
  66
  67   static XSASL_SERVER_IMPL_INFO server_impl_info[] = {
  68   #ifdef XSASL_TYPE_CYRUS
  69       XSASL_TYPE_CYRUS, xsasl_cyrus_server_init,
  70   #endif
  71   #ifdef XSASL_TYPE_FOOBAR
  72       XSASL_TYPE_FOOBAR, xsasl_foobar_server_init,
  73   #endif
  74       0,
  75   };
  76
  77 - Repeat the (almost) same procedure for xsasl/xsasl_client.c.
  78
  79 - Create your own xsasl/xsasl_foobar_{client,server}.c and support
  80   files. Perhaps it's convenient to copy the cyrus files, rip out
  81   the function bodies, and replace CYRUS by FOOBAR.
  82
  83 - List your source files in Makefile.in. Don't forget to do "make
  84   depend" after you do "make makefiles" in the step that follows
  85   after this one.
  86
  87   SRCS    = xsasl_server.c xsasl_cyrus_server.c xsasl_cyrus_log.c \
  88           xsasl_cyrus_security.c xsasl_client.c xsasl_cyrus_client.c \
  89           xsasl_foobar_client.c xsasl_foobar_server.c
  90   OBJS    = xsasl_server.o xsasl_cyrus_server.o xsasl_cyrus_log.o \
  91           xsasl_cyrus_security.o xsasl_client.o xsasl_cyrus_client.o \
  92           xsasl_foobar_client.o xsasl_foobar_server.o
  93
  94 - Create the Postfix makefiles from the top-level directory:
  95
  96   % make makefiles CCARGS='-DUSE_SASL_AUTH -DUSE_FOOBAR_SASL \
  97       -DDEF_CLIENT_SASL_TYPE=\"foobar\" -DDEF_SERVER_SASL_TYPE=\"foobar\" \
  98       -I/some/where/include' AUXLIBS='-L/some/where/lib -lfoobar'
  99
 100   Yes, you can have different default SASL implementation types for
 101   the client and server plug-ins.
 102
 103   Of course you don't have to override the default SASL implementation
 104   type; it is shown here as an example.
 105
 106
 107 - Don't forget to do "make depend" in the xsasl directory.
 108
 109 - Document your build and configuration with a README document.