Add signatureVersion config

Author: const-cloudinary

src/Api/Utils/ApiUtils.php

@@ -242,16 +242,18 @@ public static function serializeResponsiveBreakpoints(?array $breakpoints): bool
      *
      * @internal
      */
-    public static function serializeQueryParams(array $parameters = []): string
+    public static function serializeQueryParams(array $parameters = [], int $signatureVersion = 2): string
     {
-        // URL encode & characters in values to prevent parameter smuggling
-        $encodedParameters = ArrayUtils::mapAssoc(
-            static fn($key, $value) => str_replace('&', '%26', $value),
-            $parameters
-        );
-        
+        // Version 2: URL encode & characters in values to prevent parameter smuggling
+        if ($signatureVersion >= 2) {
+            $parameters = ArrayUtils::mapAssoc(
+                static fn($key, $value) => str_replace('&', '%26', $value),
+                $parameters
+            );
+        }
+
         return ArrayUtils::implodeAssoc(
-            $encodedParameters,
+            $parameters,
             self::QUERY_STRING_OUTER_DELIMITER,
             self::QUERY_STRING_INNER_DELIMITER
         );
@@ -263,6 +265,7 @@ public static function serializeQueryParams(array $parameters = []): string
      * @param array  $parameters         Parameters to sign.
      * @param string $secret             The API secret of the cloud.
      * @param string $signatureAlgorithm Signature algorithm
+     * @param int    $signatureVersion   Signature version (1 or 2)
      *
      * @return string The signature.
      *
@@ -271,13 +274,14 @@ public static function serializeQueryParams(array $parameters = []): string
     public static function signParameters(
         array $parameters,
         string $secret,
-        string $signatureAlgorithm = Utils::ALGO_SHA1
+        string $signatureAlgorithm = Utils::ALGO_SHA1,
+        int $signatureVersion = 2
     ): string {
         $parameters = array_map(self::class . '::serializeSimpleApiParam', $parameters);
 
         ksort($parameters);
 
-        $signatureContent = self::serializeQueryParams($parameters);
+        $signatureContent = self::serializeQueryParams($parameters, $signatureVersion);
 
         return Utils::sign($signatureContent, $secret, false, $signatureAlgorithm);
     }
@@ -293,7 +297,8 @@ public static function signRequest(?array &$parameters, CloudConfig $cloudConfig
         $parameters['signature'] = self::signParameters(
             $parameters,
             $cloudConfig->apiSecret,
-            $cloudConfig->signatureAlgorithm
+            $cloudConfig->signatureAlgorithm,
+            $cloudConfig->signatureVersion
         );
         $parameters['api_key']   = $cloudConfig->apiKey;
     }

src/Configuration/CloudConfig.php

@@ -19,6 +19,7 @@
  * target="_blank">Get account details from the Cloudinary Console.</a>
  *
  * @property ?string $signatureAlgorithm By default, set to self::DEFAULT_SIGNATURE_ALGORITHM.
+ * @property ?int $signatureVersion By default, set to self::DEFAULT_SIGNATURE_VERSION.
  *
  * @api
  */
@@ -29,13 +30,15 @@ class CloudConfig extends BaseConfigSection
     public const CONFIG_NAME = 'cloud';
 
     public const DEFAULT_SIGNATURE_ALGORITHM = Utils::ALGO_SHA1;
+    public const DEFAULT_SIGNATURE_VERSION = 2;
 
     // Supported parameters
     public const CLOUD_NAME = 'cloud_name';
     public const API_KEY    = 'api_key';
     public const API_SECRET = 'api_secret';
     public const OAUTH_TOKEN = 'oauth_token';
     public const SIGNATURE_ALGORITHM = 'signature_algorithm';
+    public const SIGNATURE_VERSION = 'signature_version';
 
     /**
      * @var array of configuration keys that contain sensitive data that should not be exported (for example api key)
@@ -69,6 +72,11 @@ class CloudConfig extends BaseConfigSection
      */
     protected ?string $signatureAlgorithm = null;
 
+    /**
+     * Sets the signature version (2 by default).
+     */
+    protected ?int $signatureVersion = null;
+
     /**
      * Serialises configuration section to a string representation.
      *

src/Configuration/CloudConfigTrait.php

@@ -59,6 +59,20 @@ public function signatureAlgorithm(string $signatureAlgorithm): static
         return $this->setCloudConfig(CloudConfig::SIGNATURE_ALGORITHM, $signatureAlgorithm);
     }
 
+    /**
+     * Sets the signature version.
+     *
+     * @param int $signatureVersion The signature version to use. (Can be 1 or 2).
+     *
+     * @return $this
+     *
+     * @api
+     */
+    public function signatureVersion(int $signatureVersion): static
+    {
+        return $this->setCloudConfig(CloudConfig::SIGNATURE_VERSION, $signatureVersion);
+    }
+
     /**
      * Sets the Cloud configuration key with the specified value.
      *

tests/Unit/Utils/ApiUtilsTest.php

@@ -389,4 +389,39 @@ public function testApiSignRequestPreventsParameterSmuggling()
         $expectedSmuggledSignature = '7b4e3a539ff1fa6e6700c41b3a2ee77586a025f9';
         self::assertEquals($expectedSmuggledSignature, $signatureSmugggled);
     }
+
+    /**
+     * Should apply the configured signature version from CloudConfig.
+     */
+    public function testConfiguredSignatureVersionIsApplied()
+    {
+        $params = [
+            'cloud_name' => self::API_SIGN_REQUEST_CLOUD_NAME,
+            'timestamp' => 1568810420,
+            'notification_url' => 'https://fake.com/callback?a=1&tags=hello,world'
+        ];
+
+        $config = new Configuration('cloudinary://key:' . self::API_SIGN_REQUEST_TEST_SECRET . '@test123');
+
+        // Test with signature version 1 (legacy behavior - no URL encoding)
+        $config->cloud->signatureVersion = 1;
+        $paramsV1 = $params;
+        ApiUtils::signRequest($paramsV1, $config->cloud);
+        $signatureV1 = $paramsV1['signature'];
+
+        // Test with signature version 2 (current behavior - with URL encoding)
+        $config->cloud->signatureVersion = 2;
+        $paramsV2 = $params;
+        ApiUtils::signRequest($paramsV2, $config->cloud);
+        $signatureV2 = $paramsV2['signature'];
+
+        // Signatures should be different, proving the version setting is applied
+        self::assertNotEquals($signatureV1, $signatureV2,
+                            'Signature versions should produce different results');
+
+        // Version 2 should match the expected encoded signature
+        $expectedV2Signature = '4fdf465dd89451cc1ed8ec5b3e314e8a51695704';
+        self::assertEquals($expectedV2Signature, $signatureV2,
+                          'Version 2 should match expected encoded signature');
+    }
 }