مولّد HMAC ومدقّق التوقيع

ما هو HMAC؟

const crypto = require('crypto');

// HMAC-SHA256 with a UTF-8 text key, hex output
const hmac = crypto
  .createHmac('sha256', 'my-secret-key')
  .update('Hello, World!')
  .digest('hex');

console.log(hmac);
// → 'cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699'

// Verify a signature in constant time
function verify(message, key, expectedHex) {
  const actual = crypto.createHmac('sha256', key).update(message).digest();
  const expected = Buffer.from(expectedHex, 'hex');
  return actual.length === expected.length &&
    crypto.timingSafeEqual(actual, expected);
}

الميزات الرئيسية

أمثلة HMAC

Hello, World!

cf3141611e22ea26a9cac6fe41d941274dd6653622c83cba13972d177bd69699

{"id":42,"event":"user.created"}

Cd2f7zTKaJFeG6k+t1FcvDPn51OAZ2f4GrxkCUgMhGs=

what do ya want for nothing?

5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

The quick brown fox

36f44b125a8a90639dc46733039571792e081e0fd8685ff746784b02ed14aa35629d562c7117cde4a701570551faa5a5e1b7ef1eb5c3bcd4cc1fdb8923fcf14e

كيف تولّد وتتحقّق من HMAC

1. 1

   اختر الخوارزمية

   اختر HMAC-SHA256 ‏(الافتراضية والخيار الصحيح لكل الـwebhooks والـAPIs ورموز JWT تقريبًا)، أو بدّل إلى SHA-1 أو SHA-384 أو SHA-512 لمطابقة نظامٍ يتطلّبها. تعمل الأربع جميعها أصليًا في متصفحك عبر Web Crypto API.

2. 2

   أدخل المفتاح السري واضبط ترميزه

   اكتب أو الصق مفتاحك السري، ثم اضبط ترميز المفتاح ليطابق كيفية تفسير الخادم له: Text ‏(UTF-8) لسلسلة نصية عادية، وHex لكتلة ست عشرية، وBase64 لسرٍّ بترميز base64. الخطأ هنا هو السبب الأول لعدم تطابق HMAC، فعند الشك جرّب الثلاثة جميعًا.

3. 3

   أدخل الرسالة

   الصق البايتات الدقيقة التي تريد توقيعها — بالنسبة لـwebhook هذا هو جسم الطلب الخام، بايتًا ببايت، دون إعادة ترميز أو تغيير في المسافات. يُعاد حساب HMAC حيًّا أثناء التحرير، دون إرسال أي شيء إلى خادم.

4. 4

   اختر صيغة الإخراج وانسخ

   اختر Hex ‏(على طريقة GitHub)، أو Base64 ‏(على طريقة Stripe/‏AWS)، أو Base64URL ‏(على طريقة JWT) لمطابقة ما يتوقّعه تكاملك، ثم اضغط «نسخ» لأخذ التوقيع.

5. 5

   تحقّق من توقيع موجود

   انتقل إلى تبويب «التحقّق»، والصق HMAC المتوقَّع من ترويسة أو رمز، فتؤكّد الأداة في زمنٍ ثابت ما إذا كان توقيعك المحسوب يتطابق — حتى تستطيع مصادقة الحمولة قبل التصرّف بناءً عليها.

أخطاء شائعة في HMAC

// Server stored a base64 secret but you sign the literal string
createHmac('sha256', 'c2VjcmV0LWtleQ==').update(msg)

// Decode the base64 secret to raw bytes first
createHmac('sha256', Buffer.from('c2VjcmV0LWtleQ==', 'base64')).update(msg)

// Provider sends base64, you compare hex
expected = 'Cd2f7z...=' // base64
actual   = digest('hex') // hex — never matches

// Produce the same encoding the provider uses
actual = digest('base64')

// Re-serialization changes the bytes
body = JSON.stringify(JSON.parse(rawBody))
verify(hmac(body))

// Sign the raw bytes exactly as received
verify(hmac(rawBody))

if (received === computed) { /* trust */ }

if (crypto.timingSafeEqual(receivedBuf, computedBuf)) { /* trust */ }

فيمَ يُستخدم HMAC

التحقّق من توقيعات الـwebhook

يوقّع مزوّدون مثل GitHub وStripe وSlack وTwilio كل webhook بـHMAC فوق جسم الطلب وسرٍّ تشاركه أنت فقط. أعِد حساب الوسم وقارنه بالترويسة ‏(مثل X-Hub-Signature-256) لتأكيد أن الحدث أصيل قبل التصرّف بناءً عليه. استخدم تبويب «التحقّق» للقيام بذلك دون كتابة كود مؤقّت.

توقيع طلبات الـAPI

كثيرًا ما تتطلّب الـAPIs المصادَق عليها أن يوقّع العميل الطلب ‏(الطريقة، المسار، الطابع الزمني، الجسم) بـHMAC وسرٍّ مشترك بدل إرسال السرّ نفسه. ‏AWS Signature Version 4 هو المثال القياسي. تتيح لك هذه الأداة إعادة إنتاج تلك التوقيعات وتصحيحها خطوةً بخطوة.

ضمان سلامة الرسالة

عندما تمرّر رمزًا أو cookie أو رسالة بين الخدمات، فإن إرفاق HMAC يتيح للمستقبِل كشف أي عبث. ولأن الوسم يعتمد على سرّ، لا يستطيع المهاجم إعادة حسابه بعد تعديل البيانات — على عكس مجموع تحقّق عادي.

فهم توقيع JWT HS256

رمز JWT موقَّع بـHS256 هو مجرد base64url(header) + '.' + base64url(payload)، موقَّع بـHMAC-SHA256 والنتيجة مُخرَجة كـBase64URL. اضبط الخوارزمية على SHA-256 والإخراج على Base64URL هنا لترى بالضبط كيف يُنتَج ذلك التوقيع، ثم راجِع في مُرمِّز JWT.

تصحيح توقيع غير متطابق

عندما لا يتطابق HMAC لديك مع توقيع الخادم، تكون هذه الأداة أسرع وسيلة لعزل السبب: جرّب المفتاح كـText وHex وBase64، وبدّل الإخراج بين Hex وBase64، وتأكّد من أنك توقّع البايتات الخام الدقيقة — كل ذلك دون إعادة نشر أي كود.

كيف يعمل HMAC

بنية RFC 2104

يُعرَّف HMAC بأنه H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ m))، حيث ipad هو البايت 0x36 مكرَّرًا وopad هو 0x5c مكرَّرًا، كلاهما حتى حجم كتلة التجزئة. المفتاح الأطول من حجم الكتلة يُجزَّأ أولًا؛ والمفتاح الأقصر يُحشى بالأصفار. هذا التداخل من مرورين هو ما يمنح HMAC برهان أمانه، الذي يصمد حتى لو لم تكن التجزئة الأساسية مقاوِمة للتصادم.

لماذا التجزئة المُفتاحة أفضل من تجزئة عادية

التجزئة العادية تثبت فقط أن البيانات لم تتلف عرضًا، لأن أي شخص يستطيع إعادة حسابها لأي رسالة — بما فيها المعدَّلة. أما HMAC فيمزج سرًّا، فلا يستطيع إنتاج وسمٍ صالح إلا حاملو المفتاح. وهذا يحوّل «السلامة فقط» إلى سلامة زائد أصالة، وهي الخاصية التي تحتاجها فعلًا الـwebhooks والطلبات الموقَّعة.

مقاومة تمديد الطول

‏SHA-1 وSHA-256 وSHA-512 العارية هي تجزئات Merkle–Damgård معرّضة لتمديد الطول: بمعلومية H(secret ‖ msg) يستطيع المهاجم حساب H(secret ‖ msg ‖ extra) دون معرفة السرّ. وتنكسر بهذا مخطّطات «MAC ببادئة سرّية» الساذجة. تحيّد التجزئة الخارجية في HMAC هذا الهجوم، وهو السبب الرئيسي لاستخدام HMAC بدل تجزئة السرّ والرسالة معًا.

اختيار SHA-256 مقابل SHA-512

يُنتج HMAC-SHA256 وسمًا بطول 256 بت ‏(64 حرف hex) وهو الافتراضي للتوافق البيني — سريع ومنتشر ومدعوم في كل مكان. ويُنتج HMAC-SHA512 وسمًا بطول 512 بت ‏(128 حرف hex) وكثيرًا ما يكون أسرع على معالجات 64 بت لأن SHA-512 يستخدم كلمات 64 بت. اختر SHA-256 ما لم تتطلّب مواصفة أو نظام نظير SHA-512؛ وكلاهما آمن للمصادقة.

تنفيذ Web Crypto

تستدعي هذه الأداة crypto.subtle.importKey لتحميل مفتاحك ‏(مفكوك الترميز من Text أو Hex أو Base64) وcrypto.subtle.sign('HMAC', ...) لحساب الوسم، ثم تُرمِّز البايتات الخام كـHex أو Base64 أو Base64URL. إنه نفس التنفيذ الأصلي المُدقَّق الذي يستخدمه المتصفح لـTLS، ويعمل خارج محرّك JavaScript لأجل السرعة.

أفضل ممارسات HMAC

استخدم مفتاحًا لا يقل طوله عن طول إخراج التجزئة

لـHMAC-SHA256 استخدم سرًّا لا يقل عن 32 بايت عشوائية ‏(256 بت)؛ ولـSHA-512 استخدم 64. المفتاح القصير أو منخفض الإنتروبيا هو الحلقة الأضعف. ولّد المفاتيح من مصدر عشوائي آمن وقويّ — لا من كلمة مرور أو سلسلة نصية متوقَّعة أبدًا.

قارن الأوسمة دائمًا في زمنٍ ثابت

تحقّق من التوقيعات بمقارنة في زمنٍ ثابت ‏(‏crypto.timingSafeEqual في Node، وhmac.compare_digest في Python) بدل == أو مساواة السلاسل. تعود المقارنة الساذجة باكرًا عند أول بايت مختلف، فتُسرِّب توقيتًا قد يتيح للمهاجم استعادة وسمٍ صالح بايتًا ببايت. تبويب «التحقّق» في هذه الأداة يقارن أصلًا في زمنٍ ثابت.

لا تسجّل المفتاح السري ولا تكشفه أبدًا

أبقِ أسرار التوقيع خارج السجلات ورسائل الأخطاء وعناوين URL والكود على جانب العميل. خزّنها في مدير أسرار أو متغيّرات بيئة، وناوِبها دوريًا، واقصُر كل تكامل على مفتاحه الخاص حتى لا يخترق تسريبٌ واحد كل شيء.

فضّل HMAC-SHA256 أو أقوى

اجعل الافتراضي HMAC-SHA256؛ وارتقِ إلى SHA-384 أو SHA-512 حين يتطلّبه نظير. تجنّب HMAC-SHA1 للأنظمة الجديدة ولا تستخدم HMAC-MD5 أبدًا. ومع أن HMAC يتحمّل تجزئة أضعف أفضل ممّا قد يفعله توقيع خام، فإن الانطلاق من تجزئة حديثة يمنحك أكبر هامش.

وقّع البايتات الدقيقة، بما فيها طابع زمني

وقّع الحمولة الخام غير المعدَّلة — إعادة ترميز JSON أو قصّ المسافات يغيّر البايتات ويكسر التحقّق. لتوقيع الطلبات، أدرِج طابعًا زمنيًا أو nonce ضمن البيانات الموقَّعة وارفض التوقيعات القديمة لمنع هجمات الإعادة.

أسئلة شائعة عن HMAC