پرش به محتوای اصلی

راهنمای امضای وب‌هوک (HMAC)

زمان مطالعه: ۲ دقیقه

این ابزار چیست؟

سرویس‌هایی مثل GitHub، Stripe و Slack وقتی رخدادی پیش می‌آید، یک درخواست وب‌هوک به سرور شما می‌فرستند و آن را با HMAC و یک رمز مشترک امضا می‌کنند. سرور شما باید همان امضا را حساب کند و مقایسه کند تا مطمئن شود پیام واقعاً از آن سرویس آمده و در راه تغییر نکرده است. وقتی امضا نمی‌خواند، پیدا کردن دلیلش سخت است.

این ابزار امضا را به همان شکلی می‌سازد و می‌سنجد که هر ارائه‌دهنده انتظار دارد، با سرآیند درست، و برای Stripe و Slack برچسب زمانی و بازه‌ی مجاز را هم بررسی می‌کند. رمز و بدنه از مرورگر شما بیرون نمی‌روند و در تاریخچه ذخیره نمی‌شوند.

گام‌به‌گام

  1. ارائه‌دهنده را انتخاب کنید

    GitHub، Stripe، Slack یا حالت عمومی را بردارید؛ قالب رشته‌ی امضاشده، سرآیند و الگوریتم مطابق مستندات همان سرویس تنظیم می‌شود.

  2. رمز و بدنه را بدهید

    «رمز مشترک» را همان‌طور که در تنظیمات ارائه‌دهنده آمده بنویسید و بدنه‌ی خام درخواست را دقیقاً با همان بایت‌ها بچسبانید.

  3. امضا بسازید

    در «ساخت امضا» سرآیند امضا ساخته می‌شود تا با آن درخواست آزمایشی به سرور خودتان بفرستید.

  4. امضای دریافتی را بسنجید

    در «بررسی امضا» مقدار سرآیند دریافتی را بچسبانید. نتیجه یکی از «امضا معتبر»، «امضا نامعتبر»، «امضا درست، ولی قدیمی» یا «امضا خوانا نیست» است.

نمونه‌های کاربردی

  • نمونه‌ی مستندات GitHub

    رمز و بدنه‌ی نمونه‌ای که GitHub در راهنمای اعتبارسنجی وب‌هوک آورده است.

    Hello, World!

    نتیجه: X-Hub-Signature-256: sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17

  • بدنه‌ای که یک نویسه فرق دارد

    همان امضا برای بدنه‌ای با یک علامت تعجب بیشتر سنجیده می‌شود.

    Hello, World!!

    نتیجه: امضا نمی‌خواند: رمز اشتباه است، یا بدنه دقیقاً همان بایت‌های دریافتی نیست (فاصله، خط جدید یا قالب‌بندی دوباره‌ی JSON).

اشتباه‌های رایج

  • امضا کردن JSON پس از parse و stringify دوباره: ترتیب کلیدها و فاصله‌ها عوض می‌شود و امضا نمی‌خواند. همیشه بدنه‌ی خام دریافتی را امضا کنید.
  • مقایسه‌ی امضا با == معمولی در کد سرور: این مقایسه زمان را لو می‌دهد. از تابع مقایسه‌ی زمان‌ثابت زبانتان استفاده کنید.
  • نادیده گرفتن برچسب زمانی در Stripe و Slack: بدون آن، مهاجم می‌تواند یک درخواست قدیمی معتبر را دوباره بفرستد. بازه‌ی مجاز را کوتاه نگه دارید.
  • قالب اشتباه رمز: برخی سرویس‌ها رمز را به شکل base64 یا با پیشوند می‌دهند. اگر امضا نمی‌خواند، «قالب رمز» را بررسی کنید.

چرا HMAC و نه فقط یک توکن؟

یک توکن ثابت در سرآیند فقط ثابت می‌کند فرستنده آن را می‌دانسته است؛ اما HMAC به محتوای پیام هم گره خورده است. اگر کسی حتی یک بایت از بدنه را تغییر دهد، امضا دیگر نمی‌خواند، و چون رمز هرگز در درخواست فرستاده نمی‌شود، با شنود هم لو نمی‌رود.

Stripe و Slack برچسب زمانی را هم در رشته‌ی امضاشده می‌گذارند تا امضای هر درخواست فقط برای چند دقیقه معتبر باشد.

پرسش‌های متداول

چرا امضای من با امضای ارسال‌کننده نمی‌خواند؟
تقریباً همیشه بدنه عوض شده است: امضا روی همان بایت‌های خام درخواست حساب می‌شود و اگر JSON را پیش از بررسی دوباره قالب‌بندی کنید، یک فاصله یا خط جدید امضا را عوض می‌کند. بدنه‌ی خام را بچسبانید.
بازه‌ی مجاز برچسب زمانی برای چیست؟
Stripe و Slack زمان ارسال را هم امضا می‌کنند تا گیرنده درخواست‌های قدیمی را رد کند و کسی نتواند یک درخواست شنودشده را دوباره بفرستد (replay). پیش‌فرض هر دو پنج دقیقه است.
رمز وب‌هوک من جایی فرستاده یا ذخیره می‌شود؟
خیر؛ محاسبه با Web Crypto در همین مرورگر انجام می‌شود و رمز نه در نشانی صفحه می‌رود و نه ذخیره می‌شود. با این حال رمز واقعی محیط عملیاتی را فقط در دستگاه مطمئن بچسبانید.

ابزارهای مرتبط