Проверка подписи вебхука KartaPay: HMAC-SHA256
Подпись подтверждает подлинность и целостность подписанных данных при сохранности секрета. Она не заменяет проверку заказа, защиту от повторов и контроль исполнения.
Уточните точный контракт подписи
KartaPay использует HMAC-SHA256 и заголовок X-KartaPay-Signature. Этого недостаточно для написания совместимого обработчика: нужно знать подписываемые данные, секрет и представление результата.
Проверьте в документации формат заголовка, кодировку подписи и состав сообщения. Не предполагайте hex, base64, префикс или timestamp без подтверждения.
Проверьте перед следующим шагом
- Известно назначение секрета.
- Определены подписываемые данные.
- Проверен формат заголовка.
- Есть контрольный пример из документации.
Сохраните данные до преобразования
Если протокол подписывает исходное тело запроса, получите его байты до JSON-разбора. Обратная сериализация объекта может изменить пробелы, экранирование и порядок ключей.
Настройте серверный middleware так, чтобы он не уничтожил требуемое представление. Если контракт подписывает другую строку, собирайте именно её по документированным правилам.
- Ограничить размер тела.
- Не менять подписываемые байты.
- Не логировать тело без необходимости.
- Разбирать бизнес-поля после проверки.
Вычислите ожидаемое значение
Используйте стандартную криптографическую библиотеку и HMAC-SHA256. Обычный SHA-256 от тела или конкатенации с ключом не является заменой HMAC.
Секрет храните в серверном окружении. Ошибка назначения ключа так же нарушает проверку, как ошибка кодировки. Не пытайтесь «починить» интеграцию отключением подписи.
- 1Загрузить нужный серверный секрет.
- 2Получить документированное сообщение.
- 3Вычислить HMAC-SHA256.
- 4Преобразовать результат в установленный формат.
Сравните подписи безопасно
Проверьте наличие, допустимый формат и длину полученного значения. Для сравнения используйте подходящую библиотечную операцию постоянного времени, учитывая её требования к длинам буферов.
При отсутствии или несовпадении подписи не выполняйте бизнес-действие. Ответ и диагностический код должны соответствовать контракту и не раскрывать секрет или ожидаемую подпись.
Проверьте перед следующим шагом
- Пустое значение отклоняется.
- Некорректная кодировка отклоняется.
- Сравнение не является обычным сравнением строк.
- Ошибка не открывает доступ.
Проверьте семантику после подлинности
Даже корректно подписанное событие может относиться к другому заказу или уже обработанной операции. Сверьте проект, идентификатор, сумму, валюту и допустимый статус.
Защита от повторов требует устойчивого учёта. Если протокол включает время или идентификатор события, применяйте их по документации; не придумывайте неподдерживаемое окно доставки.
- Операция известна вашему проекту.
- Параметры совпадают с заказом.
- Переход состояния допустим.
- Повтор не повторяет выдачу.
Соберите негативные тесты
Используйте контрольные данные и тестовый секрет, не рабочие ключи. Проверяйте изменение одного байта, неверную подпись, повреждённую кодировку и повтор валидного события.
Разделяйте криптографическую ошибку и ошибку бизнес-проверки в безопасном журнале. Это помогает найти причину без раскрытия содержимого запроса.
Проверьте перед следующим шагом
- Контрольная подпись проходит.
- Изменённые данные отклоняются.
- Отсутствующий заголовок не запускает действие.
- Повтор корректного события безопасен.