Civi/API/Subscriber/DynamicFKAuthorization.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 namespace Civi\API\Subscriber;
  29
  30 use Civi\API\Events;
  31 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  32
  33 /**
  34  * Given an entity which dynamically attaches itself to another entity,
  35  * determine if one has permission to the other entity.
  36  *
  37  * Example: Suppose one tries to manipulate a File which is attached to a
  38  * Mailing. DynamicFKAuthorization will enforce permissions on the File by
  39  * imitating the permissions of the Mailing.
  40  *
  41  * Note: This enforces a constraint: all matching API calls must define
  42  * "id" (e.g. for the file) or "entity_table+entity_id" or
  43  * "field_name+entity_id".
  44  *
  45  * Note: The permission guard does not exactly authorize the request, but it
  46  * may veto authorization.
  47  */
  48 class DynamicFKAuthorization implements EventSubscriberInterface {
  49
  50   /**
  51    * @return array
  52    */
  53   public static function getSubscribedEvents() {
  54     return [
  55       Events::AUTHORIZE => [
  56         ['onApiAuthorize', Events::W_EARLY],
  57       ],
  58     ];
  59   }
  60
  61   /**
  62    * @var \Civi\API\Kernel
  63    *
  64    * Treat as private. Marked public due to PHP 5.3-compatibility issues.
  65    */
  66   public $kernel;
  67
  68   /**
  69    * @var string, the entity for which we want to manage permissions
  70    */
  71   protected $entityName;
  72
  73   /**
  74    * @var array <string> the actions for which we want to manage permissions
  75    */
  76   protected $actions;
  77
  78   /**
  79    * @var string, SQL. Given a file ID, determine the entity+table it's attached to.
  80    *
  81    * ex: "SELECT if(cf.id,1,0) as is_valid, cef.entity_table, cef.entity_id
  82    * FROM civicrm_file cf
  83    * INNER JOIN civicrm_entity_file cef ON cf.id = cef.file_id
  84    * WHERE cf.id = %1"
  85    *
  86    * Note: %1 is a parameter
  87    * Note: There are three parameters
  88    *  - is_valid: "1" if %1 identifies an actual record; otherwise "0"
  89    *  - entity_table: NULL or the name of a related table
  90    *  - entity_id: NULL or the ID of a row in the related table
  91    */
  92   protected $lookupDelegateSql;
  93
  94   /**
  95    * @var string, SQL. Get a list of (field_name, table_name, extends) tuples.
  96    *
  97    * For example, one tuple might be ("custom_123", "civicrm_value_mygroup_4",
  98    * "Activity").
  99    */
 100   protected $lookupCustomFieldSql;
 101
 102   /**
 103    * @var array
 104    *
 105    * Each item is an array(field_name => $, table_name => $, extends => $)
 106    */
 107   protected $lookupCustomFieldCache;
 108
 109   /**
 110    * @var array list of related tables for which FKs are allowed
 111    */
 112   protected $allowedDelegates;
 113
 114   /**
 115    * @param \Civi\API\Kernel $kernel
 116    *   The API kernel.
 117    * @param string $entityName
 118    *   The entity for which we want to manage permissions (e.g. "File" or
 119    *   "Note").
 120    * @param array $actions
 121    *   The actions for which we want to manage permissions (e.g. "create",
 122    *   "get", "delete").
 123    * @param string $lookupDelegateSql
 124    *   See docblock in DynamicFKAuthorization::$lookupDelegateSql.
 125    * @param string $lookupCustomFieldSql
 126    *   See docblock in DynamicFKAuthorization::$lookupCustomFieldSql.
 127    * @param array|NULL $allowedDelegates
 128    *   e.g. "civicrm_mailing","civicrm_activity"; NULL to allow any.
 129    */
 130   public function __construct($kernel, $entityName, $actions, $lookupDelegateSql, $lookupCustomFieldSql, $allowedDelegates = NULL) {
 131     $this->kernel = $kernel;
 132     $this->entityName = \CRM_Utils_String::convertStringToCamel($entityName);
 133     $this->actions = $actions;
 134     $this->lookupDelegateSql = $lookupDelegateSql;
 135     $this->lookupCustomFieldSql = $lookupCustomFieldSql;
 136     $this->allowedDelegates = $allowedDelegates;
 137   }
 138
 139   /**
 140    * @param \Civi\API\Event\AuthorizeEvent $event
 141    *   API authorization event.
 142    * @throws \API_Exception
 143    * @throws \Civi\API\Exception\UnauthorizedException
 144    */
 145   public function onApiAuthorize(\Civi\API\Event\AuthorizeEvent $event) {
 146     $apiRequest = $event->getApiRequest();
 147     if ($apiRequest['version'] == 3 && \CRM_Utils_String::convertStringToCamel($apiRequest['entity']) == $this->entityName && in_array(strtolower($apiRequest['action']), $this->actions)) {
 148       if (isset($apiRequest['params']['field_name'])) {
 149         $fldIdx = \CRM_Utils_Array::index(['field_name'], $this->getCustomFields());
 150         if (empty($fldIdx[$apiRequest['params']['field_name']])) {
 151           throw new \Exception("Failed to map custom field to entity table");
 152         }
 153         $apiRequest['params']['entity_table'] = $fldIdx[$apiRequest['params']['field_name']]['entity_table'];
 154         unset($apiRequest['params']['field_name']);
 155       }
 156
 157       if (/*!$isTrusted */
 158         empty($apiRequest['params']['id']) && empty($apiRequest['params']['entity_table'])
 159       ) {
 160         throw new \API_Exception("Mandatory key(s) missing from params array: 'id' or 'entity_table'");
 161       }
 162
 163       if (isset($apiRequest['params']['id'])) {
 164         list($isValidId, $entityTable, $entityId) = $this->getDelegate($apiRequest['params']['id']);
 165         if ($isValidId && $entityTable && $entityId) {
 166           $this->authorizeDelegate($apiRequest['action'], $entityTable, $entityId, $apiRequest);
 167           $this->preventReassignment($apiRequest['params']['id'], $entityTable, $entityId, $apiRequest);
 168           return;
 169         }
 170         elseif ($isValidId) {
 171           throw new \API_Exception("Failed to match record to related entity");
 172         }
 173         elseif (!$isValidId && strtolower($apiRequest['action']) == 'get') {
 174           // The matches will be an empty set; doesn't make a difference if we
 175           // reject or accept.
 176           // To pass SyntaxConformanceTest, we won't veto "get" on empty-set.
 177           return;
 178         }
 179       }
 180
 181       if (isset($apiRequest['params']['entity_table'])) {
 182         if (!\CRM_Core_DAO_AllCoreTables::isCoreTable($apiRequest['params']['entity_table'])) {
 183           throw new \API_Exception("Unrecognized target entity table {$apiRequest['params']['entity_table']}");
 184         }
 185         $this->authorizeDelegate(
 186           $apiRequest['action'],
 187           $apiRequest['params']['entity_table'],
 188           \CRM_Utils_Array::value('entity_id', $apiRequest['params'], NULL),
 189           $apiRequest
 190         );
 191         return;
 192       }
 193
 194       throw new \API_Exception("Failed to run permission check");
 195     }
 196   }
 197
 198   /**
 199    * @param string $action
 200    *   The API action (e.g. "create").
 201    * @param string $entityTable
 202    *   The target entity table (e.g. "civicrm_mailing").
 203    * @param int|NULL $entityId
 204    *   The target entity ID.
 205    * @param array $apiRequest
 206    *   The full API request.
 207    * @throws \Exception
 208    * @throws \API_Exception
 209    * @throws \Civi\API\Exception\UnauthorizedException
 210    */
 211   public function authorizeDelegate($action, $entityTable, $entityId, $apiRequest) {
 212     if ($this->isTrusted($apiRequest)) {
 213       return;
 214     }
 215
 216     $entity = $this->getDelegatedEntityName($entityTable);
 217     if (!$entity) {
 218       throw new \API_Exception("Failed to run permission check: Unrecognized target entity table ($entityTable)");
 219     }
 220     if (!$entityId) {
 221       throw new \Civi\API\Exception\UnauthorizedException("Authorization failed on ($entity): Missing entity_id");
 222     }
 223
 224     /**
 225      * @var \Exception $exception
 226      */
 227     $exception = NULL;
 228     $self = $this;
 229     \CRM_Core_Transaction::create(TRUE)->run(function($tx) use ($entity, $action, $entityId, &$exception, $self) {
 230       // Just to be safe.
 231       $tx->rollback();
 232
 233       $params = [
 234         'version' => 3,
 235         'check_permissions' => 1,
 236         'id' => $entityId,
 237       ];
 238
 239       $result = $self->kernel->run($entity, $self->getDelegatedAction($action), $params);
 240       if ($result['is_error'] || empty($result['values'])) {
 241         $exception = new \Civi\API\Exception\UnauthorizedException("Authorization failed on ($entity,$entityId)", [
 242           'cause' => $result,
 243         ]);
 244       }
 245     });
 246
 247     if ($exception) {
 248       throw $exception;
 249     }
 250   }
 251
 252   /**
 253    * If the request attempts to change the entity_table/entity_id of an
 254    * existing record, then generate an error.
 255    *
 256    * @param int $fileId
 257    *   The main record being changed.
 258    * @param string $entityTable
 259    *   The saved FK.
 260    * @param int $entityId
 261    *   The saved FK.
 262    * @param array $apiRequest
 263    *   The full API request.
 264    * @throws \API_Exception
 265    */
 266   public function preventReassignment($fileId, $entityTable, $entityId, $apiRequest) {
 267     if (strtolower($apiRequest['action']) == 'create' && $fileId && !$this->isTrusted($apiRequest)) {
 268       // TODO: no change in field_name?
 269       if (isset($apiRequest['params']['entity_table']) && $entityTable != $apiRequest['params']['entity_table']) {
 270         throw new \API_Exception("Cannot modify entity_table");
 271       }
 272       if (isset($apiRequest['params']['entity_id']) && $entityId != $apiRequest['params']['entity_id']) {
 273         throw new \API_Exception("Cannot modify entity_id");
 274       }
 275     }
 276   }
 277
 278   /**
 279    * @param string $entityTable
 280    *   The target entity table (e.g. "civicrm_mailing" or "civicrm_activity").
 281    * @return string|NULL
 282    *   The target entity name (e.g. "Mailing" or "Activity").
 283    */
 284   public function getDelegatedEntityName($entityTable) {
 285     if ($this->allowedDelegates === NULL || in_array($entityTable, $this->allowedDelegates)) {
 286       $className = \CRM_Core_DAO_AllCoreTables::getClassForTable($entityTable);
 287       if ($className) {
 288         $entityName = \CRM_Core_DAO_AllCoreTables::getBriefName($className);
 289         if ($entityName) {
 290           return $entityName;
 291         }
 292       }
 293     }
 294     return NULL;
 295   }
 296
 297   /**
 298    * @param string $action
 299    *   API action name -- e.g. "create" ("When running *create* on a file...").
 300    * @return string
 301    *   e.g. "create" ("Check for *create* permission on the mailing to which
 302    *   it is attached.")
 303    */
 304   public function getDelegatedAction($action) {
 305     switch ($action) {
 306       case 'get':
 307         // reading attachments requires reading the other entity
 308         return 'get';
 309
 310       case 'create':
 311       case 'delete':
 312         // creating/updating/deleting an attachment requires editing
 313         // the other entity
 314         return 'create';
 315
 316       default:
 317         return $action;
 318     }
 319   }
 320
 321   /**
 322    * @param int $id
 323    *   e.g. file ID.
 324    * @return array
 325    *   (0 => bool $isValid, 1 => string $entityTable, 2 => int $entityId)
 326    * @throws \Exception
 327    */
 328   public function getDelegate($id) {
 329     $query = \CRM_Core_DAO::executeQuery($this->lookupDelegateSql, [
 330       1 => [$id, 'Positive'],
 331     ]);
 332     if ($query->fetch()) {
 333       if (!preg_match('/^civicrm_value_/', $query->entity_table)) {
 334         // A normal attachment directly on its entity.
 335         return [$query->is_valid, $query->entity_table, $query->entity_id];
 336       }
 337
 338       // Ex: Translate custom-field table ("civicrm_value_foo_4") to
 339       // entity table ("civicrm_activity").
 340       $tblIdx = \CRM_Utils_Array::index(['table_name'], $this->getCustomFields());
 341       if (isset($tblIdx[$query->entity_table])) {
 342         return [$query->is_valid, $tblIdx[$query->entity_table]['entity_table'], $query->entity_id];
 343       }
 344       throw new \Exception('Failed to lookup entity table for custom field.');
 345     }
 346     else {
 347       return [FALSE, NULL, NULL];
 348     }
 349   }
 350
 351   /**
 352    * @param array $apiRequest
 353    *   The full API request.
 354    * @return bool
 355    */
 356   public function isTrusted($apiRequest) {
 357     // isn't this redundant?
 358     return empty($apiRequest['params']['check_permissions']) or $apiRequest['params']['check_permissions'] == FALSE;
 359   }
 360
 361   /**
 362    * @return array
 363    *   Each item has keys 'field_name', 'table_name', 'extends', 'entity_table'
 364    */
 365   public function getCustomFields() {
 366     $query = \CRM_Core_DAO::executeQuery($this->lookupCustomFieldSql);
 367     $rows = [];
 368     while ($query->fetch()) {
 369       $rows[] = [
 370         'field_name' => $query->field_name,
 371         'table_name' => $query->table_name,
 372         'extends' => $query->extends,
 373         'entity_table' => \CRM_Core_BAO_CustomGroup::getTableNameByEntityName($query->extends),
 374       ];
 375     }
 376     return $rows;
 377   }
 378
 379 }