aboutsummaryrefslogtreecommitdiff
path: root/engine/lib/web_services.php
diff options
context:
space:
mode:
Diffstat (limited to 'engine/lib/web_services.php')
-rw-r--r--engine/lib/web_services.php1454
1 files changed, 1454 insertions, 0 deletions
diff --git a/engine/lib/web_services.php b/engine/lib/web_services.php
new file mode 100644
index 000000000..51cad6f39
--- /dev/null
+++ b/engine/lib/web_services.php
@@ -0,0 +1,1454 @@
+<?php
+/**
+ * Elgg web services API
+ * Functions and objects for exposing custom web services.
+ *
+ * @package Elgg.Core
+ * @subpackage WebServicesAPI
+ */
+
+// Primary Services API Server functions
+
+/**
+ * A global array holding API methods.
+ * The structure of this is
+ * $API_METHODS = array (
+ * $method => array (
+ * "description" => "Some human readable description"
+ * "function" = 'my_function_callback'
+ * "parameters" = array (
+ * "variable" = array ( // the order should be the same as the function callback
+ * type => 'int' | 'bool' | 'float' | 'string'
+ * required => true (default) | false
+ * default => value // optional
+ * )
+ * )
+ * "call_method" = 'GET' | 'POST'
+ * "require_api_auth" => true | false (default)
+ * "require_user_auth" => true | false (default)
+ * )
+ * )
+ */
+global $API_METHODS;
+$API_METHODS = array();
+
+/**
+ * Expose a function as a services api call.
+ *
+ * Limitations: Currently cannot expose functions which expect objects.
+ * It also cannot handle arrays of bools or arrays of arrays.
+ * Also, input will be filtered to protect against XSS attacks through the API.
+ *
+ * @param string $method The api name to expose - for example "myapi.dosomething"
+ * @param string $function Your function callback.
+ * @param array $parameters (optional) List of parameters in the same order as in
+ * your function. Default values may be set for parameters which
+ * allow REST api users flexibility in what parameters are passed.
+ * Generally, optional parameters should be after required
+ * parameters.
+ *
+ * This array should be in the format
+ * "variable" = array (
+ * type => 'int' | 'bool' | 'float' | 'string' | 'array'
+ * required => true (default) | false
+ * default => value (optional)
+ * )
+ * @param string $description (optional) human readable description of the function.
+ * @param string $call_method (optional) Define what http method must be used for
+ * this function. Default: GET
+ * @param bool $require_api_auth (optional) (default is false) Does this method
+ * require API authorization? (example: API key)
+ * @param bool $require_user_auth (optional) (default is false) Does this method
+ * require user authorization?
+ *
+ * @return bool
+ */
+function expose_function($method, $function, array $parameters = NULL, $description = "",
+$call_method = "GET", $require_api_auth = false, $require_user_auth = false) {
+
+ global $API_METHODS;
+
+ if (($method == "") || ($function == "")) {
+ $msg = elgg_echo('InvalidParameterException:APIMethodOrFunctionNotSet');
+ throw new InvalidParameterException($msg);
+ }
+
+ // does not check whether this method has already been exposed - good idea?
+ $API_METHODS[$method] = array();
+
+ $API_METHODS[$method]["description"] = $description;
+
+ // does not check whether callable - done in execute_method()
+ $API_METHODS[$method]["function"] = $function;
+
+ if ($parameters != NULL) {
+ if (!is_array($parameters)) {
+ $msg = elgg_echo('InvalidParameterException:APIParametersArrayStructure', array($method));
+ throw new InvalidParameterException($msg);
+ }
+
+ // catch common mistake of not setting up param array correctly
+ $first = current($parameters);
+ if (!is_array($first)) {
+ $msg = elgg_echo('InvalidParameterException:APIParametersArrayStructure', array($method));
+ throw new InvalidParameterException($msg);
+ }
+ }
+
+ if ($parameters != NULL) {
+ // ensure the required flag is set correctly in default case for each parameter
+ foreach ($parameters as $key => $value) {
+ // check if 'required' was specified - if not, make it true
+ if (!array_key_exists('required', $value)) {
+ $parameters[$key]['required'] = true;
+ }
+ }
+
+ $API_METHODS[$method]["parameters"] = $parameters;
+ }
+
+ $call_method = strtoupper($call_method);
+ switch ($call_method) {
+ case 'POST' :
+ $API_METHODS[$method]["call_method"] = 'POST';
+ break;
+ case 'GET' :
+ $API_METHODS[$method]["call_method"] = 'GET';
+ break;
+ default :
+ $msg = elgg_echo('InvalidParameterException:UnrecognisedHttpMethod',
+ array($call_method, $method));
+
+ throw new InvalidParameterException($msg);
+ }
+
+ $API_METHODS[$method]["require_api_auth"] = $require_api_auth;
+
+ $API_METHODS[$method]["require_user_auth"] = $require_user_auth;
+
+ return true;
+}
+
+/**
+ * Unregister an API method
+ *
+ * @param string $method The api name that was exposed
+ *
+ * @since 1.7.0
+ *
+ * @return void
+ */
+function unexpose_function($method) {
+ global $API_METHODS;
+
+ if (isset($API_METHODS[$method])) {
+ unset($API_METHODS[$method]);
+ }
+}
+
+/**
+ * Check that the method call has the proper API and user authentication
+ *
+ * @param string $method The api name that was exposed
+ *
+ * @return true or throws an exception
+ * @throws APIException
+ * @since 1.7.0
+ * @access private
+ */
+function authenticate_method($method) {
+ global $API_METHODS;
+
+ // method must be exposed
+ if (!isset($API_METHODS[$method])) {
+ throw new APIException(elgg_echo('APIException:MethodCallNotImplemented', array($method)));
+ }
+
+ // check API authentication if required
+ if ($API_METHODS[$method]["require_api_auth"] == true) {
+ $api_pam = new ElggPAM('api');
+ if ($api_pam->authenticate() !== true) {
+ throw new APIException(elgg_echo('APIException:APIAuthenticationFailed'));
+ }
+ }
+
+ $user_pam = new ElggPAM('user');
+ $user_auth_result = $user_pam->authenticate(array());
+
+ // check if user authentication is required
+ if ($API_METHODS[$method]["require_user_auth"] == true) {
+ if ($user_auth_result == false) {
+ throw new APIException($user_pam->getFailureMessage(), ErrorResult::$RESULT_FAIL_AUTHTOKEN);
+ }
+ }
+
+ return true;
+}
+
+/**
+ * Executes a method.
+ * A method is a function which you have previously exposed using expose_function.
+ *
+ * @param string $method Method, e.g. "foo.bar"
+ *
+ * @return GenericResult The result of the execution.
+ * @throws APIException, CallException
+ * @access private
+ */
+function execute_method($method) {
+ global $API_METHODS, $CONFIG;
+
+ // method must be exposed
+ if (!isset($API_METHODS[$method])) {
+ $msg = elgg_echo('APIException:MethodCallNotImplemented', array($method));
+ throw new APIException($msg);
+ }
+
+ // function must be callable
+ if (!(isset($API_METHODS[$method]["function"]))
+ || !(is_callable($API_METHODS[$method]["function"]))) {
+
+ $msg = elgg_echo('APIException:FunctionDoesNotExist', array($method));
+ throw new APIException($msg);
+ }
+
+ // check http call method
+ if (strcmp(get_call_method(), $API_METHODS[$method]["call_method"]) != 0) {
+ $msg = elgg_echo('CallException:InvalidCallMethod', array($method,
+ $API_METHODS[$method]["call_method"]));
+
+ throw new CallException($msg);
+ }
+
+ $parameters = get_parameters_for_method($method);
+
+ if (verify_parameters($method, $parameters) == false) {
+ // if verify_parameters fails, it throws exception which is not caught here
+ }
+
+ $serialised_parameters = serialise_parameters($method, $parameters);
+
+ // Execute function: Construct function and calling parameters
+ $function = $API_METHODS[$method]["function"];
+ $serialised_parameters = trim($serialised_parameters, ", ");
+
+ // @todo document why we cannot use call_user_func_array here
+ $result = eval("return $function($serialised_parameters);");
+
+ // Sanity check result
+ // If this function returns an api result itself, just return it
+ if ($result instanceof GenericResult) {
+ return $result;
+ }
+
+ if ($result === false) {
+ $msg = elgg_echo('APIException:FunctionParseError', array($function, $serialised_parameters));
+ throw new APIException($msg);
+ }
+
+ if ($result === NULL) {
+ // If no value
+ $msg = elgg_echo('APIException:FunctionNoReturn', array($function, $serialised_parameters));
+ throw new APIException($msg);
+ }
+
+ // Otherwise assume that the call was successful and return it as a success object.
+ return SuccessResult::getInstance($result);
+}
+
+/**
+ * Get the request method.
+ *
+ * @return string HTTP request method
+ * @access private
+ */
+function get_call_method() {
+ return $_SERVER['REQUEST_METHOD'];
+}
+
+/**
+ * This function analyses all expected parameters for a given method
+ *
+ * This function sanitizes the input parameters and returns them in
+ * an associated array.
+ *
+ * @param string $method The method
+ *
+ * @return array containing parameters as key => value
+ * @access private
+ */
+function get_parameters_for_method($method) {
+ global $API_METHODS;
+
+ $sanitised = array();
+
+ // if there are parameters, sanitize them
+ if (isset($API_METHODS[$method]['parameters'])) {
+ foreach ($API_METHODS[$method]['parameters'] as $k => $v) {
+ $param = get_input($k); // Make things go through the sanitiser
+ if ($param !== '' && $param !== null) {
+ $sanitised[$k] = $param;
+ } else {
+ // parameter wasn't passed so check for default
+ if (isset($v['default'])) {
+ $sanitised[$k] = $v['default'];
+ }
+ }
+ }
+ }
+
+ return $sanitised;
+}
+
+/**
+ * Get POST data
+ * Since this is called through a handler, we need to manually get the post data
+ *
+ * @return POST data as string encoded as multipart/form-data
+ * @access private
+ */
+function get_post_data() {
+
+ $postdata = file_get_contents('php://input');
+
+ return $postdata;
+}
+
+/**
+ * Verify that the required parameters are present
+ *
+ * @param string $method Method name
+ * @param array $parameters List of expected parameters
+ *
+ * @return true on success or exception
+ * @throws APIException
+ * @since 1.7.0
+ * @access private
+ */
+function verify_parameters($method, $parameters) {
+ global $API_METHODS;
+
+ // are there any parameters for this method
+ if (!(isset($API_METHODS[$method]["parameters"]))) {
+ return true; // no so return
+ }
+
+ // check that the parameters were registered correctly and all required ones are there
+ foreach ($API_METHODS[$method]['parameters'] as $key => $value) {
+ // this tests the expose structure: must be array to describe parameter and type must be defined
+ if (!is_array($value) || !isset($value['type'])) {
+
+ $msg = elgg_echo('APIException:InvalidParameter', array($key, $method));
+ throw new APIException($msg);
+ }
+
+ // Check that the variable is present in the request if required
+ if ($value['required'] && !array_key_exists($key, $parameters)) {
+ $msg = elgg_echo('APIException:MissingParameterInMethod', array($key, $method));
+ throw new APIException($msg);
+ }
+ }
+
+ return true;
+}
+
+/**
+ * Serialize an array of parameters for an API method call
+ *
+ * @param string $method API method name
+ * @param array $parameters Array of parameters
+ *
+ * @return string or exception
+ * @throws APIException
+ * @since 1.7.0
+ * @access private
+ */
+function serialise_parameters($method, $parameters) {
+ global $API_METHODS;
+
+ // are there any parameters for this method
+ if (!(isset($API_METHODS[$method]["parameters"]))) {
+ return ''; // if not, return
+ }
+
+ $serialised_parameters = "";
+ foreach ($API_METHODS[$method]['parameters'] as $key => $value) {
+
+ // avoid warning on parameters that are not required and not present
+ if (!isset($parameters[$key])) {
+ continue;
+ }
+
+ // Set variables casting to type.
+ switch (strtolower($value['type']))
+ {
+ case 'int':
+ case 'integer' :
+ $serialised_parameters .= "," . (int)trim($parameters[$key]);
+ break;
+ case 'bool':
+ case 'boolean':
+ // change word false to boolean false
+ if (strcasecmp(trim($parameters[$key]), "false") == 0) {
+ $serialised_parameters .= ',false';
+ } else if ($parameters[$key] == 0) {
+ $serialised_parameters .= ',false';
+ } else {
+ $serialised_parameters .= ',true';
+ }
+
+ break;
+ case 'string':
+ $serialised_parameters .= ",'" . addcslashes(trim($parameters[$key]), "'") . "'";
+ break;
+ case 'float':
+ $serialised_parameters .= "," . (float)trim($parameters[$key]);
+ break;
+ case 'array':
+ // we can handle an array of strings, maybe ints, definitely not booleans or other arrays
+ if (!is_array($parameters[$key])) {
+ $msg = elgg_echo('APIException:ParameterNotArray', array($key));
+ throw new APIException($msg);
+ }
+
+ $array = "array(";
+
+ foreach ($parameters[$key] as $k => $v) {
+ $k = sanitise_string($k);
+ $v = sanitise_string($v);
+
+ $array .= "'$k'=>'$v',";
+ }
+
+ $array = trim($array, ",");
+
+ $array .= ")";
+ $array = ",$array";
+
+ $serialised_parameters .= $array;
+ break;
+ default:
+ $msg = elgg_echo('APIException:UnrecognisedTypeCast', array($value['type'], $key, $method));
+ throw new APIException($msg);
+ }
+ }
+
+ return $serialised_parameters;
+}
+
+// API authorization handlers /////////////////////////////////////////////////////////////////////
+
+/**
+ * PAM: Confirm that the call includes a valid API key
+ *
+ * @return true if good API key - otherwise throws exception
+ *
+ * @return mixed
+ * @throws APIException
+ * @since 1.7.0
+ * @access private
+ */
+function api_auth_key() {
+ global $CONFIG;
+
+ // check that an API key is present
+ $api_key = get_input('api_key');
+ if ($api_key == "") {
+ throw new APIException(elgg_echo('APIException:MissingAPIKey'));
+ }
+
+ // check that it is active
+ $api_user = get_api_user($CONFIG->site_id, $api_key);
+ if (!$api_user) {
+ // key is not active or does not exist
+ throw new APIException(elgg_echo('APIException:BadAPIKey'));
+ }
+
+ // can be used for keeping stats
+ // plugin can also return false to fail this authentication method
+ return elgg_trigger_plugin_hook('api_key', 'use', $api_key, true);
+}
+
+
+/**
+ * PAM: Confirm the HMAC signature
+ *
+ * @return true if success - otherwise throws exception
+ *
+ * @throws SecurityException
+ * @since 1.7.0
+ * @access private
+ */
+function api_auth_hmac() {
+ global $CONFIG;
+
+ // Get api header
+ $api_header = get_and_validate_api_headers();
+
+ // Pull API user details
+ $api_user = get_api_user($CONFIG->site_id, $api_header->api_key);
+
+ if (!$api_user) {
+ throw new SecurityException(elgg_echo('SecurityException:InvalidAPIKey'),
+ ErrorResult::$RESULT_FAIL_APIKEY_INVALID);
+ }
+
+ // Get the secret key
+ $secret_key = $api_user->secret;
+
+ // get the query string
+ $query = substr($_SERVER['REQUEST_URI'], strpos($_SERVER['REQUEST_URI'], '?') + 1);
+
+ // calculate expected HMAC
+ $hmac = calculate_hmac( $api_header->hmac_algo,
+ $api_header->time,
+ $api_header->nonce,
+ $api_header->api_key,
+ $secret_key,
+ $query,
+ $api_header->method == 'POST' ? $api_header->posthash : "");
+
+
+ if ($api_header->hmac !== $hmac) {
+ throw new SecurityException("HMAC is invalid. {$api_header->hmac} != [calc]$hmac");
+ }
+
+ // Now make sure this is not a replay
+ if (cache_hmac_check_replay($hmac)) {
+ throw new SecurityException(elgg_echo('SecurityException:DupePacket'));
+ }
+
+ // Validate post data
+ if ($api_header->method == "POST") {
+ $postdata = get_post_data();
+ $calculated_posthash = calculate_posthash($postdata, $api_header->posthash_algo);
+
+ if (strcmp($api_header->posthash, $calculated_posthash) != 0) {
+ $msg = elgg_echo('SecurityException:InvalidPostHash',
+ array($calculated_posthash, $api_header->posthash));
+
+ throw new SecurityException($msg);
+ }
+ }
+
+ return true;
+}
+
+// HMAC /////////////////////////////////////////////////////////////////////
+
+/**
+ * This function looks at the super-global variable $_SERVER and extracts the various
+ * header variables needed for the HMAC PAM
+ *
+ * @return stdClass Containing all the values.
+ * @throws APIException Detailing any error.
+ * @access private
+ */
+function get_and_validate_api_headers() {
+ $result = new stdClass;
+
+ $result->method = get_call_method();
+ // Only allow these methods
+ if (($result->method != "GET") && ($result->method != "POST")) {
+ throw new APIException(elgg_echo('APIException:NotGetOrPost'));
+ }
+
+ $result->api_key = $_SERVER['HTTP_X_ELGG_APIKEY'];
+ if ($result->api_key == "") {
+ throw new APIException(elgg_echo('APIException:MissingAPIKey'));
+ }
+
+ $result->hmac = $_SERVER['HTTP_X_ELGG_HMAC'];
+ if ($result->hmac == "") {
+ throw new APIException(elgg_echo('APIException:MissingHmac'));
+ }
+
+ $result->hmac_algo = $_SERVER['HTTP_X_ELGG_HMAC_ALGO'];
+ if ($result->hmac_algo == "") {
+ throw new APIException(elgg_echo('APIException:MissingHmacAlgo'));
+ }
+
+ $result->time = $_SERVER['HTTP_X_ELGG_TIME'];
+ if ($result->time == "") {
+ throw new APIException(elgg_echo('APIException:MissingTime'));
+ }
+
+ // Must have been sent within 25 hour period.
+ // 25 hours is more than enough to handle server clock drift.
+ // This values determines how long the HMAC cache needs to store previous
+ // signatures. Heavy use of HMAC is better handled with a shorter sig lifetime.
+ // See cache_hmac_check_replay()
+ if (($result->time < (time() - 90000)) || ($result->time > (time() + 90000))) {
+ throw new APIException(elgg_echo('APIException:TemporalDrift'));
+ }
+
+ $result->nonce = $_SERVER['HTTP_X_ELGG_NONCE'];
+ if ($result->nonce == "") {
+ throw new APIException(elgg_echo('APIException:MissingNonce'));
+ }
+
+ if ($result->method == "POST") {
+ $result->posthash = $_SERVER['HTTP_X_ELGG_POSTHASH'];
+ if ($result->posthash == "") {
+ throw new APIException(elgg_echo('APIException:MissingPOSTHash'));
+ }
+
+ $result->posthash_algo = $_SERVER['HTTP_X_ELGG_POSTHASH_ALGO'];
+ if ($result->posthash_algo == "") {
+ throw new APIException(elgg_echo('APIException:MissingPOSTAlgo'));
+ }
+
+ $result->content_type = $_SERVER['CONTENT_TYPE'];
+ if ($result->content_type == "") {
+ throw new APIException(elgg_echo('APIException:MissingContentType'));
+ }
+ }
+
+ return $result;
+}
+
+/**
+ * Map various algorithms to their PHP equivs.
+ * This also gives us an easy way to disable algorithms.
+ *
+ * @param string $algo The algorithm
+ *
+ * @return string The php algorithm
+ * @throws APIException if an algorithm is not supported.
+ * @access private
+ */
+function map_api_hash($algo) {
+ $algo = strtolower(sanitise_string($algo));
+ $supported_algos = array(
+ "md5" => "md5", // @todo Consider phasing this out
+ "sha" => "sha1", // alias for sha1
+ "sha1" => "sha1",
+ "sha256" => "sha256"
+ );
+
+ if (array_key_exists($algo, $supported_algos)) {
+ return $supported_algos[$algo];
+ }
+
+ throw new APIException(elgg_echo('APIException:AlgorithmNotSupported', array($algo)));
+}
+
+/**
+ * Calculate the HMAC for the http request.
+ * This function signs an api request using the information provided. The signature returned
+ * has been base64 encoded and then url encoded.
+ *
+ * @param string $algo The HMAC algorithm used
+ * @param string $time String representation of unix time
+ * @param string $nonce Nonce
+ * @param string $api_key Your api key
+ * @param string $secret_key Your private key
+ * @param string $get_variables URLEncoded string representation of the get variable parameters,
+ * eg "method=user&guid=2"
+ * @param string $post_hash Optional sha1 hash of the post data.
+ *
+ * @return string The HMAC signature
+ * @access private
+ */
+function calculate_hmac($algo, $time, $nonce, $api_key, $secret_key,
+$get_variables, $post_hash = "") {
+
+ global $CONFIG;
+
+ elgg_log("HMAC Parts: $algo, $time, $api_key, $secret_key, $get_variables, $post_hash");
+
+ $ctx = hash_init(map_api_hash($algo), HASH_HMAC, $secret_key);
+
+ hash_update($ctx, trim($time));
+ hash_update($ctx, trim($nonce));
+ hash_update($ctx, trim($api_key));
+ hash_update($ctx, trim($get_variables));
+ if (trim($post_hash) != "") {
+ hash_update($ctx, trim($post_hash));
+ }
+
+ return urlencode(base64_encode(hash_final($ctx, true)));
+}
+
+/**
+ * Calculate a hash for some post data.
+ *
+ * @todo Work out how to handle really large bits of data.
+ *
+ * @param string $postdata The post data.
+ * @param string $algo The algorithm used.
+ *
+ * @return string The hash.
+ * @access private
+ */
+function calculate_posthash($postdata, $algo) {
+ $ctx = hash_init(map_api_hash($algo));
+
+ hash_update($ctx, $postdata);
+
+ return hash_final($ctx);
+}
+
+/**
+ * This function will do two things. Firstly it verifies that a HMAC signature
+ * hasn't been seen before, and secondly it will add the given hmac to the cache.
+ *
+ * @param string $hmac The hmac string.
+ *
+ * @return bool True if replay detected, false if not.
+ * @access private
+ */
+function cache_hmac_check_replay($hmac) {
+ // cache lifetime is 25 hours (this should be related to the time drift
+ // allowed in get_and_validate_headers
+ $cache = new ElggHMACCache(90000);
+
+ if (!$cache->load($hmac)) {
+ $cache->save($hmac, $hmac);
+
+ return false;
+ }
+
+ return true;
+}
+
+// API key functions /////////////////////////////////////////////////////////////////////
+
+/**
+ * Generate a new API user for a site, returning a new keypair on success.
+ *
+ * @param int $site_guid The GUID of the site. (default is current site)
+ *
+ * @return stdClass object or false
+ */
+function create_api_user($site_guid) {
+ global $CONFIG;
+
+ if (!isset($site_guid)) {
+ $site_guid = $CONFIG->site_id;
+ }
+
+ $site_guid = (int)$site_guid;
+
+ $public = sha1(rand() . $site_guid . microtime());
+ $secret = sha1(rand() . $site_guid . microtime() . $public);
+
+ $insert = insert_data("INSERT into {$CONFIG->dbprefix}api_users
+ (site_guid, api_key, secret) values
+ ($site_guid, '$public', '$secret')");
+
+ if ($insert) {
+ return get_api_user($site_guid, $public);
+ }
+
+ return false;
+}
+
+/**
+ * Find an API User's details based on the provided public api key.
+ * These users are not users in the traditional sense.
+ *
+ * @param int $site_guid The GUID of the site.
+ * @param string $api_key The API Key
+ *
+ * @return mixed stdClass representing the database row or false.
+ */
+function get_api_user($site_guid, $api_key) {
+ global $CONFIG;
+
+ $api_key = sanitise_string($api_key);
+ $site_guid = (int)$site_guid;
+
+ $query = "SELECT * from {$CONFIG->dbprefix}api_users"
+ . " where api_key='$api_key' and site_guid=$site_guid and active=1";
+
+ return get_data_row($query);
+}
+
+/**
+ * Revoke an api user key.
+ *
+ * @param int $site_guid The GUID of the site.
+ * @param string $api_key The API Key (public).
+ *
+ * @return bool
+ */
+function remove_api_user($site_guid, $api_key) {
+ global $CONFIG;
+
+ $keypair = get_api_user($site_guid, $api_key);
+ if ($keypair) {
+ return delete_data("DELETE from {$CONFIG->dbprefix}api_users where id={$keypair->id}");
+ }
+
+ return false;
+}
+
+
+// User Authorization functions
+
+/**
+ * Check the user token
+ * This examines whether an authentication token is present and returns true if
+ * it is present and is valid. The user gets logged in so with the current
+ * session code of Elgg, that user will be logged out of all other sessions.
+ *
+ * @return bool
+ * @access private
+ */
+function pam_auth_usertoken() {
+ global $CONFIG;
+
+ $token = get_input('auth_token');
+ if (!$token) {
+ return false;
+ }
+
+ $validated_userid = validate_user_token($token, $CONFIG->site_id);
+
+ if ($validated_userid) {
+ $u = get_entity($validated_userid);
+
+ // Could we get the user?
+ if (!$u) {
+ return false;
+ }
+
+ // Not an elgg user
+ if ((!$u instanceof ElggUser)) {
+ return false;
+ }
+
+ // User is banned
+ if ($u->isBanned()) {
+ return false;
+ }
+
+ // Fail if we couldn't log the user in
+ if (!login($u)) {
+ return false;
+ }
+
+ return true;
+ }
+
+ return false;
+}
+
+/**
+ * See if the user has a valid login sesson
+ *
+ * @return bool
+ * @access private
+ */
+function pam_auth_session() {
+ return elgg_is_logged_in();
+}
+
+// user token functions
+
+/**
+ * Obtain a token for a user.
+ *
+ * @param string $username The username
+ * @param int $expire Minutes until token expires (default is 60 minutes)
+ *
+ * @return bool
+ */
+function create_user_token($username, $expire = 60) {
+ global $CONFIG;
+
+ $site_guid = $CONFIG->site_id;
+ $user = get_user_by_username($username);
+ $time = time();
+ $time += 60 * $expire;
+ $token = md5(rand() . microtime() . $username . $time . $site_guid);
+
+ if (!$user) {
+ return false;
+ }
+
+ if (insert_data("INSERT into {$CONFIG->dbprefix}users_apisessions
+ (user_guid, site_guid, token, expires) values
+ ({$user->guid}, $site_guid, '$token', '$time')
+ on duplicate key update token='$token', expires='$time'")) {
+ return $token;
+ }
+
+ return false;
+}
+
+/**
+ * Get all tokens attached to a user
+ *
+ * @param int $user_guid The user GUID
+ * @param int $site_guid The ID of the site (default is current site)
+ *
+ * @return false if none available or array of stdClass objects
+ * (see users_apisessions schema for available variables in objects)
+ * @since 1.7.0
+ */
+function get_user_tokens($user_guid, $site_guid) {
+ global $CONFIG;
+
+ if (!isset($site_guid)) {
+ $site_guid = $CONFIG->site_id;
+ }
+
+ $site_guid = (int)$site_guid;
+ $user_guid = (int)$user_guid;
+
+ $tokens = get_data("SELECT * from {$CONFIG->dbprefix}users_apisessions
+ where user_guid=$user_guid and site_guid=$site_guid");
+
+ return $tokens;
+}
+
+/**
+ * Validate a token against a given site.
+ *
+ * A token registered with one site can not be used from a
+ * different apikey(site), so be aware of this during development.
+ *
+ * @param string $token The Token.
+ * @param int $site_guid The ID of the site (default is current site)
+ *
+ * @return mixed The user id attached to the token if not expired or false.
+ */
+function validate_user_token($token, $site_guid) {
+ global $CONFIG;
+
+ if (!isset($site_guid)) {
+ $site_guid = $CONFIG->site_id;
+ }
+
+ $site_guid = (int)$site_guid;
+ $token = sanitise_string($token);
+
+ $time = time();
+
+ $user = get_data_row("SELECT * from {$CONFIG->dbprefix}users_apisessions
+ where token='$token' and site_guid=$site_guid and $time < expires");
+
+ if ($user) {
+ return $user->user_guid;
+ }
+
+ return false;
+}
+
+/**
+ * Remove user token
+ *
+ * @param string $token The toekn
+ * @param int $site_guid The ID of the site (default is current site)
+ *
+ * @return bool
+ * @since 1.7.0
+ */
+function remove_user_token($token, $site_guid) {
+ global $CONFIG;
+
+ if (!isset($site_guid)) {
+ $site_guid = $CONFIG->site_id;
+ }
+
+ $site_guid = (int)$site_guid;
+ $token = sanitise_string($token);
+
+ return delete_data("DELETE from {$CONFIG->dbprefix}users_apisessions
+ where site_guid=$site_guid and token='$token'");
+}
+
+/**
+ * Remove expired tokens
+ *
+ * @return bool
+ * @since 1.7.0
+ */
+function remove_expired_user_tokens() {
+ global $CONFIG;
+
+ $site_guid = $CONFIG->site_id;
+
+ $time = time();
+
+ return delete_data("DELETE from {$CONFIG->dbprefix}users_apisessions
+ where site_guid=$site_guid and expires < $time");
+}
+
+// Client api functions
+
+/**
+ * Utility function to serialise a header array into its text representation.
+ *
+ * @param array $headers The array of headers "key" => "value"
+ *
+ * @return string
+ * @access private
+ */
+function serialise_api_headers(array $headers) {
+ $headers_str = "";
+
+ foreach ($headers as $k => $v) {
+ $headers_str .= trim($k) . ": " . trim($v) . "\r\n";
+ }
+
+ return trim($headers_str);
+}
+
+/**
+ * Send a raw API call to an elgg api endpoint.
+ *
+ * @param array $keys The api keys.
+ * @param string $url URL of the endpoint.
+ * @param array $call Associated array of "variable" => "value"
+ * @param string $method GET or POST
+ * @param string $post_data The post data
+ * @param string $content_type The content type
+ *
+ * @return string
+ */
+function send_api_call(array $keys, $url, array $call, $method = 'GET', $post_data = '',
+$content_type = 'application/octet-stream') {
+
+ global $CONFIG;
+
+ $headers = array();
+ $encoded_params = array();
+
+ $method = strtoupper($method);
+ switch (strtoupper($method)) {
+ case 'GET' :
+ case 'POST' :
+ break;
+ default:
+ $msg = elgg_echo('NotImplementedException:CallMethodNotImplemented', array($method));
+ throw new NotImplementedException($msg);
+ }
+
+ // Time
+ $time = time();
+
+ // Nonce
+ $nonce = uniqid('');
+
+ // URL encode all the parameters
+ foreach ($call as $k => $v) {
+ $encoded_params[] = urlencode($k) . '=' . urlencode($v);
+ }
+
+ $params = implode('&', $encoded_params);
+
+ // Put together the query string
+ $url = $url . "?" . $params;
+
+ // Construct headers
+ $posthash = "";
+ if ($method == 'POST') {
+ $posthash = calculate_posthash($post_data, 'md5');
+ }
+
+ if ((isset($keys['public'])) && (isset($keys['private']))) {
+ $headers['X-Elgg-apikey'] = $keys['public'];
+ $headers['X-Elgg-time'] = $time;
+ $headers['X-Elgg-nonce'] = $nonce;
+ $headers['X-Elgg-hmac-algo'] = 'sha1';
+ $headers['X-Elgg-hmac'] = calculate_hmac('sha1',
+ $time,
+ $nonce,
+ $keys['public'],
+ $keys['private'],
+ $params,
+ $posthash
+ );
+ }
+ if ($method == 'POST') {
+ $headers['X-Elgg-posthash'] = $posthash;
+ $headers['X-Elgg-posthash-algo'] = 'md5';
+
+ $headers['Content-type'] = $content_type;
+ $headers['Content-Length'] = strlen($post_data);
+ }
+
+ // Opt array
+ $http_opts = array(
+ 'method' => $method,
+ 'header' => serialise_api_headers($headers)
+ );
+ if ($method == 'POST') {
+ $http_opts['content'] = $post_data;
+ }
+
+ $opts = array('http' => $http_opts);
+
+ // Send context
+ $context = stream_context_create($opts);
+
+ // Send the query and get the result and decode.
+ elgg_log("APICALL: $url");
+ $results = file_get_contents($url, false, $context);
+
+ return $results;
+}
+
+/**
+ * Send a GET call
+ *
+ * @param string $url URL of the endpoint.
+ * @param array $call Associated array of "variable" => "value"
+ * @param array $keys The keys dependant on chosen authentication method
+ *
+ * @return string
+ */
+function send_api_get_call($url, array $call, array $keys) {
+ return send_api_call($keys, $url, $call);
+}
+
+/**
+ * Send a GET call
+ *
+ * @param string $url URL of the endpoint.
+ * @param array $call Associated array of "variable" => "value"
+ * @param array $keys The keys dependant on chosen authentication method
+ * @param string $post_data The post data
+ * @param string $content_type The content type
+ *
+ * @return string
+ */
+function send_api_post_call($url, array $call, array $keys, $post_data,
+$content_type = 'application/octet-stream') {
+
+ return send_api_call($keys, $url, $call, 'POST', $post_data, $content_type);
+}
+
+/**
+ * Return a key array suitable for the API client using the standard
+ * authentication method based on api-keys and secret keys.
+ *
+ * @param string $secret_key Your secret key
+ * @param string $api_key Your api key
+ *
+ * @return array
+ */
+function get_standard_api_key_array($secret_key, $api_key) {
+ return array('public' => $api_key, 'private' => $secret_key);
+}
+
+// System functions
+
+/**
+ * Simple api to return a list of all api's installed on the system.
+ *
+ * @return array
+ * @access private
+ */
+function list_all_apis() {
+ global $API_METHODS;
+
+ // sort first
+ ksort($API_METHODS);
+
+ return $API_METHODS;
+}
+
+/**
+ * The auth.gettoken API.
+ * This API call lets a user log in, returning an authentication token which can be used
+ * to authenticate a user for a period of time. It is passed in future calls as the parameter
+ * auth_token.
+ *
+ * @param string $username Username
+ * @param string $password Clear text password
+ *
+ * @return string Token string or exception
+ * @throws SecurityException
+ * @access private
+ */
+function auth_gettoken($username, $password) {
+ // check if username is an email address
+ if (is_email_address($username)) {
+ $users = get_user_by_email($username);
+
+ // check if we have a unique user
+ if (is_array($users) && (count($users) == 1)) {
+ $username = $users[0]->username;
+ }
+ }
+
+ // validate username and password
+ if (true === elgg_authenticate($username, $password)) {
+ $token = create_user_token($username);
+ if ($token) {
+ return $token;
+ }
+ }
+
+ throw new SecurityException(elgg_echo('SecurityException:authenticationfailed'));
+}
+
+// Error handler functions
+
+/** Define a global array of errors */
+$ERRORS = array();
+
+/**
+ * API PHP Error handler function.
+ * This function acts as a wrapper to catch and report PHP error messages.
+ *
+ * @see http://uk3.php.net/set-error-handler
+ *
+ * @param int $errno Error number
+ * @param string $errmsg Human readable message
+ * @param string $filename Filename
+ * @param int $linenum Line number
+ * @param array $vars Vars
+ *
+ * @return void
+ * @access private
+ *
+ * @throws Exception
+ */
+function _php_api_error_handler($errno, $errmsg, $filename, $linenum, $vars) {
+ global $ERRORS;
+
+ $error = date("Y-m-d H:i:s (T)") . ": \"" . $errmsg . "\" in file "
+ . $filename . " (line " . $linenum . ")";
+
+ switch ($errno) {
+ case E_USER_ERROR:
+ error_log("ERROR: " . $error);
+ $ERRORS[] = "ERROR: " . $error;
+
+ // Since this is a fatal error, we want to stop any further execution but do so gracefully.
+ throw new Exception("ERROR: " . $error);
+ break;
+
+ case E_WARNING :
+ case E_USER_WARNING :
+ error_log("WARNING: " . $error);
+ $ERRORS[] = "WARNING: " . $error;
+ break;
+
+ default:
+ error_log("DEBUG: " . $error);
+ $ERRORS[] = "DEBUG: " . $error;
+ }
+}
+
+/**
+ * API PHP Exception handler.
+ * This is a generic exception handler for PHP exceptions. This will catch any
+ * uncaught exception, end API execution and return the result to the requestor
+ * as an ErrorResult in the requested format.
+ *
+ * @param Exception $exception Exception
+ *
+ * @return void
+ * @access private
+ */
+function _php_api_exception_handler($exception) {
+
+ error_log("*** FATAL EXCEPTION (API) *** : " . $exception);
+
+ $code = $exception->getCode() == 0 ? ErrorResult::$RESULT_FAIL : $exception->getCode();
+ $result = new ErrorResult($exception->getMessage(), $code, NULL);
+
+ echo elgg_view_page($exception->getMessage(), elgg_view("api/output", array("result" => $result)));
+}
+
+
+// Services handler
+
+/**
+ * Services handler - turns request over to the registered handler
+ * If no handler is found, this returns a 404 error
+ *
+ * @param string $handler Handler name
+ * @param array $request Request string
+ *
+ * @return void
+ * @access private
+ */
+function service_handler($handler, $request) {
+ global $CONFIG;
+
+ elgg_set_context('api');
+
+ $request = explode('/', $request);
+
+ // after the handler, the first identifier is response format
+ // ex) http://example.org/services/api/rest/json/?method=test
+ $response_format = array_shift($request);
+ // Which view - xml, json, ...
+ if ($response_format && elgg_is_valid_view_type($response_format)) {
+ elgg_set_viewtype($response_format);
+ } else {
+ // default to json
+ elgg_set_viewtype("json");
+ }
+
+ if (!isset($CONFIG->servicehandler) || empty($handler)) {
+ // no handlers set or bad url
+ header("HTTP/1.0 404 Not Found");
+ exit;
+ } else if (isset($CONFIG->servicehandler[$handler]) && is_callable($CONFIG->servicehandler[$handler])) {
+ $function = $CONFIG->servicehandler[$handler];
+ call_user_func($function, $request, $handler);
+ } else {
+ // no handler for this web service
+ header("HTTP/1.0 404 Not Found");
+ exit;
+ }
+}
+
+/**
+ * Registers a web services handler
+ *
+ * @param string $handler Web services type
+ * @param string $function Your function name
+ *
+ * @return bool Depending on success
+ * @since 1.7.0
+ */
+function register_service_handler($handler, $function) {
+ global $CONFIG;
+
+ if (!isset($CONFIG->servicehandler)) {
+ $CONFIG->servicehandler = array();
+ }
+ if (is_callable($function, true)) {
+ $CONFIG->servicehandler[$handler] = $function;
+ return true;
+ }
+
+ return false;
+}
+
+/**
+ * Remove a web service
+ * To replace a web service handler, register the desired handler over the old on
+ * with register_service_handler().
+ *
+ * @param string $handler web services type
+ *
+ * @return void
+ * @since 1.7.0
+ */
+function unregister_service_handler($handler) {
+ global $CONFIG;
+
+ if (isset($CONFIG->servicehandler, $CONFIG->servicehandler[$handler])) {
+ unset($CONFIG->servicehandler[$handler]);
+ }
+}
+
+/**
+ * REST API handler
+ *
+ * @return void
+ * @access private
+ *
+ * @throws SecurityException|APIException
+ */
+function rest_handler() {
+ global $CONFIG;
+
+ // Register the error handler
+ error_reporting(E_ALL);
+ set_error_handler('_php_api_error_handler');
+
+ // Register a default exception handler
+ set_exception_handler('_php_api_exception_handler');
+
+ // Check to see if the api is available
+ if ((isset($CONFIG->disable_api)) && ($CONFIG->disable_api == true)) {
+ throw new SecurityException(elgg_echo('SecurityException:APIAccessDenied'));
+ }
+
+ // plugins should return true to control what API and user authentication handlers are registered
+ if (elgg_trigger_plugin_hook('rest', 'init', null, false) == false) {
+ // for testing from a web browser, you can use the session PAM
+ // do not use for production sites!!
+ //register_pam_handler('pam_auth_session');
+
+ // user token can also be used for user authentication
+ register_pam_handler('pam_auth_usertoken');
+
+ // simple API key check
+ register_pam_handler('api_auth_key', "sufficient", "api");
+ // hmac
+ register_pam_handler('api_auth_hmac', "sufficient", "api");
+ }
+
+ // Get parameter variables
+ $method = get_input('method');
+ $result = null;
+
+ // this will throw an exception if authentication fails
+ authenticate_method($method);
+
+ $result = execute_method($method);
+
+
+ if (!($result instanceof GenericResult)) {
+ throw new APIException(elgg_echo('APIException:ApiResultUnknown'));
+ }
+
+ // Output the result
+ echo elgg_view_page($method, elgg_view("api/output", array("result" => $result)));
+}
+
+// Initialization
+
+/**
+ * Unit tests for API
+ *
+ * @param string $hook unit_test
+ * @param string $type system
+ * @param mixed $value Array of tests
+ * @param mixed $params Params
+ *
+ * @return array
+ * @access private
+ */
+function api_unit_test($hook, $type, $value, $params) {
+ global $CONFIG;
+
+ $value[] = $CONFIG->path . 'engine/tests/services/api.php';
+ return $value;
+}
+
+/**
+ * Initialise the API subsystem.
+ *
+ * @return void
+ * @access private
+ */
+function api_init() {
+ // Register a page handler, so we can have nice URLs
+ register_service_handler('rest', 'rest_handler');
+
+ elgg_register_plugin_hook_handler('unit_test', 'system', 'api_unit_test');
+
+ // expose the list of api methods
+ expose_function("system.api.list", "list_all_apis", NULL,
+ elgg_echo("system.api.list"), "GET", false, false);
+
+ // The authentication token api
+ expose_function(
+ "auth.gettoken",
+ "auth_gettoken",
+ array(
+ 'username' => array ('type' => 'string'),
+ 'password' => array ('type' => 'string'),
+ ),
+ elgg_echo('auth.gettoken'),
+ 'POST',
+ false,
+ false
+ );
+}
+
+
+elgg_register_event_handler('init', 'system', 'api_init');