Сұрау салуларға қол қою және тексеру

Сұрау салудың қолы жіберушінің түпнұсқалығын және мазмұнының бүтіндігін дәлелдейді. TLS-ден (арнаны қорғайтын) айырмашылығы, қолданбалы қолтаңба әрбір хабарды тексеруге және прокси, кэш және кейінге қалдырылған жеткізілімге төзімді етеді.

1. Түпнұсқалық (кім жіберді) және тұтастық (өзгерген жоқ).

2. Қайталанбаушылық (реплеядан қорғау).

3. Көліктен ажырату (HTTP, кезек, вебхук үстінде жұмыс істейді).

4. Аудиттелуі (айлардан кейін қайталанатын тексеру).

1) Қатерлер моделі (минимум)

Жүру жолында денені/тақырыптарды ауыстыру.
Реплика (заңды сұрауды қайталау).
Қолтаңба тақырыптарын Downgrade/strip.
Интеграция құпияларын ұрлау.
Синхронды емес сағаттар (clock skew) және ұзақ кезектер.

2) Примитив таңдау

HMAC (симметрия): қарапайым және жылдам, кілт екі жақта да сақталады. B2B вебхуктер мен ішкі 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 параметрлерінің жолы мен тәртібін қалыпқа келтіріңіз.
• Бос орындар/юникод/регистр - белгілеңіз (мысалы, 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 қайталауларын қабылдамаңыз.
Вебхуктар үшін: тұрақты 'event _ id' және inbox-кестені пайдаланыңыз - бұл тек nonce емес.
Қайта жеткізу (ретра) жаңаларын генерациялаудан басқа, сол ts/nonce/event_id пайдалануы тиіс.

7) Мульти-тенант және өңірлер

per tenant/region кілттерін сақтаңыз: 'kid = <tenant>: <region>: <key _ id>'.
Құпия пулдар мен лимиттерді бөлісіңіз; data residency бағдарламасын сақтаңыз.
Тақырыптарда/каноникаландыруда 'X-Tenant' дегенді және аймақты көрсетіңіз - бұл тексерілетін контекстің бөлігі.

8) Кілттерді басқару және ротация

Кілттер тізілімі (KMS/Vault): 'kid', түрі, алгоритмі, мәртебесі ('active', 'deprecating', 'retired'), 'valid _ from/valid _ to'.
Dual-secret: ағымдық және келесі кілтті бір уақытта сақтаңыз (қабылдағыш екеуін де қабылдайды).
Кесте бойынша және оқиға бойынша ротация (компромисс).
Key pinning (мүмкіндігінше) және кілттер материалдарына қатынауды шектеу.
Кілттерге және олармен әрекеттерге қол жеткізу логтары.

9) mTLS және OAuth бірге

mTLS арнаны және «сіз кімсіз» дегенді куәлік деңгейінде тексереді.
Қолтаңба хабарды қорғайды (прокси/кеши/кезек арқылы пайдалы).
OAuth/JWT аутентификацияны/авторизацияны толықтырады, бірақ дененің бүтіндігіне кепілдік бермейді (егер оған каноникализацияда қол қойылмаса).
Үздік тәжірибелер: 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) Өнімділік

Денені стримингпен хештеңіз (есте сақтаңыз).
Ашық кілттерді 'kid' бойынша қысқа TTL және оқиға бойынша мүгедектікпен кэштеңіз.
edge/gateway алдын ала тексерулерді (ts/nonce/пішім) шығарыңыз.
HMAC ECDSA-дан жылдам; ECDSA сыртқы интеграциялар мен «бөлінбейтін» кілттер үшін ыңғайлы.

13) Тестілеу

Фикстуралар жиынтығы: бірдей сұрау → бірдей каноникализация/қолтаңба; «лас» бос орындар/query/тақырыптар тәртібі → тұрақты.
Negative: дұрыс емес 'kid/alg', өзгертілген дене/host, қайталау nonce, ескірген ts, clock skew.
Property-based: кез келген эквивалентті сұраулар бір canonical-жолды береді.
Interop: тілдік тексеру (Go/Java/Node/Python).
Chaos: кідірістер, ретрациялар, «ұшу» кілтін ауыстыру.

14) Плейбуктар (runbooks)

1. 'SIGNATURE _ INVALID' бумасы

Кілттердің ротациясын, рассинхрон clock, жіберушідегі каноникаландырудың өзгерістерін тексеру.
Ескі 'kid' үшін 'dual-accept' дегенді уақытша қосу, серіктеске хабарлау.

2. 'REPLAYED' өсуі

nonce сақтау TTL ұлғайту, жіберушіде ретрайнерлерді салыстыру, clock skew тексеріңіз.
Теріс пайдаланатын IP/ASN edge жабу.

3. 'DIGEST _ MISMATCH' жаппай

Прокси/компрессия/тақырыптардың қайта жазылуын тексеру; каноникализацияның нұсқасын тіркеу.
Денені/тақырыптарды бұзатын делдалдарды өшіру.

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', кілттер тізілімі және dual-secret іске асырылды.
• Анти-реплика (nonce + ts) және вебхуктер үшін inbox/event_id сақтау қосылған.
• Теңшелген қате кодтары/Ретра саясаты және троттлинг per tenant/key.
• Бақылануы: verify метрикасы, логы, трассировка, жарылыс алаңдары.
• Кілттердің ротациясы автоматтандырылған; аудит және қол жеткізу құқықтары шектелген.
• Каноникализацияға және тіларалық үйлесімділікке арналған тест-жиынтықтар.
• Мысалы 3-4 тілде және фикстуралары бар интеграторларға арналған құжаттама.
• mTLS сезімтал интеграциялар үшін қосылған; JWT тек қосымша ретінде пайдаланылады, дененің қолтаңбасын ауыстырмайды.

Қорытынды

Сұрау салуларға қол қою және верификациялау - бұл «бір тақырып» емес, тәртіп: нақты каноникализация, қысқа уақыт терезелері, анти-реплика, кілттерді ротациялау және бақылау. Барлық интеграциялар үшін бірыңғай стандарт (API және веб-хуктер) жасаңыз, 'kid '/KMS пайдаланыңыз, ротация кезінде екі кілтті қабылдаңыз және сіздің контурларыңыз ауыстыруға төзімді, болжамды және аудитке ыңғайлы болады.