Signieren und Verifizieren von Anfragen

Die Signatur der Anfrage beweist die Authentizität des Absenders und die Integrität des Inhalts. Im Gegensatz zu TLS (das den Kanal schützt) macht die angewandte Signatur jede Nachricht überprüfbar und resistent gegen Proxy, Cache und verzögerte Zustellung.

1. Authentizität (wer gesendet hat) und Integrität (nicht geändert).

2. Unwiederholbarkeit (Replikationsschutz).

3. Entkopplung vom Transport (funktioniert über HTTP, Warteschlangen, Webhooks).

4. Prüfbarkeit (reproduzierbare Prüfung nach Monaten).

1) Bedrohungsmodell (Minimum)

Ersetzen Sie Körper/Überschriften auf dem Weg.
Replay (Wiederholung einer legitimen Anfrage).
Downgrade/Strip-Titel der Signatur.
Geheimnisse der Integration stehlen.
Nicht synchrone Uhren (clock skew) und lange Warteschlangen.

2) Auswahl des Primitivs

HMAC (Symmetrie): einfach und schnell, der Schlüssel wird auf beiden Seiten gespeichert. Geeignet für B2B-Webhooks und interne APIs.
RSA/ECDSA (Asymmetrie): Der Schlüssel ist beim Absender privat, beim Empfänger öffentlich. Geeignet für offene Integrationen und wenn es wichtig ist, kein Geheimnis zu teilen.
mTLS: gegenseitige Authentifizierung auf der Transportschicht; oft kombiniert mit NMAS/Körpersignatur.
JWT/JWS: praktisch für Bearer-Token und autarke Stempel; Für die Signatur des Körpers ist es besser, Kanonikalisierung + JWS Detached/HTTP Message Signatures zu verwenden.
HTTP-Nachrichtensignaturen (Signatur ausgewählter Teile der Anfrage): ein moderner Ansatz für REST.

Empfehlung: für Webhooks - HMAC + Timestamp + Nonce + Körperkanonisierung; für öffentliche API - HTTP-Nachrichtensignaturen oder JWS; bei hohen Risiken - mTLS hinzufügen.

3) Kanonikalisierung (was genau wir unterschreiben)

Sie müssen eine deterministische Zeichenfolge signieren, die von beiden Seiten gleichermaßen wiederhergestellt wird.

method \n path_with_query_normalized \n content-type \n digest: SHA-256=BASE64(SHA256(body)) \n x-ts: <unix    iso> \n x-nonce: <uuid> \n host \n x-tenant: <tenant_id> \n

canonical = join("\n", fields)
signature = HMAC(secret, canonical)  # или ECDSA_sign(private_key, canonical)

• Normalisieren Sie den Pfad und die Reihenfolge der Query-Parameter.
• Leerzeichen/Unicode/Groß-/Kleinschreibung - fix (z.B. lower-case header, trim).
• Große Körper - Hash (Digest), nicht einschalten „wie es ist“.

4) Format der Überschriften

X-Signature-Alg: hmac-sha256
X-Signature: v1=hex(hmac),ts=1730379005,nonce=550e8400-e29b-41d4-a716-446655440000,kid=prov_42
Digest: SHA-256=BASE64(SHA256(body))
X-Tenant: brand_eu

Signature: keyId="prov_42", alg="ecdsa-p256-sha256",
ts="2025-10-31T12:30:05Z", nonce="550e...", headers="(request-target) host digest x-tenant",
sig="BASE64(raw_signature)"

Mit 'kid'/' keyId' können Sie einen Schlüssel aus der Registrierung auswählen (siehe Rotation).

5) Überprüfung auf der Empfangsseite

python def verify(request):
1) Basic assert abs (now () - request. ts) <= ALLOWED_SKEW  # напр., 300 с assert not replayed(request. nonce, window = TTL) # store nonce/ts in KV

2) Restore canonical canonical = build_canonical (
method=request. method,
path=normalize_path(request. path, request. query),
content_type=request. headers["content-type"],
digest=hash_body(request. body),
ts=request. ts,
nonce=request. nonce,
host=request. headers["host"],
tenant=request. headers. get("x-tenant")
)

3) Get the key key = key_registry. get(request. kid) # secret (HMAC) или public key (ECDSA)

4) Verify if request signature. alg. startswith("hmac"):
ok = hmac_compare(key. secret, canonical, request. signature)
else:
ok = asym_verify(key. public, canonical, request. signature)

5) Solution if not ok: return 401, "SIGNATURE_INVALID"
return 200, "OK"

Constant-Time-Vergleich HMAC, Speicherung von 'nonce '/' (ts, event_id)' in schnellen KV (TTL ≥ Lieferfenster).

6) Anti-Replikation und Fenster

Timestamp + Nonce: Lehnen Sie Anfragen ab, die älter als' ± Δ 'sind (z. B. 5 Minuten), und wiederholen Sie Nonce in diesem Fenster.
Für Webhooks: Verwenden Sie eine stabile' event _ id 'und eine Inbox-Tabelle - diese ist zuverlässiger als nur nonce.
Re-Delivery (Retrays) sollte die gleichen ts/nonce/event_id verwenden, anstatt neue zu generieren.

7) Multi-Tenant und Regionen

Speichern Sie die Schlüssel per tenant/region: 'kid = <tenant>: <region>: <key _ id>'.
Teilen Sie Pools von Geheimnissen und Grenzen; Datenresidenz beachten.
Geben Sie in den Überschriften/Kanonikalisierungen „X-Tenant“ an und die Region ist Teil des zu überprüfenden Kontexts.

8) Schlüsselverwaltung und Rotation

Schlüsselregistrierung (KMS/Vault): 'kid', Typ, Algorithmus, Status ('active', 'deprecating', 'retired'), 'valid _ from/valid _ to'.
Dual-Secret: Halten Sie den aktuellen und den nächsten Schlüssel gleichzeitig (der Empfänger akzeptiert beide).
Rotation nach Zeitplan und Ereignis (Kompromittierung).
Schlüsselpinning (wenn möglich) und Beschränkung des Zugriffs auf Schlüsselmaterialien.
Protokolle für den Zugriff auf Schlüssel und Aktionen mit ihnen.

9) Kombination mit mTLS und OAuth

mTLS überprüft den Kanal und „wer Sie sind“ auf Zertifikatsebene.
Die Signatur schützt die Nachricht (nützlich über Proxy/Cache/Warteschlangen).
OAuth/JWT ergänzt die Authentifizierung/Autorisierung, garantiert jedoch nicht die Integrität des Körpers (es sei denn, er wird in der Kanonikalisierung signiert).
Best Practices: mTLS + Körpersignatur (Digest) + HMAC/ECDSA + kurzes' ts' -Interview.

10) Fehler und Antwortcodes

"401 SIGNATURE_INVALID' ist eine falsche Signatur/Algorithmus.
„401 KEY_REVOKED' -“ kid' ist ungültig/abgelaufen.
"400 TIMESTAMP_OUT_OF_RANGE' - Uhr/Fenster.
'409 NONCE_REPLAYED' - Wiederholung entdeckt.
"400 DIGEST_MISMATCH' - Körper verändert.
"415 UNSUPPORTED_ALGORITHM' ist ein ungelöster" alg ".
"429 TOO_MANY_ATTEMPTS' - Trottling nach Schlüssel/Tenant.

Treten Sie die genaue Ursache in den maschinenlesbaren 'error _ code'; geben Sie Geheimnisse/Kanonikalisierung nicht zurück, „wie es ist“.

11) Beobachtbarkeit und Auditierung

• `verify_p95_ms`, `verify_error_rate`, `digest_mismatch_rate`, `replay_blocked_rate`, `alg_usage{hmac,ecdsa}`, `clock_skew_ms`.
• Protokolle (strukturell): „kid“, „alg“, „tenant“, „region“, „ts“, „nonce“, „digest _ hash“, „decision“, „reason“.
• Tracing: Attribute' signature. kid`, `signature. alg`, `signature. ts_skew`.
• Audit: Unveränderliches Protokoll der Rotation, Verwendung von Schlüsseln und Toleranzflags.

12) Produktivität

Hash den Körper durch Streaming (nicht im Gedächtnis behalten).
Zwischenspeichern Sie öffentliche Schlüssel durch 'kid' mit kurzer TTL und Behinderung durch Ereignis.
Führen Sie auf edge/gateway Vorprüfungen durch (ts/nonce/format).
HMAC ist schneller als ECDSA; ECDSA ist bequemer für externe Integrationen und „untrennbare“ Schlüssel.

13) Testen

Sätze von Fixturen: gleiche Anforderungen → gleiche Kanonikation/Signatur; "Die schmutzigen" Lücken/Ordnungen der query/Titel → sind standfest.
Negativ: falsches' kid/alg', modifizierter Body/Host, Nonce-Wiederholung, veraltete ts, clock skew.
Property-based: Alle äquivalenten Abfragen ergeben einen canonical-String.
Interop: sprachübergreifende Prüfungen (Go/Java/Node/Python).
Chaos: Verzögerungen, Retrays, Schlüsselwechsel „on the fly“.

14) Playbooks (Runbooks)

1. Spitze' SIGNATUR _ UNGÜLTIG '

Überprüfen Sie die Rotation der Schlüssel, die Synchronisierung der Uhr, die Änderungen der Kanonizierung beim Absender.
Aktivieren Sie vorübergehend 'dual-accept' für das alte' kid', benachrichtigen Sie den Partner.

2. Wachstum von 'REPLAYED'

Erhöhen Sie die TTL der Nonce-Speicherung, überprüfen Sie die Retrainer beim Absender, überprüfen Sie die Uhr skew.
Blockiere missbräuchliche IP/ASN am Rand.

3. „DIGEST _ MISMATCH“ massiv

Proxy/Kompression/Überschreiben von Headern prüfen; die Version der Kanonikalisierung zu fixieren.
Deaktivieren Sie Vermittler, die Körper/Überschriften verletzen.

4. Kompromittierung des Schlüssels

Sofort revoke' kid', übersetzen in 'next _ kid', regenerieren alle Geheimnisse/Token, Audit-Zugriff.

15) Typische Fehler

Ein „Körperteil“ oder JSON zu signieren, ohne die Reihenfolge festzulegen, → eine Anfälligkeit für die Neuanordnung von Feldern.
Das Fehlen eines "Digest' → Proxy kann den Körper unbemerkt verändern.
Das lange' ts' -Fenster ohne Nonce → durch Replikate geöffnet.
Halten Sie Geheimnisse in Umgebungsvariablen ohne KMS/Vault.
Vergleichen Sie die Signatur nicht constant-time.
Ignorieren Sie' host '/' path 'in Kanonikalisierung → Angriffe auf die Weiterleitung.
Mix' kid 'von verschiedenen Tenanten und Regionen.

16) Checkliste vor dem Verkauf

• Das Format der Kanonikalisierung ist definiert (Methode, Pfad + Abfrage, Inhaltstyp, Digest, ts, nonce, Host, Tenant).
• Implementierte HMAC/ECDSA mit 'kid', Schlüsselregister und Dual-Secret.
• Anti-Replies (nonce + ts) und inbox/event_id für Webhooks sind enthalten.
• Fehlercodes/Retrae-Richtlinie und per tenant/key Trottling konfiguriert.
• Beobachtbarkeit: Metriken verify, logs, trace, alerts on bursts.
• Die Schlüsselrotation ist automatisiert; Audits und Zugriffsrechte sind eingeschränkt.
• Testkits für Kanonikalisierung und interlinguale Kompatibilität.
• Dokumentation für Integratoren mit Beispiel in 3-4 Sprachen und Fikturen.
• mTLS ist für sensible Integrationen aktiviert; JWT wird nur als Ergänzung, nicht als Ersatz für eine Körpersignatur verwendet.

Schlussfolgerung

Das Signieren und Verifizieren von Anfragen ist keine „einzelne Überschrift“, sondern eine Disziplin: klare Kanonikation, kurze Zeitfenster, Anti-Replikation, Schlüsselrotation und Beobachtbarkeit. Erstellen Sie einen einheitlichen Standard für alle Integrationen (APIs und Webhooks), verwenden Sie' kid'/KMS, akzeptieren Sie zwei Schlüssel während der Rotation und Ihre Konturen werden resistent gegen Spoofings, vorhersehbar und leicht zu überwachen.