plenigo-Signatur

    Inhalt dieses Artikels

    1. Vorbemerkungen
    2. plenigo-Signatur prüfen

    1. Vorbemerkungen

    Jeder Callback aus dem plenigo System ist mit einer Signatur versehen, die im Header zu finden ist, um sicherzustellen, dass der Aufruf von einer vertrauenswürdigen Quelle stammt und nicht manipuliert wurde.

    2. plenigo-Signatur prüfen

    Jeder Callback wird über einen Signatur-Header signiert. 
    Der Header heißt plenigo-signature und sieht wie folgt aus:
    t=1729583536,s=fdcd0a0ccd0b4db629d35a33c3aada5cf669a28f91adb38abcc9ffcdb1663d38
    Der Header enthält zwei Elemente. Einen Zeitstempel, der den Zeitpunkt angibt, zu dem der Rückruf erzeugt wurde (t), und einen hashbasierten Nachrichtenauthentifizierungscode (HMAC) mit SHA-256 (s). 

    Zusammenfassung:

    plenigo-signature: t=<zeitstempel>,s=<signatur>

    • t = Unix-Zeitstempel (Sekunden seit dem 01.01.1970)

    • s = HMAC-SHA256-Signatur (hexadezimal codiert)

    So wird die Signatur erstellt

    Frisbii Media berechnet die Signatur in folgenden Schritten:

    1. Aktuellen Zeitstempel als Zeichenkette holen

    2. Zeitstempel und Rohdaten des Bodys mit einem Punkt (.) verbinden

    3. HMAC mit SHA256 erzeugen, unter Verwendung des Callback-Secrets von Frisbii Media

    4. Header setzen:

      plenigo-signature: t=zeitstempel,s=signatur

    Um bei versionierungsspezifischer Logik zu helfen, enthält jede Callback-Anfrage auch den HTTP-Header:

    X-Plenigo-Api-Version

    Header verifizieren

    Schritt 1: Zeitstempel und Signaturen aus dem Header extrahieren
    Der Inhalt des Headers kann mit dem Zeichen "," (Komma) getrennt werden, um eine Liste von Elementen zu erhalten. Durch das Zeichen "=" (Gleichheitszeichen) als Trennzeichen kann jedes Element in ein Datenpaar aus einem Präfix und einem Wert unterteilt werden. 

    Werte der Präfixe:
    • "t" = Zeitstempel
    • "s" = eine Signatur oder mehrere Signaturen
    Eventuelle weitere Elemente können ignoriert werden.

    Schritt 2: Zeichenkette "signed_payload" vorbereiten
    Die Zeichenfolge "signed_payload" wird durch eine Verkettung erstellt: 
    • der Zeitstempel als String
    • das Zeichen "." (Punkt) 
    • der eigentliche JSON-Payload (d. h. der Anfrageinhalt) als String 

    Schritt 3: Erwartete Signatur bestimmen
    Es wird ein HMAC Authentifizierungscode mit einer SHA256-Hash-Funktion benötigt. Das Signiergeheimnis des Endpunkts wird als Schlüssel und die Zeichenkette "signed_payload" als Nachricht verwendet.

    Schritt 4: Signaturen vergleichen
    Die Signatur (oder Signaturen) in der Kopfzeile sollte mit der erwarteten Signatur verglichen werden. 
    Für den Vergleich sollte die Differenz zwischen dem aktuellen Zeitstempel und dem empfangenen Zeitstempel errechnet werden, um dann zu entscheiden, ob die Differenz innerhalb einer akzeptablen Toleranz liegt. 

    Hier ist ein Beispiel für die Verarbeitung des empfangenen Callbacks:

    ⚠️ Sicherheitshinweise

    • Verwende zum Schutz vor Timing-Angriffen unbedingt eine zeitkonstante Vergleichsfunktion, um die erwartete Signatur mit den empfangenen zu vergleichen.

    • Immer hmac.Equal(...) für den Vergleich verwenden.

    • Callbacks mit einem Zeitstempel, der zu weit in der Vergangenheit oder Zukunft liegt (z. B. mehr als 5 Minuten), ablehnen.

    • Das Callback-Secret niemals öffentlich teilen.


    Veröffentlicht