إنتقل إلى المحتوى الرئيسي

توقيع طلبات HMAC

يُوقّع كل طلب إلى /v1/* باستخدام HMAC-SHA256 وسر التطبيق. تتولى SDK ذلك، أما هذه الصفحة فلمن يحتاج إلى توقيع الطلب يدويًا، باستخدام curl أو لغة أخرى أو أثناء التشخيص.

الرؤوس الأربعة​

يحمل كل طلب موقّع:

الرأسالقيمة
X-Application-IDمعرّف التطبيق من ztxbas app create
X-Timestampثواني Unix، ضمن ±300 ثانية من ساعة الخادم
X-Nonceقيمة عشوائية فريدة لكل طلب؛ تصلح 32 خانة سداسية
X-Signaturehex(HMAC-SHA256(secret, canonical))

الصيغة الموحّدة​

سطر واحد دون سطر جديد في النهاية:

METHOD "|" PATH "|" TIMESTAMP "|" NONCE "|" BODY
  • METHOD — بأحرف كبيرة (GET وPOST وDELETE).
  • PATH — مسار URL تمامًا كما يظهر في سطر الطلب، ويبدأ بـ/، دون سلسلة استعلام (لا تستخدمها API).
  • TIMESTAMP — القيمة نفسها في X-Timestamp.
  • NONCE — القيمة نفسها في X-Nonce.
  • BODY — بايتات الطلب الخام، أو نص فارغ لطلبي GET/DELETE دون جسم. يجب أن تطابق البايتات المرسلة ما وُقّع؛ فلا تعِد تنسيق JSON بين التوقيع والإرسال.

مثال​

توقيع POST /v1/users بجسم {"email":"alice@example.com"}:

canonical = 'POST|/v1/users|1704067200|abc123|{"email":"alice@example.com"}'
signature = hex(HMAC-SHA256("topsecret", canonical))
          = 92c2aca00ba47b4377aebf3e3af134aff93cf7ad959d05e31a0f0618df9f7d9a

الطلب المرسل:

POST /v1/users HTTP/1.1
Host: ztxbas.example.com
X-Application-ID: app_test
X-Timestamp: 1704067200
X-Nonce: abc123
X-Signature: 92c2aca00ba47b4377aebf3e3af134aff93cf7ad959d05e31a0f0618df9f7d9a
Content-Type: application/json

{"email":"alice@example.com"}

تتضمن كل SDK اختبار وحدة يثبت هذا المتجه بعينه. إذا طورت أداة توقيع بلغة جديدة، فاستخدم المُدخلات نفسها للتحقق.

ملاحظات أمنية​

  • احفظ السر بصلاحيات 0600. كما تفعل مع أي مفتاح خاص.
  • استخدم المقارنة ذات الزمن الثابت على الخادم. ينفذ الخادم ذلك بالفعل (crypto/subtle.ConstantTimeCompare في Go). نفّذ الأمر نفسه إن كتبت أدوات توقيع أو تحقق خاصة بك.
  • جسم الطلب محدود بـ8 KiB. تتسبب الأحجام الأكبر في 413 BODY_TOO_LARGE. جميع مسارات v1 لها حمولات صغيرة.
  • تفاوت الساعة محدود بـ300 ثانية. عند ظهور TIMESTAMP_EXPIRED بصورة متقطعة، تحقق من تشغيل NTP.
  • من المفترض أن تُستخدم Nonce مرة واحدة، لكن ZTXBAS v1 لا ينفّذ فرض التفرد. نافذة الطابع الزمني هي الحد الحالي لإعادة التشغيل. استخدم مع ذلك قيمة عشوائية جديدة لكل طلب، دون تكلفة تذكر، استعدادًا لنمط أكثر صرامة مستقبلًا.

موضوعات ذات صلة​