spiderrobb / signed-request
Simple Class for encoding and decoding SignedRequests that support a number of features and hash algorithms
Requires
- php: >=5.2.0
- ext-json: *
Requires (Dev)
- phpunit/phpunit: ~4.0
This package is not auto-updated.
Last update: 2024-04-13 12:43:20 UTC
README
The SignedRequest class is an easy and feature rich way to encode and decode signed requests. Signed requests are used by companies such as Facebook, Kongregate, and Salesforce to pass data to 3rd party applications in a secure and reliable way.
Note: SignedRequest does not Encrypt your data, it Encodes your data. All data inside a SignedRequest can be read by anyone. SignedRequest's are useful when you want to trust the data.
##Format
A signed request is a concatenation of a HMAC SHA-256 (HMAC SHA-256 by default) signature string, a period (.), and a base64url encoded JSON object. It looks somthing like this (without the newlines).:
vlXgu64BQGFSQrY0ZcJBZASMvYvTHu9GQ0YM9rjPSso
.
eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsIjAiOiJwYXlsb2FkIn0
The Signed request consists of a signature and a payload SIGNATURE.PAYLOAD
##Basic Use
The most basic use of a signed request is to encode the data with a secret, and pass the data through HTTP POST or GET, then decode the signed request using the same secret. The Simplest use is:
// File that is encoding Signed Request // ------------------------------------ // defining secret to encode data with $mySecret = '[My Super Secret String]'; // defining data to encode in signed request // Note: myData does not need to be an array, it can be an Array, String, Boolean... etc. $myData = array( 'dataKey' => 'dataValue' ); $mySR = SignedRequest::encode( $myData, array('secret' => $mySecret) ); // File That is decoding Signed Request // ------------------------------------ // defining secret to decode data with $mySecret = '[My Super Secret String]'; // decoding signed request try { // decoding signed request using same secret $myData = SignedRequest::decode( $mySR, array( 'secret' => $mySecret ) ) print_r($myData); } catch (Exception $e) { // signed request has been malformatted or cannot be trusted var_dump($e); } /* output Array( 'dataKey' => 'dataValue' ) */
##Features
###Support for multiple hash algorithms
Hash algorithms supported include all algorithms in php hash_algos
Example:
$mySecret = '[My super secret secret]'; $myData = array( 'dataKey' => 'dataValue' ); $mySR = SignedRequest::encode( $myData, array( 'secret' => $mySecret, 'algorithm' => 'HMAC-SHA1' // (optional) default: HMAC-SHA256 ) );
To get a list of supported algorithms you can use the function:
$supportedAlgorithms = SignedRequest::getAlgorithms();
###Expiration Date
The ability to specify a specific date for the signed request to expire. (unix time stamp format)
Example:
$mySecret = '[My super secret secret]'; $myData = array( 'dataKey' => 'dataValue' ); $mySR = SignedRequest::encode( $myData, array( 'secret' => $mySecret, 'expires' => strtotime('2015-01-01 01:00:00') ) );
###Time to Expire
The ability to specify an amount of time (in seconds) until the signed requests expires.
Example:
$mySecret = '[My super secret secret]'; $myData = array( 'dataKey' => 'dataValue' ); $mySR = SignedRequest::encode( $myData, array( 'secret' => $mySecret, 'timeout' => 3600 // signed request will expire in 1 hour ) );
###Method Validation
Using best practice the same secret should not be used in multiple situations. Say you want to encode an id for an object1
, so you encode data like this:
$myData = array( 'id' => 153 );
Now you want to encode an id for an object2
so you encode it the same way:
$myData = array( 'id' => 351 );
If the same secret is used in both examples than it is possible for sombody to take a secret for object1
and use it in a different context for object2
.
To protect yourself from this security hazard you can use the method option.
Example:
// Encoding data in signed request using method attribute $mySecret = '[My super secret secret]'; $myData = array( 'dataKey' => 'dataValue' ); $mySR = SignedRequest::encode( $myData, array( 'method' => 'object1', 'timeout' => 3600 // signed request will expire in 1 hour ) ); // Decoding data in signed request using method attribute try { // decoding signed request using same secret $myData = SignedRequest::decode( $mySR, array( 'method' => 'object1', 'secret' => $mySecret ) ) print_r($myData); } catch (Exception $e) { // signed request has been malformatted or cannot be trusted var_dump($e); }