--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_auth_cyrus/README.md	Sun Oct 17 17:08:07 2021 +0200
@@ -0,0 +1,125 @@
+---
+title: Cyrus SASL
+rockspec:
+  build:
+    modules:
+      util.sasl_cyrus: sasl_cyrus.lua
+---
+
+# Introduction
+
+XMPP uses a standard authentication protocol called 'SASL' to validate
+client credentials. Prosody has a built-in SASL library, and uses this
+by default to validate credentials against Prosody's internal account
+store.
+
+Alternatively Prosody supports using Cyrus SASL, an external SASL
+provider which can validate user-supplied credentials against other
+sources, such as PAM, LDAP, SQL and more. It also allows the use of
+GSSAPI for single-sign-on services.
+
+# Usage
+
+## lua-cyrussasl
+
+To allow Prosody to access Cyrus SASL you need to install lua-cyrussasl.
+Information on how to do that on most platforms can be found on our
+[dependencies page](/doc/depends). Those running Debian/Ubuntu can
+simply:
+
+``` {.code}
+ sudo apt-get install lua-cyrussasl
+```
+
+On Redhat/CentOS, the [EPEL
+repository](https://fedoraproject.org/wiki/EPEL) needs to be enabled,
+after which you can install the package:
+
+``` {.code}
+ sudo yum install lua-cyrussasl
+```
+
+## Configuration
+
+Enable the cyrus backend by adding the following line to your config
+file:
+
+``` {.code .lua}
+   authentication = "cyrus"
+   cyrus_service_name = "xmpp" -- Optional, defaults to "xmpp"
+```
+
+Configuring Cyrus SASL itself is currently beyond the scope of this
+documentation. If you feel you could contribute a simple how-to, or know
+the link of a good one to add below then [let us know](/discuss)
+[:smile:]{.icon}
+
+Prosody's Cyrus SASL-related options:
+
+  Option                       Default   Description
+  ---------------------------- --------- --------------------------------------------------------------------------------------------------------------
+  cyrus_service_name           xmpp      The service name to pass to Cyrus SASL.
+  cyrus_service_realm          (auto)    The realm to pass to Cyrus SASL, the virtual host the user is signing into if not specified.
+  cyrus_require_provisioning   false     If true then Prosody requires user accounts to exist in Prosody, even if successfully authenticated via SASL
+  cyrus_application_name       prosody   The application name to pass to Cyrus SASL. Determines the Cyrus SASL configuration file name.
+  cyrus_server_fqdn                      hostname passed to Cyrus
+
+## Troubleshooting
+
+### Permissions
+
+One of the most common issues is Prosody being unable to access the
+saslauthd socket (this is obviously only an issue if you are using the
+saslauthd daemon), used to communicate with the authentication daemon.
+An example error caused by this would be:
+
+``` {.code}
+ Got SASL error condition -1: Password verification failed
+```
+
+This can be confirmed by trying testsaslauthd as root and then as the
+user prosody runs as (typically 'prosody'); the former should succeed
+and the latter should fail.
+
+The solution is to make sure that prosody can access the socket
+(typically in /var/run/saslauthd/) by adding the 'prosody' user to the
+'sasl' group (or otherwise ensuring that the prosody user has filesystem
+permissions to access the socket).
+
+### Cyrus SASL Configuration file {#cyrus_sasl_configuration_file}
+
+Cyrus SASL needs a configuration file in order to know where to look for
+user credentials. For Prosody, the file will be named prosody.conf by
+default. Its location varies by OS and distribution; refer to the table
+below or your local system documentation for where it should go.
+
+  Location     Platforms
+  ------------ -------------------
+  /etc/sasl    Debian and Ubuntu
+  /etc/sasl2   Arch, RHEL/CentOS
+
+The contents of the configuration file depend on what you want to
+authenticate against. If you want to authenticate against local
+accounts, you'll want to set up saslauthd (the configuration of
+saslauthd varies from system to system), and your prosody.conf will look
+like this:
+
+``` {.code}
+pwcheck_method: saslauthd
+mech_list: PLAIN
+```
+
+If using saslauthd, you must specify only PLAIN in the mech_list, as it
+only supports plaintext authentication methods.
+
+## Other references {#other_references}
+
+-   [Setting up Prosody to authenticate against LDAP (blog
+    post)](http://blog.marc-seeger.de/2009/12/30/setting-up-prosody-to-authenticate-against-ldap/)
+    -   This post uses xmpp.conf, but the name is now prosody.conf (see
+        cyrus_application_name above)
+-   [Surviving Cyrus SASL
+    (PDF)](http://www.arschkrebs.de/slides/surviving_cyrus_sasl-handout.pdf)
+    [(view)](http://docs.google.com/viewer?url=http%3A%2F%2Fwww.arschkrebs.de%2Fslides%2Fsurviving_cyrus_sasl-handout.pdf)
+-   [Cyrus SASL error
+    codes](http://cvs.opensolaris.org/source/xref/onnv/onnv-gate/usr/src/lib/libsasl/include/sasl.h#186)

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_auth_cyrus/mod_auth_cyrus.lua	Sun Oct 17 17:08:07 2021 +0200
@@ -0,0 +1,85 @@
+-- Prosody IM
+-- Copyright (C) 2008-2010 Matthew Wild
+-- Copyright (C) 2008-2010 Waqas Hussain
+--
+-- This project is MIT/X11 licensed. Please see the
+-- COPYING file in the source package for more information.
+--
+-- luacheck: ignore 212
+
+local log = require "util.logger".init("auth_cyrus");
+
+local usermanager_user_exists = require "core.usermanager".user_exists;
+
+local cyrus_service_realm = module:get_option("cyrus_service_realm");
+local cyrus_service_name = module:get_option("cyrus_service_name");
+local cyrus_application_name = module:get_option("cyrus_application_name");
+local require_provisioning = module:get_option("cyrus_require_provisioning") or false;
+local host_fqdn = module:get_option("cyrus_server_fqdn");
+
+prosody.unlock_globals(); --FIXME: Figure out why this is needed and
+						  -- why cyrussasl isn't caught by the sandbox
+local cyrus_new = require "util.sasl_cyrus".new;
+prosody.lock_globals();
+local new_sasl = function(realm)
+	return cyrus_new(
+		cyrus_service_realm or realm,
+		cyrus_service_name or "xmpp",
+		cyrus_application_name or "prosody",
+		host_fqdn
+	);
+end
+
+do -- diagnostic
+	local list;
+	for mechanism in pairs(new_sasl(module.host):mechanisms()) do
+		list = (not(list) and mechanism) or (list..", "..mechanism);
+	end
+	if not list then
+		module:log("error", "No Cyrus SASL mechanisms available");
+	else
+		module:log("debug", "Available Cyrus SASL mechanisms: %s", list);
+	end
+end
+
+local host = module.host;
+
+-- define auth provider
+local provider = {};
+log("debug", "initializing default authentication provider for host '%s'", host);
+
+function provider.test_password(username, password)
+	return nil, "Legacy auth not supported with Cyrus SASL.";
+end
+
+function provider.get_password(username)
+	return nil, "Passwords unavailable for Cyrus SASL.";
+end
+
+function provider.set_password(username, password)
+	return nil, "Passwords unavailable for Cyrus SASL.";
+end
+
+function provider.user_exists(username)
+	if require_provisioning then
+		return usermanager_user_exists(username, host);
+	end
+	return true;
+end
+
+function provider.create_user(username, password)
+	return nil, "Account creation/modification not available with Cyrus SASL.";
+end
+
+function provider.get_sasl_handler()
+	local handler = new_sasl(host);
+	if require_provisioning then
+		function handler.require_provisioning(username)
+			return usermanager_user_exists(username, host);
+		end
+	end
+	return handler;
+end
+
+module:provides("auth", provider);
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_auth_cyrus/sasl_cyrus.lua	Sun Oct 17 17:08:07 2021 +0200
@@ -0,0 +1,169 @@
+-- sasl.lua v0.4
+-- Copyright (C) 2008-2009 Tobias Markmann
+--
+--    All rights reserved.
+--
+--    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+--
+--        * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+--        * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+--        * Neither the name of Tobias Markmann nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+--
+--    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+local cyrussasl = require "cyrussasl";
+local log = require "util.logger".init("sasl_cyrus");
+
+local setmetatable = setmetatable
+
+local pcall = pcall
+local s_match, s_gmatch = string.match, string.gmatch
+
+local sasl_errstring = {
+	-- SASL result codes --
+	[1]   = "another step is needed in authentication";
+	[0]   = "successful result";
+	[-1]  = "generic failure";
+	[-2]  = "memory shortage failure";
+	[-3]  = "overflowed buffer";
+	[-4]  = "mechanism not supported";
+	[-5]  = "bad protocol / cancel";
+	[-6]  = "can't request info until later in exchange";
+	[-7]  = "invalid parameter supplied";
+	[-8]  = "transient failure (e.g., weak key)";
+	[-9]  = "integrity check failed";
+	[-12] = "SASL library not initialized";
+
+	-- client only codes --
+	[2]   = "needs user interaction";
+	[-10] = "server failed mutual authentication step";
+	[-11] = "mechanism doesn't support requested feature";
+
+	-- server only codes --
+	[-13] = "authentication failure";
+	[-14] = "authorization failure";
+	[-15] = "mechanism too weak for this user";
+	[-16] = "encryption needed to use mechanism";
+	[-17] = "One time use of a plaintext password will enable requested mechanism for user";
+	[-18] = "passphrase expired, has to be reset";
+	[-19] = "account disabled";
+	[-20] = "user not found";
+	[-23] = "version mismatch with plug-in";
+	[-24] = "remote authentication server unavailable";
+	[-26] = "user exists, but no verifier for user";
+
+	-- codes for password setting --
+	[-21] = "passphrase locked";
+	[-22] = "requested change was not needed";
+	[-27] = "passphrase is too weak for security policy";
+	[-28] = "user supplied passwords not permitted";
+};
+setmetatable(sasl_errstring, { __index = function() return "undefined error!" end });
+
+local _ENV = nil;
+-- luacheck: std none
+
+local method = {};
+method.__index = method;
+local initialized = false;
+
+local function init(service_name)
+	if not initialized then
+		local st, errmsg = pcall(cyrussasl.server_init, service_name);
+		if st then
+			initialized = true;
+		else
+			log("error", "Failed to initialize Cyrus SASL: %s", errmsg);
+		end
+	end
+end
+
+-- create a new SASL object which can be used to authenticate clients
+-- host_fqdn may be nil in which case gethostname() gives the value.
+--      For GSSAPI, this determines the hostname in the service ticket (after
+--      reverse DNS canonicalization, only if [libdefaults] rdns = true which
+--      is the default).
+local function new(realm, service_name, app_name, host_fqdn)
+
+	init(app_name or service_name);
+
+	local st, ret = pcall(cyrussasl.server_new, service_name, host_fqdn, realm, nil, nil)
+	if not st then
+		log("error", "Creating SASL server connection failed: %s", ret);
+		return nil;
+	end
+
+	local sasl_i = { realm = realm, service_name = service_name, cyrus = ret };
+
+	if cyrussasl.set_canon_cb then
+		local c14n_cb = function (user)
+			local node = s_match(user, "^([^@]+)");
+			log("debug", "Canonicalizing username %s to %s", user, node)
+			return node
+		end
+		cyrussasl.set_canon_cb(sasl_i.cyrus, c14n_cb);
+	end
+
+	cyrussasl.setssf(sasl_i.cyrus, 0, 0xffffffff)
+	local mechanisms = {};
+	local cyrus_mechs = cyrussasl.listmech(sasl_i.cyrus, nil, "", " ", "");
+	for w in s_gmatch(cyrus_mechs, "[^ ]+") do
+		mechanisms[w] = true;
+	end
+	sasl_i.mechs = mechanisms;
+	return setmetatable(sasl_i, method);
+end
+
+-- get a fresh clone with the same realm and service name
+function method:clean_clone()
+	return new(self.realm, self.service_name)
+end
+
+-- get a list of possible SASL mechanims to use
+function method:mechanisms()
+	return self.mechs;
+end
+
+-- select a mechanism to use
+function method:select(mechanism)
+	if not self.selected and self.mechs[mechanism] then
+		self.selected = mechanism;
+		return true;
+	end
+end
+
+-- feed new messages to process into the library
+function method:process(message)
+	local err;
+	local data;
+
+	if not self.first_step_done then
+		err, data = cyrussasl.server_start(self.cyrus, self.selected, message or "")
+		self.first_step_done = true;
+	else
+		err, data = cyrussasl.server_step(self.cyrus, message or "")
+	end
+
+	self.username = cyrussasl.get_username(self.cyrus)
+
+	if (err == 0) then -- SASL_OK
+		if self.require_provisioning and not self.require_provisioning(self.username) then
+			return "failure", "not-authorized", "User authenticated successfully, but not provisioned for XMPP";
+		end
+		return "success", data
+	elseif (err == 1) then -- SASL_CONTINUE
+		return "challenge", data
+	elseif (err == -4) then -- SASL_NOMECH
+		log("debug", "SASL mechanism not available from remote end")
+		return "failure", "invalid-mechanism", "SASL mechanism not available"
+	elseif (err == -13) then -- SASL_BADAUTH
+		return "failure", "not-authorized", sasl_errstring[err];
+	else
+		log("debug", "Got SASL error condition %d: %s", err, sasl_errstring[err]);
+		return "failure", "undefined-condition", sasl_errstring[err];
+	end
+end
+
+return {
+	new = new;
+};