تدوير المفتاح

Robert Ferens

Demián Renzulli

يقدّم هذا المستند معلومات أساسية حول عملية تدوير المفاتيح لتطبيق ويب معزول، بما في ذلك الحالات التي تكون فيها هذه العملية ضرورية والخطوات التي يجب أن يتّبعها المطوّرون في حال فقدان مفتاح أو اختراقه.

تغيير المفتاح في "الأنشطة على الويب وفي التطبيقات"

تتيح عملية تدوير المفاتيح استبدال المفاتيح الخاصة المستخدَمة لتوقيع IWA في حال تسرّبها أو فقدانها. تضمن هذه العملية استمرار عمل التطبيق والحفاظ على معرّف حزمة ثابت ومصدر ثابت، ما يضمن استمرار توزيع تطبيقك وتلقّيه التحديثات.

لا تتطلّب عملية تدوير المفاتيح أي تغييرات من المشرف أو المستخدم، وإذا تم تنفيذها بشكل صحيح، لن يلاحظها أي منهما. إنّ قنوات جهات الاتصال الموثوق بها التي تم إنشاؤها أثناء عملية الإدراج في القائمة المسموح بها الأولية ضرورية لتفعيل عملية تدوير المفاتيح.

الحاجة إلى تغيير المفاتيح بالتناوب

يكون تغيير المفتاح ضروريًا في حالتين أساسيتين:

• تسريب المفتاح أو اختراقه: إذا تم اختراق مفتاح التوقيع الخاص أو تسريبه، عليك البدء فورًا في عملية تغيير المفتاح لتأمين تطبيقك. يمكن استخدام المفتاح المسروق لانتحال هويتك وإلحاق الضرر بمستخدمي تطبيقك وتعريض سمعة شركتك للخطر.
• فقدان المفتاح: إذا فقدت إمكانية الوصول إلى مفتاح التوقيع الخاص وتعذّر عليك توقيع التحديثات الجديدة، يجب تدوير المفتاح لاستعادة إمكانية توزيع تطبيقك.

متطلبات المطوّر

قبل بدء عملية تدوير المفتاح، يجب استيفاء المعايير التالية:

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

إعادة توقيع التطبيقات المستضافة وإصدار إصدارات جديدة

بعد تغيير المفتاح، يتم حظر جميع مثيلات التطبيق المثبَّتة التي لم يتم توقيعها باستخدام مفتاح صالح. لتجنُّب حدوث أي انقطاع للمستخدمين، عليك تقديم تطبيق موقَّع باستخدام المفتاح الجديد (أو كلا المفتاحين). يمكنك الاطّلاع على التفاصيل الفنية المتعلقة بإعادة توقيع الحِزم في القسم كيفية توقيع حِزمة باستخدام مفاتيح متعددة. استنادًا إلى حالتك المحدّدة، تتوفّر سيناريوهات مختلفة:

السيناريو (أ): لم يتم فقدان المفتاح (على سبيل المثال، التدوير الاستباقي أو التسريب)

يجب توقيع التطبيق باستخدام كلا المفتاحين (القديم والجديد) وتوفيرهما للمستخدمين من خلال إحدى الطريقتين التاليتين:

• طرح إصدار جديد من التطبيق (إضافة الإصدار الجديد إلى بيانات التحديث)
• تعديل ملفات .swbn المستضافة (المرتبطة ببيانات التعديل) لتوقيعها باستخدام كلا المفتاحين تتيح لك أداة واجهة سطر الأوامر إضافة توقيع آخر إلى حزمة swbn الحالية.

يجب إجراء ذلك قبل أن تعالج Google عملية تدوير المفتاح لضمان عدم ملاحظة المستخدمين للتغيير.

السيناريو (ب): فقدان المفتاح

هذه الحالة أكثر تعقيدًا لأنّه لا يمكن توقيع التطبيق باستخدام المفتاح المفقود. اطلب تغيير المفتاح وتواصل مع جهة اتصال Google لمعرفة الخطوات التالية. قد يُطلب منك إضافة التواقيع الجديدة إلى حِزمك المستضافة باتّباع هذه التعليمات.

عملية تغيير المفتاح

تتضمّن عملية تدوير المفاتيح الخطوات التالية:

تعديل قناة التحديث وتثبيت الإصدار

يستخدم المشرفون أحيانًا قنوات تحديث مخصّصة أو تثبيت إصدار محدّد، ما يتيح لهم إدارة إصدارات التطبيقات على أجهزة العميل. بعد تغيير المفتاح، تصبح جميع التطبيقات المثبَّتة باستخدام مفاتيح غير صالحة غير صالحة ويتم حظرها. لمنع حدوث ذلك، يجب أيضًا تعديل الإصدارات السابقة من التطبيقات المستضافة ضمن الروابط المقدَّمة في update_manifest.json وتوقيعها بتوقيعَين قبل استبدال المفتاح. إذا فقدت مفتاحك القديم وتعذّر توقيع التطبيق باستخدام مفتاحَين، عليك إبلاغ جهة اتصالك في Google على الفور. وسنتعاون معك لحلّ المشكلة كي يتمكّن المستخدمون من تحديث التطبيق بدون التأثير في سير عملهم.

كيفية توقيع حِزمة باستخدام مفاتيح متعددة

يوضّح هذا القسم كيف يمكنك توقيع حِزم الويب باستخدام مفتاح واحد أو مفتاحين من خلال أدوات سطر الأوامر أو إعدادات المكوّنات الإضافية Webpack/Rollup/Vite. تتيح أدوات واجهة سطر الأوامر أيضًا إضافة توقيع آخر إلى حِزم swbn الحالية، وهو ما قد يكون مفيدًا في حالات فقدان المفتاح أو تحديث الحِزم المستضافة السابقة.

أدوات واجهة سطر الأوامر

أولاً، تأكَّد من تثبيت حزمة wbn-sign باستخدام npm:

$ npm i wbn-sign

أضِف -g لتثبيت الحزمة على مستوى العالم بدلاً من تثبيتها في المجلد الحالي فقط.

التوقيع باستخدام مفتاح واحد

$ wbn-sign -i unsigned.wbn -o signed.swbn -k private.pem

التوقيع باستخدام مفتاحَين

$ wbn-sign sign webbundle.wbn old_key.pem new_key.pem -o signed.swbn --web-bundle-id <your-id-from-old-private>

يمكن تخطّي الوسيطة --web-bundle-id <id> إذا كان old_key هو المفتاح الأول الذي تم توقيع الإصدار الأولي من التطبيق به، وفي هذه الحالة سيتم استخلاص معرّف الحزمة من المفتاح. يمكنك التحقّق من معرّف الحزمة باستخدام الأمر wbn-sign info signed.swbn.

إضافة توقيع إلى الحزمة الحالية

$ wbn-sign add-signature signed.swbn key3.pem --in-place

استخدِم -o إذا كنت لا تريد تجاهل الحِزمة ولكنك تريد إنشاء حزمة جديدة موقّعة مرّتين.

مزيد من المعلومات حول أداة واجهة سطر الأوامر

لمزيد من المعلومات حول استخدام أداة واجهة سطر الأوامر، يمكنك الاطّلاع على صفحة npm wbn-sign. يمكنك بدلاً من ذلك استخدام: wnb-sign help.

المكوّن الإضافي Webpack

التوقيع باستخدام مفتاح واحد

لضبط إضافة Webpack من أجل توقيع تطبيق الويب المعزول باستخدام مفتاح خاص واحد، اتّبِع الخطوات التالية:

• اضبط WebBundlePlugin لاشتقاق عنوان URL الأساسي المطلوب تلقائيًا مباشرةً من هذا المفتاح.
• استخدِم NodeCryptoSigningStrategy واحدًا لإنشاء ملف .swbn الموقّع.

// key is parsePemKey(private.pem)

plugins.push(
  new WebBundlePlugin({
    baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategy: new NodeCryptoSigningStrategy(key)
    }
  })
)

التوقيع باستخدام مفتاحَين

عندما تحتاج إلى توقيع تطبيقك مرّتين أثناء تغيير المفتاح:

• حدِّد webBundleId وعنوان URL الأساسي استنادًا إلى الحزمة الأصلية (old_key) لضمان بقاء هوية التطبيق ثابتة للمستخدمين.
• استخدِم مجموعة من استراتيجيات التوقيع لتطبيق كل من مفتاحَي التوقيع الخاصَّين القديم والجديد.

// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)

plugins.push(
  new WebBundlePlugin({
    baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public') },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategies: [
        new NodeCryptoSigningStrategy(old_key),
        new NodeCryptoSigningStrategy(new_key)
      ],
      webBundleId: new WebBundleId(old_key).serialize()
    }
  })
)

إضافة Rollup أو Vite

التوقيع باستخدام مفتاح واحد

لاستخدام إضافة Rollup أو Vite لتوقيع تطبيقك باستخدام مفتاح خاص واحد، على غرار إعداد Webpack، تستخدم الإضافة استراتيجية توقيع واحدة وتتعامل مع استخلاص عنوان URL الأساسي من المفتاح المقدَّم لإنشاء الناتج الموقَّع.

// key is parsePemKey(private.pem)

plugins.push({
  ...wbn({
    baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategy: new NodeCryptoSigningStrategy(key)
    }
  }),
  enforce: 'post'
})

التوقيع باستخدام مفتاحَين

لتوقيع تطبيقك مرتين باستخدام Rollup أو Vite، عليك ضبط الإضافة لقبول مفاتيح متعددة. يستخدم هذا المقتطف كلاً من المفتاح الخاص القديم والجديد باستخدام مصفوفة الاستراتيجيات. يضمن ذلك عملية نقل سلسة من خلال الاحتفاظ بشكل صريح بعنوان URL الأساسي وwebBundleId المستمد من مفتاحك الأصلي الحالي.

// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)

plugins.push({
  ...wbn({
    baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategies: [
        new NodeCryptoSigningStrategy(old_key),
        new NodeCryptoSigningStrategy(new_key)
      ],
      webBundleId: new WebBundleId(old_key).serialize()
    }
  }),
  enforce: 'post'
})

الخاتمة

تُعدّ إدارة عملية تغيير المفاتيح في تطبيقك الذي يمكن تثبيته أمرًا بالغ الأهمية للحفاظ على أمان تطبيقك واستمرار توزيعه. وبغض النظر عن حالتك المحدّدة (على سبيل المثال، ما إذا كان المفتاح مفقودًا أم لا)، يضمن اتّباع الخطوات الموضّحة أدناه ألا يواجه المستخدمون أي انقطاع في الخدمة. باستخدام أدوات واجهة سطر الأوامر أو إعدادات المكوّنات الإضافية المتوفّرة في Webpack أو Rollup أو Vite، يمكنك إدارة توقيعات تطبيقك بكفاءة وتسهيل عملية تدوير المفاتيح. في حالات الطوارئ، احرص على التواصل على الفور مع جهة اتصالك في Google من خلال عنوان البريد الإلكتروني الموثوق الذي حدّدته.