Verify message signatures (#154)

The code was already in the codebase but needed a tiny tweak and some documentation so people can find it. Fixes #90

Author: lornajane

README.md

@@ -167,6 +167,8 @@ echo "The body of the message was: " . $message->getBody();
 
 ### Signing a Message
 
+_You may also like to read the [documentation about message signing](https://developer.nexmo.com/concepts/guides/signing-messages)._
+
 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`
@@ -180,11 +182,26 @@ Both your application and Nexmo need to agree on which algorithm is used. In the
 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'));
+$client = new Nexmo\Client(new Nexmo\Client\Credentials\SignatureSecret(API_KEY, SIGNATURE_SECRET, 'sha256'));
 ```
 
 Using this client, your SMS API messages will be sent as signed messages.
 
+### Verifying an Incoming Message Signature
+
+_You may also like to read the [documentation about message signing](https://developer.nexmo.com/concepts/guides/signing-messages)._
+
+If you have message signing enabled for incoming messages, the SMS webhook will include the fields `sig`, `nonce` and `timestamp`. To verify the signature is from Nexmo, you create a Signature object using the incoming data, your signature secret and the signature method. Then use the `check()` method with the actual signature that was received (usually `_GET['sig']`) to make sure that it is correct.
+
+```php
+$signature = new \Nexmo\Client\Signature($_GET, SIGNATURE_SECRET, 'sha256');
+
+// is it valid? Will be true or false
+$isValid = $signature->check($_GET['sig']);
+```
+
+Using your signature secret and the other supplied parameters, the signature can be calculated and checked against the incoming signature value.
+
 ### 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/Signature.php

@@ -67,7 +67,7 @@ protected function sign($signatureMethod, $data, $secret) {
             case 'sha1':
             case 'sha256':
             case 'sha512':
-                return hash_hmac($signatureMethod, $data, $secret);
+                return strtoupper(hash_hmac($signatureMethod, $data, $secret));
                 break;
             default:
                 throw new Exception('Unknown signature algorithm: '.$signatureMethod.'. Expected: md5hash, md5, sha1, sha256, or sha512');
@@ -107,7 +107,12 @@ public function getSignedParams()
     /**
      * Check that a signature (or set of parameters) is valid.
      *
-     * @param array| string $signature
+     * First instantiate a Signature object: this will drop any supplied
+     * signature parameter and calculate the correct one. Then call this
+     * method and supply the signature that came in with the request.
+     *
+     * @param array| string $signature The incoming sig parameter to check 
+     *      (or all incoming params)
      * @return bool
      * @throws \InvalidArgumentException
      */
@@ -121,7 +126,7 @@ public function check($signature)
             throw new \InvalidArgumentException('signature must be string, or present in array or parameters');
         }
 
-        return $signature == $this->signed['sig'];
+        return strtolower($signature) == strtolower($this->signed['sig']);
     }
 
     /**

test/Client/SignatureTest.php

@@ -42,10 +42,10 @@ public function testHmacSignature($algorithm, $expected){
     public function hmacSignatureProvider() {
         $data = [];
 
-        $data['md5'] = ['md5', '51cdafebb4bbce9525b195c1617cb8d2'];
-        $data['sha1'] = ['sha1', '0162aec64bc183b2e1256545951fe5639dc98020'];
-        $data['sha256'] = ['sha256', '9fec5ef6d0f2b3d2bb7558b6e4042569823cab9ea0dd30503472b7b304601975'];
-        $data['sha512'] = ['sha512', '40bd12b9a4b6000ad1138eefd24ffe9fbd72aee13c3fa04b32bb69dbc256ad0a04a463b1a9af6660d10f6e1e769ee14b9cff6a635502e93afcd0bfab29f38f87'];
+        $data['md5'] = ['md5', '51CDAFEBB4BBCE9525B195C1617CB8D2'];
+        $data['sha1'] = ['sha1', '0162AEC64BC183B2E1256545951FE5639DC98020'];
+        $data['sha256'] = ['sha256', '9FEC5EF6D0F2B3D2BB7558B6E4042569823CAB9EA0DD30503472B7B304601975'];
+        $data['sha512'] = ['sha512', '40BD12B9A4B6000AD1138EEFD24FFE9FBD72AEE13C3FA04B32BB69DBC256AD0A04A463B1A9AF6660D10F6E1E769EE14B9CFF6A635502E93AFCD0BFAB29F38F87'];
 
         return $data;
     }