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       $tx->rollback(); // Just to be safe.
 231
 232       $params = [
 233         'version' => 3,
 234         'check_permissions' => 1,
 235         'id' => $entityId,
 236       ];
 237
 238       $result = $self->kernel->run($entity, $self->getDelegatedAction($action), $params);
 239       if ($result['is_error'] || empty($result['values'])) {
 240         $exception = new \Civi\API\Exception\UnauthorizedException("Authorization failed on ($entity,$entityId)", [
 241           'cause' => $result,
 242         ]);
 243       }
 244     });
 245
 246     if ($exception) {
 247       throw $exception;
 248     }
 249   }
 250
 251   /**
 252    * If the request attempts to change the entity_table/entity_id of an
 253    * existing record, then generate an error.
 254    *
 255    * @param int $fileId
 256    *   The main record being changed.
 257    * @param string $entityTable
 258    *   The saved FK.
 259    * @param int $entityId
 260    *   The saved FK.
 261    * @param array $apiRequest
 262    *   The full API request.
 263    * @throws \API_Exception
 264    */
 265   public function preventReassignment($fileId, $entityTable, $entityId, $apiRequest) {
 266     if (strtolower($apiRequest['action']) == 'create' && $fileId && !$this->isTrusted($apiRequest)) {
 267       // TODO: no change in field_name?
 268       if (isset($apiRequest['params']['entity_table']) && $entityTable != $apiRequest['params']['entity_table']) {
 269         throw new \API_Exception("Cannot modify entity_table");
 270       }
 271       if (isset($apiRequest['params']['entity_id']) && $entityId != $apiRequest['params']['entity_id']) {
 272         throw new \API_Exception("Cannot modify entity_id");
 273       }
 274     }
 275   }
 276
 277   /**
 278    * @param string $entityTable
 279    *   The target entity table (e.g. "civicrm_mailing" or "civicrm_activity").
 280    * @return string|NULL
 281    *   The target entity name (e.g. "Mailing" or "Activity").
 282    */
 283   public function getDelegatedEntityName($entityTable) {
 284     if ($this->allowedDelegates === NULL || in_array($entityTable, $this->allowedDelegates)) {
 285       $className = \CRM_Core_DAO_AllCoreTables::getClassForTable($entityTable);
 286       if ($className) {
 287         $entityName = \CRM_Core_DAO_AllCoreTables::getBriefName($className);
 288         if ($entityName) {
 289           return $entityName;
 290         }
 291       }
 292     }
 293     return NULL;
 294   }
 295
 296   /**
 297    * @param string $action
 298    *   API action name -- e.g. "create" ("When running *create* on a file...").
 299    * @return string
 300    *   e.g. "create" ("Check for *create* permission on the mailing to which
 301    *   it is attached.")
 302    */
 303   public function getDelegatedAction($action) {
 304     switch ($action) {
 305       case 'get':
 306         // reading attachments requires reading the other entity
 307         return 'get';
 308
 309       case 'create':
 310       case 'delete':
 311         // creating/updating/deleting an attachment requires editing
 312         // the other entity
 313         return 'create';
 314
 315       default:
 316         return $action;
 317     }
 318   }
 319
 320   /**
 321    * @param int $id
 322    *   e.g. file ID.
 323    * @return array
 324    *   (0 => bool $isValid, 1 => string $entityTable, 2 => int $entityId)
 325    * @throws \Exception
 326    */
 327   public function getDelegate($id) {
 328     $query = \CRM_Core_DAO::executeQuery($this->lookupDelegateSql, [
 329       1 => [$id, 'Positive'],
 330     ]);
 331     if ($query->fetch()) {
 332       if (!preg_match('/^civicrm_value_/', $query->entity_table)) {
 333         // A normal attachment directly on its entity.
 334         return [$query->is_valid, $query->entity_table, $query->entity_id];
 335       }
 336
 337       // Ex: Translate custom-field table ("civicrm_value_foo_4") to
 338       // entity table ("civicrm_activity").
 339       $tblIdx = \CRM_Utils_Array::index(['table_name'], $this->getCustomFields());
 340       if (isset($tblIdx[$query->entity_table])) {
 341         return [$query->is_valid, $tblIdx[$query->entity_table]['entity_table'], $query->entity_id];
 342       }
 343       throw new \Exception('Failed to lookup entity table for custom field.');
 344     }
 345     else {
 346       return [FALSE, NULL, NULL];
 347     }
 348   }
 349
 350   /**
 351    * @param array $apiRequest
 352    *   The full API request.
 353    * @return bool
 354    */
 355   public function isTrusted($apiRequest) {
 356     // isn't this redundant?
 357     return empty($apiRequest['params']['check_permissions']) or $apiRequest['params']['check_permissions'] == FALSE;
 358   }
 359
 360   /**
 361    * @return array
 362    *   Each item has keys 'field_name', 'table_name', 'extends', 'entity_table'
 363    */
 364   public function getCustomFields() {
 365     $query = \CRM_Core_DAO::executeQuery($this->lookupCustomFieldSql);
 366     $rows = [];
 367     while ($query->fetch()) {
 368       $rows[] = [
 369         'field_name' => $query->field_name,
 370         'table_name' => $query->table_name,
 371         'extends' => $query->extends,
 372         'entity_table' => \CRM_Core_BAO_CustomGroup::getTableNameByEntityName($query->extends),
 373       ];
 374     }
 375     return $rows;
 376   }
 377
 378 }