1<?php
2/**
3 * Elgg Simple PAM library
4 * Contains functions for managing authentication.
5 * This is not a full implementation of PAM. It supports a single facility
6 * (authentication) and allows multiple policies (user authentication is the
7 * default). There are two control flags possible for each module: sufficient
8 * or required. The entire chain for a policy is processed (or until a
9 * required module fails). A module fails by returning false or throwing an
10 * exception. The order that modules are processed is determined by the order
11 * they are registered. For an example of a PAM, see pam_auth_userpass() in
12 * sessions.php.
13 *
14 * For more information on PAMs see:
15 * http://www.freebsd.org/doc/en/articles/pam/index.html
16 *
17 * @see \ElggPAM
18 */
19
20/**
21 * Register a PAM handler.
22 *
23 * A PAM handler should return true if the authentication attempt passed. For a
24 * failure, return false or throw an exception. Returning nothing indicates that
25 * the handler wants to be skipped.
26 *
27 * Note, $handler must be string callback (not an array/Closure).
28 *
29 * @param string $handler    Callable global handler function in the format ()
30 * 		                     pam_handler($credentials = null);
31 * @param string $importance The importance - "sufficient" (default) or "required"
32 * @param string $policy     The policy type, default is "user"
33 *
34 * @return bool
35 */
36function register_pam_handler($handler, $importance = "sufficient", $policy = "user") {
37	// setup array for this type of pam if not already set
38	if (!isset(\ElggPAM::$_handlers[$policy])) {
39		\ElggPAM::$_handlers[$policy] = [];
40	}
41
42	// @todo remove requirement that $handle be a global function
43	if (is_string($handler) && is_callable($handler, true)) {
44		\ElggPAM::$_handlers[$policy][$handler] = new \stdClass;
45
46		\ElggPAM::$_handlers[$policy][$handler]->handler = $handler;
47		\ElggPAM::$_handlers[$policy][$handler]->importance = strtolower($importance);
48
49		return true;
50	}
51
52	return false;
53}
54
55/**
56 * Unregisters a PAM handler.
57 *
58 * @param string $handler The PAM handler function name
59 * @param string $policy  The policy type, default is "user"
60 *
61 * @return void
62 * @since 1.7.0
63 */
64function unregister_pam_handler($handler, $policy = "user") {
65	unset(\ElggPAM::$_handlers[$policy][$handler]);
66}
67