 |
VOOZH | about |
|
VOOZH | about |
This document describes the cryptographic signing system for URLs in hypervel/router. Signed URLs protect routes by requiring a valid signature that proves the URL was generated by the application. This prevents unauthorized access to sensitive operations and enables time-limited URL sharing.
For general URL generation concepts, see UrlGenerator Class. For implementing signature validation in routes, see Signature Validation Middleware.
The signing system uses HMAC-SHA256 to cryptographically sign URLs, ensuring they cannot be tampered with. The signature is computed from the complete URL (including query parameters) and a secret key. Signed URLs can optionally include an expiration timestamp for temporary access control.
Key Components:
| Component | Location | Purpose |
|---|---|---|
signedRoute() | src/UrlGenerator.php197-216 | Generates signed URLs for named routes |
temporarySignedRoute() | src/UrlGenerator.php239-242 | Generates signed URLs with expiration |
hasValidSignature() | src/UrlGenerator.php247-251 | Validates signature and expiration |
hasCorrectSignature() | src/UrlGenerator.php264-285 | Validates signature only (ignores expiration) |
ValidateSignature | src/Middleware/ValidateSignature.php15-92 | Middleware for automatic validation |
InvalidSignatureException | src/Exceptions/InvalidSignatureException.php9-18 | Exception thrown on invalid signatures |
Sources: src/UrlGenerator.php1-519 src/Middleware/ValidateSignature.php1-92
Signed URLs are created by:
signature, expires)expires parameter (Unix timestamp)Diagram: Signature Generation Process
Sources: src/UrlGenerator.php197-234
Two parameter names are reserved for the signing system and cannot be used in route parameters:
| Parameter | Purpose | Error Message |
|---|---|---|
signature | Holds the HMAC-SHA256 hash | "Signature" is a reserved parameter when generating signed routes. Please rename your route parameter. |
expires | Holds the expiration timestamp | "Expires" is a reserved parameter when generating signed routes. Please rename your route parameter. |
The ensureSignedRouteParametersAreNotReserved() method at src/UrlGenerator.php221-234 enforces this constraint.
Sources: src/UrlGenerator.php221-234
Diagram: Signed URL Generation Methods
Sources: src/UrlGenerator.php197-242
| Parameter | Type | Default | Description |
|---|---|---|---|
name | BackedEnum|string | required | Named route identifier |
parameters | array | [] | Route parameters and query parameters |
expiration | DateInterval|DateTimeInterface|int|null | null | Expiration time (timestamp, interval, or datetime) |
absolute | bool | true | Generate absolute or relative URL |
server | string | 'http' | Server name for route resolution |
Sources: src/UrlGenerator.php197-242
The signedRoute() method generates a signed URL for a named route:
The temporarySignedRoute() method is a convenience wrapper that requires an expiration:
Sources: src/UrlGenerator.php197-242
The UrlGenerator provides three validation methods:
Diagram: Signature Validation Flow
Sources: src/UrlGenerator.php247-295
| Method | Validates Signature | Validates Expiration | Use Case |
|---|---|---|---|
hasValidSignature() | ✓ | ✓ | Complete validation (recommended) |
hasCorrectSignature() | ✓ | ✗ | Signature check only |
signatureHasNotExpired() | ✗ | ✓ | Expiration check only |
hasValidRelativeSignature() | ✓ | ✓ | Validate relative URLs |
The hasValidSignature() method at src/UrlGenerator.php247-251 performs both signature and expiration validation:
Sources: src/UrlGenerator.php247-295
Signed URLs can be validated in two modes:
| Mode | URL Format | Use Case | Validation Call |
|---|---|---|---|
| Absolute | https://example.com/path?signature=... | External links, email links | hasValidSignature($request, true) |
| Relative | /path?signature=... | Internal redirects, same-domain links | hasValidSignature($request, false) |
The difference affects which portion of the URL is included in the signature computation:
https://example.com/path?param=value)/path?param=value)Sources: src/UrlGenerator.php247-285
The hasCorrectSignature() method at src/UrlGenerator.php264-285 reconstructs the original URL for comparison:
Sources: src/UrlGenerator.php264-285
The ValidateSignature middleware provides automatic signature validation for routes. It supports both absolute and relative validation modes with parameter exclusions.
Diagram: ValidateSignature Middleware Flow
Sources: src/Middleware/ValidateSignature.php56-81
The middleware can be applied with different configurations:
| Configuration | Method Call | Description |
|---|---|---|
| Absolute (default) | ValidateSignature::class | Validates absolute URLs |
| Absolute with ignores | ValidateSignature::absolute(['param1', 'param2']) | Validates absolute URLs, ignores specified parameters |
| Relative | ValidateSignature::relative() | Validates relative URLs |
| Relative with ignores | ValidateSignature::relative(['param1', 'param2']) | Validates relative URLs, ignores specified parameters |
The absolute() and relative() static methods at src/Middleware/ValidateSignature.php37-54 generate middleware strings with encoded configuration:
Sources: src/Middleware/ValidateSignature.php37-54
Three levels of parameter exclusions are supported:
Diagram: Parameter Exclusion Hierarchy
Global exclusions can be configured for all validation operations:
The except() method at src/Middleware/ValidateSignature.php86-91 modifies the static $neverValidate property, which applies to all instances.
Sources: src/Middleware/ValidateSignature.php22-91
The signing key defaults to the application key configured in config/autoload/app.php:
The getSignedKey() method at src/UrlGenerator.php477-485 retrieves this key:
Sources: src/UrlGenerator.php477-485
For specialized use cases, a custom signing key can be set using setSignedKey() at src/UrlGenerator.php447-452:
Use cases for custom keys:
Sources: src/UrlGenerator.php447-485
Diagram: Security Architecture
Sources: src/UrlGenerator.php197-285
| Feature | Implementation | Protection Against |
|---|---|---|
| HMAC-SHA256 | hash_hmac('sha256', ...) | Signature forgery |
| Timing-safe comparison | hash_equals() | Timing attacks |
| Parameter sorting | ksort($parameters) | Parameter order tampering |
| Reserved parameters | ensureSignedRouteParametersAreNotReserved() | Parameter injection |
| Expiration timestamps | expires query parameter | Replay attacks |
| Signature parameter exclusion | Always excluded from validation | Signature removal |
The signature validation at src/UrlGenerator.php277-282 uses hash_equals() for timing-safe comparison:
This prevents timing attacks where an attacker could determine the correct signature by measuring comparison times.
Sources: src/UrlGenerator.php197-285
When signature validation fails, the InvalidSignatureException at src/Exceptions/InvalidSignatureException.php9-18 is thrown:
Response details:
ValidateSignature middlewareThe exception extends HttpException, allowing the framework's exception handler to convert it to an appropriate HTTP response.
Sources: src/Exceptions/InvalidSignatureException.php9-18 src/Middleware/ValidateSignature.php64
The ValidateSignature middleware integrates with the request abstraction through the RequestContract interface. The middleware uses $request->hasValidSignatureWhileIgnoring() at src/Middleware/ValidateSignature.php60 which is a method provided by the request implementation that delegates to the UrlGenerator validation methods.
Diagram: Request Validation Sequence
Sources: src/Middleware/ValidateSignature.php56-65 src/UrlGenerator.php247-295
Refresh this wiki