Semnarea și verificarea cererilor

Semnarea cererii dovedește autenticitatea expeditorului și integritatea conținutului. Spre deosebire de TLS (care protejează canalul), o semnătură aplicată face ca fiecare mesaj să fie verificabil și rezistent la proxy, cache și livrare întârziată.

1. Autenticitate (cine a trimis) și integritate (nu sa schimbat).

2. Unicitate (protecție împotriva reluărilor).

3. Decuplarea de transport (lucrări pe partea de sus a HTTP, cozi, cârlige web).

4. Auditabilitate (verificare reproductibilă după luni).

1) Model de amenințare (minim)

Înlocuirea corpului/anteturilor de-a lungul traseului.
Replay (repetați cererea legitimă).
Legendă Downgrade/benzi.
Furtul secretelor de integrare.
Ceas non-sincron (înclinare a ceasului) și cozi lungi.

2) Alegerea primitivă

HMAC (simetrie): simplu și rapid, cheia este stocată pe ambele părți. Potrivit pentru carti web B2B si API-uri interne.
RSA/ECDSA (asimetrie): cheie privată de la expeditor, cheie publică de la destinatar. Potrivit pentru integrări deschise și atunci când este important să nu împărtășiți un secret.
mTLS: autentificarea reciprocă a stratului de transport, adesea combinată cu semnătura NMAC/corp.
JWT/JWS: convenabil pentru jetoane la purtător și ștampile autosuficiente; pentru a semna corpul, este mai bine să utilizați canonicalizarea + JWS Detașat/HTTP Semnături mesaj.
Semnăturile mesajului HTTP (semnătura părților selectate ale cererii): abordare modernă pentru REST.

Recomandare: pentru carti web - HMAC + timestamp + nonce + canonicalizare corp; pentru semnăturile publice API - HTTP Message Signatures sau JWS; la riscuri ridicate - adăugați mTLS.

3) Canonicalizarea (ceea ce semnăm exact)

Trebuie să semnați un șir determinist care este la fel de recuperabil de ambele părți.

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)

• Normalizați calea și ordinea parametrilor de interogare.
• Spații/unicode/carcasă - remediați (de exemplu, anteturi mai mici, tăiați).
• Corpuri mari - hash (Digest), nu porniți „așa cum este”.

4) Formatul titlului

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)"

În cazul în care "kid "/" keyId' vă permite să selectați o cheie din registru (a se vedea rotația).

5) Verificarea la sfârșitul primirii

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"

Comparație HMAC în timp constant, stocarea „nonce ”/„ (ts, event_id)” în fereastra de livrare rapidă KV (TTL ≥).

6) Anti-reluare și ferestre

Timestamp + Nonce: respinge cererile mai vechi decât „± Δ” (de ex. 5 min) și nonce reintră în această fereastră.
Pentru webhookuri: utilizați un tabel stabil 'event _ id' și un tabel inbox - acest lucru este mai fiabil decât doar nonce.
Re-livrare (retribuții) ar trebui să utilizeze aceleași ts/nonce/event_id, nu să genereze altele noi.

7) Multi-chiriaș și regiuni

Stocați cheile per chiriaș/regiune: 'kid = <chiriaș>: <regiune>: <key _ id>'.
Piscine și limite secrete separate; să respecte rezidența datelor.
În rubricile/canonicalizare, indicați „X-Tenant” și regiunea face parte din contextul verificat.

8) Managementul și rotația cheilor

Registru cheie (KMS/Vault): 'kid', type, algorithm, status ('activ', 'depreciere', 'pensionat'), 'valid _ from/valid _ to'.
Dual-secret: țineți curentul și următoarea cheie simultan (receptorul acceptă ambele).
Rotație pe un program și pe un eveniment (compromis).
Fixarea cheilor (dacă este posibil) și restricționarea accesului la materiale cheie.
Jurnalele de acces la chei și acțiuni cu ei.

9) Combinație cu mTLS și OAuth

mTLS verifică canalul și „cine ești” la nivelul certificatului.
Semnătura protejează mesajul (util prin proxy-uri/cache-uri/cozi).
OAuth/JWT completează autentificarea/autorizarea, dar prin ea însăși nu garantează integritatea corpului (cu excepția cazului în care este semnat în canonicalizare).
Cele mai bune practici: mTLS + semnătură corporală (Digest) + HMAC/ECDSA + scurt 'ts' -interval.

10) Erori și coduri de răspuns

'401 SIGNATURE_INVALID' este o semnătură/algoritm nevalid.
"401 KEY_REVOKED' -" copil "este invalid/expirat.
'400 TIMESTAMP_OUT_OF_RANGE' - ceas/fereastră.
'409 NONCE_REPLAYED' - Redo detectat.
'400 DIGEST_MISMATCH' - corpul s-a schimbat.
"415 UNSUPPORTED_ALGORITHM' este un" alg "nerezolvat.
'429 TOO_MANY_ATTEMPTS' - limitarea cheilor/chiriașilor.

Lovi cu piciorul cauza exactă în mașină de citit „error _ code”; nu returnați secrete/canonicalizare „așa cum este”.

11) Observabilitate și audit

• 'verify _ p95 _ ms',' verify _ error _ rate ',' digest _ mumatch _ rate ',' relay _ blocked _ rate ',' alg _ usage {hmac, ecdsa} ',' clock _ skew _ ms'.
• Jurnale (structurale): "kid", "alg", "chiriaș", "regiune", "ts'," nonce "," digest _ hash "," decizie "," motiv ".
• Urmărire: semnătura atributelor. Semnătura puştiului. alg ',' semnătură. ts_skew'.
• Audit: jurnal imuabil de rotație, utilizare cheie și steaguri de toleranță.

12) Performanță

Hash corpul prin streaming (nu-l păstrați în memorie).
Cache chei publice de „copil” cu TTL scurt și handicap de eveniment.
Pe margine/gateway, efectuați verificări preliminare (ts/nonce/format).
HMAC mai rapid decât ECDSA; ECDSA este mai convenabil pentru integrări externe și chei „non-partajate”.

13) Testarea

Seturi de fixare: aceleași cereri → aceeași canonicalizare/semnătură; spațiile murdare/ordinea de interogare/anteturile → sunt stabile.
Negativ: invalid 'kid/alg', corp modificat/gazdă, repetare nonce, ts învechite, înclinare ceas.
Bazat pe proprietate: Orice interogări echivalente produc un singur șir canonic.
Interop: verificarea limbajului încrucișat (Go/Java/Node/Python).
Haos: întârzieri, retrageri, schimbări cheie în zbor.

14) Cărți de joc (runbooks)

1. 'SEMNĂTURĂ _ INVALID' spike

Verificați rotația cheii, alinierea greșită a ceasului, modificările canonicalizării la expeditor.
Activați temporar „dual-accept” pentru bătrânul „copil”, notificați partenerul.

2. Creşterea „RELUATĂ”

Măriți TTL de stocare nonce, verificați recalificatorii la expeditor, verificați înclinarea ceasului.
Suprascrie IP/ASN abuziv pe margine.

3. „DIGEST _ MISMATCH” masiv

Verificați anteturile proxy/compresie/rescriere; fixați versiunea de canonicalizare.
Dezactivați intrușii corpului/antetului.

4. Compromisul cheie

Revocați imediat „kid”, traduceți „next _ kid”, regenerați toate secretele/jetoanele, auditați accesul.

15) Erori tipice

Semnarea unei „părți a corpului” sau JSON fără a fixa ordinea → vulnerabilitatea la permutarea câmpului.
Absența unui proxy → 'Digest' poate schimba corpul neobservat.
O fereastră lungă fără nonce este → deschisă pentru reluare.
Păstrați secrete în variabilele de mediu fără KMS/Vault.
Comparați semnătura nu în timp constant.
Ignorați „gazdă ”/„ cale” în canonicalizare → atac înainte.
Se amestecă „copil” chiriași diferite și regiuni.

16) Lista de verificare pre-vânzare

• Formatul canonicalizării definit (metodă, cale + interogare, tip de conținut, Digest, ts, nonce, gazdă, chiriaș).
• Implementat HMAC/ECDSA cu „kid”, registru cheie și dual-secret.
• Incluse anti-reluare (nonce + ts) și stocare inbox/event_id pentru webhooks.
• Configurat coduri de eroare/politica de retray și accelerarea per chiriaș/cheie.
• Observabilitate: verifica metrica, busteni, urme, alerte pentru explozii.
• Rotația cheii este automatizată; drepturile de audit și de acces sunt limitate.
• Canonicalizarea și kiturile de testare a compatibilității între limbi.
• Documentație pentru integratori cu un exemplu în 3-4 limbi și remedieri.
• mTLS activat pentru integrări sensibile; JWT este folosit numai ca adaos, nu ca înlocuitor pentru semnătura corpului.

Concluzie

Semnarea și verificarea cererilor nu este „un antet”, ci o disciplină: canonicalizare clară, ferestre scurte de timp, anti-reluare, rotație cheie și observabilitate. Construiți un singur standard pentru toate integrările (API-uri și webhookuri), utilizați „kid ”/KMS, acceptați două taste în timpul rotației, iar contururile dvs. vor deveni rezistente la spoofing, previzibile și ușor de auditat.