summaryrefslogtreecommitdiffstats
path: root/src/xsasl/README
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--src/xsasl/README109
1 files changed, 109 insertions, 0 deletions
diff --git a/src/xsasl/README b/src/xsasl/README
new file mode 100644
index 0000000..d1b2f5a
--- /dev/null
+++ b/src/xsasl/README
@@ -0,0 +1,109 @@
+Purpose of this document
+========================
+
+This document describes how to add your own SASL implementation to
+Postfix. You don't have to provide both the server and client side.
+You can provide just one and omit the other. The examples below
+assume you do both.
+
+The plug-in API is described in cyrus_server.c and cyrus_client.c.
+It was unavoidably contaminated^h^h^h^h^h^h^h^h^h^h^h^hinfluenced
+by Cyrus SASL and may need revision as other implementations are
+added.
+
+For an example of how the plug-in interface is implemented, have a
+look at the xsasl/xsasl_cyrus_client.c and xsasl/xsasl_cyrus_server.c.
+
+Configuration features
+======================
+
+There are two configuration parameters that allow you to pass
+information from main.cf into the plug_in:
+
+ smtpd_sasl_path, smtpd_sasl_security_options
+ smtp_sasl_path, smtp_sasl_security_options
+ lmtp_sasl_path, lmtp_sasl_security_options
+
+As usual, newline characters are removed from multi-line parameter
+values, and $name is expanded recursively. The parameter values
+are passed to the plug-in without any further processing. The
+following restrictions are imposed by the main.cf file parser:
+
+- parameter values never contain newlines,
+
+- parameter values never start or end with whitespace characters.
+
+The _path parameter value is passed only once during process
+initialization (i.e. it is a class variable). The path typically
+specifies the location of a configuration file or rendez-vous point.
+The _security_options parameter value is passed each time SASL is
+turned on for a connection (i.e. it is an instance variable). The
+options may depend on whether or not TLS encryption is turned on.
+Remember that one Postfix process may perform up to 100 mail
+transactions during its life time. Things that happen in one
+transaction must not affect later transactions.
+
+Adding Postfix support for your own SASL implementation
+=======================================================
+
+To add your own SASL implementation, say, FOOBAR:
+
+- Copy xsasl/xsasl_cyrus.h to xsasl/xsasl_foobar.h and replace
+ CYRUS by FOOBAR:
+
+ #if defined(USE_SASL_AUTH) && defined(USE_FOOBAR_SASL)
+ /*
+ * SASL protocol interface
+ */
+ #define XSASL_TYPE_FOOBAR "foobar"
+ extern XSASL_SERVER_IMPL *xsasl_foobar_server_init(const char *, const char *);
+ extern XSASL_CLIENT_IMPL *xsasl_foobar_client_init(const char *, const char *);
+ #endif
+
+- Edit xsasl/xsasl_server.c, add your #include <xsasl_foobar.h> line
+ under #include <xsasl_cyrus.h> at the top, and add your initialization
+ function in the table at the bottom as shown below:
+
+ static XSASL_SERVER_IMPL_INFO server_impl_info[] = {
+ #ifdef XSASL_TYPE_CYRUS
+ XSASL_TYPE_CYRUS, xsasl_cyrus_server_init,
+ #endif
+ #ifdef XSASL_TYPE_FOOBAR
+ XSASL_TYPE_FOOBAR, xsasl_foobar_server_init,
+ #endif
+ 0,
+ };
+
+- Repeat the (almost) same procedure for xsasl/xsasl_client.c.
+
+- Create your own xsasl/xsasl_foobar_{client,server}.c and support
+ files. Perhaps it's convenient to copy the cyrus files, rip out
+ the function bodies, and replace CYRUS by FOOBAR.
+
+- List your source files in Makefile.in. Don't forget to do "make
+ depend" after you do "make makefiles" in the step that follows
+ after this one.
+
+ SRCS = xsasl_server.c xsasl_cyrus_server.c xsasl_cyrus_log.c \
+ xsasl_cyrus_security.c xsasl_client.c xsasl_cyrus_client.c \
+ xsasl_foobar_client.c xsasl_foobar_server.c
+ OBJS = xsasl_server.o xsasl_cyrus_server.o xsasl_cyrus_log.o \
+ xsasl_cyrus_security.o xsasl_client.o xsasl_cyrus_client.o \
+ xsasl_foobar_client.o xsasl_foobar_server.o
+
+- Create the Postfix makefiles from the top-level directory:
+
+ % make makefiles CCARGS='-DUSE_SASL_AUTH -DUSE_FOOBAR_SASL \
+ -DDEF_CLIENT_SASL_TYPE=\"foobar\" -DDEF_SERVER_SASL_TYPE=\"foobar\" \
+ -I/some/where/include' AUXLIBS='-L/some/where/lib -lfoobar'
+
+ Yes, you can have different default SASL implementation types for
+ the client and server plug-ins.
+
+ Of course you don't have to override the default SASL implementation
+ type; it is shown here as an example.
+
+
+- Don't forget to do "make depend" in the xsasl directory.
+
+- Document your build and configuration with a README document.