diff options
| -rw-r--r-- | endpoints/rest.php | 206 | ||||
| -rw-r--r-- | engine/lib/api.php | 312 | ||||
| -rw-r--r-- | index.php | 26 |
3 files changed, 343 insertions, 201 deletions
diff --git a/endpoints/rest.php b/endpoints/rest.php index 6f9efc1e8..147899865 100644 --- a/endpoints/rest.php +++ b/endpoints/rest.php @@ -11,67 +11,11 @@ * @link http://elgg.org/ */ - - - - - /* - - Elgg API system -A brief specification: internal only - -NB: this is a loose specification, and as such some holes or shortcomings may become evident in -implementation. Therefore, feel free to adjust as necessary, bearing in mind the goals, which -are unmovable ... - -Goals: an extensible, two-way API that can be used to easily code secure client applications -on a variety of networked systems, whether web or application-based. The results should be available, -at the very least, in JSON, serialised PHP, XML and CSV, but the output formats should also be -extensible by plugins in a documented way. Similarly, plugins must be able to add new function calls, -in a similar way to how they register events or enable actions. - - - - - - -On release, we will need to provide simple client libraries for PHP, .NET, C, Java and (although this -can hopefully be outsourced to Kevin or similar) Ruby on Rails. Additionally, Django, vanilla Python -and Perl libraries would be a bonus, although not required. - -Brief implementation requirements: A set of procedural functions. If possible, the output should -use the existing views system, creating a new base view set for xml, json, csv and php. That way other -output formats can be specified simply by changing the &view URL parameter, and added / extended by plugins. -(It would also allow RSS output pretty much for free for certain types of data.) On failure, a friendly -message should be returned in a way that can be read by the client software. - -These functions should be made available in a simple api.php module within engine/lib.php, without the use of -any external libraries. If an external library really must be used, ensure that it has a compatible license -and can be used on all systems where Elgg can be installed, including Apache for Windows and Apache-compatible -web servers. - -When a plugin or core software module registers an API call, it should reference a function name, the -parameters it requires, and an English description of the call. A special API call – and internal function - -should return a list of enabled calls, for the use of client applications and internal help pages respectively. - -As one application of the API is as a back-end for AJAX applications, the API endpoint should check $_SESSION -for logged in user information before checking for any other kind of login data. This way the browser can -simply make an asynchronous callback request, allowing for many very interesting Javascript applications. -In an ideal world, client applications should not need a special API key. This is because an application would -have to install a new key for each installed Elgg site, which is not preferable, as it has a serious user -experience hit (before the user can use a new client software on a particular install, they have to go to -their account settings and obtain something that to them looks like a string of gobbledygook). If possible, -all the client application should need is a valid username and password. - -Using a $CONFIG configuration option, site admins should be able to shut down the entire API system if -required, or disallow the $_SESSION authentication method. - - */ - - // Include required files require_once('../engine/start.php'); global $CONFIG; + + $CONFIG->debug = true; // Register the error handler error_reporting(E_ALL); @@ -83,45 +27,25 @@ required, or disallow the $_SESSION authentication method. // Check to see if the api is available if ((isset($CONFIG->disable_api)) && ($CONFIG->disable_api == true)) throw new ConfigurationException("Sorry, API access has been disabled by the administrator."); - - - + + // Register some default PAM methods, plugins can add their own + register_api_pam_handler('pam_auth_session'); + register_api_pam_handler('pam_auth_hmac'); // Get parameter variables $format = get_input('format', 'php'); $method = get_input('method'); $result = null; - // See if we have a session - /** - * If we have a session then we can assume that this is being called by AJAX from - * within an already logged on browser. - * - * NB. This may be a gaping security hole, but hey ho. - */ - if (!isloggedin()) + // Authenticate session + if (api_pam_authenticate()) { - //$CONFIG->api_header = get_and_validate_api_headers(); // Get api header - //$CONFIG->api_user = get_api_user($CONFIG->api_header->api_key); // Pull API user details - - - - - - - - - - - - } - else - { - // User is logged in, just execute - - - - + // Authenticated somehow, now execute. + $token = ""; + $params = $_REQUEST; + if (isset($params['auth_token'])) $token = $params['auth_token']; + + // TODO EXECUTE } // Finally output @@ -130,107 +54,5 @@ required, or disallow the $_SESSION authentication method. // Output the result echo output_result($result, $format); - - - - - - - - - - - - - - - - - - - - - - - - // See if we have a session - /** - * If we have a session then we can assume that this is being called by AJAX from - * within an already logged on browser. - * - * NB. This may be a gaping security hole, but hey ho. - */ -// if (!isloggedin()) -// { -/* // Get api header - $api_header = get_and_validate_api_headers(); - $ApiEnvironment->api_header = $api_header; - - // Pull API user details - $ApiEnvironment->api_user = get_api_user($api_header->api_key); - - // Get site - $ApiEnvironment->site_id = $ApiEnvironment->api_user->side_id; - - if ($ApiEnvironment->api_user) - { - // Get the secret key - $secret_key = $ApiEnvironment->api_user->secret; - - // Validate HMAC - $hmac = calculate_hmac($api_header->hmac_algo, - $api_header->time, - $api_header->api_key, - $secret_key, - $api_header->get_variables, - $api_header->method == 'POST' ? $api_header->posthash : ""); - - if (strcmp( - $api_header->hmac, - $hmac - )==0) - { - // Now make sure this is not a replay - if (!cache_hmac_check_replay($hmac)) - { - $postdata = ""; - $token = ""; - $params = $_REQUEST; - - // 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) - throw new SecurityException("POST data hash is invalid - Expected $calculated_posthash but got {$api_header->posthash}."); - } - - // Execute - if (isset($params['auth_token'])) - $result = execute_method($method, $params, $token); - } - else - throw new SecurityException("Packet signature already seen."); - } - else - throw new SecurityException("HMAC is invalid. {$api_header->hmac} != [calc]$hmac = {$api_header->hmac_algo}(**SECRET KEY**, time:{$api_header->time}, apikey:{$api_header->api_key}, get_vars:{$api_header->get_variables}" . ($api_header->method=="POST"? "posthash:$api_header->posthash}" : ")")); - } - else - throw new SecurityException("Invalid or missing API Key.",ErrorResult::$RESULT_FAIL_APIKEY_INVALID); - }*/ -// else -// { -// // Set site environment -// $ApiEnvironment->site_id = $CONFIG->site_id; -// -// // User is logged in, just execute -// if (isset($params['auth_token'])) $token = $params['auth_token']; -// $result = execute_method($method, $params, $token); -// } - - - ?>
\ No newline at end of file diff --git a/engine/lib/api.php b/engine/lib/api.php index 53c548b19..b5371f605 100644 --- a/engine/lib/api.php +++ b/engine/lib/api.php @@ -75,11 +75,14 @@ * Override this to include any more specific information, however api results should be attached to the * class using setResult(). * + * if $CONFIG->debug is set then additional information about the runtime environment and authentication will be + * returned. + * * @return stdClass Object containing the serialised result. */ public function toStdClass() { - global $ERRORS; + global $ERRORS, $CONFIG, $PAM_HANDLER_MSG; $result = new stdClass; @@ -89,8 +92,14 @@ $resultdata = $this->getResult(); if (isset($resultdata)) $result->result = $resultdata; - if (count($ERRORS)) - $result->runtime_errors = $ERRORS; + if ((isset($CONFIG->debug)) && ($CONFIG->debug == true)) + { + if (count($ERRORS)) + $result->runtime_errors = $ERRORS; + + if (count($PAM_HANDLER_MSG)) + $result->pam = $PAM_HANDLER_MSG; + } return $result; } @@ -158,10 +167,307 @@ } } + // PAM AUTH HMAC functions //////////////////////////////////////////////////////////////// + /** + * 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. + */ + function map_api_hash($algo) + { + $algo = strtolower(sanitise_string($algo)); + $supported_algos = array( + "md5" => "md5", + "sha" => "sha1", // alias for sha1 + "sha1" => "sha1", + "sha256" => "sha256" + ); + + if (array_key_exists($algo)) + return $supported_algos[$algo]; + + throw new APIException("Algorithm '$algo' is not supported or has been disabled."); + } + /** + * Calculate the HMAC for the query. + * This function signs an api request using the information provided and is then verified by + * searunner. + * + * @param $algo string The HMAC algorithm used as stored in X-Searunner-hmac-algo. + * @param $time string String representation of unix time as stored in X-Searunner-time. + * @param $api_key string Your api key. + * @param $secret string Your secret key. + * @param $get_variables string URLEncoded string representation of the get variable parameters, eg "format=php&method=searunner.test". + * @param $post_hash string Optional sha1 hash of the post data. + * @return string The HMAC string. + */ + function calculate_hmac($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($api_key)); + hash_update($ctx, trim($get_variables)); + if (trim($post_hash)!="") hash_update($ctx, trim($post_hash)); + + return hash_final($ctx); + } + + /** + * Calculate a hash for some post data. + * + * TODO: Work out how to handle really large bits of data. + * + * @param $postdata string The post data. + * @param $algo string The algorithm used. + * @return string The hash. + */ + 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 verifys that a $hmac hasn't been seen before, and + * secondly it will add the given hmac to the cache. + * + * TODO : REWRITE TO NOT USE ZEND + * + * @param $hmac The hmac string. + * @return bool True if replay detected, false if not. + */ + function cache_hmac_check_replay($hmac) + { + global $CONFIG; + + throw new NotImplementedException("Writeme!"); + + return true; + } + /** + * Find an API User's details based on the provided public api key. + * + * @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; + + return get_data_row("SELECT * from {$CONFIG->dbprefix}api_users where api_key='$api_key' and site_guid=$site_guid and active=1"); + } + + /** + * This function looks at the super-global variable $_SERVER and extracts the various + * header variables needed to pass to the validation functions after performing basic validation. + * + * @return stdClass Containing all the values. + * @throws APIException Detailing any error. + */ + function get_and_validate_api_headers() + { + $result = new stdClass; + + $result->method = $_SERVER['REQUEST_METHOD']; + if (($result->method != "GET") && ($result->method!= "POST")) // Only allow these methods + throw new APIException("Request method must be GET or POST"); + + $result->api_key = $_SERVER['HTTP_X_ELGG_APIKEY']; + if ($result->api_key == "") + throw new APIException("Missing X-Elgg-apikey HTTP header"); + + $result->hmac = $_SERVER['HTTP_X_ELGG_HMAC']; + if ($result->hmac == "") + throw new APIException("Missing X-Elgg-hmac header"); + + $result->hmac_algo = $_SERVER['HTTP_X_ELGG_HMAC_ALGO']; + if ($result->hmac_algo == "") + throw new APIException("Missing X-Elgg-hmac-algo header"); + + $result->time = $_SERVER['HTTP_X_ELGG_TIME']; + if ($result->time == "") + throw new APIException("Missing X-Elgg-time header"); + if (($result->time<(microtime(true)-86400.00)) || ($result->time>(microtime(true)+86400.00))) // Basic timecheck, think about making this smaller if we get loads of users and the cache gets really big. + throw new APIException("X-Elgg-time is too far in the past or future"); + + $result->get_variables = $_SERVER['QUERY_STRING']; + if ($result->get_variables == "") + throw new APIException("No data on the query string"); + + if ($result->method=="POST") + { + $result->posthash = $_SERVER['HTTP_X_ELGG_POSTHASH']; + if ($result->posthash == "") + throw new APIException("Missing X-Elgg-posthash header"); + + $result->posthash_algo = $_SERVER['HTTP_X_ELGG_POSTHASH_ALGO']; + if ($result->posthash_algo == "") + throw new APIException("Missing X-Elgg-posthash_algo header"); + + $result->content_type = $_SERVER['CONTENT_TYPE']; + if ($result->content_type == "") + throw new APIException("Missing content type for post data"); + } + + return $result; + } + + /** + * Return a sanitised form of the POST data sent to the script + * + * @return string + */ + function get_post_data() + { + global $GLOBALS; + + return $GLOBALS['HTTP_RAW_POST_DATA']; + } + + // PAM functions ////////////////////////////////////////////////////////////////////////// + + $PAM_HANDLERS = array(); + $PAM_HANDLER_MSG = array(); // Messages + + /** + * Register a method of authenticating an incoming API request. + * This function registers a PAM handler which is a function that matches the desciption pam_handler_name() + * and returns either 'true' if an incoming api request was authorised, false or throws an exception if not. + * + * The handlers are tried in turn until one of them successfully authenticates the session. + * + * This architecture lets an administrator choose what methods to accept for API authentication or + * + * @param unknown_type $handler + */ + function register_api_pam_handler($handler) + { + global $PAM_HANDLERS; + + if (is_callable($handler)) + { + $PAM_HANDLERS[$handler] = $handler; + return true; + } + + return false; + } + + /** + * Magically authenticate an API session using one of the registered methods. + * + * This function will return true if authentication was possible, otherwise it'll throw an exception. + * + * If $CONFIG->debug is set then additional debug information will be returned. + */ + function api_pam_authenticate() + { + global $PAM_HANDLERS, $PAM_HANDLER_MSG; + global $CONFIG; + + $dbg_msgs = array(); + + foreach ($PAM_HANDLERS as $k => $v) + { + try { + // Execute the handler + if ($v()) + { + // Explicitly returned true + $PAM_HANDLER_MSG[$k] = "Authenticated!"; + + return true; + } + else + $PAM_HANDLER_MSG[$k] = "Not Authenticated."; + } + catch (Exception $e) + { + $PAM_HANDLER_MSG[$k] = "$e"; + } + } + + // Got this far, so no methods could be found to authenticate the session + throw new SecurityException("No authentication methods were found that could authenticate the session."); + } + + /** + * See if the user has a valid login sesson. + */ + function pam_auth_session() + { + return isloggedin(); + } + + /** + * Secure authentication through headers and HMAC. + */ + function pam_auth_hmac() + { + global $CONFIG; + + $api_header = get_and_validate_api_headers(); // Get api header + $api_user = get_api_user($CONFIG->api_header->api_key); // Pull API user details + + if ($api_user) + { + // Get the secret key + $secret_key = $api_user->secret; + + // Validate HMAC - TODO: Maybe find a simpler way to do this that is still secure...? + $hmac = calculate_hmac($api_header->hmac_algo, + $api_header->time, + $api_header->api_key, + $secret_key, + $api_header->get_variables, + $api_header->method == 'POST' ? $api_header->posthash : ""); + + if (strcmp( + $api_header->hmac, + $hmac + )==0) + { + // Now make sure this is not a replay + if (!cache_hmac_check_replay($hmac)) + { + // 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) + throw new SecurityException("POST data hash is invalid - Expected $calculated_posthash but got {$api_header->posthash}."); + } + + // If we've passed all the checks so far then we can be reasonably certain that the request is authentic, so return this fact to the PAM engine. + return true; + } + else + throw new SecurityException("Packet signature already seen."); + } + else + throw new SecurityException("HMAC is invalid. {$api_header->hmac} != [calc]$hmac = {$api_header->hmac_algo}(**SECRET KEY**, time:{$api_header->time}, apikey:{$api_header->api_key}, get_vars:{$api_header->get_variables}" . ($api_header->method=="POST"? "posthash:$api_header->posthash}" : ")")); + } + else + throw new SecurityException("Invalid or missing API Key.",ErrorResult::$RESULT_FAIL_APIKEY_INVALID); + + return false; + } // XML functions ////////////////////////////////////////////////////////////////////////// @@ -14,8 +14,15 @@ /**
* Start the Elgg engine
*/
- require_once(dirname(__FILE__) . "/engine/start.php");
- + require_once(dirname(__FILE__) . "/engine/start.php"); + + +
+ // Testing /////// + if ($_SESSION['id']==-1) $_SESSION['id'] = 1; + + + /**
* Check to see if user is logged in, if not display login form
**/
@@ -89,7 +96,7 @@ error_log("GETTIGN SITE ".$_SESSION['id']. " " . print_r($site, true)); // get site metadata
error_log("SITE Metadata : " . print_r($site->getMetadata("Metaname"), true)); */ - +/* // get site annotations $site = get_site_by_url("http://localhost/"); error_log("GETTIGN SITE ".$_SESSION['id']. " " . print_r($site, true)); @@ -128,10 +135,17 @@ error_log("GETTIGN SITE ".$_SESSION['id']. " " . print_r($site, true)); error_log("SITE Metadata : " . print_r(get_entities_from_metadata("Metaname","","site"), true)); + $site->metatwo = "a different way"; - // Get objects belonging to a site - - // get objects of type + // annotate site + $site->annotate("Test","TestValue"); + + + // get site annotations + error_log("SITE Annotations : " . print_r($site->getAnnotations("Test"), true)); + + */ + |