Merge pull request #146 from Nexmo/signature-secret

Add support for hmac related request signing

Author: lornajane

README.md

@@ -151,6 +151,26 @@ $client->message()->search($message);
 echo "The body of the message was: " . $message->getBody();
 ```
 
+### Signing a Message
+
+The SMS API supports the ability to sign messages by generating and adding a signature using a "Signature Secret" rather than your API secret.  The algorithms supported are:
+
+* `md5hash1`
+* `md5`
+* `sha1`
+* `sha256`
+* `sha512`
+
+Both your application and Nexmo need to agree on which algorithm is used. In the [dashboard](https://dashboard.nexmo.com), visit your account settings page and under "API Settings" you can select the algorithm to use. This is also the location where you will find your "Signature Secret" (it's different from the API secret).
+
+Create a client using these credentials and the algorithm to use, for example:
+
+```php
+$client = new Nexmo\Client(new Nexmo\Client\Credentials\SignatureSecret(API_KEY, API_SECRET, 'sha256'));
+```
+
+Using this client, your SMS API messages will be sent as signed messages.
+
 ### Starting a Verification
 
 Nexmo's [Verify API][doc_verify] makes it easy to prove that a user has provided their own phone number during signup,

src/Client.php

@@ -157,7 +157,7 @@ public static function signRequest(RequestInterface $request, SignatureSecret $c
                 $content = $body->getContents();
                 $params = json_decode($content, true);
                 $params['api_key'] = $credentials['api_key'];
-                $signature = new Signature($params, $credentials['signature_secret']);
+                $signature = new Signature($params, $credentials['signature_secret'], $credentials['signature_method']);
                 $body->rewind();
                 $body->write(json_encode($signature->getSignedParams()));
                 break;
@@ -168,7 +168,7 @@ public static function signRequest(RequestInterface $request, SignatureSecret $c
                 $params = [];
                 parse_str($content, $params);
                 $params['api_key'] = $credentials['api_key'];
-                $signature = new Signature($params, $credentials['signature_secret']);
+                $signature = new Signature($params, $credentials['signature_secret'], $credentials['signature_method']);
                 $params = $signature->getSignedParams();
                 $body->rewind();
                 $body->write(http_build_query($params, null, '&'));
@@ -177,7 +177,7 @@ public static function signRequest(RequestInterface $request, SignatureSecret $c
                 $query = [];
                 parse_str($request->getUri()->getQuery(), $query);
                 $query['api_key'] = $credentials['api_key'];
-                $signature = new Signature($query, $credentials['signature_secret']);
+                $signature = new Signature($query, $credentials['signature_secret'], $credentials['signature_method']);
                 $request = $request->withUri($request->getUri()->withQuery(http_build_query($signature->getSignedParams())));
                 break;
         }

src/Client/Credentials/SignatureSecret.php

@@ -16,9 +16,10 @@ class SignatureSecret extends AbstractCredentials implements CredentialsInterfac
      * @param string $key    API Key
      * @param string $signature_secret Signature Secret
      */
-    public function __construct($key, $signature_secret)
+    public function __construct($key, $signature_secret, $method='md5hash')
     {
         $this->credentials['api_key'] = $key;
         $this->credentials['signature_secret'] = $signature_secret;
+        $this->credentials['signature_method'] = $method;
     }
 }

src/Client/Signature.php

@@ -8,6 +8,8 @@
 
 namespace Nexmo\Client;
 
+use Nexmo\Client\Exception\Exception;
+
 class Signature
 {
     /**
@@ -28,7 +30,7 @@ class Signature
      * @param array $params
      * @param $secret
      */
-    public function __construct(array $params, $secret)
+    public function __construct(array $params, $secret, $signatureMethod)
     {
         $this->params = $params;
         $this->signed = $params;
@@ -51,11 +53,25 @@ public function __construct(array $params, $secret)
         //create base string
         $base = '&'.urldecode(http_build_query($signed));
 
-        //append the secret
-        $base .= $secret;
+        $this->signed['sig'] = $this->sign($signatureMethod, $base, $secret);
+    }
 
-        //create hash
-        $this->signed['sig'] = md5($base);
+    protected function sign($signatureMethod, $data, $secret) {
+       switch($signatureMethod) {
+            case 'md5hash':
+                // md5hash needs the secret appended
+                $data .= $secret;
+                return md5($data);
+                break;
+            case 'md5':
+            case 'sha1':
+            case 'sha256':
+            case 'sha512':
+                return hash_hmac($signatureMethod, $data, $secret);
+                break;
+            default:
+                throw new Exception('Unknown signature algorithm: '.$signatureMethod.'. Expected: md5hash, md5, sha1, sha256, or sha512');
+        }
     }
 
     /**
@@ -117,4 +133,4 @@ public function __toString()
     {
         return $this->getSignature();
     }
-}
+}

test/Client/SignatureTest.php

@@ -10,10 +10,46 @@
 
 use Nexmo\Client\Signature;
 use PHPUnit\Framework\TestCase;
+use Nexmo\Client\Exception\Exception;
 
 
 class SignatureTest extends TestCase
 {
+    public function testInvalidSignatureMethod() {
+        $this->expectException(Exception::class);
+        $this->expectExceptionMessage('Unknown signature algorithm: fake_algo. Expected: md5hash, md5, sha1, sha256, or sha512');
+        $signature = new Signature(['foo' => 'bar'], 'sig_secret', 'fake_algo');
+    }
+
+    /**
+     * @dataProvider hmacSignatureProvider
+     */
+    public function testHmacSignature($algorithm, $expected){
+        $data = [
+            'api_key' => 'fake_api_key',
+            'to' => '14155550100',
+            'from' => 'AcmeInc',
+            'text' => 'Test From Nexmo',
+            'type' => 'text',
+            'timestamp' => '1540924779'
+        ];
+        $secret = '71efab63122f1d179f51c46bac838fb5';
+        $signature = new Signature($data, $secret, $algorithm);
+
+        $this->assertEquals($expected, $signature->getSignature());
+    }
+
+    public function hmacSignatureProvider() {
+        $data = [];
+
+        $data['md5'] = ['md5', '51cdafebb4bbce9525b195c1617cb8d2'];
+        $data['sha1'] = ['sha1', '0162aec64bc183b2e1256545951fe5639dc98020'];
+        $data['sha256'] = ['sha256', '9fec5ef6d0f2b3d2bb7558b6e4042569823cab9ea0dd30503472b7b304601975'];
+        $data['sha512'] = ['sha512', '40bd12b9a4b6000ad1138eefd24ffe9fbd72aee13c3fa04b32bb69dbc256ad0a04a463b1a9af6660d10f6e1e769ee14b9cff6a635502e93afcd0bfab29f38f87'];
+
+        return $data;
+    }
+
     /**
      * @dataProvider signatures
      * @param $sig
@@ -23,7 +59,7 @@ class SignatureTest extends TestCase
     public function testSignature($sig, $params, $secret)
     {
         //a signature is created from a set of parameters and a secret
-        $signature = new Signature($params, $secret);
+        $signature = new Signature($params, $secret, 'md5hash');
 
         //the parameters should ne be changed
         $this->assertEquals($params, $signature->getParams());

test/ClientTest.php

@@ -569,7 +569,7 @@ public static function assertValidSignature($array, $secret)
         self::assertArrayHasKey('api_key', $array);
 
         //params should be correctly signed
-        $signature = new Signature($array, $secret);
+        $signature = new Signature($array, $secret, 'md5hash');
         self::assertTrue($signature->check($array));
     }
 }