Sorğuların imzalanması və yoxlanılması

Sorğunun imzası göndəricinin həqiqiliyini və məzmunun bütövlüyünü sübut edir. TLS-dən (hansı ki, kanalı qoruyur) fərqli olaraq, tətbiqi imza hər bir mesajı yoxlanıla bilən və proxy, cache və gecikmiş çatdırılmaya davamlı edir.

1. Orijinallıq (kim göndərdi) və bütövlük (dəyişmədi).

2. Təkrarolunmazlıq (repleylərdən qorunma).

3. Nəqliyyatdan ayrılma (HTTP, növbələr, vebhuklar üzərində işləyir).

4. Audit (aylar sonra təkrar yoxlama).

1) Təhdid modeli (minimum)

Yol boyu bədən/başlıqların dəyişdirilməsi.
Replay (legitim sorğunun təkrarı).
Altyazıları Downgrade/strip.
İnteqrasiya sirlərinin oğurlanması.
Qeyri-sinxron saat (clock skew) və uzun növbələr.

2) Primitiv seçimi

HMAC (simmetriya): sadə və sürətli, açar hər iki tərəfdə saxlanılır. B2B vebhook və daxili API üçün uyğundur.
RSA/ECDSA (asimmetriya): göndəricidə xüsusi açar, alıcıda açıq. Açıq inteqrasiya üçün uyğundur və sirri bölüşməmək vacibdir.
mTLS: nəqliyyat səviyyəsində qarşılıqlı autentifikasiya; tez-tez NMAS/bədən imzası ilə birləşir.
JWT/JWS: bearer tokenləri və özünü təmin edən markalar üçün əlverişlidir; bədən imzalamaq üçün + JWS Detached/HTTP Message Signatures istifadə etmək daha yaxşıdır.
HTTP Message Signatures (seçilmiş sorğu hissələrinin imzası): REST üçün müasir yanaşma.

Tövsiyə: vebhuk üçün - HMAC + timestamp + nonce + bədən kanonikasiyası; ictimai API üçün - HTTP Message Signatures və ya JWS; yüksək risklərlə - mTLS əlavə edin.

3) Kanonikalizasiya (tam olaraq nə imzalayırıq)

Hər iki tərəfin eyni şəkildə bərpa etdiyi determinik bir sətir imzalamaq lazımdır.

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)

• Query parametrlərinin yolunu və qaydasını normallaşdırın.
• Boşluqlar/unicode/registr- qeyd (məsələn, lower-case başlıqları, trim).
• Böyük cisimlər - Hash (Digest) və «olduğu kimi» daxil deyil.

4) Başlıq formatı

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

Burada 'kid '/' keyId' reyestrdən açar seçməyə imkan verir (rotasiyaya bax).

5) Qəbul tərəfində yoxlama

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 müqayisə HMAC, saxlama 'nonce '/' (ts, event_id)' sürətli KV (TTL ≥ çatdırılma pəncərə).

6) Anti-replay və pəncərə

Timestamp + Nonce: Bu pəncərədə '± Δ' (məsələn, 5 dəq) və nonce təkrar sorğularını rədd edin.
Webhook üçün: sabit 'event _ id' və inbox cədvəlini istifadə edin - bu yalnız nonce daha etibarlıdır.
Təkrar çatdırılma (retraj) yenilərini yaratmaq əvəzinə eyni ts/nonce/event_id istifadə etməlidir.

7) Multi-tenant və regionlar

per tenant/region açarlarını saxlayın: 'kid = <tenant>: <region>: <key _ id>'.
Gizli hovuzları və limitləri bölüşün; data residency saxlayın.
Başlıqlarda/kanonikalizasiyada 'X-Tenant' və bölgə yoxlanılan kontekstin bir hissəsidir.

8) Açarların idarə edilməsi və rotasiya

Açar reyestri (KMS/Vault): 'kid', növü, alqoritmi, statusu ('active', 'deprecating', 'retired'), 'valid _ from/valid _ to'.
Dual-secret: cari və növbəti açarı eyni vaxtda saxlayın (alıcı hər ikisini qəbul edir).
Cədvəl və hadisə üzrə rotasiya (güzəşt).
Key pinning (mümkünsə) və açar materiallarına çıxışın məhdudlaşdırılması.
Açarlara və onlarla hərəkətlərə giriş qeydləri.

9) mTLS və OAuth ilə birləşməsi

mTLS kanal və sertifikat səviyyəsində «siz kimsiniz» yoxlayır.
İmza mesajı qoruyur (proxy/keşi/növbələr vasitəsilə faydalıdır).
OAuth/JWT autentifikasiya/icazəni tamamlayır, lakin özü bədənin bütövlüyünə zəmanət vermir (kanonikalizasiyada imzalanmasa).
Ən yaxşı təcrübələr: mTLS + bədən imzası (Digest) + HMAC/ECDSA + qısa 'ts' interval.

10) Səhvlər və cavab kodları

'401 SIGNATURE_INVALID' - səhv imza/alqoritm.
'401 KEY_REVOKED' -' kid 'etibarsız/vaxtı keçmiş.
'400 TIMESTAMP_OUT_OF_RANGE' - saat/pəncərə.
'409 NONCE_REPLAYED' - təkrar aşkar edilmişdir.
'400 DIGEST_MISMATCH' - bədən dəyişdirilib.
'415 UNSUPPORTED_ALGORITHM' - həll olunmamış' alg '.
'429 TOO_MANY_ATTEMPTS' - açar/tenant üzrə trottling.

Maşın oxunan 'error _ code' -də dəqiq səbəbi vurun; sirləri/kanonikalizasiyanı «olduğu kimi» qaytarmayın.

11) Müşahidə və audit

• `verify_p95_ms`, `verify_error_rate`, `digest_mismatch_rate`, `replay_blocked_rate`, `alg_usage{hmac,ecdsa}`, `clock_skew_ms`.
• Loqlar (struktur): 'kid', 'alg', 'tenant', 'region', 'ts', 'nonce', 'digest _ hash', 'decision', 'reason'.
• Trace: 'signature' atributları. kid`, `signature. alg`, `signature. ts_skew`.
• Audit: dəyişməz rotasiya jurnalı, açar və qəbul bayraqlarından istifadə.

12) Performans

Bədəni axınla heşləşdirin (yaddaşda saxlamayın).
Qısa TTL və hadisə əlilliyi ilə 'kid' ilə ictimai açarları cache edin.
edge/gateway ön yoxlamalar (ts/nonce/format).
HMAC ECDSA daha sürətli; ECDSA xarici inteqrasiya və «ayrılmaz» açarlar üçün daha rahatdır.

13) Test

Fikstura dəstləri: eyni sorğular → eyni kanonikalizasiya/imza; «çirkli» boşluqlar/sifariş query/başlıqlar → davamlı.
Negative: səhv 'kid/alg', modifikasiya edilmiş bədən/host, nonce təkrar, köhnəlmiş ts, clock skew.
Property-based: Hər hansı bir ekvivalent sorğu bir canonical-line verir.
Interop: Xaç-dil yoxlamaları (Go/Java/Node/Python).
Chaos: gecikmələr, retralar, açarın dəyişdirilməsi.

14) Playbooks (runbooks)

1. Sıçrayış 'SIGNATURE _ INVALID'

Açarların rotasiyasını, rassinxron saatını, göndəricidə kanonikalizasiya dəyişikliklərini yoxlayın.
Köhnə 'kid' üçün müvəqqəti olaraq 'dual-accept' işə salın, tərəfdaşa bildirin.

2. Böyümə 'REPLAYED'

nonce TTL saxlama artırmaq, göndərici retrainer yoxlamaq, clock skew yoxlamaq.
edge-də sui-istifadə IP/ASN bağlayın.

3. 'DIGEST _ MISMATCH' kütləvi

Proxy/sıxılma/başlıqların yenidən yazılmasını yoxlayın; kanonikalizasiya versiyasını düzəltmək.
Cisim/başlıqları pozan vasitəçiləri söndürün.

4. Açarın güzəşti

Dərhal revoke 'kid', 'next _ kid' tərcümə, bütün sirləri/tokenləri bərpa, giriş auditi.

15) Tipik səhvlər

ardıcıllığı qeyd etmədən «bədən hissəsi» və ya JSON imzalayın → boşluq sahələri.
'Digest' → proxy olmaması bədəni hiss olunmadan dəyişdirə bilər.
Uzun pəncərə 'ts' olmadan nonce → açılır.
KMS/Vault olmadan mühit dəyişənlərində sirləri saxlayın.
constant-time deyil imza müqayisə.
Kanonikalizasiyada 'host '/' path' -ə məhəl qoymayın → yönləndirmə hücumları.
Müxtəlif tenant və bölgələrin 'kid' qarışdırın.

16) Satış öncəsi yoxlama siyahısı

• Kanonikalizasiya formatı müəyyən edilmişdir (method, path + query, content-type, Digest, ts, nonce, host, tenant).
• HMAC/ECDSA kid ', açar reyestri və iki gizli ilə həyata keçirilmişdir.
• Anti-replay (nonce + ts) və veb-hook inbox/event_id saxlama daxildir.
• Xüsusi səhv kodları/retraj siyasəti və trottling per tenant/key.
• Müşahidə: verify metrlər, log, izləmə, sıçrayışlar üçün həyəcan.
• Açarların rotasiyası avtomatlaşdırılmışdır; audit və giriş hüquqları məhduddur.
• Kanonikalizasiya və dillərarası uyğunluq üçün test dəstləri.
• 3-4 dildə və fiksturlarda nümunə ilə inteqratorlar üçün sənədləşmə.
• mTLS həssas inteqrasiya üçün daxil; JWT yalnız əlavə olaraq istifadə olunur, bədən imzasını əvəz etmir.

Nəticə

İmza və sorğuların yoxlanılması «bir başlıq» deyil, nizam-intizamdır: aydın kanonikalizasiya, qısa vaxt pəncərələri, anti-replay, açarların rotasiyası və müşahidə. Bütün inteqrasiyalar üçün vahid standart qurun (API və vebhuk), 'kid '/KMS istifadə edin, rotasiya zamanı iki açar qəbul edin və konturlarınız dəyişdirilməyə davamlı, proqnozlaşdırıla bilən və audit üçün əlverişli olacaq.