README

A simple, general-purpose PHP library for signing and validating HTTP requests. It enables secure server-to-server communication by authenticating requests using a shared secret, an automatic timestamp, and an HMAC signature.

Installation

Install via Composer:

composer require acinader/signed-request

Usage

<?php
require 'vendor/autoload.php';

use Acinader\SignedRequest;

// 1. Initialize with a shared secret and TTL (in seconds)
$secret = 'your-strong-secret-key';
$ttl = 3600; // Default is 1 hour
$signedRequest = new SignedRequest($secret, $ttl);

// 2. Sign parameters and generate a ready-to-use query string
$params = [
    'action'  => 'process',
    'user_id' => 42,
    'data'    => ['nested' => 'value'] // Nested arrays are automatically flattened for signing
];

$queryString = $signedRequest->generateValidQueryString($params);
// Output: action=process&user_id=42&data=Array&timestamp=...&signature=...
$url = "https://example.com/api/callback?{$queryString}";
echo "Signed URL: {$url}";

// 3. Validate an incoming request
// When a request hits your server with the query string, validate it:
$isValid = $signedRequest->validateCurrentRequest();
if ($isValid) {
    echo "Request is valid, authenticated, and within the TTL.";
} else {
    echo "Request is invalid, tampered, or expired.";
}
?>

A working demo/test script is included in the repository at index.php. It demonstrates the full lifecycle: building a form, signing the payload, generating a clickable link, and validating the request upon click.

Configuration

The SignedRequest constructor accepts three parameters:

$signer = new SignedRequest($secret, $ttl = 3600, $hash_algorithm = 'sha256');

$secret (string, required): The shared secret key used to generate and verify the HMAC signature.
$ttl (int, optional): Time-to-live in seconds. Requests older than this duration will be marked invalid. Defaults to 3600 (1 hour).
$hash_algorithm (string, optional): The hash algorithm to use for HMAC. Must be a valid algorithm from hash_algos(). Defaults to sha256. Throws an Exception if an invalid algorithm is provided.

Key Features

HMAC Signing: Uses standard PHP hash_hmac() for cryptographic request signing.
Automatic Timestamping: Injects a timestamp into the request to prevent replay attacks.
TTL Expiration: Automatically rejects requests that exceed the configured time-to-live.
Consistent Serialization: Automatically flattens nested arrays and normalizes keys/values to lowercase before signing to ensure consistent signature generation across different PHP environments.
Zero Dependencies: Lightweight library with no external requirements.

API Methods

Method	Description
`__construct($secret, $ttl, $hash_algorithm)`	Initializes the signer with the provided configuration.
`signRequest($params)`	Adds `timestamp` and `signature` keys to the provided parameters array. Returns the new array.
`validateRequest($params)`	Validates an array of parameters against the secret and TTL. Returns `true` if valid.
`validateCurrentRequest()`	Convenience method that parses `$_SERVER['QUERY_STRING']` and validates it. Returns `true` if valid.
`generateValidQueryString($params)`	Signs the parameters and returns a URL-safe query string.

License & Author

Author: Arthur Cinader
License: MIT

acinader / signed-request

Maintainers

Package info

Statistics

Security