(NFC) hook_civicrm_alterApiRoutePermissions - Expand on docblock

[civicrm-core.git] / CRM / Utils / Hook.php

diff --git a/CRM/Utils/Hook.php b/CRM/Utils/Hook.php
index 95a5496ffd60fd784edfe717de6fa71da3bef4fb..2c0d1958626fe36ea2832017361b5b3ba72fee3e 100644 (file)
--- a/CRM/Utils/Hook.php
+++ b/CRM/Utils/Hook.php
@@ -1759,6 +1759,26 @@ abstract class CRM_Utils_Hook {
     );
   }
 
+  /**
+   * Register cryptographic resources, such as keys and cipher-suites.
+   *
+   * Ex: $crypto->addSymmetricKey([
+   *   'key' => hash_hkdf('sha256', 'abcd1234'),
+   *   'suite' => 'aes-cbc-hs',
+   * ]);
+   *
+   * @param \Civi\Crypto\CryptoRegistry $crypto
+   *
+   * @return mixed
+   */
+  public static function crypto($crypto) {
+    return self::singleton()->invoke(['crypto'], $crypto, self::$_nullObject,
+      self::$_nullObject, self::$_nullObject, self::$_nullObject,
+      self::$_nullObject,
+      'civicrm_crypto'
+    );
+  }
+
   /**
    * This hook collects the trigger definition from all components.
    *
@@ -2063,6 +2083,47 @@ abstract class CRM_Utils_Hook {
     );
   }
 
+  /**
+   * Rotate the cryptographic key used in the database.
+   *
+   * The purpose of this hook is to visit any encrypted values in the database
+   * and re-encrypt the content.
+   *
+   * For values encoded via `CryptoToken`, you can use `CryptoToken::rekey($oldToken, $tag)`
+   *
+   * @param string $tag
+   *   The type of crypto-key that is currently being rotated.
+   *   The hook-implementer should use this to decide which (if any) fields to visit.
+   *   Ex: 'CRED'
+   * @param \Psr\Log\LoggerInterface $log
+   *   List of messages about re-keyed values.
+   *
+   * @code
+   * function example_civicrm_rekey($tag, &$log) {
+   *   if ($tag !== 'CRED') return;
+   *
+   *   $cryptoToken = Civi::service('crypto.token');
+   *   $rows = sql('SELECT id, secret_column FROM some_table');
+   *   foreach ($rows as $row) {
+   *     $new = $cryptoToken->rekey($row['secret_column']);
+   *     if ($new !== NULL) {
+   *       sql('UPDATE some_table SET secret_column = %1 WHERE id = %2',
+   *         $new, $row['id']);
+   *     }
+   *   }
+   * }
+   * @endCode
+   *
+   * @return null
+   *   The return value is ignored
+   */
+  public static function cryptoRotateKey($tag, $log) {
+    return self::singleton()->invoke(['tag', 'log'], $tag, $log, self::$_nullObject,
+      self::$_nullObject, self::$_nullObject, self::$_nullObject,
+      'civicrm_cryptoRotateKey'
+    );
+  }
+
   /**
    * @param CRM_Core_Exception $exception
    * @param mixed $request
@@ -2724,4 +2785,37 @@ abstract class CRM_Utils_Hook {
     );
   }
 
+  /**
+   * Alter APIv4 route permissions based on the Entity and Action
+   *
+   * This is an experimental hook intended to *relax* the requirement
+   * for "access AJAX API" when calling public-oriented APIs.
+   *
+   * Historically, when APIv2/v3 were first exposed to an HTTP interface, using
+   * the HTTP interface required an extra permission "access AJAX API". This is a
+   * broad hedge against security flaws within those API's. In the current APIv4
+   * era, security concerns are often baked into each API, so there is a debate about
+   * whether "access AJAX API" serves a purpose or just makes
+   * administration/development more complicated. (So far, there's more support
+   * for the latter.)
+   *
+   * This hook might foreseeably be abandoned either...
+   *
+   * - if it is found that "access AJAX API" guard is not needed for APIv4.
+   * - if the policy is moved into metadata.
+   *
+   * @param array|string $permissions
+   * @param string $entity
+   * @param string $action
+   *
+   * @return mixed
+   */
+  public static function alterApiRoutePermissions(&$permissions, $entity, $action) {
+    return self::singleton()->invoke(
+      ['permissions', 'entity', 'action'],
+      $permissions, $entity, $action, self::$_nullObject, self::$_nullObject,
+      self::$_nullObject, 'civicrm_alterApiRoutePermissions'
+    );
+  }
+
 }