From b5896ba9f6047e7031e2bdee0622d543e11a6734 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 03:46:30 +0200 Subject: Adding upstream version 3.4.23. Signed-off-by: Daniel Baumann --- src/xsasl/README | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 src/xsasl/README (limited to 'src/xsasl/README') 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 line + under #include 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. -- cgit v1.2.3