Typhoon Url Signer is a package that signs and validates URLs with ease. You can make secure URLs for your files and any kind of URLs that you want so that no one can access them without permission. You can make URLs with a limited lifetime to make them expire.
You can use this package both standalone and with your Laravel application
Features
$ composer require salibhdr/typhoon-url-signer
You are ready to use the package and no other configuration needed.
Register the UrlSignerServiceProvider
in your config/app.php configuration file:
'providers' => [
// Other service providers...
SaliBhdr\UrlSigner\Laravel\ServiceProviders\UrlSignerServiceProvider::class,
],
Run vendor:publish
command:
php artisan vendor:publish --provider="SaliBhdr\UrlSigner\Laravel\ServiceProviders\UrlSignerServiceProvider"
It will generate the urlSigner.php
under config directory.
Copy URL_SIGN_KEY
to your env:
URL_SIGN_KEY=
Run the urlSigner:generate
command to generate a signKey:
php artisan urlSigner:generate
It will generate the a sign key in .env
file.
Register The the UrlSignerServiceProvider
In bootstrap/app.php:
$app->register(SaliBhdr\UrlSigner\Laravel\ServiceProviders\UrlSignerServiceProvider::class);
Copy the package config file to config directory (you may need to create one):
Copy URL_SIGN_KEY
to your env:
URL_SIGN_KEY=
Run the urlSigner:generate
command to generate a signKey:
php artisan urlSigner:generate
It will generate the a sign key in .env
file.
You have 3 options to sign urls:
All of 3 signers above has implemented form SaliBhdr\UrlSigner\UrlSignerInterface
and has 3 methods:
All 3 methods sign method take 2 parameters as input.The $url parameter and $params. you can pass only url with query string attach to it:
<?php
$url = 'www.example.com/api/v1/book?timestamp=153664546&id=2';
$signedUrl = $urlSigner->create($url);
Or you can pass url and query separately :
<?php
$url = 'www.example.com/api/v1/book';
$params = [
'timestamp' => '153664546',
'id' => 2
];
$signedUrl = $urlSigner->create($url,$params);
So keep this in mind in all 3 methods.
Feel free to make your own signer by implementing UrlSignerInterface
.
The url signer default ttl is 7200 seconds (2 hours). Pass null to ttl so that the url's will not expire at all.
Make instance of Md5UrlSigner
:
<?php
use SaliBhdr\UrlSigner\Md5UrlSigner;
//your sign key
$signKey = 'EKtF4lFP6D1FjBGtSRIk1gGn2YCRmtGPocBWV39wAeM=';
// default ttl is 7200 seconds
// pass null to make url's without expire time
$ttl = 7200;
$urlSigner = new Md5UrlSigner($signKey,$ttl);
Make instance of HmacUrlSigner
:
<?php
use SaliBhdr\UrlSigner\HmacUrlSigner;
//your sign key
$signKey = 'EKtF4lFP6D1FjBGtSRIk1gGn2YCRmtGPocBWV39wAeM=';
$algorithm = 'sha1';
// default ttl is 7200 seconds
// pass null to make url's without expire time
$ttl = 7200;
$urlSigner = new HmacUrlSigner($signKey,$algorithm,$ttl);
The HmacUrlSigner gets algorithm through second parameter.
Default hashing algorithm is sha256
. Pass second
parameter if you want to pass another algorithm other than sha256
.
You can see list of all available algorithms here
The url signer ecosystem is working based on 3 main class:
So by the description above you must define all 3 to make the base url signer work.
This way you are free to use any signer and signature to make urls as long
as implement SignerInterface
for the signer and SignatureInterface
for the
signature.
First make a signer
You can use one of 3 signers built in this package.
use SaliBhdr\UrlSigner\Signers\Md5; use SaliBhdr\UrlSigner\Signers\Hmac; use SaliBhdr\UrlSigner\Signers\Rsa; use phpseclib\Crypt\RSA as BaseRSA;
//-------------Md5 signer example------------- //your sign key $signKey = 'EKtF4lFP6D1FjBGtSRIk1gGn2YCRmtGPocBWV39wAeM=';
$signer = new Md5($signKey);
//-------------Hmac signer example------------
$signer = new Hmac($signKey);
//-------------Rsa signer example-------------
/* Rsa needs 2 extra parameters
*/ $algorithm = 'sha1'; // default is sha256 $signMode = BaseRSA::SIGNATURE_PKCS1;
$signer = new Rsa($algorithm,$signMode);
$signer->setPublicKey('----RSA PUBLIC KEY HERE----'); $signer->setPrivateKey('----RSA PRIVATE KEY HERE----');
Second make a **signature** and path the signer:
```php
<?php
use SaliBhdr\UrlSigner\Signatures\Signature;
// default ttl is 7200 seconds
// pass null to make url's without expire time
$ttl = 7200;
$signature = new Signature($signer,$ttl);
Third and final step make UrlSigner and path the signature:
<?php
use SaliBhdr\UrlSigner\UrlSigner;
$urlSigner = new UrlSigner($signature);
Now you can use the url signer:
Creating signed url:
<?php
$url = 'www.example.com/api/v1/book';
$params = [
'timestamp' => '153664546',
'id' => 2
];
$signedUrl = $urlSigner->create($url,$params);
Validate signed url:
<?php
// throws exception
$urlSigner->validate($signedUrl);
// returns true/false
echo $urlSigner->isValid($signedUrl) ? 'valid' : 'notValid';
The validate() method will throw one these 2 errors:
sg
parameter in itsg
parameter is not a valid onets
parameter in itNote 1: If you want to handle exceptions, All exceptions are extended from UrlSignerException
Note 2: The Url expiration and missing timestamp exception are throw when you define a ttl (time to live)
Notice: Please read Standalone section above for read the details about methods.
The url signer default ttl is 7200 seconds (2 hours). Set null to ttl in config so that the url's will not expire at all.
You can use UrlSigner
facade to sign and validate urls.
<?php
use UrlSigner;
$url = 'www.example.com/api/v1/book?timestamp=153664546&id=2';
$signedUrl = UrlSigner::create($url);
Or you can pass url and query separately :
<?php
use SaliBhdr\UrlSigner\Laravel\Facades\UrlSigner;
$url = 'www.example.com/api/v1/book';
$params = [
'timestamp' => '153664546',
'id' => 2
];
$signedUrl = UrlSigner::create($url, $params);
To validate url's :
<?php
//throws exception
UrlSigner::validate($signedUrl);
// returns true/false
echo UrlSigner::isValid($signedUrl) ? 'valid':'notValid';
You can report issues in github repository here
Typhoon-Url-Signer is released under the MIT License.
Built with ❤ for you.
Free Software, Hell Yeah!
Contributions, useful comments, and feedback are most welcome!
Fearless refactoring, it does a lot of smart checks to find certain errors.
Repository for Website Programming Tasks
A new experience in Laravel LMS followed by gamification, onboarding, marketing and course management
Spatial Map Fields for Laravel Nova
Adds a beautiful WhatsApp Sticky Button on the WordPress frontend
RTL layout for Laravel Nova.
PHP library for ArCaptcha