Signatur

• Funktionsweise
• Generierung
  • Beispielimplementierung in PHP
  • Beispielimplementierung in JavaScript
• Rückmeldung bei ungültigem Hash

Funktionsweise

Um den Konsumenten gegenüber der API zu authentifizieren, muss jeder API-Request mit einem Hash signiert werden.

Der Hash wird wie die Signatur für Webhooks mit Hilfe des secret generiert.

Generierung

Folgende Werte des API-Requests werden zu einem String zusammengesetzt. Alle Werte sind durch einen . voneinander zu trennen.

{
    "target": "48:88:1F:C9:B0:BA",
    "consumer": "8d8d52b6-ab21-4984-8abc-c5640b2e107e",
    "data": {
        "event": "Normalruf",
        "position": "Haupteingang",
        "closed": false
    }
}

Aus dem obenstehenden Webhook ergibt sich also folgender Prüfstring:

48:88:1F:C9:B0:BA.8d8d52b6-ab21-4984-8abc-c5640b2e107e.{"event":"Normalruf","position":"Haupteingang","closed":false}

Aus diesem String wird nun ein Hash mit Schlüssel unter Verwendung von HMAC berechnet. Der verwendete Hash-Algorithmus ist sha256. Als Schlüssel wird das hinterlegte Hash-Secret verwendet.

Hinweis zum JSON-Format

Es gelten die gleichen Formatierungsregeln wie bei den Webhooks. Siehe Webhooks → Signatur → Hinweis zum JSON-Format.

Beispielimplementierung in PHP

$hashString = implode('.', [
    $request->target,
    $request->consumer,
    json_encode($request->data, JSON_UNESCAPED_UNICODE)
]);
// 48:88:1F:C9:B0:BA.8d8d52b6-ab21-4984-8abc-c5640b2e107e.{"event":"Normalruf","position":"Haupteingang","closed":false}

$hash = hash_hmac('sha256', $hashString, 'secret');
// 5ef777799388eb3a38a6c52d055232fa30ba5174ad32d6dcbacbb5aaf9e18ae2

$request->hash = $hash;

Beispielimplementierung in JavaScript

// https://github.com/brix/crypto-js
import * as CryptoJS from 'crypto-js';

const hashString = [
    request.target,
    request.consumer,
    JSON.stringify(request.data)
].join('.');
// 48:88:1F:C9:B0:BA.8d8d52b6-ab21-4984-8abc-c5640b2e107e.{"event":"Normalruf","position":"Haupteingang","closed":false}

const hash = CryptoJS.HmacSHA256(hashString, 'secret').toString();
// 5ef777799388eb3a38a6c52d055232fa30ba5174ad32d6dcbacbb5aaf9e18ae2

request.hash = hash;

Rückmeldung bei ungültigem Hash

Ist der Hash eines API-Requests ungültig, wird eine HTTP-Response mit Status 400 Bad Request zurückgegeben.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "success": false,
    "messages": [
        {
            "code":  "invalid_hash",
            "status_code": 400,
            "errors": "Ungültiger Hash"
        }
    ]
}