Кол коюу жана суроо-талаптарды текшерүү

Суроо-талаптын кол тамгасы жөнөтүүчүнүн аныктыгын жана мазмундун бүтүндүгүн далилдейт. TLS айырмаланып (бул каналды коргойт), прикладдык кол ар бир билдирүүнү текшерилүүчү жана прокси, кэш жана кийинкиге калтырылган жеткирүүгө туруктуу кылат.

1. Аныктыгы (ким жөнөткөн) жана бүтүндүгү (өзгөргөн эмес).

2. Кайталанбастык (репликалардан коргоо).

3. Транспорттон ажыратуу (HTTP, кезек, вебхуктардын үстүнөн иштейт).

4. Аудитордук (айлар өткөндөн кийин кайталануучу текшерүү).

1) коркунуч модели (минималдуу)

жолдо дене/аталыштарды алмаштыруу.
Реплика (легитимдүү суроо-талаптын кайталанышы).
Downgrade/strip кол тамгалар.
Интеграциянын сырларын уурдоо.
Синхрондуу эмес саат (clock skew) жана узун кезек.

2) Primitive тандоо

HMAC (симметрия): жөнөкөй жана тез, ачкыч эки тарапта сакталат. B2B-Webhook жана ички API үчүн ылайыктуу.
RSA/ECDSA (асимметрия): жөнөтүүчүнүн жеке ачкычы, алуучунун ачык ачкычы. Ачык интеграция үчүн ылайыктуу жана сырды бөлүшпөө маанилүү болгондо.
mTLS: транспорттук денгээлде өз ара аутентификация; көбүнчө НМАС/дененин кол тамгасы менен айкалышат.
JWT/JWS: bearer-токендер жана өзүн-өзү камсыз маркалар үчүн ыңгайлуу; Денеге кол коюу үчүн + JWS Detached/HTTP Message Signatures каноникализациясын колдонуу жакшы.
HTTP Message Signatures (тандалган суроо бөлүктөрүнүн кол тамгасы): REST үчүн заманбап ыкма.

Сунуш: вебхуктар үчүн - HMAC + timestamp + nonce + дене канонизациясы; коомдук API үчүн - HTTP Message Signatures же JWS; жогорку тобокелдиктер - mTLS кошуу.

3) Канонизация (биз так эмнеге кол коёбуз)

Эки тарап бирдей калыбына келтирген детерминацияланган сапка кол коюу керек.

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-параметрлердин жолун жана тартибин нормалдаштырыңыз.
• Боштуктар/Unicode/Registr- бекитүү (мисалы, lower-case аталыштары, trim).
• Чоң денелер - хештегиле (Digest), "кандай болсо, ошондой" эмес.

4) аталыштары формат

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

Бул жерде 'kid '/' keyId' реестрден ачкычты тандоого мүмкүндүк берет (ротацияны караңыз).

5) Кабыл алуу тарабында текшерүү

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 салыштыруу HMAC, сактоо 'nonce '/' (ts, event_id)' тез KV (TTL ≥ жеткирүү терезе).

6) Анти-реплика жана терезелер

Timestamp + Nonce: улуу '± Δ' (мисалы, 5 мин) жана бул терезеде nonce кайталоо өтүнүчүн четке кагуу.
Webhook үчүн: туруктуу 'event _ id' жана inbox таблицасын колдонуңуз - бул nonce гана эмес.
Кайра жеткирүү (retry) жаңы эмес, ошол эле ts/nonce/event_id колдонуу керек.

7) Көп-тенант жана региондор

per tenant/region ачкычтарын сактаңыз: 'kid = <tenant>: <region>: <key _ id>'.
Жашыруун бассейндерди жана лимиттерди бөлүшүү; data residency сактоого.
Баш макалада/канонизацияда 'X-Tenant' жана аймак текшерилүүчү контексттин бир бөлүгү болуп саналат.

8) Ачкычтарды башкаруу жана ротация

Keys реестри (KMS/Vault): 'kid', түрү, алгоритми, статусу ('active', 'deprecating', 'retired'), 'valid _ from/valid _ to'.
Double-secret: учурдагы жана кийинки ачкычты бир эле учурда сактаңыз (кабыл алуучу экөөнү тең кабыл алат).
График жана окуя боюнча ротация (компромисс).
Key pinning (мүмкүн болушунча) жана ачкыч материалдарына кирүүнү чектөө.
Ачкычтарга жана алар менен иш-аракеттерге кирүү логдору.

9) mTLS жана OAuth менен айкалышы

mTLS канал жана күбөлүк деъгээлинде "сен ким" текшерет.
Кол билдирүүнү коргойт (прокси/кэши/кезек аркылуу пайдалуу).
OAuth/JWT аутентификацияны/авторизацияны толуктайт, бирок өзү дененин бүтүндүгүнө кепилдик бербейт (эгерде каноникализацияда кол коюлбаса).
Best Practices: mTLS + кол дене (Digest) + HMAC/ECDSA + кыска 'ts' -интервал.

10) Каталар жана жооп коддору

'401 SIGNATURE_INVALID' - туура эмес кол тамга/алгоритм.
'401 KEY_REVOKED' -' kid 'жараксыз/мөөнөтү өтүп кеткен.
'400 TIMESTAMP_OUT_OF_RANGE' - саат/терезе.
'409 NONCE_REPLAYED' - кайталоо табылды.
'400 DIGEST_MISMATCH' - орган өзгөртүлгөн.
'415 UNSUPPORTED_ALGORITHM' - чечилбеген' alg '.
'429 TOO_MANY_ATTEMPTS' - ачкыч/тенант боюнча троттлинг.

Машинада окуй турган 'error _ code' так себебин тепкиле; сырларды/каноникализацияны "ошол бойдон" кайтарып бербеңиз.

11) Байкоо жана аудит

• `verify_p95_ms`, `verify_error_rate`, `digest_mismatch_rate`, `replay_blocked_rate`, `alg_usage{hmac,ecdsa}`, `clock_skew_ms`.
• Логи (структуралык): 'kid', 'alg', 'tenant', 'region', 'ts', 'nonce', 'digest _ hash', 'decision', 'reason'.
• Trace: 'signature' атрибуттары. kid`, `signature. alg`, `signature. ts_skew`.
• Аудит: өзгөрүлбөгөн айлануу журналы, ачкычтарды жана кабыл алуу желектерин колдонуу.

12) аткаруу

Денени стриминг менен хештегиле (эстен чыгарбаңыз).
Кыска TTL жана иш-чара майыптыгы менен 'kid' боюнча коомдук ачкычтарды кэш.
edge/gateway алдын ала текшерүү (ts/nonce/формат).
HMAC тезирээк ECDSA; ECDSA тышкы бириктирүү жана "бөлүнбөгөн" ачкычтар үчүн ыңгайлуу болуп саналат.

13) сыноо

Фикстура топтомдору: бирдей суроолор → бирдей канонизация/кол тамга; "кир" боштуктар/тартиби query/баш → туруктуу.
Negative: туура эмес 'kid/alg', өзгөртүлгөн дене/host, кайталоо nonce, эскирген ts, clock skew.
Property-based: ар кандай эквиваленттүү суроолор бир канондук-сапты берет.
Interop: кросс-тилдик текшерүү (Go/Java/Node/Python).
Chaos: кечигүү, retra, ачкычын өзгөртүү "учуу".

14) Playbooks (runbooks)

1. 'SIGNATURE _ INVALID'

Ачкычтардын айлануусун, рассинхрондук саат, жөнөтүүчүдөгү канонизациянын өзгөрүшүн текшерүү.
Убактылуу эски 'kid' үчүн 'dual-accept' киргизип, өнөктөш билдирүүгө.

2. Өсүү 'REPLAYED'

nonce сактоо TTL жогорулатуу, жөнөтүүчүдөн ретрансляторлорду текшерүү, clock skew текшерүү.
edge боюнча IP/ASN кыянаттык менен жабуу.

3. 'DIGEST _ MISMATCH' массалык түрдө

Proxy/кысуу/аталыштарын кайра текшерүү; канонизациянын версиясын бекитүү.
Денени/баш макалаларды бузган ортомчуларды өчүрүү.

4. Ачкычтын компромисстери

Дароо revoke 'kid', которуу 'next _ kid', бардык сырларды/белгилерди калыбына келтирүү, кирүү аудити.

15) типтүү каталар

Кол коюу "дене бөлүгү" же JSON тартиби жок → талааларды алмаштыруу үчүн алсыздык.
Жок 'Digest' → прокси байкабай денени өзгөртө алат.
узун терезе 'ts' nonce → ачык реплика жок.
KMS/Vault жок чөйрө өзгөрмөлүү сырларды сактоо.
constant-time эмес, кол салыштыруу.
Канонизацияда 'host '/' path' дегенге көңүл бурбоо → багыттоо чабуулдары.
аралаштыруу 'kid' ар кандай тенанттар жана региондор.

16) Азык-түлүктүн алдындагы чек-тизме

• Канонизация форматы аныкталган (method, path + query, content-type, Digest, ts, nonce, host, tenant).
• ишке ашырылган HMAC/ECDSA менен 'kid', Keys реестри жана эки-жашыруун.
• Камтылган анти-реплика (nonce + ts) жана сактоо inbox/event_id Webhook үчүн.
• орнотулган ката коддору/retrains саясаты жана Trottling per tenant/key.
• Байкоо: verify метрика, Логи, Tracking, Splash боюнча Алерт.
• Ачкычтарды айлантуу автоматташтырылган; аудит жана кирүү укугу чектелүү.
• Канонизация жана тилдер аралык шайкештик үчүн сыноо топтомдору.
• 3-4 тилдерде жана фикстуралар үлгүсү менен интеграторлор үчүн документтер.
• mTLS сезимтал бириктирүү үчүн киргизилген; JWT гана кошумча катары колдонулат, дене кол алмаштыруу эмес.

Корутунду

Кол коюу жана өтүнүчтөрдү текшерүү - бул "бир аталыш" эмес, тартип: так канонизация, кыска убакыт терезелери, анти-реплика, ачкычтарды айлантуу жана байкоо жүргүзүү. Бардык интеграциялар үчүн бирдиктүү стандарт түзүңүз (API жана веб-хакерлер), 'kid '/KMSди колдонуңуз, ротацияда эки ачкычты кабыл алыңыз жана сиздин контурларыңыз алмаштырууга туруктуу, алдын ала айтууга боло турган жана аудит үчүн ыңгайлуу болот.