README
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