1 files changed, 71 insertions, 86 deletions
diff --git a/engine/lib/pam.php b/engine/lib/pam.php
index 1faa0014e..1c9c3bfe1 100644
--- a/engine/lib/pam.php
+++ b/engine/lib/pam.php
@@ -1,91 +1,76 @@
-<?php
-
-	/**
-	 * Elgg PAM library
-	 * Contains functions for managing authentication using various arbitrary methods
-	 * 
-	 * @package Elgg
-	 * @subpackage Core
-	 * @license http://www.gnu.org/licenses/old-licenses/gpl-2.0.html GNU Public License version 2
-	 * @author Marcus Povey
-	 * @copyright Curverider Ltd 2008
-	 * @link http://elgg.org/
-	 */
+<?php
+/**
+ * Elgg Simple PAM library
+ * Contains functions for managing authentication.
+ * This is not a full implementation of PAM. It supports a single facility
+ * (authentication) and allows multiple policies (user authentication is the
+ * default). There are two control flags possible for each module: sufficient
+ * or required. The entire chain for a policy is processed (or until a
+ * required module fails). A module fails by returning false or throwing an
+ * exception. The order that modules are processed is determined by the order
+ * they are registered. For an example of a PAM, see pam_auth_userpass() in
+ * sessions.php.
+ *
+ * For more information on PAMs see:
+ * http://www.freebsd.org/doc/en/articles/pam/index.html
+ *
+ * @see ElggPAM
+ *
+ * @package Elgg.Core
+ * @subpackage Authentication.PAM
+ */
 
-	$_PAM_HANDLERS = array();
-	$_PAM_HANDLERS_MSG = array();
-	
-	
-	/**
-	 * Register a PAM handler.
-	 * 
-	 * @param string $handler The handler function in the format 
-	 * 		pam_handler($credentials = NULL);
-	 * @param string $importance The importance - "sufficient" or "required"
-	 */
-	function register_pam_handler($handler, $importance = "sufficient")
-	{
-		global $_PAM_HANDLERS;
-		
-		if (is_callable($handler))
-		{
-			$_PAM_HANDLERS[$handler] = new stdClass;
-			
-			$_PAM_HANDLERS[$handler]->handler = $handler;
-			$_PAM_HANDLERS[$handler]->importance = strtolower($importance);
-			
-			return true;
-		}
-		
-		return false;
+global $_PAM_HANDLERS;
+$_PAM_HANDLERS = array();
+
+/**
+ * Register a PAM handler.
+ *
+ * A PAM handler should return true if the authentication attempt passed. For a
+ * failure, return false or throw an exception. Returning nothing indicates that
+ * the handler wants to be skipped.
+ *
+ * Note, $handler must be string callback (not an array/Closure).
+ *
+ * @param string $handler    Callable global handler function in the format ()
+ * 		                     pam_handler($credentials = NULL);
+ * @param string $importance The importance - "sufficient" (default) or "required"
+ * @param string $policy     The policy type, default is "user"
+ *
+ * @return bool
+ */
+function register_pam_handler($handler, $importance = "sufficient", $policy = "user") {
+	global $_PAM_HANDLERS;
+
+	// setup array for this type of pam if not already set
+	if (!isset($_PAM_HANDLERS[$policy])) {
+		$_PAM_HANDLERS[$policy] = array();
 	}
-	
-	/**
-	 * Attempt to authenticate.
-	 * This function will go through all registered PAM handlers to see if a user can be authorised.
-	 *
-	 * If $credentials are provided the PAM handler should authenticate using the provided credentials, if
-	 * not then credentials should be prompted for or otherwise retrieved (eg from the HTTP header or $_SESSION).
-	 * 
-	 * @param mixed $credentials Mixed PAM handler specific credentials (eg username,password or hmac etc)
-	 * @return bool true if authenticated, false if not.
-	 */
-	function pam_authenticate($credentials = NULL)
-	{
-		global $_PAM_HANDLERS, $_PAM_HANDLERS_MSG;
-		
-		$authenticated = false;
-		
-		foreach ($_PAM_HANDLERS as $k => $v)
-		{
-			$handler = $v->handler;
-			$importance = $v->importance;
-			
-			try {
-				// Execute the handler 
-				if ($handler($credentials))
-				{
-					// Explicitly returned true
-					$_PAM_HANDLERS_MSG[$k] = "Authenticated!";
 
-					$authenticated = true;
-				}
-				else
-				{
-					$_PAM_HANDLERS_MSG[$k] = "Not Authenticated.";
-					
-					// If this is required then abort.
-					if ($importance == 'required')
-						return false;
-				}
-			} 
-			catch (Exception $e)
-			{
-				$_PAM_HANDLERS_MSG[$k] = "$e";
-			}	
-		}
+	// @todo remove requirement that $handle be a global function
+	if (is_string($handler) && is_callable($handler, true)) {
+		$_PAM_HANDLERS[$policy][$handler] = new stdClass;
+
+		$_PAM_HANDLERS[$policy][$handler]->handler = $handler;
+		$_PAM_HANDLERS[$policy][$handler]->importance = strtolower($importance);
 
-		return $authenticated;
+		return true;
 	}
-	
-?>
-\ No newline at end of file
+
+	return false;
+}
+
+/**
+ * Unregisters a PAM handler.
+ *
+ * @param string $handler The PAM handler function name
+ * @param string $policy  The policy type, default is "user"
+ *
+ * @return void
+ * @since 1.7.0
+ */
+function unregister_pam_handler($handler, $policy = "user") {
+	global $_PAM_HANDLERS;
+
+	unset($_PAM_HANDLERS[$policy][$handler]);
+}