CRM/Utils/REST.php

   1 <?php
   2 /*
   3    +--------------------------------------------------------------------+
   4    | CiviCRM version 5                                                  |
   5    +--------------------------------------------------------------------+
   6    | Copyright CiviCRM LLC (c) 2004-2019                                |
   7    +--------------------------------------------------------------------+
   8    | This file is a part of CiviCRM.                                    |
   9    |                                                                    |
  10    | CiviCRM is free software; you can copy, modify, and distribute it  |
  11    | under the terms of the GNU Affero General Public License           |
  12    | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13    |                                                                    |
  14    | CiviCRM is distributed in the hope that it will be useful, but     |
  15    | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16    | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17    | See the GNU Affero General Public License for more details.        |
  18    |                                                                    |
  19    | You should have received a copy of the GNU Affero General Public   |
  20    | License and the CiviCRM Licensing Exception along                  |
  21    | with this program; if not, contact CiviCRM LLC                     |
  22    | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23    | GNU Affero General Public License or the licensing of CiviCRM,     |
  24    | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25    +--------------------------------------------------------------------+
  26  */
  27
  28 /**
  29  * This class handles all REST client requests.
  30  *
  31  * @package CRM
  32  * @copyright CiviCRM LLC (c) 2004-2019
  33  */
  34 class CRM_Utils_REST {
  35
  36   /**
  37    * Number of seconds we should let a REST process idle
  38    */
  39   static $rest_timeout = 0;
  40
  41   /**
  42    * Cache the actual UF Class
  43    */
  44   public $ufClass;
  45
  46   /**
  47    * Class constructor.  This caches the real user framework class locally,
  48    * so we can use it for authentication and validation.
  49    *
  50    * @internal param string $uf The userframework class
  51    */
  52   public function __construct() {
  53     // any external program which call Rest Server is responsible for
  54     // creating and attaching the session
  55     $args = func_get_args();
  56     $this->ufClass = array_shift($args);
  57   }
  58
  59   /**
  60    * Simple ping function to test for liveness.
  61    *
  62    * @param string $var
  63    *   The string to be echoed.
  64    *
  65    * @return string
  66    */
  67   public static function ping($var = NULL) {
  68     $session = CRM_Core_Session::singleton();
  69     $key = $session->get('key');
  70     // $session->set( 'key', $var );
  71     return self::simple(array('message' => "PONG: $key"));
  72   }
  73
  74   /**
  75    * Generates values needed for error messages.
  76    * @param string $message
  77    *
  78    * @return array
  79    */
  80   public static function error($message = 'Unknown Error') {
  81     $values = array(
  82       'error_message' => $message,
  83       'is_error' => 1,
  84     );
  85     return $values;
  86   }
  87
  88   /**
  89    * Generates values needed for non-error responses.
  90    * @param array $params
  91    *
  92    * @return array
  93    */
  94   public static function simple($params) {
  95     $values = array('is_error' => 0);
  96     $values += $params;
  97     return $values;
  98   }
  99
 100   /**
 101    * @return string
 102    */
 103   public function run() {
 104     $result = self::handle();
 105     return self::output($result);
 106   }
 107
 108   /**
 109    * @return string
 110    */
 111   public function bootAndRun() {
 112     $response = $this->loadCMSBootstrap();
 113     if (is_array($response)) {
 114       return self::output($response);
 115     }
 116     return $this->run();
 117   }
 118
 119   /**
 120    * @param $result
 121    *
 122    * @return string
 123    */
 124   public static function output(&$result) {
 125     $requestParams = CRM_Utils_Request::exportValues();
 126
 127     $hier = FALSE;
 128     if (is_scalar($result)) {
 129       if (!$result) {
 130         $result = 0;
 131       }
 132       $result = self::simple(array('result' => $result));
 133     }
 134     elseif (is_array($result)) {
 135       if (CRM_Utils_Array::isHierarchical($result)) {
 136         $hier = TRUE;
 137       }
 138       elseif (!array_key_exists('is_error', $result)) {
 139         $result['is_error'] = 0;
 140       }
 141     }
 142     else {
 143       $result = self::error('Could not interpret return values from function.');
 144     }
 145
 146     if (!empty($requestParams['json'])) {
 147       if (!empty($requestParams['prettyprint'])) {
 148         // Don't set content-type header for api explorer output
 149         return json_encode(array_merge($result), JSON_PRETTY_PRINT + JSON_UNESCAPED_SLASHES + JSON_UNESCAPED_UNICODE);
 150         return self::jsonFormated(array_merge($result));
 151       }
 152       CRM_Utils_System::setHttpHeader('Content-Type', 'application/json');
 153       return json_encode(array_merge($result));
 154     }
 155
 156     if (isset($result['count'])) {
 157       $count = ' count="' . $result['count'] . '" ';
 158     }
 159     else {
 160       $count = "";
 161     }
 162     $xml = "<?xml version=\"1.0\"?>
 163       <ResultSet xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" $count>
 164       ";
 165     // check if this is a single element result (contact_get etc)
 166     // or multi element
 167     if ($hier) {
 168       foreach ($result['values'] as $k => $v) {
 169         if (is_array($v)) {
 170           $xml .= "<Result>\n" . CRM_Utils_Array::xml($v) . "</Result>\n";
 171         }
 172         elseif (!is_object($v)) {
 173           $xml .= "<Result>\n<id>{$k}</id><value>{$v}</value></Result>\n";
 174         }
 175       }
 176     }
 177     else {
 178       $xml .= "<Result>\n" . CRM_Utils_Array::xml($result) . "</Result>\n";
 179     }
 180
 181     $xml .= "</ResultSet>\n";
 182     return $xml;
 183   }
 184
 185   /**
 186    * @return array|int
 187    */
 188   public static function handle() {
 189     $requestParams = CRM_Utils_Request::exportValues();
 190
 191     // Get the function name being called from the q parameter in the query string
 192     $q = CRM_Utils_Array::value('q', $requestParams);
 193     // or for the rest interface, from fnName
 194     $r = CRM_Utils_Array::value('fnName', $requestParams);
 195     if (!empty($r)) {
 196       $q = $r;
 197     }
 198     $entity = CRM_Utils_Array::value('entity', $requestParams);
 199     if (empty($entity) && !empty($q)) {
 200       $args = explode('/', $q);
 201       // If the function isn't in the civicrm namespace, reject the request.
 202       if ($args[0] != 'civicrm') {
 203         return self::error('Unknown function invocation.');
 204       }
 205
 206       // If the query string is malformed, reject the request.
 207       // Does this mean it will reject it
 208       if ((count($args) != 3) && ($args[1] != 'ping')) {
 209         return self::error('Unknown function invocation.');
 210       }
 211       $store = NULL;
 212
 213       if ($args[1] == 'ping') {
 214         return self::ping();
 215       }
 216     }
 217     else {
 218       // or the api format (entity+action)
 219       $args = array();
 220       $args[0] = 'civicrm';
 221       $args[1] = CRM_Utils_Array::value('entity', $requestParams);
 222       $args[2] = CRM_Utils_Array::value('action', $requestParams);
 223     }
 224
 225     // Everyone should be required to provide the server key, so the whole
 226     // interface can be disabled in more change to the configuration file.
 227     // first check for civicrm site key
 228     if (!CRM_Utils_System::authenticateKey(FALSE)) {
 229       $docLink = CRM_Utils_System::docURL2("Managing Scheduled Jobs", TRUE, NULL, NULL, NULL, "wiki");
 230       $key = CRM_Utils_Array::value('key', $requestParams);
 231       if (empty($key)) {
 232         return self::error("FATAL: mandatory param 'key' missing. More info at: " . $docLink);
 233       }
 234       return self::error("FATAL: 'key' is incorrect. More info at: " . $docLink);
 235     }
 236
 237     // At this point we know we are not calling ping which does not require authentication.
 238     // Therefore we now need a valid server key and API key.
 239     // Check and see if a valid secret API key is provided.
 240     $api_key = CRM_Utils_Request::retrieve('api_key', 'String', $store, FALSE, NULL, 'REQUEST');
 241     if (!$api_key || strtolower($api_key) == 'null') {
 242       return self::error("FATAL: mandatory param 'api_key' (user key) missing");
 243     }
 244     $valid_user = CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact', $api_key, 'id', 'api_key');
 245
 246     // If we didn't find a valid user, die
 247     if (empty($valid_user)) {
 248       return self::error("User API key invalid");
 249     }
 250
 251     return self::process($args, self::buildParamList());
 252   }
 253
 254   /**
 255    * @param $args
 256    * @param array $params
 257    *
 258    * @return array|int
 259    */
 260   public static function process(&$args, $params) {
 261     $params['check_permissions'] = TRUE;
 262     $fnName = $apiFile = NULL;
 263     // clean up all function / class names. they should be alphanumeric and _ only
 264     for ($i = 1; $i <= 3; $i++) {
 265       if (!empty($args[$i])) {
 266         $args[$i] = CRM_Utils_String::munge($args[$i]);
 267       }
 268     }
 269
 270     // incase of ajax functions className is passed in url
 271     if (isset($params['className'])) {
 272       $params['className'] = CRM_Utils_String::munge($params['className']);
 273
 274       // functions that are defined only in AJAX.php can be called via
 275       // rest interface
 276       if (!CRM_Core_Page_AJAX::checkAuthz('method', $params['className'], $params['fnName'])) {
 277         return self::error('Unknown function invocation.');
 278       }
 279
 280       return call_user_func(array($params['className'], $params['fnName']), $params);
 281     }
 282
 283     if (!array_key_exists('version', $params)) {
 284       $params['version'] = 3;
 285     }
 286
 287     if ($params['version'] == 2) {
 288       $result['is_error'] = 1;
 289       $result['error_message'] = "FATAL: API v2 not accessible from ajax/REST";
 290       $result['deprecated'] = "Please upgrade to API v3";
 291       return $result;
 292     }
 293
 294     if ($_SERVER['REQUEST_METHOD'] == 'GET' &&
 295        strtolower(substr($args[2], 0, 3)) != 'get' &&
 296        strtolower($args[2] != 'check')) {
 297       // get only valid for non destructive methods
 298       require_once 'api/v3/utils.php';
 299       return civicrm_api3_create_error("SECURITY: All requests that modify the database must be http POST, not GET.",
 300         array(
 301           'IP' => $_SERVER['REMOTE_ADDR'],
 302           'level' => 'security',
 303           'referer' => $_SERVER['HTTP_REFERER'],
 304           'reason' => 'Destructive HTTP GET',
 305         )
 306       );
 307     }
 308
 309     // trap all fatal errors
 310     $errorScope = CRM_Core_TemporaryErrorScope::create(array('CRM_Utils_REST', 'fatal'));
 311     $result = civicrm_api($args[1], $args[2], $params);
 312     unset($errorScope);
 313
 314     if ($result === FALSE) {
 315       return self::error('Unknown error.');
 316     }
 317     return $result;
 318   }
 319
 320   /**
 321    * @return array|mixed|null
 322    */
 323   public static function &buildParamList() {
 324     $requestParams = CRM_Utils_Request::exportValues();
 325     $params = array();
 326
 327     $skipVars = array(
 328       'q' => 1,
 329       'json' => 1,
 330       'key' => 1,
 331       'api_key' => 1,
 332       'entity' => 1,
 333       'action' => 1,
 334     );
 335
 336     if (array_key_exists('json', $requestParams) && $requestParams['json'][0] == "{") {
 337       $params = json_decode($requestParams['json'], TRUE);
 338       if ($params === NULL) {
 339         CRM_Utils_JSON::output(array('is_error' => 1, 'error_message', 'Unable to decode supplied JSON.'));
 340       }
 341     }
 342     foreach ($requestParams as $n => $v) {
 343       if (!array_key_exists($n, $skipVars)) {
 344         $params[$n] = $v;
 345       }
 346     }
 347     if (array_key_exists('return', $requestParams) && is_array($requestParams['return'])) {
 348       foreach ($requestParams['return'] as $key => $v) {
 349         $params['return.' . $key] = 1;
 350       }
 351     }
 352     return $params;
 353   }
 354
 355   /**
 356    * @param $pearError
 357    */
 358   public static function fatal($pearError) {
 359     CRM_Utils_System::setHttpHeader('Content-Type', 'text/xml');
 360     $error = array();
 361     $error['code'] = $pearError->getCode();
 362     $error['error_message'] = $pearError->getMessage();
 363     $error['mode'] = $pearError->getMode();
 364     $error['debug_info'] = $pearError->getDebugInfo();
 365     $error['type'] = $pearError->getType();
 366     $error['user_info'] = $pearError->getUserInfo();
 367     $error['to_string'] = $pearError->toString();
 368     $error['is_error'] = 1;
 369
 370     echo self::output($error);
 371
 372     CRM_Utils_System::civiExit();
 373   }
 374
 375   /**
 376    * used to load a template "inline", eg. for ajax, without having to build a menu for each template
 377    */
 378   public static function loadTemplate() {
 379     $request = CRM_Utils_Request::retrieve('q', 'String');
 380     if (FALSE !== strpos($request, '..')) {
 381       die ("SECURITY FATAL: the url can't contain '..'. Please report the issue on the forum at civicrm.org");
 382     }
 383
 384     $request = explode('/', $request);
 385     $entity = _civicrm_api_get_camel_name($request[2]);
 386     $tplfile = _civicrm_api_get_camel_name($request[3]);
 387
 388     $tpl = 'CRM/' . $entity . '/Page/Inline/' . $tplfile . '.tpl';
 389     $smarty = CRM_Core_Smarty::singleton();
 390     CRM_Utils_System::setTitle("$entity::$tplfile inline $tpl");
 391     if (!$smarty->template_exists($tpl)) {
 392       CRM_Utils_System::setHttpHeader("Status", "404 Not Found");
 393       die ("Can't find the requested template file templates/$tpl");
 394     }
 395     if (array_key_exists('id', $_GET)) {// special treatmenent, because it's often used
 396       $smarty->assign('id', (int) $_GET['id']);// an id is always positive
 397     }
 398     $pos = strpos(implode(array_keys($_GET)), '<');
 399
 400     if ($pos !== FALSE) {
 401       die ("SECURITY FATAL: one of the param names contains &lt;");
 402     }
 403     $param = array_map('htmlentities', $_GET);
 404     unset($param['q']);
 405     $smarty->assign_by_ref("request", $param);
 406
 407     if (!array_key_exists('HTTP_X_REQUESTED_WITH', $_SERVER) ||
 408       $_SERVER['HTTP_X_REQUESTED_WITH'] != "XMLHttpRequest"
 409     ) {
 410
 411       $smarty->assign('tplFile', $tpl);
 412       $config = CRM_Core_Config::singleton();
 413       $content = $smarty->fetch('CRM/common/' . strtolower($config->userFramework) . '.tpl');
 414
 415       if (!defined('CIVICRM_UF_HEAD') && $region = CRM_Core_Region::instance('html-header', FALSE)) {
 416         CRM_Utils_System::addHTMLHead($region->render(''));
 417       }
 418       CRM_Utils_System::appendTPLFile($tpl, $content);
 419
 420       return CRM_Utils_System::theme($content);
 421
 422     }
 423     else {
 424       $content = "<!-- .tpl file embedded: $tpl -->\n";
 425       CRM_Utils_System::appendTPLFile($tpl, $content);
 426       echo $content . $smarty->fetch($tpl);
 427       CRM_Utils_System::civiExit();
 428     }
 429   }
 430
 431   /**
 432    * This is a wrapper so you can call an api via json (it returns json too)
 433    * http://example.org/civicrm/api/json?entity=Contact&action=Get"&json={"contact_type":"Individual","email.get.email":{}}
 434    * to take all the emails from individuals.
 435    * Works for POST & GET (POST recommended).
 436    */
 437   public static function ajaxJson() {
 438     $requestParams = CRM_Utils_Request::exportValues();
 439
 440     require_once 'api/v3/utils.php';
 441     $config = CRM_Core_Config::singleton();
 442     if (!$config->debug && (!array_key_exists('HTTP_X_REQUESTED_WITH', $_SERVER) ||
 443         $_SERVER['HTTP_X_REQUESTED_WITH'] != "XMLHttpRequest"
 444       )
 445     ) {
 446       $error = civicrm_api3_create_error("SECURITY ALERT: Ajax requests can only be issued by javascript clients, eg. CRM.api3().",
 447         array(
 448           'IP' => $_SERVER['REMOTE_ADDR'],
 449           'level' => 'security',
 450           'referer' => $_SERVER['HTTP_REFERER'],
 451           'reason' => 'CSRF suspected',
 452         )
 453       );
 454       CRM_Utils_JSON::output($error);
 455     }
 456     if (empty($requestParams['entity'])) {
 457       CRM_Utils_JSON::output(civicrm_api3_create_error('missing entity param'));
 458     }
 459     if (empty($requestParams['entity'])) {
 460       CRM_Utils_JSON::output(civicrm_api3_create_error('missing entity entity'));
 461     }
 462     if (!empty($requestParams['json'])) {
 463       $params = json_decode($requestParams['json'], TRUE);
 464     }
 465     $entity = CRM_Utils_String::munge(CRM_Utils_Array::value('entity', $requestParams));
 466     $action = CRM_Utils_String::munge(CRM_Utils_Array::value('action', $requestParams));
 467     if (!is_array($params)) {
 468       CRM_Utils_JSON::output(array(
 469           'is_error' => 1,
 470           'error_message' => 'invalid json format: ?{"param_with_double_quote":"value"}',
 471         ));
 472     }
 473
 474     $params['check_permissions'] = TRUE;
 475     $params['version'] = 3;
 476     $_GET['json'] = $requestParams['json'] = 1; // $requestParams is local-only; this line seems pointless unless there's a side-effect influencing other functions
 477     if (!$params['sequential']) {
 478       $params['sequential'] = 1;
 479     }
 480
 481     // trap all fatal errors
 482     $errorScope = CRM_Core_TemporaryErrorScope::create(array('CRM_Utils_REST', 'fatal'));
 483     $result = civicrm_api($entity, $action, $params);
 484     unset($errorScope);
 485
 486     echo self::output($result);
 487
 488     CRM_Utils_System::civiExit();
 489   }
 490
 491   /**
 492    * Run ajax request.
 493    *
 494    * @return array
 495    */
 496   public static function ajax() {
 497     $requestParams = CRM_Utils_Request::exportValues();
 498
 499     // this is driven by the menu system, so we can use permissioning to
 500     // restrict calls to this etc
 501     // the request has to be sent by an ajax call. First line of protection against csrf
 502     $config = CRM_Core_Config::singleton();
 503     if (!$config->debug &&
 504       (!array_key_exists('HTTP_X_REQUESTED_WITH', $_SERVER) ||
 505         $_SERVER['HTTP_X_REQUESTED_WITH'] != "XMLHttpRequest"
 506       )
 507     ) {
 508       require_once 'api/v3/utils.php';
 509       $error = civicrm_api3_create_error("SECURITY ALERT: Ajax requests can only be issued by javascript clients, eg. CRM.api3().",
 510         array(
 511           'IP' => $_SERVER['REMOTE_ADDR'],
 512           'level' => 'security',
 513           'referer' => $_SERVER['HTTP_REFERER'],
 514           'reason' => 'CSRF suspected',
 515         )
 516       );
 517       CRM_Utils_JSON::output($error);
 518     }
 519
 520     $q = CRM_Utils_Array::value('fnName', $requestParams);
 521     if (!$q) {
 522       $entity = CRM_Utils_Array::value('entity', $requestParams);
 523       $action = CRM_Utils_Array::value('action', $requestParams);
 524       if (!$entity || !$action) {
 525         $err = array('error_message' => 'missing mandatory params "entity=" or "action="', 'is_error' => 1);
 526         echo self::output($err);
 527         CRM_Utils_System::civiExit();
 528       }
 529       $args = array('civicrm', $entity, $action);
 530     }
 531     else {
 532       $args = explode('/', $q);
 533     }
 534
 535     // get the class name, since all ajax functions pass className
 536     $className = CRM_Utils_Array::value('className', $requestParams);
 537
 538     // If the function isn't in the civicrm namespace, reject the request.
 539     if (($args[0] != 'civicrm' && count($args) != 3) && !$className) {
 540       return self::error('Unknown function invocation.');
 541     }
 542
 543     // Support for multiple api calls
 544     if (isset($entity) && $entity === 'api3') {
 545       $result = self::processMultiple();
 546     }
 547     else {
 548       $result = self::process($args, self::buildParamList());
 549     }
 550
 551     echo self::output($result);
 552
 553     CRM_Utils_System::civiExit();
 554   }
 555
 556   /**
 557    * Callback for multiple ajax api calls from CRM.api3()
 558    * @return array
 559    */
 560   public static function processMultiple() {
 561     $output = array();
 562     foreach (json_decode($_REQUEST['json'], TRUE) as $key => $call) {
 563       $args = array(
 564         'civicrm',
 565         $call[0],
 566         $call[1],
 567       );
 568       $output[$key] = self::process($args, CRM_Utils_Array::value(2, $call, array()));
 569     }
 570     return $output;
 571   }
 572
 573   /**
 574    * @return array|NULL
 575    *   NULL if execution should proceed; array if the response is already known
 576    */
 577   public function loadCMSBootstrap() {
 578     $requestParams = CRM_Utils_Request::exportValues();
 579     $q = CRM_Utils_Array::value('q', $requestParams);
 580     $args = explode('/', $q);
 581
 582     // Proceed with bootstrap for "?entity=X&action=Y"
 583     // Proceed with bootstrap for "?q=civicrm/X/Y" but not "?q=civicrm/ping"
 584     if (!empty($q)) {
 585       if (count($args) == 2 && $args[1] == 'ping') {
 586         CRM_Utils_System::loadBootStrap(array(), FALSE, FALSE);
 587         return NULL; // this is pretty wonky but maybe there's some reason I can't see
 588       }
 589       if (count($args) != 3) {
 590         return self::error('ERROR: Malformed REST path');
 591       }
 592       if ($args[0] != 'civicrm') {
 593         return self::error('ERROR: Malformed REST path');
 594       }
 595       // Therefore we have reasonably well-formed "?q=civicrm/X/Y"
 596     }
 597
 598     if (!CRM_Utils_System::authenticateKey(FALSE)) {
 599       // FIXME: At time of writing, this doesn't actually do anything because
 600       // authenticateKey abends, but that's a bad behavior which sends a
 601       // malformed response.
 602       CRM_Utils_System::loadBootStrap(array(), FALSE, FALSE);
 603       return self::error('Failed to authenticate key');
 604     }
 605
 606     $uid = NULL;
 607     if (!$uid) {
 608       $store = NULL;
 609       $api_key = CRM_Utils_Request::retrieve('api_key', 'String', $store, FALSE, NULL, 'REQUEST');
 610       if (empty($api_key)) {
 611         CRM_Utils_System::loadBootStrap(array(), FALSE, FALSE);
 612         return self::error("FATAL: mandatory param 'api_key' (user key) missing");
 613       }
 614       $contact_id = CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact', $api_key, 'id', 'api_key');
 615       if ($contact_id) {
 616         $uid = CRM_Core_BAO_UFMatch::getUFId($contact_id);
 617       }
 618     }
 619
 620     if ($uid && $contact_id) {
 621       CRM_Utils_System::loadBootStrap(array('uid' => $uid), TRUE, FALSE);
 622       $session = CRM_Core_Session::singleton();
 623       $session->set('ufID', $uid);
 624       $session->set('userID', $contact_id);
 625       CRM_Core_DAO::executeQuery('SET @civicrm_user_id = %1',
 626         array(1 => array($contact_id, 'Integer'))
 627       );
 628       return NULL;
 629     }
 630     else {
 631       CRM_Utils_System::loadBootStrap(array(), FALSE, FALSE);
 632       return self::error('ERROR: No CMS user associated with given api-key');
 633     }
 634   }
 635
 636 }