1Purpose of this document 2======================== 3 4This document describes how to add your own SASL implementation to 5Postfix. You don't have to provide both the server and client side. 6You can provide just one and omit the other. The examples below 7assume you do both. 8 9The plug-in API is described in cyrus_server.c and cyrus_client.c. 10It was unavoidably contaminated^h^h^h^h^h^h^h^h^h^h^h^hinfluenced 11by Cyrus SASL and may need revision as other implementations are 12added. 13 14For an example of how the plug-in interface is implemented, have a 15look at the xsasl/xsasl_cyrus_client.c and xsasl/xsasl_cyrus_server.c. 16 17Configuration features 18====================== 19 20There are two configuration parameters that allow you to pass 21information 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 27As usual, newline characters are removed from multi-line parameter 28values, and $name is expanded recursively. The parameter values 29are passed to the plug-in without any further processing. The 30following 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 36The _path parameter value is passed only once during process 37initialization (i.e. it is a class variable). The path typically 38specifies the location of a configuration file or rendez-vous point. 39The _security_options parameter value is passed each time SASL is 40turned on for a connection (i.e. it is an instance variable). The 41options may depend on whether or not TLS encryption is turned on. 42Remember that one Postfix process may perform up to 100 mail 43transactions during its life time. Things that happen in one 44transaction must not affect later transactions. 45 46Adding Postfix support for your own SASL implementation 47======================================================= 48 49To 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. 110