Taleplerin imzalanması ve doğrulanması

Talebin imzası, gönderenin gerçekliğini ve içeriğin bütünlüğünü kanıtlar. TLS'nin (kanalı koruyan) aksine, uygulanan imza her iletiyi doğrulanabilir ve proxy, önbellek ve gecikmeli dağıtıma karşı dirençli hale getirir.

1. Özgünlük (kim gönderdi) ve bütünlük (değişmedi).

2. Benzersizlik (tekrarlara karşı koruma).

3. Aktarımdan ayırma (HTTP'nin üstünde çalışır, kuyruklar, web kitapları).

4. Denetlenebilirlik (aylar sonra tekrarlanabilir kontrol).

1) Tehdit modeli (minimum)

Rota boyunca gövde/başlıkların değiştirilmesi.
Tekrar oynatma (meşru isteği tekrarla).
Downgrade/strip altyazı.
Entegrasyon sırlarını çalmak.
Senkronize olmayan saat (saat eğriliği) ve uzun kuyruklar.

2) İlkel seçimi

HMAC (simetri): basit ve hızlı, anahtar her iki tarafta da saklanır. B2B webhook'lar ve dahili API'ler için uygundur.
RSA/ECDSA (asimetri): Göndericiden özel anahtar, alıcıdan genel anahtar. Açık entegrasyonlar için ve bir sırrı paylaşmamanın önemli olduğu durumlarda uygundur.
mTLS: taşıma katmanı karşılıklı kimlik doğrulaması genellikle NMAC/gövde imzası ile birleştirilir.
JWT/JWS: Taşıyıcı belirteçler ve kendi kendine yeterli pullar için uygundur; Gövdeyi imzalamak için, kanonikleştirme + JWS Müstakil/HTTP Mesaj İmzalarını kullanmak daha iyidir.
HTTP İleti İmzaları (isteğin seçilen bölümlerinin imzası): REST için modern yaklaşım.

Öneri: webhooks için - HMAC + zaman damgası + nonce + vücut canonicalization; Genel API için - HTTP İleti İmzaları veya JWS; Yüksek risklerde - mTLS ekleyin.

3) Kanonikleştirme (tam olarak neyi imzalıyoruz)

Her iki tarafça da eşit derecede kurtarılabilir bir deterministik dize imzalamanız gerekir.

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)

• Sorgu parametrelerinin yolunu ve sırasını normalleştirin.
• Spaces/unicode/case - fix (örneğin, küçük harfli başlıklar, trim).
• Büyük gövdeler - hash (Digest), "olduğu gibi" açılmaz.

4) Başlık 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' kayıt defterinden bir anahtar seçmenize izin verir (rotasyona bakın).

5) Alıcı ucunda doğrulama

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"

Sabit zamanlı HMAC karşılaştırması, hızlı KV'de 'nonce'/' (ts, event_id)' saklama (TTL ≥ teslimat penceresi).

6) Anti-tekrar ve pencereler

Zaman damgası + Nonce: '± Δ'den eski istekleri reddet (örn. 5 dk) ve nonce bu pencerede yeniden çalışır.
Webhooks için: kararlı bir 'event _ id've bir gelen kutusu tablosu kullanın - bu sadece nonce'den daha güvenilirdir.
Yeniden teslimat (retrays) aynı ts/nonce/event_id kullanmalı, yenilerini üretmemelidir.

7) Çok kiracı ve bölgeler

Kiracı/bölge başına anahtarları saklayın: 'kid = <tenant>: <region>: <key _ id>'.
Ayrı gizli havuzlar ve limitler; veri ikametini gözlemleyin.
Başlıklarda/kanonikleştirme, 'X-Kiracı' belirtin ve bölge kontrol edilen bağlamın bir parçasıdır.

8) Anahtar yönetimi ve rotasyon

Anahtar kayıt defteri (KMS/Vault): 'kid', tip, algoritma, durum ('aktif ',' amortisman ',' emekli '),' valid _ from/valid _ to '.
Dual-secret: Geçerli ve sonraki anahtarı aynı anda tutun (alıcı her ikisini de kabul eder).
Bir programda ve bir olayda rotasyon (uzlaşma).
Anahtar sabitleme (mümkünse) ve anahtar malzemelere erişimi kısıtlama.
Anahtarlara erişim ve onlarla yapılan işlemlerin günlükleri.

9) mTLS ve OAuth ile kombinasyon

mTLS, sertifika düzeyinde kanalı ve'kim olduğunuzu "kontrol eder.
İmza mesajı korur (proxy'ler/önbellekler/kuyruklar aracılığıyla kullanışlıdır).
OAuth/JWT kimlik doğrulama/yetkilendirmeyi tamamlar, ancak tek başına vücudun bütünlüğünü garanti etmez (kanonikleştirmede imzalanmadıkça).
En iyi uygulamalar: mTLS + vücut imzası (Digest) + HMAC/ECDSA + kısa 'ts' -interval.

10) Hatalar ve yanıt kodları

'401 SIGNATURE_INVALID' geçersiz bir imza/algoritmadır.
'401 KEY_REVOKED' -'çocuk' geçersiz/süresi dolmuş.
'400 TIMESTAMP_OUT_OF_RANGE' - saat/pencere.
'409 NONCE_REPLAYED' - Yineleme tespit edildi.
'400 DIGEST_MISMATCH' - vücut değişti.
'415 UNSUPPORTED_ALGORITHM' çözülmemiş bir' alg '.
'429 TOO_MANY_ATTEMPTS' - anahtar/kiracı azaltma.

Makinede okunabilir 'error _ code' içindeki kesin nedeni tekmeleyin; Sırları/kanonikleştirmeyi "olduğu gibi" iade etmeyin.

11) Gözlemlenebilirlik ve denetim

• 'verify _ p95 _ ms', 'verify _ error _ rate', 'digest _ mismatch _ rate', 'replay _ blocked _ rate', 'alg _ usage {hmac, ecdsa}','clock _ skew _ ms '.
• Loglar (yapısal): 'kid', 'alg', 'tenant', 'region', 'ts', 'nonce', 'digest _ hash', 'decision', 'reason'.
• İzleme: niteliklerin imzası. Çocuk ',' imza. alg ',' imzası. ts_skew'.
• Denetim: değişmez rotasyon günlüğü, anahtar kullanımı ve tolerans bayrakları.

12) Performans

Vücudu akışla karıştırın (hafızanızda tutmayın).
Açık anahtarları'çocuk'tarafından kısa TTL ve etkinliğe göre engellilik ile önbelleğe alın.
Kenar/ağ geçidinde, ön kontroller yapın (ts/nonce/format).
HMAC, ECDSA'dan daha hızlıdır. ECDSA, harici entegrasyonlar ve "paylaşılmayan" anahtarlar için daha uygundur.

13) Test etme

Fikstür setleri: aynı istekler - aynı kanonikleştirme/imza; Kirli alanlar/sorgu düzeni/- başlıklar kararlı.
Negatif: geçersiz'çocuk/alg ', değiştirilmiş vücut/host, nonce tekrar, eskimiş ts, saat eğriliği.
Özellik tabanlı: Herhangi bir eşdeğer sorgu tek bir kanonik dize üretir.
Interop: çapraz dil kontrolleri (Go/Java/Node/Python).
Kaos: gecikmeler, geri çekilmeler, anında anahtar değişiklikleri.

14) Playbook'lar (runbook'lar)

1. 'SIGNATURE _ INVALID' spike

Anahtar rotasyonunu, saat yanlış hizalamasını, göndericideki kanonikleştirme değişikliklerini kontrol edin.
Eski'çocuk "için geçici olarak 'çift kabul' seçeneğini etkinleştirin, ortağınızı bilgilendirin.

2. 'TEKRARLANAN' büyüme

Nonce depolamanın TTL'sini artırın, göndericideki geri göndericileri kontrol edin, saat eğriliğini kontrol edin.
Kötü amaçlı IP/ASN'yi kenardan geçersiz kılın.

3. 'DIGEST _ MISMATCH' kitlesel olarak

Proxy/sıkıştırma/yeniden yazma başlıklarını kontrol edin; Kanonikleştirme versiyonunu düzeltin.
Gövde/başlık davetsiz misafirlerini devre dışı bırak.

4. Anahtar uzlaşma

Hemen'çocuk'u iptal et, 'next _ kid'e çevir, tüm sırları/belirteçleri yeniden oluştur, erişimi denetle.

15) Tipik hatalar

Siparişi düzeltmeden bir "gövde parçası" veya JSON imzalamak - alan permütasyonuna karşı güvenlik açığı.
Bir 'Digest' - proxy yokluğu fark edilmeden vücudu değiştirebilir.
Nonce olmayan uzun bir 'ts' penceresi tekrar oynatmaya açıktır.
KMS/Vault olmadan ortam değişkenlerinde sır saklayın.
İmzayı karşılaştırın, sabit zaman değil.
Canonicalization 'host'/' path' yoksaymak - ileri saldırı.
'Çocuk' farklı kiracı ve bölgeleri karıştırın.

16) Satış öncesi kontrol listesi

• Kanonikleştirme biçimi tanımlanmıştır (yöntem, yol + sorgu, içerik türü, Özet, ts, nonce, host, kiracı).
• Uygulanan HMAC/ECDSA ile'çocuk ', anahtar kayıt defteri ve çift gizli.
• Anti-replay (nonce + ts) ve web kitapları için inbox/event_id depolama dahil.
• Yapılandırılmış hata kodları/yeniden ödeme politikası ve kiracı/anahtar başına azaltma.
• Gözlemlenebilirlik: ölçümleri, günlükleri, izi, patlamalar için uyarıları doğrulayın.
• Anahtar rotasyon otomatiktir; denetim ve erişim hakları sınırlıdır.
• Kanonikleştirme ve diller arası uyumluluk test kitleri.
• Entegratörler için 3-4 dilde örnek içeren belgeler ve düzeltmeler.
• Hassas entegrasyonlar için etkinleştirilen mTLS; JWT sadece bir ek olarak kullanılır, vücudun imzasının yerine geçmez.

Sonuç

İstekleri imzalamak ve doğrulamak'tek başlık'değil, bir disiplindir: açık kanonlaştırma, kısa zaman pencereleri, anti-replay, anahtar döndürme ve gözlemlenebilirlik. Tüm entegrasyonlar (API'ler ve webhook'lar) için tek bir standart oluşturun,'çocuk'/KMS kullanın, rotasyon sırasında iki tuşu kabul edin ve konturlarınız sahteciliğe karşı dirençli, öngörülebilir ve denetlenmesi kolay hale gelecektir.