Inroduce dynamic hash algo for hooks

Author: DigitalTimK

.env

@@ -1,5 +1,6 @@
-# Specify the value of your BigBlueButton secret
+# Specify the URL and SECRET of your BigBlueButton-Server (check on your BBB-Server with command 'bbb-conf --secret')
 BBB_SERVER_BASE_URL="https://test-install.blindsidenetworks.com/bigbluebutton/"
+BBB_SECRET="8cd8ef52e8e101574e400365b55e11a6"
 
-# Specify the Server Base URL of your BigBlueButton
-BBB_SECRET="8cd8ef52e8e101574e400365b55e11a6"
+# SET THE HASHING ALGORITHM FOR HOOKS (BBB-SERVER < 3.0 MUST USE 'sha_1')
+HASH_ALGO_FOR_HOOKS="sha1"

src/BigBlueButton.php

@@ -64,14 +64,14 @@ class BigBlueButton
     protected string $jSessionId;
     protected string $hashingAlgorithm;
 
-    protected UrlBuilder $urlBuilder;
-
     /**
      * @var array<int, mixed>
      */
     protected array $curlOpts = [];
     protected int $timeOut    = 10;
 
+    private UrlBuilder $urlBuilder;
+
     /**
      * @param null|array<string, mixed> $opts
      */
@@ -469,13 +469,18 @@ public function setTimeOut(int $TimeOutInSeconds): self
     }
 
     /**
-     * @deprecated Replaced by same function-name provided by UrlBuilder-BigBlueButton
+     * @deprecated replaced by same function-name provided by UrlBuilder-BigBlueButton
      *
-     * Public accessor for buildUrl.
+     * Public accessor for buildUrl
      */
     public function buildUrl(string $method = '', string $params = '', bool $append = true): string
     {
-        return $this->urlBuilder->buildUrl($method, $params, $append);
+        return $this->getUrlBuilder()->buildUrl($method, $params, $append);
+    }
+
+    public function getUrlBuilder(): UrlBuilder
+    {
+        return $this->urlBuilder;
     }
 
     // ____________________ INTERNAL CLASS METHODS ___________________

src/Util/UrlBuilder.php

@@ -21,6 +21,7 @@
 namespace BigBlueButton\Util;
 
 use BigBlueButton\Core\ApiMethod;
+use BigBlueButton\Enum\HashingAlgorithm;
 use BigBlueButton\Parameters\CreateMeetingParameters;
 use BigBlueButton\Parameters\DeleteRecordingsParameters;
 use BigBlueButton\Parameters\EndMeetingParameters;
@@ -47,11 +48,16 @@ class UrlBuilder
 
     private string $bbbServerBaseUrl;
 
+    /** @deprecated This property will disappear after a while */
+    private string $hashAlgoForHooks;
+
     public function __construct(string $secret, string $serverBaseUrl, string $hashingAlgorithm)
     {
         $this->securitySalt     = $secret;
         $this->bbbServerBaseUrl = $serverBaseUrl;
         $this->hashingAlgorithm = $hashingAlgorithm;
+
+        $this->initiateAlgorithmForHooks();
     }
 
     /**
@@ -62,6 +68,11 @@ public function setHashingAlgorithm(string $hashingAlgorithm): void
         $this->hashingAlgorithm = $hashingAlgorithm;
     }
 
+    public function getHashingAlgorithm(): string
+    {
+        return $this->hashingAlgorithm;
+    }
+
     /**
      * Builds an API method URL that includes the url + params + its generated checksum.
      */
@@ -144,18 +155,94 @@ public function getPutRecordingTextTrackUrl(PutRecordingTextTrackParameters $put
         return $this->buildUrl(ApiMethod::PUT_RECORDING_TEXT_TRACK, $putRecordingTextTrackParams->getHTTPQuery());
     }
 
+    /**
+     * BBB-Server < 3.0 can only use SHA1 in the handling with hooks.
+     * Please configure the HASH_ALGO_FOR_HOOKS environment variable in case SHA1 shall not be used.
+     *
+     * @see https://github.com/bigbluebutton/bbb-webhooks/issues/30
+     */
     public function getHooksCreateUrl(HooksCreateParameters $hookCreateParams): string
     {
-        return $this->buildUrl(ApiMethod::HOOKS_CREATE, $hookCreateParams->getHTTPQuery());
+        // change hashing algorithm for hooks
+        $this->setHashingAlgorithm($this->hashAlgoForHooks);
+
+        // build URL
+        $url = $this->buildUrl(ApiMethod::HOOKS_CREATE, $hookCreateParams->getHTTPQuery());
+
+        // reset to 'normal' hashing algorithm
+        $this->setHashingAlgorithm($this->getHashingAlgorithm());
+
+        return $url;
     }
 
+    /**
+     * BBB-Server < 3.0 can only use SHA1 in the handling with hooks.
+     * Please configure the HASH_ALGO_FOR_HOOKS environment variable in case SHA1 shall not be used.
+     *
+     * @see https://github.com/bigbluebutton/bbb-webhooks/issues/30
+     */
     public function getHooksListUrl(): string
     {
-        return $this->buildUrl(ApiMethod::HOOKS_LIST);
+        // change hashing algorithm for hooks
+        $this->setHashingAlgorithm($this->hashAlgoForHooks);
+
+        // build URL
+        $url = $this->buildUrl(ApiMethod::HOOKS_LIST);
+
+        // reset to 'normal' hashing algorithm
+        $this->setHashingAlgorithm($this->getHashingAlgorithm());
+
+        return $url;
     }
 
+    /**
+     * BBB-Server < 3.0 can only use SHA1 in the handling with hooks.
+     * Please configure the HASH_ALGO_FOR_HOOKS environment variable in case SHA1 shall not be used.
+     *
+     * @see https://github.com/bigbluebutton/bbb-webhooks/issues/30
+     */
     public function getHooksDestroyUrl(HooksDestroyParameters $hooksDestroyParams): string
     {
-        return $this->buildUrl(ApiMethod::HOOKS_DESTROY, $hooksDestroyParams->getHTTPQuery());
+        // change hashing algorithm for hooks
+        $this->setHashingAlgorithm($this->hashAlgoForHooks);
+
+        // build URL
+        $url = $this->buildUrl(ApiMethod::HOOKS_DESTROY, $hooksDestroyParams->getHTTPQuery());
+
+        // reset to 'normal' hashing algorithm
+        $this->setHashingAlgorithm($this->getHashingAlgorithm());
+
+        return $url;
+    }
+
+    /**
+     *  Defines the algorithm to be used for hooks.
+     *
+     *  Background: BBB-Server below 3.0 are using SHA1-algorithm for hooks. The current planning for
+     *              BBB-Server 3.0 (and on) is to align the hashing algorithm  for hooks with the rest
+     *              of the system. Having this in mind the two situations need to be covered:
+     *                 - BBB-Server <  3.0 ==> SHA1 is default for hooks (even rest is using other algorithm)
+     *                 - BBB-Server >= 3.0 ==> same algorithm everywhere (according to planning).
+     *
+     *  This function will evolve in phases:
+     *   - Phase 1: SHA1 as default                 (or superseded by environment-variable HASH_ALGO_FOR_HOOKS).
+     *   - Phase 2: same algo everywhere as default (or superseded by environment-variable HASH_ALGO_FOR_HOOKS and which will trigger in this case a deprecation-warning).
+     *   - Phase 3: removal of this function, the class-property '$hashAlgoForHooks' and the use of env-variable HASH_ALGO_FOR_HOOKS.
+     *
+     * @deprecated This function will evolve in phases and will later disappear
+     */
+    private function initiateAlgorithmForHooks(): void
+    {
+        // in case this env-variable is not set, SHA1 shall be used as default (phase 1)
+        $this->hashAlgoForHooks = getenv('HASH_ALGO_FOR_HOOKS') ?: HashingAlgorithm::SHA_1;
+
+        /* ---------------------------------- phase 2 ----------------------------------
+         * // in case this env-variable is not set, the 'normal' algorithm shall be used as default (phase 2)
+         * $this->hashAlgoForHooks = getenv('HASH_ALGO_FOR_HOOKS') ?: $this->getHashingAlgorithm();
+         *
+         * if (getenv('HASH_ALGO_FOR_HOOKS')) {
+         *   trigger_error('The environment variable HASH_ALGO_FOR_HOOKS will be removed soon. This will require you to run a BBB-Server 3.0 or higher!', E_USER_DEPRECATED);
+         * }
+         * ---------------------------------- phase 2 ---------------------------------- */
     }
 }

tests/BigBlueButtonTest.php

@@ -27,11 +27,11 @@
 use BigBlueButton\Parameters\GetMeetingInfoParameters;
 use BigBlueButton\Parameters\GetRecordingsParameters;
 use BigBlueButton\Parameters\HooksCreateParameters;
+use BigBlueButton\Parameters\HooksDestroyParameters;
 use BigBlueButton\Parameters\IsMeetingRunningParameters;
 use BigBlueButton\Parameters\PublishRecordingsParameters;
 use BigBlueButton\Util\ParamsIterator;
 use Dotenv\Dotenv;
-use Tracy\Debugger;
 
 /**
  * Class BigBlueButtonTest.
@@ -89,9 +89,9 @@ public function testApiVersion(): void
     // Create Meeting
 
     /**
-     * @deprecated Test will be removed together with the deprecated function from BigBlueButton::class
+     * @deprecated test will be removed together with the deprecated function from BigBlueButton::class
      *
-     * Test create meeting URL.
+     * Test create meeting URL
      */
     public function testCreateMeetingUrl(): void
     {
@@ -179,9 +179,9 @@ public function testCreateMeetingWithMultiDocument(): void
     // Join Meeting
 
     /**
-     * @deprecated Test will be removed together with the deprecated function from BigBlueButton::class
+     * @deprecated test will be removed together with the deprecated function from BigBlueButton::class
      *
-     * Test create join meeting URL.
+     * Test create join meeting URL
      */
     public function testCreateJoinMeetingUrl(): void
     {
@@ -233,9 +233,9 @@ public function testJoinMeeting(): void
     // End Meeting
 
     /**
-     * @deprecated Test will be removed together with the deprecated function from BigBlueButton::class
+     * @deprecated test will be removed together with the deprecated function from BigBlueButton::class
      *
-     * Test generate end meeting URL.
+     * Test generate end meeting URL
      */
     public function testCreateEndMeetingUrl(): void
     {
@@ -392,7 +392,32 @@ public function testHooksCreate(): void
         // create a hook
         $hooksCreateParameters = new HooksCreateParameters($this->faker->url);
         $hooksCreateResponse   = $this->bbb->hooksCreate($hooksCreateParameters);
-        $this->assertEquals('SUCCESS', $hooksCreateResponse->getReturnCode(), $hooksCreateResponse->getMessage());
+        $this->assertTrue($hooksCreateResponse->success(), $hooksCreateResponse->getMessage());
+    }
+
+    public function testHooksList(): void
+    {
+        // create a hook
+        $hooksListResponse = $this->bbb->hooksList();
+        $this->assertTrue($hooksListResponse->success(), $hooksListResponse->getMessage());
+    }
+
+    public function testHooksDestroy(): void
+    {
+        // create a hook
+        $hooksCreateParameters = new HooksCreateParameters($this->faker->url);
+        $hooksCreateResponse   = $this->bbb->hooksCreate($hooksCreateParameters);
+        $this->assertTrue($hooksCreateResponse->success(), $hooksCreateResponse->getMessage());
+
+        // destroy existing hook
+        $hooksDestroyParameters = new HooksDestroyParameters($hooksCreateResponse->getHookId());
+        $hooksCreateResponse    = $this->bbb->hooksDestroy($hooksDestroyParameters);
+        $this->assertTrue($hooksCreateResponse->success(), $hooksCreateResponse->getMessage());
+
+        // destroy non-existing hook
+        $hooksDestroyParameters = new HooksDestroyParameters($this->faker->uuid);
+        $hooksCreateResponse    = $this->bbb->hooksDestroy($hooksDestroyParameters);
+        $this->assertFalse($hooksCreateResponse->success(), $hooksCreateResponse->getMessage());
     }
 
     /**

tests/Parameters/HooksCreateParametersTest.php

@@ -21,7 +21,6 @@
 namespace BigBlueButton\Parameters;
 
 use BigBlueButton\TestCase;
-use Tracy\Debugger;
 
 /**
  * @internal
@@ -39,12 +38,10 @@ public function testHooksCreateParameters(): void
         }
         $eventIds = implode(',', $eventIds);
 
-
         $hooksCreateParameters = new HooksCreateParameters($callBackUrl = $this->faker->url);
 
         $this->assertEquals($callBackUrl, $hooksCreateParameters->getCallbackUrl());
 
-
         // Test setters that are ignored by the constructor
         $hooksCreateParameters->setMeetingId($meetingId = $this->faker->uuid);
         $hooksCreateParameters->setGetRaw($getRaw = $this->faker->boolean);