README

English | 中文

A Symfony bundle that provides signature verification support for JSON-RPC services, inspired by Alibaba Cloud's signature design. This bundle ensures API security by validating request signatures using HMAC-SHA1 or MD5 algorithms.

Features

Signature Verification: Complete JSON-RPC request signature verification system
Multiple Algorithms: Support for MD5 and HMAC-SHA1 signature algorithms
Attribute-based: Simple #[CheckSign] attribute for method protection
Event-driven: Seamless integration with Symfony's event system
Time Tolerance: Configurable timestamp validation to prevent replay attacks
API Management: Built-in API caller identification and validation
Logging: Comprehensive logging for debugging and monitoring

Requirements

PHP 8.1 or higher
Symfony 6.4 or higher
ext-hash extension

Installation

Install via Composer:

composer require tourze/json-rpc-sign-bundle

Quick Start

1. Register the Bundle

In your config/bundles.php:

<?php

return [
    // ...
    Tourze\JsonRPCSignBundle\JsonRPCSignBundle::class => ['all' => true],
];

2. Mark Methods for Signature Verification

Add the CheckSign attribute to any class that needs signature verification:

<?php

namespace App\JsonRPC;

use Tourze\JsonRPCSignBundle\Attribute\CheckSign;

#[CheckSign]
class SecureService
{
    public function sensitiveMethod(array $params): array
    {
        // This method requires a valid signature
        return [
            'status' => 'success',
            'data' => $params,
        ];
    }
}

3. Making Signed Requests

When calling a protected JSON-RPC method, include the following headers:

Signature-AppID: your_app_id
Signature-Nonce: random_32_character_string
Signature-Timestamp: current_unix_timestamp
Signature-Method: HMAC-SHA1 (or MD5)
Signature-Version: 1.0
Signature: your_calculated_signature

4. Signature Algorithm

The signature is calculated differently based on the algorithm:

HMAC-SHA1 (Recommended)

$payload = json_encode($yourData);
$timestamp = time();
$nonce = bin2hex(random_bytes(16)); // 32-character random string
$appSecret = 'your_app_secret';

$rawText = $payload . $timestamp . $nonce;
$signature = hash_hmac('sha1', $rawText, $appSecret);

MD5 (Less Secure)

$payload = json_encode($yourData);
$timestamp = time();
$nonce = bin2hex(random_bytes(16)); // 32-character random string
$appSecret = 'your_app_secret';

$rawText = $payload . $timestamp . $nonce . $appSecret;
$signature = md5($rawText);

Advanced Usage

Environment Variables

You can set the following environment variable for development:

# Allow bypassing signature verification with special query parameter
JSON_RPC_GOD_SIGN=your_secret_bypass_key

Then use ?__ignoreSign=your_secret_bypass_key to bypass signature verification during development.

Custom Configuration

Each API caller can have:

appId: Unique identifier for the API caller
appSecret: Secret key for signature generation
signTimeoutSecond: Custom timeout for signature validation (default: 180 seconds)
valid: Whether the API caller is active

Error Handling

The bundle provides specific exceptions for different error scenarios:

SignAppIdMissingException: When Signature-AppID header is missing
SignAppIdNotFoundException: When the provided AppID is not found or invalid
SignNonceMissingException: When Signature-Nonce header is missing
SignRequiredException: When no signature is provided
SignTimeoutException: When the timestamp is outside the tolerance window
SignErrorException: When signature verification fails

Security Considerations

Timestamp Validation: The bundle validates request timestamps to prevent replay attacks
Nonce Uniqueness: While the bundle doesn't store nonces, you should implement nonce tracking for maximum security
HTTPS Required: Always use HTTPS in production to protect signatures in transit
Secret Management: Keep your app secrets secure and rotate them regularly

Testing

Run the test suite:

./vendor/bin/phpunit packages/json-rpc-sign-bundle/tests

Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

License

The MIT License (MIT). Please see License File for more information.

tourze / json-rpc-sign-bundle

Maintainers

Details