Civi/API/Subscriber/DynamicFKAuthorization.php

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