feat: HmacService — HMAC-Signing und Verifikation mit Constant-Time-Vergleich #4

New Issue

2026-07-26T19:20:07+02:00

claudeCode commented

2026-07-26 19:20:07 +02:00

Motivation

OAuth-Webhook-Validierung, API-Request-Signing und Token-Integrität erfordern HMAC. Ein dedizierter HmacService mit Constant-Time-Vergleich verhindert Timing-Angriffe, die bei naivem ===-Vergleich möglich sind.

API

$service = new HmacService(secret: 'my-secret', algorithm: HmacAlgorithm::Sha256);

$signature = $service->sign($payload);         // hex-String
$valid      = $service->verify($payload, $signature); // bool, Constant-Time

// Typischer Webhook-Use-Case:
$valid = $service->verify(
    $request->getBody(),
    $request->getHeader('X-Hub-Signature-256')
);

HmacAlgorithm Enum

enum HmacAlgorithm: string {
    case Sha256 = 'sha256';
    case Sha384 = 'sha384';
    case Sha512 = 'sha512';
}

Implementierungsdetails

sign(string $payload): string — gibt lowercase Hex-String zurück via hash_hmac()
verify(string $payload, string $signature): bool — nutzt hash_equals() für Constant-Time-Vergleich
HmacAlgorithm als Backed Enum mit BackedEnumTrait (konsistent mit AesCipher)
Namespace: Tez\Utils\Crypto\Hmac

Aufgaben

src/Hmac/HmacAlgorithm.php implementieren
src/Hmac/HmacService.php implementieren
Unit-Tests in tests/Hmac/HmacServiceTest.php
- Sign + Verify Roundtrip für alle Algorithmen
- Verify schlägt fehl bei verändertem Payload
- Verify schlägt fehl bei veränderter Signatur
- Leerer Payload wird korrekt verarbeitet
README-Abschnitt mit Webhook-Beispiel
HmacAlgorithm in AesCipher-Stil dokumentieren

Abhängigkeiten

Blockiert von #1 (Namespace-Reorganisation)
Keine weiteren Abhängigkeiten — kann parallel zu #2/#3 entwickelt werden

## Motivation OAuth-Webhook-Validierung, API-Request-Signing und Token-Integrität erfordern HMAC. Ein dedizierter `HmacService` mit Constant-Time-Vergleich verhindert Timing-Angriffe, die bei naivem `===`-Vergleich möglich sind. ## API ```php $service = new HmacService(secret: 'my-secret', algorithm: HmacAlgorithm::Sha256); $signature = $service->sign($payload); // hex-String $valid = $service->verify($payload, $signature); // bool, Constant-Time // Typischer Webhook-Use-Case: $valid = $service->verify( $request->getBody(), $request->getHeader('X-Hub-Signature-256') ); ``` ## HmacAlgorithm Enum ```php enum HmacAlgorithm: string { case Sha256 = 'sha256'; case Sha384 = 'sha384'; case Sha512 = 'sha512'; } ``` ## Implementierungsdetails - `sign(string $payload): string` — gibt lowercase Hex-String zurück via `hash_hmac()` - `verify(string $payload, string $signature): bool` — nutzt `hash_equals()` für Constant-Time-Vergleich - `HmacAlgorithm` als Backed Enum mit `BackedEnumTrait` (konsistent mit `AesCipher`) - Namespace: `Tez\Utils\Crypto\Hmac` ## Aufgaben - [ ] `src/Hmac/HmacAlgorithm.php` implementieren - [ ] `src/Hmac/HmacService.php` implementieren - [ ] Unit-Tests in `tests/Hmac/HmacServiceTest.php` - Sign + Verify Roundtrip für alle Algorithmen - Verify schlägt fehl bei verändertem Payload - Verify schlägt fehl bei veränderter Signatur - Leerer Payload wird korrekt verarbeitet - [ ] README-Abschnitt mit Webhook-Beispiel - [ ] `HmacAlgorithm` in `AesCipher`-Stil dokumentieren ## Abhängigkeiten - Blockiert von #1 (Namespace-Reorganisation) - Keine weiteren Abhängigkeiten — kann parallel zu #2/#3 entwickelt werden

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: tez/tez-utils-crypto#4