├── .gitignore ├── .scrutinizer.yml ├── .travis.yml ├── CHANGELOG.md ├── LICENSE ├── README.md ├── composer.json ├── phpunit.xml ├── src ├── Auth.php ├── Exceptions │ ├── SignatureException.php │ ├── SignatureKeyException.php │ ├── SignatureSignatureException.php │ ├── SignatureTimestampException.php │ └── SignatureVersionException.php ├── Guards │ ├── CheckKey.php │ ├── CheckSignature.php │ ├── CheckTimestamp.php │ ├── CheckVersion.php │ └── Guard.php ├── Request.php └── Token.php └── tests ├── AuthTest.php ├── Guards ├── CheckKeyTest.php ├── CheckSignatureTest.php ├── CheckTimestampTest.php └── CheckVersionTest.php ├── RequestTest.php └── TokenTest.php /.gitignore: -------------------------------------------------------------------------------- 1 | /vendor 2 | composer.phar 3 | composer.lock 4 | .DS_Store 5 | -------------------------------------------------------------------------------- /.scrutinizer.yml: -------------------------------------------------------------------------------- 1 | filter: 2 | paths: [src/*] 3 | excluded_paths: [vendor/*, tests/*] 4 | before_commands: 5 | - 'composer install --dev --prefer-source' 6 | tools: 7 | external_code_coverage: true 8 | php_mess_detector: true 9 | php_code_sniffer: true 10 | sensiolabs_security_checker: true 11 | php_code_coverage: true 12 | php_pdepend: true 13 | php_loc: 14 | enabled: true 15 | excluded_dirs: [vendor, tests] 16 | php_cpd: 17 | enabled: true 18 | excluded_dirs: [vendor, tests] 19 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: php 2 | 3 | php: 4 | - 5.4 5 | - 5.5 6 | - 5.6 7 | - 7.0 8 | - hhvm 9 | 10 | matrix: 11 | allow_failures: 12 | - php: 7.0 13 | 14 | before_script: 15 | - travis_retry composer self-update 16 | - travis_retry composer install --no-interaction --prefer-source --dev 17 | 18 | script: 19 | - phpunit --coverage-clover=coverage.clover 20 | 21 | after_script: 22 | - wget https://scrutinizer-ci.com/ocular.phar 23 | - php ocular.phar code-coverage:upload --format=php-clover coverage.clover 24 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # CHANGELOG 2 | 3 | ## 5.1.2 4 | 5 | * Set the value of `array_change_key_case` 6 | * Set default value for request params to empty array 7 | 8 | ## 5.1.0 9 | 10 | * Add the ability to use your own prefix for instead of `auth_*`. The default is still `auth_*` so no BC breaks are introduced. 11 | 12 | ## 5.0.0 13 | 14 | * `Request::payload()` and `Request::signature()` methods are now private. The `Request::sign()` method should be used instead. 15 | 16 | ## 4.0.0 17 | 18 | * Fixes a security flaw due to not including `auth_*` fields in the signature payload. 19 | 20 | ## 3.0.3 21 | 22 | * Fixed a bug where the `CheckTimestamp` guard would only protect against request timestamps in the past. 23 | 24 | ## 3.0.2 25 | 26 | ## 3.0.1 27 | 28 | ## 3.0.0 29 | 30 | ## 2.0.0 31 | 32 | ## 1.0.1 33 | 34 | ## 1.0.0 35 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2014 Philip Brown 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of 6 | this software and associated documentation files (the "Software"), to deal in 7 | the Software without restriction, including without limitation the rights to 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 9 | the Software, and to permit persons to whom the Software is furnished to do so, 10 | subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Signature 2 | 3 | **A PHP 5.4+ port of the [Signature](https://github.com/mloughran/signature) ruby gem** 4 | 5 | [![Build Status](https://travis-ci.org/philipbrown/signature-php.png?branch=master)](https://travis-ci.org/philipbrown/signature-php) 6 | [![Code Coverage](https://scrutinizer-ci.com/g/philipbrown/signature-php/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/philipbrown/signature-php/?branch=master) 7 | [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/philipbrown/signature-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/philipbrown/signature-php/?branch=master) 8 | 9 | ## Installation 10 | Add `philipbrown/signature-php` as a requirement to `composer.json`: 11 | ```bash 12 | $ composer require philipbrown/signature-php 13 | ``` 14 | 15 | ## What is HMAC-SHA authentication? 16 | HMAC-SHA authentication allows you to implement very simple key / secret authentication for your API using hashed signatures. 17 | 18 | ## Making a request 19 | ```php 20 | use PhilipBrown\Signature\Token; 21 | use PhilipBrown\Signature\Request; 22 | 23 | $data = ['name' => 'Philip Brown']; 24 | $token = new Token('abc123', 'qwerty'); 25 | $request = new Request('POST', 'users', $data); 26 | 27 | $auth = $request->sign($token); 28 | 29 | $http->post('users', array_merge($auth, $data)); 30 | 31 | ``` 32 | 33 | ## Authenticating a response 34 | ```php 35 | use PhilipBrown\Signature\Auth; 36 | use PhilipBrown\Signature\Token; 37 | use PhilipBrown\Signature\Guards\CheckKey; 38 | use PhilipBrown\Signature\Guards\CheckVersion; 39 | use PhilipBrown\Signature\Guards\CheckTimestamp; 40 | use PhilipBrown\Signature\Guards\CheckSignature; 41 | use PhilipBrown\Signature\Exceptions\SignatureException; 42 | 43 | $auth = new Auth('POST', 'users', $_POST, [ 44 | new CheckKey, 45 | new CheckVersion, 46 | new CheckTimestamp, 47 | new CheckSignature 48 | ]); 49 | 50 | $token = new Token('abc123', 'qwerty'); 51 | 52 | try { 53 | $auth->attempt($token); 54 | } 55 | 56 | catch (SignatureException $e) { 57 | // return 4xx 58 | } 59 | ``` 60 | 61 | ## Changing the default HTTP request prefix 62 | By default, this package uses `auth_*` in requests. You can change this behaviour when signing and and authenticating requests: 63 | ```php 64 | // default, the HTTP request uses auth_version, auth_key, auth_timestamp and auth_signature 65 | $request->sign($token); 66 | // the HTTP request now uses x-version, x-key, x-timestamp and x-signature 67 | $request->sign($token, 'x-'); 68 | ``` 69 | 70 | If you changed the default, you will need to authenticate the request accordingly: 71 | ```php 72 | $auth->attempt($token, 'x-'); 73 | ``` 74 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "philipbrown/signature-php", 3 | "description": "HMAC-SHA authentication", 4 | "keywords": ["HMAC-SHA", "authentication"], 5 | "license": "MIT", 6 | "authors": [ 7 | { 8 | "name": "Philip Brown", 9 | "email": "phil@ipbrown.com" 10 | } 11 | ], 12 | "autoload": { 13 | "psr-4": { 14 | "PhilipBrown\\Signature\\": "src" 15 | } 16 | }, 17 | "autoload-dev": { 18 | "psr-4": { 19 | "PhilipBrown\\Signature\\Tests\\": "tests" 20 | } 21 | }, 22 | "require": { 23 | "php": ">=5.4" 24 | }, 25 | "require-dev": { 26 | "phpunit/phpunit": "~4.0" 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /phpunit.xml: -------------------------------------------------------------------------------- 1 | 2 | 12 | 13 | 14 | ./tests/ 15 | 16 | 17 | 18 | -------------------------------------------------------------------------------- /src/Auth.php: -------------------------------------------------------------------------------- 1 | method = strtoupper($method); 42 | $this->uri = $uri; 43 | $this->params = $params; 44 | $this->guards = $guards; 45 | } 46 | 47 | /** 48 | * Attempt to authenticate a request 49 | * 50 | * @param Token $token 51 | * @param string $prefix 52 | * @return bool 53 | */ 54 | public function attempt(Token $token, $prefix = Request::PREFIX) 55 | { 56 | $auth = $this->getAuthParams($prefix); 57 | $body = $this->getBodyParams($prefix); 58 | 59 | $request = new Request($this->method, $this->uri, $body, $auth[$prefix . 'timestamp']); 60 | $signature = $request->sign($token, $prefix); 61 | 62 | foreach ($this->guards as $guard) { 63 | $guard->check($auth, $signature, $prefix); 64 | } 65 | 66 | return true; 67 | } 68 | 69 | /** 70 | * Get the auth params 71 | * 72 | * @param $prefix 73 | * @return array 74 | */ 75 | private function getAuthParams($prefix) 76 | { 77 | return array_intersect_key($this->params, array_flip($this->addPrefix($this->auth, $prefix))); 78 | } 79 | 80 | /** 81 | * Get the body params 82 | * 83 | * @param $prefix 84 | * @return array 85 | */ 86 | private function getBodyParams($prefix) 87 | { 88 | return array_diff_key($this->params, array_flip($this->addPrefix($this->auth, $prefix))); 89 | } 90 | 91 | /** 92 | * @param array $auth 93 | * @param $prefix 94 | * 95 | * @return array 96 | */ 97 | private function addPrefix(array $auth, $prefix) 98 | { 99 | return array_map(function ($item) use ($prefix) { 100 | return $prefix . $item; 101 | }, $auth); 102 | } 103 | } 104 | -------------------------------------------------------------------------------- /src/Exceptions/SignatureException.php: -------------------------------------------------------------------------------- 1 | grace = $grace; 21 | } 22 | 23 | /** 24 | * Check to ensure the auth parameters 25 | * satisfy the rule of the guard 26 | * 27 | * @param array $auth 28 | * @param array $signature 29 | * @param string $prefix 30 | * @throws SignatureTimestampException 31 | * @return bool 32 | */ 33 | public function check(array $auth, array $signature, $prefix) 34 | { 35 | if (! isset($auth[$prefix . 'timestamp'])) { 36 | throw new SignatureTimestampException('The timestamp has not been set'); 37 | } 38 | 39 | if (abs($auth[$prefix . 'timestamp'] - time()) >= $this->grace) { 40 | throw new SignatureTimestampException('The timestamp is invalid'); 41 | } 42 | 43 | return true; 44 | } 45 | } 46 | -------------------------------------------------------------------------------- /src/Guards/CheckVersion.php: -------------------------------------------------------------------------------- 1 | method = strtoupper($method); 40 | $this->uri = $uri; 41 | $this->params = $params; 42 | $this->timestamp = $timestamp ?: time(); 43 | } 44 | 45 | /** 46 | * Sign the Request with a Token 47 | * 48 | * @param Token $token 49 | * @param string $prefix 50 | * @return array 51 | */ 52 | public function sign(Token $token, $prefix = self::PREFIX) 53 | { 54 | $auth = [ 55 | $prefix . 'version' => self::VERSION, 56 | $prefix . 'key' => $token->key(), 57 | $prefix . 'timestamp' => $this->timestamp, 58 | ]; 59 | 60 | $payload = $this->payload($auth, $this->params); 61 | 62 | $signature = $this->signature($payload, $this->method, $this->uri, $token->secret()); 63 | 64 | $auth[$prefix . 'signature'] = $signature; 65 | 66 | return $auth; 67 | } 68 | 69 | /** 70 | * Create the payload 71 | * 72 | * @param array $auth 73 | * @param array $params 74 | * @return array 75 | */ 76 | private function payload(array $auth, array $params) 77 | { 78 | $payload = array_merge($auth, $params); 79 | $payload = array_change_key_case($payload, CASE_LOWER); 80 | 81 | ksort($payload); 82 | 83 | return $payload; 84 | } 85 | 86 | /** 87 | * Create the signature 88 | * 89 | * @param array $payload 90 | * @param string $method 91 | * @param string $uri 92 | * @param string $secret 93 | * @return string 94 | */ 95 | private function signature(array $payload, $method, $uri, $secret) 96 | { 97 | $payload = urldecode(http_build_query($payload)); 98 | 99 | $payload = implode("\n", [$method, $uri, $payload]); 100 | 101 | return hash_hmac('sha256', $payload, $secret); 102 | } 103 | } 104 | -------------------------------------------------------------------------------- /src/Token.php: -------------------------------------------------------------------------------- 1 | key = $key; 25 | $this->secret = $secret; 26 | } 27 | 28 | /** 29 | * Get the key 30 | * 31 | * @return string 32 | */ 33 | public function key() 34 | { 35 | return $this->key; 36 | } 37 | 38 | /** 39 | * Get the secret 40 | * 41 | * @return string 42 | */ 43 | public function secret() 44 | { 45 | return $this->secret; 46 | } 47 | } 48 | -------------------------------------------------------------------------------- /tests/AuthTest.php: -------------------------------------------------------------------------------- 1 | 'Philip Brown']; 16 | $this->token = new Token('abc123', 'qwerty'); 17 | 18 | $request = new Request('POST', 'users', $params); 19 | $signed = $request->sign($this->token); 20 | 21 | $this->params = array_merge($params, $signed); 22 | } 23 | 24 | /** @test */ 25 | public function should_throw_exception_on_invalid_version() 26 | { 27 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureVersionException'); 28 | 29 | $this->params['auth_version'] = '2.0'; 30 | 31 | $auth = new Auth('POST', 'users', $this->params, [ 32 | new CheckVersion 33 | ]); 34 | 35 | $auth->attempt($this->token); 36 | } 37 | 38 | /** @test */ 39 | public function should_throw_exception_on_invalid_key() 40 | { 41 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureKeyException'); 42 | 43 | $this->params['auth_key'] = 'edf456'; 44 | 45 | $auth = new Auth('POST', 'users', $this->params, [ 46 | new CheckKey 47 | ]); 48 | 49 | $auth->attempt($this->token); 50 | } 51 | 52 | /** @test */ 53 | public function should_throw_exception_on_invalid_timestamp() 54 | { 55 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureTimestampException'); 56 | 57 | $this->params['auth_timestamp'] = time() + 60 * 60; 58 | 59 | $auth = new Auth('POST', 'users', $this->params, [ 60 | new CheckTimestamp 61 | ]); 62 | 63 | $auth->attempt($this->token); 64 | } 65 | 66 | /** @test */ 67 | public function should_throw_exception_on_invalid_signature() 68 | { 69 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureSignatureException'); 70 | 71 | $this->params['auth_signature'] = ''; 72 | 73 | $auth = new Auth('POST', 'users', $this->params, [ 74 | new CheckSignature 75 | ]); 76 | 77 | $auth->attempt($this->token); 78 | } 79 | 80 | /** @test */ 81 | public function should_return_true_on_successful_authentication() 82 | { 83 | $auth = new Auth('POST', 'users', $this->params, [ 84 | new CheckKey, 85 | new CheckVersion, 86 | new CheckTimestamp, 87 | new CheckSignature 88 | ]); 89 | 90 | $this->assertTrue($auth->attempt($this->token)); 91 | } 92 | 93 | /** @test */ 94 | public function should_return_true_on_successful_attempt_with_custom_prefix() 95 | { 96 | $params = ['name' => 'Philip Brown']; 97 | $token = new Token('abc123', 'qwerty'); 98 | $request = new Request('POST', 'users', $params); 99 | $signed = $request->sign($token, 'x-'); 100 | $params = array_merge($params, $signed); 101 | 102 | $token = new Token('abc123', 'qwerty'); 103 | 104 | $auth = new Auth('POST', 'users', $params, [ 105 | new CheckKey, 106 | new CheckVersion, 107 | new CheckTimestamp, 108 | new CheckSignature 109 | ]); 110 | 111 | $this->assertTrue($auth->attempt($token, 'x-')); 112 | } 113 | } 114 | -------------------------------------------------------------------------------- /tests/Guards/CheckKeyTest.php: -------------------------------------------------------------------------------- 1 | guard = new CheckKey; 13 | } 14 | 15 | /** @test */ 16 | public function should_throw_exception_on_missing_key() 17 | { 18 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureKeyException'); 19 | 20 | $this->guard->check([], ['auth_key' => 'abc123'], 'auth_'); 21 | } 22 | 23 | /** @test */ 24 | public function should_throw_exception_on_invalid_key() 25 | { 26 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureKeyException'); 27 | 28 | $this->guard->check(['auth_key' => 'edf456'], ['auth_key' => 'abc123'], 'auth_'); 29 | } 30 | 31 | /** @test */ 32 | public function should_return_true_with_valid_key() 33 | { 34 | $this->assertTrue($this->guard->check( 35 | ['auth_key' => 'abc123'], ['auth_key' => 'abc123'], 'auth_' 36 | )); 37 | } 38 | } 39 | -------------------------------------------------------------------------------- /tests/Guards/CheckSignatureTest.php: -------------------------------------------------------------------------------- 1 | guard = new CheckSignature; 13 | } 14 | 15 | /** @test */ 16 | public function should_throw_exception_on_missing_signature() 17 | { 18 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureSignatureException'); 19 | 20 | $this->guard->check([], [], 'auth_'); 21 | } 22 | 23 | /** @test */ 24 | public function should_throw_exception_on_invalid_hash() 25 | { 26 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureException'); 27 | 28 | $this->guard->check(['auth_signature' => 'hello'], ['auth_signature' => 'world'], 'auth_'); 29 | } 30 | 31 | /** @test */ 32 | public function should_return_true_with_valid_hash() 33 | { 34 | $hash = '74386c24552f7a044bba201b46bd713d40050b9c411d8e7d0aeb98e7e3ed6e83'; 35 | 36 | $this->assertTrue($this->guard->check(['auth_signature' => $hash], ['auth_signature' => $hash], 'auth_')); 37 | } 38 | } 39 | -------------------------------------------------------------------------------- /tests/Guards/CheckTimestampTest.php: -------------------------------------------------------------------------------- 1 | guard = new CheckTimestamp; 13 | } 14 | 15 | /** @test */ 16 | public function should_throw_exception_on_missing_timestamp() 17 | { 18 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureTimestampException'); 19 | 20 | $this->guard->check([], [], 'auth_'); 21 | } 22 | 23 | /** @test */ 24 | public function should_throw_exception_on_expired_timestamp() 25 | { 26 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureTimestampException'); 27 | 28 | $timestamp = time() + 60 * 60; 29 | 30 | $this->guard->check(['auth_timestamp' => $timestamp], [], 'auth_'); 31 | } 32 | 33 | /** @test */ 34 | public function should_throw_exception_on_future_expired_timestamp() 35 | { 36 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureTimestampException'); 37 | 38 | $timestamp = time() - 60 * 60; 39 | 40 | $this->guard->check(['auth_timestamp' => $timestamp], [], 'auth_'); 41 | } 42 | 43 | /** @test */ 44 | public function should_return_true_with_valid_timestamp() 45 | { 46 | $timestamp = time(); 47 | 48 | $this->guard->check(['auth_timestamp' => $timestamp], [], 'auth_'); 49 | } 50 | } 51 | -------------------------------------------------------------------------------- /tests/Guards/CheckVersionTest.php: -------------------------------------------------------------------------------- 1 | guard = new CheckVersion; 13 | } 14 | 15 | /** @test */ 16 | public function should_throw_exception_on_missing_version_number() 17 | { 18 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureVersionException'); 19 | 20 | $this->guard->check([], ['auth_version' => '4.0.0'], 'auth_'); 21 | } 22 | 23 | /** @test */ 24 | public function should_throw_exception_on_invalid_version_number() 25 | { 26 | $this->setExpectedException('PhilipBrown\Signature\Exceptions\SignatureVersionException'); 27 | 28 | $this->guard->check(['auth_version' => '1.1'], ['auth_version' => '4.0.0'], 'auth_'); 29 | } 30 | 31 | /** @test */ 32 | public function should_return_true_with_valid_version_number() 33 | { 34 | $this->assertTrue($this->guard->check(['auth_version' => '4.0.0'], ['auth_version' => '4.0.0'], 'auth_')); 35 | } 36 | } 37 | -------------------------------------------------------------------------------- /tests/RequestTest.php: -------------------------------------------------------------------------------- 1 | 'Philip Brown']; 17 | $this->token = new Token('abc123', 'qwerty'); 18 | $this->request = new Request('POST', 'users', $params, 1412506800); 19 | } 20 | 21 | /** @test */ 22 | public function should_sign_request() 23 | { 24 | $auth = $this->request->sign($this->token); 25 | 26 | $this->assertEquals('5.1.2', $auth['auth_version']); 27 | $this->assertEquals('abc123', $auth['auth_key']); 28 | $this->assertEquals('1412506800', $auth['auth_timestamp']); 29 | $this->assertRegExp('/[a-z0-9]{64}/', $auth['auth_signature']); 30 | } 31 | 32 | /** @test */ 33 | public function should_accept_custom_prefix() 34 | { 35 | $auth = $this->request->sign($this->token, 'x-'); 36 | 37 | $this->assertEquals('5.1.2', $auth['x-version']); 38 | $this->assertEquals('abc123', $auth['x-key']); 39 | $this->assertEquals('1412506800', $auth['x-timestamp']); 40 | $this->assertRegExp('/[a-z0-9]{64}/', $auth['x-signature']); 41 | } 42 | } 43 | -------------------------------------------------------------------------------- /tests/TokenTest.php: -------------------------------------------------------------------------------- 1 | assertInstanceOf('PhilipBrown\Signature\Token', $token); 13 | $this->assertEquals('key', $token->key()); 14 | $this->assertEquals('secret', $token->secret()); 15 | } 16 | } 17 | --------------------------------------------------------------------------------