Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dsentker/url-signature
Build urls with a hash signature to prevent the modification of URL parts.
https://github.com/dsentker/url-signature
hash-based-signatures url-protection url-signature
Last synced: 18 days ago
JSON representation
Build urls with a hash signature to prevent the modification of URL parts.
- Host: GitHub
- URL: https://github.com/dsentker/url-signature
- Owner: dsentker
- License: other
- Created: 2019-02-22T21:56:20.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-01-26T10:07:31.000Z (almost 2 years ago)
- Last Synced: 2024-10-08T13:31:49.079Z (about 1 month ago)
- Topics: hash-based-signatures, url-protection, url-signature
- Language: PHP
- Homepage:
- Size: 112 KB
- Stars: 18
- Watchers: 3
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
## UrlSignature
**Create URLs with a signature to prevent modification**
[](https://travis-ci.org/dsentker/url-signature)
This small PHP >7.2.0 library allows developers to build urls with a hash to prevent the modification of URL parts.
## Why?
A common attack method that pentesters and actual attackers will use is to capture a URL with "id" values in it (like `/user/view?id=1234`) and manually change this value to try to bypass authorization checks. While an application should always have some kind of auth check when the URL is called, there's another step that can help to prevent URL changes: a signature value.
This signature value is built using the contents of the current URL along with a "secret" value unique to the application. This signature is then appended to the URL and can be used directly in links. When the URL is used and the request is received, the signature is then checked against the current URL values. If there's no match, the check fails.
## Installation
Installing via [Composer](https://getcomposer.org) is simple:
`composer require dsentker/url-signature`
If you do not like composer, you can download this repository and use any PSR-4-Autoloader to get everything loaded.
There is also [a **Symfony bundle**](https://github.com/dsentker/url-signature-bundle/) available:
`composer require dsentker/url-signature-bundle`
## Usage
To sign (or validate) URLs, a key is required (which is of course secret). The key is used to hash special parts* of the URL and attach them as a signature in the query string of the URL.
_*) You can decide for yourself which parts of the URL should be hashed._
Later, on validation, the same key is used to hash the current URL. This hash is compared with the hash in query string.
### Signing URLs
```php
signUrl('https://example.com/foo?bar=42'); // http://example.com?foo?bar=42&_signature=90b7ac1...
```
In this example we've created a new `Builder` instance with a configuration object, and using it to create the URL based on the data and URL provided. The `$url` result has the signature (the hash) value appended to the query string.
### Verifying URLs
The other half of the equation is the verification of a URL. The library provides a `Validator` class to help with that. The validator must be initiated with the same configuration as the builder. Otherwise different hash values would be calculated.
```php
isValid('https://example.com/foo?bar=42&_signature=90b7ac1...')); // returns true or false, depending on the signature
// If you want to catch Exceptions to determine the cause of an invalid URL, use Validator::verify() instead
$validator->verify('http://example.com?foo=this+is+a+test&_signature=90b7ac1...'); // Returns true or a \UrlSignature\Exception\ValidationException.
```
`Validator::isValid($url)` returns a boolean value based on the validation result, nothing more.
`Validator::verify($url)` Will throw some of these exceptions if the url signature (or the expiration parameter) is not valid:
* ValidationException
* SignatureNotFoundException (if not present in query string)
* SignatureInvalidException (if present, but empty or invalid)
* SignatureExpiredException (if the expiration parameter has expired, never thrown if expiration was not part of the signature)
### Expiring URLs
The library also provides the ability to create URLs that will fail validation because they've expired. To make use of this, simply pass in a second parameter for the `signUrl()` method call. This value should either be a relative string (parsable by PHPs [strtotime](https://php.net/strtotime)) or a \DateTime object:
```php
signUrl('http://example.com/foo?bar=42', '+10 minutes'); // https://example.com?foo=bar&_expires=1521661473&_signature=009e2d70...
```
You'll notice the addition of a new URL parameter, the `_expires` value. This value is automatically read when the `validate` call is made to ensure the URL hasn't timed out. If it has, even if the rest of the data is correct, the result will be `false`.
Even if the attacker tries to update the `_expires` date to extend the length of the URL, the validation will fail as that's not the `_expires` value it was originally hashed with.
### Advanced Configuration
#### Rename query parameter
The URL query keys "_expires" and "_signature" can be modified with the configuration object:
```php
signUrl('https://example.com/?id=1234', new \DateTime('MONDAY NEXT WEEK'));
var_dump($hashedUrl); // https://example.com/?id=1234&ttl=123456789&_hash=009e2d70...
```
#### Control what parts of URL to sign
Per default, the following parts of the URL are considered for hash generation:
* Host (example.com)
* Path (/foo/bar)
* Query String (?qux=baz)
The configuration allows to modify these components with Bitmask Contants. Use `HashConfiguration::setHashMask()` to pass the Flags (use the pipe | to join flags).
For example, consider to add the URL scheme to the hashing process. That means that the validation of an URL fails only if the protocols (https <-> http) has changed.
```php
setHashMask(
HashConfiguration::FLAG_HASH_SCHEME
| HashConfiguration::FLAG_HASH_HOST
| HashConfiguration::FLAG_HASH_PORT
| HashConfiguration::FLAG_HASH_PATH
| HashConfiguration::FLAG_HASH_QUERY
| HashConfiguration::FLAG_HASH_FRAGMENT
);
```
## Limitations and Security notes ##
This library creates a hash from one or more URL parts. That means, that the URL is only valid if the given signature matches the current signature. Like any other hash event (for example, hashing passwords), this is considered quite secure. For a signed URL to be truly secure, the developer must ensure that (when receiving a request) a check is made as to whether a hash check is required and / or whether the submitted signature is correct. In other words, **if the user has the ability to retrieve a URL without a signature, the best hashing algorithm will not work**.
### Do NOT use this library if... ###
* ...you are not 100% sure whether the processing part of the request (e.g., the controller) can check the hash at any time.
* ...your goal is to prevent the distribution of URLs to unauthorized persons (that is not the purpose of this library!)
* ...this library is the only auditing mechanism designed to prevent a user from retrieving content that is not intended for them.
* ...you want to validate an hash URI hash where the URI contains arrays in query string (see [issue #3](https://github.com/dsentker/url-signature/issues/3))
## Credits
Based on the ideas by [psecio](https://github.com/psecio), the project was forked by [me](https://github.com/dsentker) to upgrade the code for PHP 7.x applications. The adjustments then resulted in a separate library (this one) and a symfony bundle.
## Dependencies
The library uses the URL functions of [thephpleague/uri](https://github.com/thephpleague/uri) to parse, extract and (re-)build URL components. For unit tests, PhpUnit is used.
## I look forward to your help!
If you notice bugs, have general questions or want to implement a feature, you are welcome to collaborate.
### Roadmap
- Drop support for PHP 7.2
- Refactor the hash process, provide a solution for issue #3
### Submitting bugs and feature requests
Bugs and feature request are tracked on GitHub.
## Symfony 4/5 Bundle
I also created [a bundle for Symfony](https://github.com/dsentker/url-signature-bundle/) (with twig support and annotations).
## Testing
`./vendor/bin/phpunit`
Do not be surprised about a short break of two seconds during the tests. A `sleep(2)` was built in to test for the validation of the timeout functionality.
## See also
* [URL Signature Bundle](https://github.com/dsentker/url-signature-bundle/) for Symfony 4
* [ivanakimov/hashids](https://github.com/ivanakimov/hashids.php) A PHP Version from [hashids.org](https://hashids.org/)
* [HashidsBundle](https://github.com/roukmoute/HashidsBundle) The relating Symfony Bundle from _roukmoute_