Проверка подписи вебхуков с помощью HMAC
Заголовок X-Signature вебхука Chaingateway позволяет проверить, что запрос действительно пришёл от Chaingateway. Он содержит HMAC-SHA256 идентификатора транзакции (txid) из данных уведомления, закодированный в base64 и вычисленный с вашим личным секретом в качестве ключа. Ваш приёмник заново вычисляет значение и сравнивает его с заголовком. Заголовок отправляется после того, как вы задали личный секрет.
От чего защищает заголовок X-Signature?
Заголовок раздела «От чего защищает заголовок X-Signature?»Он защищает от поддельных запросов: отправить POST на публичный URL вашего приёмника может кто угодно, но подходящую подпись создаст только тот, кто знает личный секрет. HMAC, определённый в RFC 2104, объединяет хеш-функцию с секретным ключом, здесь это SHA-256. NIST FIPS 198-1 описывает ту же конструкцию как Keyed-Hash Message Authentication Code.
Подпись охватывает txid и ничего больше. Сумма, адреса и поля токена в теле не подписываются. Поэтому действительная пара txid и подписи не доказывает, что остальная часть тела не изменена. После проверки используйте txid как ключ поиска: прочитайте транзакцию запросом GET /api/v2/{chain}/transactions/{txid} и зачисляйте платёж по данным, которые вернул API, а не по сумме из тела уведомления.
Как задать личный секрет?
Заголовок раздела «Как задать личный секрет?»Личный секрет задаётся или создаётся заново в настройках профиля. Выполните следующие шаги:
- Откройте настройки профиля.
- Найдите раздел «Personal Secret».
- Если секрет не задан, нажмите «Set Personal Secret», чтобы создать его. Если секрет уже есть, нажмите «Regenerate Secret», чтобы заменить его.
Для работающей системы важны две детали. Если личного секрета ещё нет, его добавление включает заголовок X-Signature для всех исходящих вебхуков. Перед этим разверните приёмник, который принимает и проверяет заголовок. Если вы заново создаёте уже заданный секрет, новый секрет сразу применяется к уведомлениям вебхуков. Обновите приёмник одновременно, иначе он отклонит действительные запросы.
Как формируется заголовок X-Signature?
Заголовок раздела «Как формируется заголовок X-Signature?»Chaingateway читает txid из данных уведомления, вычисляет над ним HMAC с хеш-функцией SHA-256, используя личный секрет в качестве ключа, и кодирует 32 байта результата в base64. Txid — это уникальный идентификатор транзакции, который уже есть в теле вебхука, поэтому у приёмника есть всё необходимое для повторного вычисления значения. Секрет известен только Chaingateway и вам.
Как проверить подпись в моём коде?
Заголовок раздела «Как проверить подпись в моём коде?»Вычислите HMAC заново по txid из тела и сравните его со значением заголовка. Используйте функцию сравнения за постоянное время, чтобы время сравнения ничего не раскрывало об ожидаемом значении. Примеры ниже делают это на Python, Java, PHP и JavaScript.
import hmacimport hashlibimport base64
def verify_signature(txid, received_signature, personal_secret): # Generate the expected signature expected_signature = base64.b64encode(hmac.new( personal_secret.encode(), txid.encode(), hashlib.sha256 ).digest()).decode()
# Compare the expected signature with the received signature return hmac.compare_digest(expected_signature, received_signature)
# Example usagetxid = 'your_txid_here'received_signature = 'received_signature_here'personal_secret = 'your_personal_secret_here'
if verify_signature(txid, received_signature, personal_secret): print("Signature is valid.")else: print("Invalid signature.")import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;import java.nio.charset.StandardCharsets;import java.security.MessageDigest;import java.util.Base64;
public class SignatureVerifier { public static boolean verifySignature(String txid, String receivedSignature, String personalSecret) throws Exception { Mac mac = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(personalSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); mac.init(secretKeySpec);
byte[] signatureBytes = mac.doFinal(txid.getBytes(StandardCharsets.UTF_8)); String expectedSignature = Base64.getEncoder().encodeToString(signatureBytes);
// Constant-time comparison return MessageDigest.isEqual( expectedSignature.getBytes(StandardCharsets.UTF_8), receivedSignature.getBytes(StandardCharsets.UTF_8)); }
public static void main(String[] args) { try { String txid = "your_txid_here"; String receivedSignature = "received_signature_here"; String personalSecret = "your_personal_secret_here";
if (verifySignature(txid, receivedSignature, personalSecret)) { System.out.println("Signature is valid."); } else { System.out.println("Invalid signature."); } } catch (Exception e) { e.printStackTrace(); } }}<?phpfunction verifySignature($txid, $receivedSignature, $personalSecret) { // Generate the expected signature $expectedSignature = base64_encode(hash_hmac('sha256', $txid, $personalSecret, true));
// Compare the expected signature with the received signature return hash_equals($expectedSignature, $receivedSignature);}
// Example usage$txid = 'your_txid_here';$receivedSignature = 'received_signature_here';$personalSecret = 'your_personal_secret_here';
if (verifySignature($txid, $receivedSignature, $personalSecret)) { echo "Signature is valid.";} else { echo "Invalid signature.";}const crypto = require('crypto');
function verifySignature(txid, receivedSignature, personalSecret) { // Generate the expected signature const expectedSignature = crypto .createHmac('sha256', personalSecret) .update(txid) .digest('base64');
// timingSafeEqual throws if the lengths differ, so check them first const expected = Buffer.from(expectedSignature); const received = Buffer.from(receivedSignature); return expected.length === received.length && crypto.timingSafeEqual(expected, received);}
// Example usageconst txid = 'your_txid_here';const receivedSignature = 'received_signature_here';const personalSecret = 'your_personal_secret_here';
if (verifySignature(txid, receivedSignature, personalSecret)) { console.log("Signature is valid.");} else { console.log("Invalid signature.");}Как проверить мой код проверки?
Заголовок раздела «Как проверить мой код проверки?»Проверьте функцию на фиксированном входе, прежде чем подключать её к реальному трафику. Значения ниже — тестовый вектор, который можно воспроизвести любым инструментом HMAC-SHA256. Секрет — это заглушка, а не настоящий личный секрет. Если ваша функция возвращает для этого входа другое значение, ошибка в вашем коде, а не в вебхуке.
personal_secret: my_personal_secrettxid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988X-Signature: t2vU2mYBCv/UvpKprNJB7qbgrCpPXKb6NWgL77xsZgQ=Типичные ошибки: хеширование всего тела JSON вместо txid, использование hex-представления вместо base64 и сравнение через ==, которое выполняется не за постоянное время. Помните также, что личный секрет действует для всего аккаунта. Секрет, который вы создали заново в настройках профиля, одновременно меняет подпись всех вебхуков аккаунта.
Что делать, если подпись не совпадает?
Заголовок раздела «Что делать, если подпись не совпадает?»Отклоните запрос с кодом ошибки, например 401 или 403, и не обрабатывайте тело. Записывайте в лог txid, полученный заголовок и адрес источника, чтобы отличить неверно настроенный секрет от поддельного запроса. Если один и тот же отправитель даёт несовпадения сразу после того, как вы создали секрет заново, приёмник всё ещё использует старый. Поддельный запрос, который лишь угадывает txid, не может создать действительную подпись без секрета.
Что ещё должен делать приёмник вебхуков?
Заголовок раздела «Что ещё должен делать приёмник вебхуков?»Проверка подписи — это один уровень защиты. Следующие меры покрывают остальной путь.
- Обслуживайте приёмник по HTTPS, чтобы данные шифровались при передаче. REST Security Cheat Sheet от OWASP рекомендует HTTPS для каждого эндпоинта, который обрабатывает конфиденциальные данные.
- Отклоняйте запросы с отсутствующим или неверным
X-Signatureс кодом ошибки и записывайте их в лог. - Используйте
txidкак ключ идемпотентности. Уведомление, которое вы отправляете повторно черезPOST /api/v2/{chain}/webhooks/notifications/{id}/retry, содержит тот жеtxidи не должно зачислять платёж дважды. - Храните личный секрет в хранилище секретов, а не в репозитории, и меняйте его, если он мог утечь. Chaingateway не повторяет неудавшиеся доставки самостоятельно, поэтому планируйте обновление приёмника и секрета как один шаг, а пропущенные уведомления затем отправьте повторно из списка неудавшихся.
Источники
Заголовок раздела «Источники»- RFC 2104, HMAC: Keyed-Hashing for Message Authentication
- NIST FIPS 198-1, The Keyed-Hash Message Authentication Code (HMAC)
- OWASP REST Security Cheat Sheet
- Вебхуки в этой документации: данные уведомления и эндпоинты повтора.