Підпис вебхука HMAC, мітка часу і захист від replay

Твій приймач приймає подію від будь-кого

Минулого уроку ти навмисно лишив у ньому дірку. Сьогодні ти її закриваєш — і закриваєш так, як це зроблено у Stripe, Slack і GitHub

Чого навчишся за цей урок

• підписувати запит так, щоб підробити його не вийшло навіть з адресою на руках;
• відрізняти чужий запис у своєму журналі від власного;
• відхиляти запит, який хтось перехопив учора й надсилає сьогодні;
• не приймати той самий запит удруге, навіть якщо він прийшов за секунду;
• описати свою схему так, щоб чужа людина надіслала тобі подію без твоїх підказок.

Хід уроку

Слова HMAC, replay і nonce поки нічого не означають. Розберемо їх по черзі, кожне на своєму місці.

Урок 11 закінчився файлом api/hook.php. Він дописує рядок у ~/data/events.jsonl кожному, хто надішле POST. Будь-кому.

Урок 3 додавав до схожого приймача токен у заголовку. Це вже краще, але сьогодні ти зробиш крок далі. Замість «покажи пароль» буде підпис самого тіла запиту.

Що ти зробиш за 120 хвилин

1. подивишся, як учитель кладе чужий запис у твій журнал, знаючи лише URL;
2. розберешся, чим HMAC відрізняється від звичайного хеша;
3. порахуєш підпис у лабораторії просто на цій сторінці й побачиш, що робить один змінений символ;
4. додаси в hook.php перевірку X-Signature через hash_hmac і hash_equals;
5. додаси вікно 300 секунд для X-Timestamp;
6. заведеш сховище nonce у ~/data/nonces/ і закриєш повтор остаточно;
7. опишеш свою схему в api/security.md — так, щоб чужа команда змогла надіслати тобі запит, не питаючи тебе.

Атака-демо: чужий запис у твоєму журналі

Учитель знає тільки адресу твого ендпойнта. Цього достатньо, щоб у твоєму events.jsonl з'явився рядок, якого ти не писав

Двісті. Приймач відповів «прийнято», бо заперечити йому нічим: він не знає, хто це був.

У журналі цей рядок не відрізняється від справжнього нічим. Той самий source, той самий формат, та сама структура. Відрізнити його ти не зможеш і завтра.

«Ну я ж додам токен» — і чому цього мало

На уроці 3 ти клав у заголовок X-Auth-Token довгий випадковий рядок із ~/.env. Це вже щось: випадковий бот його не вгадає.

Але подивись, що з цим токеном відбувається далі. Він їде мережею в кожному запиті — і щоразу той самий.

HMAC: хеш, який уміє порахувати тільки той, хто знає секрет

Порахувати звичайний хеш може будь-хто. А порахувати його разом із твоїм секретом — тільки той, хто цей секрет знає

Уяви сургучеву печатку на конверті. Підробити відбиток без персня не вийде, а перевірити його може кожен, хто цей перстень бачив. Приблизно так працює й підпис запиту.

Почнімо з хеша. Це м'ясорубка в один бік: подаєш будь-який текст і отримуєш рівно 256 біт (у SHA-256). Зібрати текст назад із цих бітів неможливо.

Далі все тримається на двох його властивостях:

детермінованість

той самий вхід завжди дає той самий вихід. Інакше перевірити підпис було б неможливо в принципі.

лавинний ефект

змінив один біт входу — приблизно половина бітів виходу перевернулася. Не «схожий хеш», а зовсім інше число.

Чому не просто хеш від тіла

Ідея на вигляд логічна. Нехай відправник рахує sha256(тіло) і кладе результат у заголовок. А сервер перевіряє збіг.

Спробуй сам знайти, що з нею не так, перш ніж читати врізку.

Ось тут і з'являється HMAC. У м'ясорубку разом із повідомленням заходить секрет, який знають лише дві сторони. Без нього число не порахувати.

Розшифровується назва так: MAC — Message Authentication Code, код автентичності повідомлення. Літера H попереду означає «побудований на хеші». Ось означення з RFC 2104:

HMAC(K, m) = H( (K ⊕ opad) ‖ H( (K ⊕ ipad) ‖ m ) )

H     — хеш-функція, у нас SHA-256
K     — секрет, доповнений нулями до розміру блоку (для SHA-256 це 64 байти)
m     — повідомлення, яке підписуємо
ipad  — байт 0x36, повторений 64 рази
opad  — байт 0x5C, повторений 64 рази
‖     — просте склеювання байтів
⊕     — побітове «виключне або»

Секрет тут підмішується двічі, і щоразу по-різному. Це не примха авторів.

Проста схема sha256(секрет ‖ тіло) у хешів сімейства SHA-2 має відому ваду — атаку подовженням повідомлення. Зловмисник не знає секрету, але дописує байти в кінець тіла й рахує правильний підпис для нового, довшого тіла.

Подвійна конструкція HMAC це закриває. Тому власну схему вигадувати не треба — треба взяти готову hash_hmac().

Лабораторія підпису: рахуй сам і дивись, що ламається

Підпис нижче обчислюється по-справжньому, у твоєму браузері, через crypto.subtle з алгоритмом HMAC-SHA256. Це те саме число, яке видасть hash_hmac у PHP

Сервер у лабораторії — не справжній: це модель твого hook.php тут-таки на сторінці, з секретом 2f8b1c…2a8f, вікном 300 секунд і сховищем nonce в пам'яті вкладки. А от підпис рахується по-справжньому, тим самим алгоритмом, що й на сервері: скопіюй рядок і перевір echo -n '<рядок>' | openssl dgst -sha256 -hmac '<секрет>'.

Що ти щойно побачив

• змінив один символ у тілі — у підписі змінилося близько 60 символів із 64. Це не збіг: кожен шістнадцятковий символ має 1 шанс із 16 випадково лишитися тим самим, тож 64 × 15/16 = 60 — очікуване значення;
• змінив секрет — те саме. Підпис не «трохи інший», він інший увесь;
• жодної закономірності між зміною входу й зміною виходу немає. Саме тому підпис неможливо «підправити», знаючи старий.

Порівняння в сталий час: чому == тут вразливість

Підпис ти вже вмієш рахувати. Лишилося порівняти два рядки — і саме на цьому рядку коду ламаються дорослі проєкти

Порівняння рядків у будь-якій мові працює очевидно. Воно йде посимвольно й виходить на першій розбіжності. Швидко й правильно.

І саме тому небезпечно. Час відповіді сервера залежить від того, скільки перших символів підпису зловмисник угадав. Що більше вгадав, то довше відповідь.

// ✗ ВРАЗЛИВО: вихід на першій розбіжності
if ($sig !== $expected) { http_response_code(401); exit('bad signature'); }

// ✓ ПРАВИЛЬНО: сталий час, перший аргумент — відомий (наш) підпис
if (!hash_equals($expected, $sig)) { http_response_code(401); exit('bad signature'); }

hash_equals() є в PHP із версії 5.6 і не потребує розширень. Він спершу порівнює довжини. Потім проходить усі байти через XOR і накопичує різницю.

Тому він працює однаково довго, хоч рядки розійшлися на першому символі, хоч на останньому. Виміряти час і щось із нього дізнатися вже не вийде.

Порядок аргументів у документації заданий прямо. Перший — відомий рядок, той, що порахував ти. Другий — той, що прийшов ззовні.

Replay: правильний підпис, який усе одно ламає тобі дані

Найнеприємніша атака цього уроку тим, що в ній усе валідне. Підпис справжній, секрет не витік, тіло не змінене

Уяви квиток у кіно зі справжнім штрихкодом. Підробити його не вийшло б. А от відсканувати чужий і показати той самий код ще двадцять разів — цілком.

Із запитами буває так само. Твій вебхук приймає подію «зарахувати оплату 200 грн». Зловмисник не знає секрету й підробити підпис не може.

Зате він перехопив один валідний запит цілком: тіло і всі заголовки. І тепер надсилає його ще раз. І ще. І ще двадцять разів. Це й зветься replay-атакою — повтором.

Де це трапляється не в теорії

• сервіс-відправник не дочекався відповіді за таймаут і сам повторив доставку — той самий запит прийшов двічі, зловмисника немає взагалі;
• проксі або мобільна мережа продублювали запит;
• твій сервер відповів 500 уже після запису в журнал — відправник вважає, що не дійшло, і надсилає ще раз;
• хтось натиснув «Replay» просто в панелі сервісу — така кнопка є в Zapier, GitHub і Stripe, вона там навмисне.

Вікно допустимого віку: чому саме 5 хвилин

Відправник кладе в заголовок X-Timestamp час, коли він підписав запит. Сервер дивиться, наскільки цей час відстав від його власного

$age = abs(time() - (int)$ts);          // модуль: майбутнє теж підозріле
if ($age > 300) { http_response_code(401); exit('stale timestamp'); }

Модуль тут не для краси. Без нього пройде перевірку запит із міткою часу на добу вперед.

А далі він лежатиме в зловмисника як «вічний квиток». Годиться цілу добу й проходить щоразу.

Що робити з годинником у себе

Nonce: сервер пам'ятає, що цей запит уже був

На вході в клуб браслет надягають один раз і вдруге не приймають. Тут те саме, тільки браслет — це число в заголовку

Відправник кладе в кожен запит унікальний ідентифікатор. Це 16 випадкових шістнадцяткових символів, наприклад a1b2c3d4e5f60718.

Сервер перевіряє підпис, а потім дивиться: чи бачив він це число раніше? Якщо бачив, відповідає 409 Conflict і далі не робить нічого.

Таке одноразове число зветься nonce — від англійського number used once, «число, використане один раз».

Три способи зберігати nonce — і чому ми беремо перший

Симулятор replay: три обробники, один запит

Надішли валідний запит, потім натисни «повторити той самий» і дивись, як три різні обробники поводяться з тими самими байтами

Симулятор моделює три обробники й свій годинник. Підпис у ньому не рахується — це зроблено в лабораторії кроку 4; тут важлива сама логіка рішень і коди відповіді.

Порядок дій, який варто пройти

1. «надіслати новий валідний запит» — усі три пропускають, скрізь по 1 запису;
2. «повторити той самий» — A і B пропускають знову, C відповідає 409. Ось воно: підпис і мітка часу від повтору не рятують;
3. «час +6 хв», потім знову «повторити» — B нарешті відповідає 401 stale, A все ще пише запис;
4. «час +20 хв» і ще повтор — A продовжує писати. Він робитиме це вічно: у нього немає жодної причини відмовити.

Порядок перевірок і код відповіді на кожній

Перевірки не переставляються місцями довільно. Порядок — це теж частина захисту, і він має власне пояснення на кожному кроці

Коди, які ти віддаєш, і що вони означають відправнику

api/hook.php — версія з підписом

Це той самий файл із уроку 11, у який дописано кроки 0—5 конвеєра. Скопіюй, розберись у кожному рядку, залий по FTP

<?php
declare(strict_types=1);

const WINDOW    = 300;    // вікно допустимого віку запиту, секунд
const NONCE_TTL = 900;    // скільки тримаємо nonce: утричі більше за вікно
const MAX_BODY  = 8192;   // 8 КБ — більше подія важити не має

function fail(int $code, string $msg): void {
    http_response_code($code);
    header('Content-Type: text/plain; charset=utf-8');
    exit($msg);
}

// ── 0. Секрет: тільки з ~/.env, поза веб-корінням ────────────────
$home   = dirname(__DIR__, 2);            // ~/www/api -> ~/www -> ~
$env    = @parse_ini_file($home . '/.env');
$secret = (string)($env['HOOK_SECRET'] ?? '');
if ($secret === '') {
    fail(500, 'server misconfigured');    // 500 — бо зламався САМ сервер
}

// ── 1. Метод і розмір ─────────────────────────────────────────────
if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
    fail(405, 'method not allowed');
}
$raw = file_get_contents('php://input');
if (strlen($raw) > MAX_BODY) {
    fail(413, 'body too large');
}

// ── 2. Заголовки на місці й правдоподібні ────────────────────────
$ts    = (string)($_SERVER['HTTP_X_TIMESTAMP'] ?? '');
$nonce = (string)($_SERVER['HTTP_X_NONCE']     ?? '');
$sig   = (string)($_SERVER['HTTP_X_SIGNATURE'] ?? '');
if ($ts === '' || $nonce === '' || $sig === '') {
    fail(401, 'unsigned');
}
// nonce стане ІМЕНЕМ ФАЙЛУ — пускаємо лише hex, інакше буде ../../ у шляху
if (!ctype_digit($ts) || !preg_match('/^[a-f0-9]{16,64}$/i', $nonce)
                      || !preg_match('/^[a-f0-9]{64}$/i',    $sig)) {
    fail(401, 'bad headers');
}

// ── 3. Вік запиту: модуль, щоб «майбутнє» теж не проходило ───────
if (abs(time() - (int)$ts) > WINDOW) {
    fail(401, 'stale timestamp');
}

// ── 4. Підпис: від СИРИХ байтів, до будь-якого розбору ───────────
$expected = hash_hmac('sha256', $ts . '.' . $nonce . '.' . $raw, $secret);
if (!hash_equals($expected, strtolower($sig))) {   // відомий рядок — ПЕРШИЙ
    fail(401, 'bad signature');
}

// ── 5. Nonce: тільки ПІСЛЯ перевірки підпису ─────────────────────
$dir = $home . '/data/nonces';
if (!is_dir($dir) && !mkdir($dir, 0700, true) && !is_dir($dir)) {
    fail(500, 'nonce store unavailable');
}
foreach (glob($dir . '/*') ?: [] as $old) {        // прибираємо протухлі
    if (filemtime($old) < time() - NONCE_TTL) { @unlink($old); }
}
$fh = @fopen($dir . '/' . strtolower($nonce), 'x'); // 'x' — атомарно
if ($fh === false) {
    fail(409, 'replay');                            // файл уже існував
}
fclose($fh);

// ── 6. Тепер — і тільки тепер — розбираємо тіло ──────────────────
$data = json_decode($raw, true);
if (!is_array($data)) {
    fail(400, 'bad json');
}
$event = [
    'ts'     => gmdate('c'),
    'source' => substr((string)($data['source'] ?? 'unknown'), 0, 40),
    'type'   => substr((string)($data['type']   ?? 'event'),   0, 40),
    'title'  => substr((string)($data['title']  ?? ''),        0, 200),
];

// ── 7. Записуємо ПОЗА веб-корінням і відповідаємо ────────────────
$line = json_encode($event, JSON_UNESCAPED_UNICODE) . "\n";
if (file_put_contents($home . '/data/events.jsonl', $line, FILE_APPEND | LOCK_EX) === false) {
    fail(500, 'cannot write journal');
}
http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['ok' => true]);

fopen(..., 'x')

режим «створити, і тільки якщо файлу ще немає». На рівні файлової системи це атомарна операція: два однакові запити, що прийшли одночасно, не зможуть обидва створити той самий файл. Перевірка file_exists() плюс touch() такої гарантії не дає — між ними встигає прослизнути другий процес.

strtolower($nonce)

щоб A1B2 і a1b2 не стали двома різними файлами й не дали лазівку для повтору. Те саме зроблено з підписом перед hash_equals.

preg_match на nonce

nonce потрапляє в шлях до файлу. Без цього фільтра значення ../../www/index.php дозволило б створювати файли де завгодно. Правило уроку 4 діє й тут: усе, що прийшло ззовні, — недовірене.

$raw до json_decode

підпис рахується від байтів, що прийшли. Найпоширеніша причина «підпис ніколи не сходиться» — розібрати JSON і зібрати назад: пробіли, порядок ключів і екранування зміняться, а байти мусили лишитися ті самі.

@parse_ini_file

читає ~/.env як КЛЮЧ=значення. Секрет роби з літер і цифр без лапок, # і пробілів — інакше цей парсер зрозуміє рядок не так, як ти задумав.

fail(500, …)

500 тут лише там, де винен сервер: немає секрету, не пишеться файл. На чужу помилку 500 віддавати не можна — відправник почне повторювати доставку.

Бік відправника: секрет, підпис і три заголовки

Перевіряти вміє тільки той, хто вміє підписувати. Спершу — секрет, який ніколи не потрапляє у ~/www

Секрет: створити й покласти в ~/.env

Підписуємо запит: curl плюс дві команди

Найпростіший чесний спосіб перевірити свій обробник — підписати запит прямо в оболонці. Тіло, мітка часу й nonce склеюються в один рядок. Від нього й рахується HMAC.

SECRET='твій-секрет-із-.env'
BODY='{"source":"test","type":"manual","title":"підписана подія"}'
TS=$(date +%s)
NONCE=$(openssl rand -hex 8)
SIG=$(printf '%s' "$TS.$NONCE.$BODY" \
      | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  http://91.219.61.4/s/твій-логін/api/hook.php \
  -H 'Content-Type: application/json' \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIG" \
  --data-raw "$BODY"

$secret = 'твій-секрет-із-.env'
$body   = '{"source":"test","type":"manual","title":"підписана подія"}'
$ts     = [int][Math]::Floor(((Get-Date).ToUniversalTime() - [datetime]'1970-01-01').TotalSeconds)
$nonce  = -join ((1..16) | ForEach-Object { '{0:x}' -f (Get-Random -Maximum 16) })

$h = New-Object System.Security.Cryptography.HMACSHA256
$h.Key = [Text.Encoding]::UTF8.GetBytes($secret)
$msg   = [Text.Encoding]::UTF8.GetBytes("$ts.$nonce.$body")
$sig   = ($h.ComputeHash($msg) | ForEach-Object { $_.ToString('x2') }) -join ''

curl.exe -s -o NUL -w "%{http_code}" -X POST `
  http://91.219.61.4/s/твій-логін/api/hook.php `
  -H 'Content-Type: application/json' `
  -H "X-Timestamp: $ts" -H "X-Nonce: $nonce" -H "X-Signature: $sig" `
  --data-raw $body

Google Apps Script: справжні події, а не curl

Тут той самий план Б, що й на уроці 11. Безкоштовні тарифи Zapier та IFTTT не дають вебхука на власний сервер. Тому події надсилає Apps Script, прив'язаний до форми. Тепер він ще й підписує їх.

function onFormSubmit(e) {
  const SECRET = PropertiesService.getScriptProperties().getProperty('HOOK_SECRET');
  const body = JSON.stringify({
    source: 'apps-script',
    type:   'form',
    title:  String(e.namedValues['Назва заявки'] || '').slice(0, 200)
  });
  const ts = Math.floor(Date.now() / 1000);
  const nonce = Utilities.getUuid().replace(/-/g, '').slice(0, 16);

  const sigBytes = Utilities.computeHmacSha256Signature(
      ts + '.' + nonce + '.' + body, SECRET);
  const sig = sigBytes
      .map(b => ((b & 0xFF) + 0x100).toString(16).slice(1)).join('');

  UrlFetchApp.fetch('http://91.219.61.4/s/твій-логін/api/hook.php', {
    method: 'post',
    contentType: 'application/json',
    payload: body,                      // ті самі байти, що підписані
    headers: { 'X-Timestamp': String(ts), 'X-Nonce': nonce, 'X-Signature': sig },
    muteHttpExceptions: true
  });
}

ScriptProperties

секрет живе в налаштуваннях проєкту Apps Script, а не в тексті скрипта. Інакше він поїде разом із копією скрипта до будь-кого, з ким ти поділишся файлом.

payload: body

у мережу йде той самий рядок, який підписано. Якщо передати сюди об'єкт, бібліотека серіалізує його по-своєму — і байти розійдуться з підписом.

(b & 0xFF) + 0x100

Apps Script віддає байти зі знаком (від −128 до 127). Ця арифметика перетворює їх на два шістнадцяткові символи без «−7f».

api/security.md: щоб чужа команда підключилася без тебе

Документ пишеться не для вчителя. Він пишеться для людини, яка завтра захоче надіслати тобі подію, а тебе поруч не буде

Перевірити якість цього файлу просто. Дай його однокласникові й подивись, чи збере він правильний підпис із першої спроби.

Якщо не зібрав — у документі бракує рядка. Найчастіше про те, у якому порядку склеювати частини, або про кодування.

# Підпис запитів до /api/hook.php

## Заголовки

| Заголовок     | Формат                          |
|---------------|---------------------------------|
| X-Timestamp   | секунди Unix, ціле число         |
| X-Nonce       | 16 шістнадцяткових символів      |
| X-Signature   | 64 шістнадцяткові символи, малі  |

## Рядок для підпису

    X-Timestamp + "." + X-Nonce + "." + тіло-запиту

Тіло береться в тому вигляді, у якому воно йде в мережу — байт у байт,
у UTF-8, без BOM і без завершального переводу рядка.

## Алгоритм

    X-Signature = HMAC-SHA256(рядок-для-підпису, HOOK_SECRET) у hex

Секрет видається окремим каналом і в цьому файлі не наводиться.

## Правила приймання

| Умова                                   | Відповідь |
|-----------------------------------------|-----------|
| усе гаразд                              | 200       |
| не POST                                 | 405       |
| тіло більше за 8192 байти               | 413       |
| немає одного з трьох заголовків         | 401       |
| вік мітки часу більший за 300 с         | 401       |
| підпис не збігається                    | 401       |
| X-Nonce уже використовували             | 409       |
| підпис правильний, тіло не JSON         | 400       |

Nonce зберігається 900 секунд. Повторна доставка з тим самим nonce
завжди дає 409 і НЕ створює другого запису.

## Приклад коректного запиту

    X-Timestamp: 1788338467
    X-Nonce:     a1b2c3d4e5f60718
    X-Signature: d5d5027a9a872bc190677dcf95a9b4f1a672861c4b39ad568e47b65cf5b5bd6f
    тіло: {"source":"apps-script","type":"form","title":"Заявка на гурток робототехніки"}
    секрет: ***

## Приклад некоректного запиту

Те саме, але в тілі "…робототехніки!" — один доданий символ.
Очікувана відповідь: 401 bad signature.

Практика: секрет, підпис, вікно, nonce

Кроки 1—4 і 12—14 — по SSH на сервері. Кроки 5—11 і 15 — у себе на комп'ютері. По FTP їдуть два файли: api/hook.php з кроку 12 і api/security.md з кроку 16. Галочки зберігаються

Автоперевірка

Чекер знає твій секрет (ти сам поклав його в ~/.env, а чекер читає його на сервері від твого імені) і надсилає п'ять запитів: один валідний і чотири зіпсовані

Демонстраційний режим: результат згенеровано для показу. На сервері ця кнопка викликає POST /api/check, який запускає /opt/lessons/12/check.sh від імені учня.

Які саме п'ять запитів надійде

Що вчитель дивиться на твоєму екрані

• як ти формуєш заголовки X-Timestamp і X-Signature у своєму відправнику — саме крок обчислення підпису, а не готовий результат;
• твоє сховище nonce після двох запитів: ls -l ~/data/nonces/ — скільки там файлів і чому саме стільки;
• права на ~/.env — має бути 600;
• твій security.md, і просить назвати рядок для підпису напам'ять, посимвольно;
• як ти пояснюєш, чому перевірка nonce стоїть після перевірки підпису, а не перед нею.

Шкала виконання

Це те, що бачить учитель, коли виставляє оцінку.

Сім речень, які варто запам'ятати

• токен доводить «я знаю пароль», підпис доводить «я знаю пароль і надсилав саме цей текст»;
• звичайний хеш від тіла порахує будь-хто — секрет усередині м'ясорубки і є вся різниця;
• підпис порівнюють через hash_equals, а не через ===: час відповіді не має нічого підказувати;
• від replay підпис не рятує взагалі — у повторі він правильний;
• мітка часу не зупиняє повтор, а лише скорочує термін придатності перехопленого запиту до 5 хвилин;
• повтор остаточно закриває nonce, і зберігати його треба на диску, бо PHP на кожен запит стартує заново;
• підпис рахується від сирих байтів тіла — до json_decode і взагалі до будь-якого розбору.

Де найчастіше помиляються

• підпис рахується від тіла після декодування й повторного кодування JSON: байти не збігаються, і підпис не сходиться ніколи — а виглядає це як «у мене неправильний секрет»;
• nonce зберігається в пам'яті процесу або в $_SESSION: після перезапуску сервера replay проходить знову;
• у підпис не входить мітка часу — і зловмисник просто ставить свіжу, а вікно 300 с перестає щось означати;
• перевірка nonce стоїть перед перевіркою підпису: будь-хто заповнює тобі сховище мільйоном чужих nonce;
• рядок у events.jsonl дописується до перевірки nonce: код відповіді правильний, а другий запис усе одно є;
• секрет підпису потрапив у security.md або scenario.md усередині ~/www — блокуючий провал на крос-аудиті;
• hash_equals викликано з переставленими аргументами або замінено на == «бо так коротше»;
• вікно поставлено 2 секунди «для надійності» — і чесні доставки падають через розбіжність годинників;
• 500 віддається на чужі помилки — відправник вважає це тимчасовим збоєм і повторює доставку по колу.

Домашнє завдання

Додай у ~/www/api/security.md два приклади запиту: коректний і зіпсований. У кожному — усі три заголовки з конкретними значеннями, тіло і код відповіді, який має прийти. Секрет у прикладі заміни на ***.

Зіпсований приклад зроби так, щоб він відрізнявся від коректного рівно одним символом у тілі. Постав поруч обидва підписи — буде видно, наскільки вони різні.

Другим абзацом опиши, як ти замінятимеш секрет, якщо він завтра витече. У якому порядку, щоб доставки не зупинилися. І що робити з подіями, які прийдуть якраз у момент заміни.

Звідки взяті числа й формулювання

Підписи на цій сторінці справжні: будь-який із них перераховується в лабораторії кроку 4 або командою openssl dgst -sha256 -hmac

• RFC 2104 «HMAC: Keyed-Hashing for Message Authentication» — першоджерело конструкції H((K⊕opad) ‖ H((K⊕ipad) ‖ m)), значення ipad = 0x36, opad = 0x5C і розмір блоку 64 байти. rfc-editor.org/rfc/rfc2104
• FIPS 198-1, «The Keyed-Hash Message Authentication Code» — чинний стандарт NIST на HMAC; там же вимога порівнювати MAC цілком. nist.gov · FIPS 198-1
• FIPS 180-4 — сама SHA-256: 256 бітів виходу, тобто рівно 64 шістнадцяткові символи. Звідси всі «64 символи» на сторінці. nist.gov · FIPS 180-4
• Stripe, «Verify webhook signatures» — промисловий зразок тієї самої схеми: заголовок Stripe-Signature з полями t= і v1=, рядок для підпису timestamp + "." + payload, допуск за замовчуванням 300 секунд і пряма вимога порівнювати підписи в сталий час. docs.stripe.com · webhooks
• Slack, «Verifying requests from Slack» — заголовки X-Slack-Request-Timestamp і X-Slack-Signature, вікно 5 хвилин із прямою згадкою replay-атаки як причини. api.slack.com · verifying requests
• GitHub, «Validating webhook deliveries» — заголовок X-Hub-Signature-256, HMAC-SHA256 від сирого тіла й вимога користуватися порівнянням у сталий час. docs.github.com · validating webhooks
• PHP: hash_hmac() — повертає hex-рядок у нижньому регістрі; для sha256 це 64 символи. php.net · hash_hmac
• PHP: hash_equals() — порівняння в сталий час, доступне з PHP 5.6. У документації прямо задано порядок аргументів: перший — відомий рядок, другий — той, що прийшов від користувача. php.net · hash_equals
• PHP: режими fopen() — режим 'x' створює файл і повертає false, якщо файл уже існує; операція виконується атомарно. Саме на цьому стоїть перевірка nonce. php.net · fopen
• Атака подовженням повідомлення (length extension) — чому наївне sha256(секрет ‖ повідомлення) не є MAC для хешів конструкції Меркла — Дамґарда, до яких належить SHA-2. wikipedia · length extension attack
• Атаки за часом на порівняння MAC — класична робота Nate Lawson, «Timing attack in Google Keyczar library» (2009): посимвольне порівняння підпису дозволяє добирати його байт за байтом. rdist.root.org · timing attack
• Web Crypto API: SubtleCrypto.sign() — те, чим лабораторія кроку 4 рахує підпис у браузері: importKey з {name:'HMAC', hash:'SHA-256'} і далі sign('HMAC', …). developer.mozilla.org · SubtleCrypto.sign
• Google Apps Script, Utilities.computeHmacSha256Signature — повертає масив знакових байтів, звідси арифметика (b & 0xFF) + 0x100 у прикладі кроку 12. developers.google.com · Utilities
• Коди відповіді HTTP — RFC 9110: 400, 401, 405, 409 Conflict, 413 Content Too Large. rfc-editor.org/rfc/rfc9110
• Принцип Керкгоффса — чому схему підпису можна публікувати, а ключ ні. wikipedia · Kerckhoffs's principle

Повний список із поясненнями, що звідки взято, які числа перевіряються, а які є ілюстративними, — у файлі urok-12-джерела.md поруч із цією сторінкою.