كيفية إعداد Signed Exchange باستخدام Web Packager

تعرَّف على كيفية عرض عمليات التبادل الموقَّعة (SXG) باستخدام Web Packager.

Katie Hempenius
Katie Hempenius
X

التبادل الموقَّع (SXG) هو آلية تسليم تجعل من الممكن مصادقة مصدر أحد الموارد بغض النظر عن كيفية تسليمه. توضّح التعليمات التالية كيفية إعداد Signed Exchange باستخدام Web Packager. يتم تضمين تعليمات لكل من الشهادات الموقَّعة ذاتيًا وشهادات CanSignHttpExchanges.

عرض ملفات SXG باستخدام شهادة موقَّعة ذاتيًا

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

المتطلبات الأساسية

اتّباع هذه التعليمات يتطلّب تثبيت openssl و Go في بيئة التطوير

إنشاء شهادة موقَّعة ذاتيًا

يوضّح هذا القسم كيفية إنشاء شهادة موقَّعة ذاتيًا يمكن استخدامها مع عمليات التبادل الموقَّعة.

التعليمات

  1. أنشئ مفتاحًا خاصًا.

    openssl ecparam -out priv.key -name prime256v1 -genkey

    سيتم حفظ المفتاح الخاص كملف باسم priv.key.

  2. أنشئ طلب توقيع شهادة (CSR).

    openssl req -new -sha256 -key priv.key -out cert.csr -subj '/O=Web Packager Demo/CN=example.com'

    طلب توقيع الشهادة هو جزء من نص مرمّز ينقل المعلومات اللازمة لطلب شهادة من هيئة إصدار الشهادات(CA). على الرغم من أنّك لن تطلب شهادة من هئية إصدار الشهادات، لا يزال من الضروري إنشاء طلب توقيع شهادة.

    ينشئ الأمر أعلاه طلب توقيع شهادة لمؤسسة اسمها Web Packager Demo التي لها اسم شائع example.com. يجب أن يكون الاسم الشائع هو اسم النطاق المؤهَّل بالكامل للموقع الإلكتروني الذي يحتوي على المحتوى الذي تريد حزمه كملف SXG.

    في عملية إعداد SXG للنشر، سيكون هذا الموقع الإلكتروني مملوكًا لك. ومع ذلك، في بيئة اختبار مثل تلك الموضّحة في هذه التعليمات، يمكن أن يكون أي موقع إلكتروني.

  3. أنشئ شهادة تتضمّن إضافة CanSignHttpExchanges.

    openssl x509 -req -days 90 -in cert.csr -signkey priv.key -out cert.pem -extfile <(echo -e "1.3.6.1.4.1.11129.2.1.22 = ASN1:NULL\nsubjectAltName=DNS:example.com")

    يستخدم هذا الأمر المفتاح الخاص وطلب توقيع الشهادة الذي تم إنشاؤه في الخطوتَين 1 و2 لإنشاءملف الشهادةcert.pem. تربط العلامة -extfile الشهادة بإضافة الشهادة CanSignHttpExchanges (1.3.6.1.4.1.11129.2.1.22 هو معرّف العنصر لإضافة CanSignHttpExchanges). بالإضافة إلى ذلك، تحدِّد العلامة -extfile أيضًاexample.com على أنّه اسم بديل للموضوع.

    إذا أردت الاطّلاع على محتوى cert.pem، يمكنك عرضها باستخدام العبارة التالية: 

    openssl x509 -in cert.pem -noout -text

    لقد انتهيت من إنشاء المفاتيح الخاصة والشهادات. ستحتاج إلى الملفَين priv.key وcert.pem في القسم التالي.

إعداد خادم Web Packager للاختبار

المتطلبات الأساسية

  1. ثبِّت Web Packager.

    git clone https://github.com/google/webpackager.git

  2. الإصدار webpkgserver

    cd webpackager/cmd/webpkgserver
go build .

    webpkgserver هو ملف ثنائي محدّد ضمن مشروع Web Packager.

  3. تأكَّد من أنّه تم تثبيت webpkgserver بشكل صحيح.

    ./webpkgserver --help

    من المفترض أن يعرِض هذا الأمر معلومات عن استخدام webpkgserver. إذا لم تنجح هذه الطريقة، من المفيد أولاً التأكّد من صحة ضبط GOPATH لتحديد المشاكل وحلّها.

التعليمات

  1. انتقِل إلى الدليل webpkgserver (قد تكون في هذا الدليل حاليًا).

    cd /path/to/cmd/webpkgserver

  2. يمكنك إنشاء ملف webpkgsever.toml من خلال نسخ المثال.

    cp ./webpkgserver.example.toml ./webpkgserver.toml

    يحتوي هذا الملف على خيارات الضبط لـ webpkgserver.

  3. افتح webpkgserver.toml باستخدام محرِّر من اختيارك وأدخِل التعديلات التالية:

    • غيِّر السطر #AllowTestCert = false إلى AllowTestCert = true.
    • غيِّر السطر PEMFile = 'path/to/your.pem' ليعكس مسار شهادة PEM، cert.pem، التي أنشأتها. لا تغيِّر السطر الذي يشير إلى TLS.PEMFile، فهذا خيار إعداد مختلف.
    • غيِّر السطر KeyFile = 'priv.key' ليعكس مسار المفتاح الخاص priv.key الذي أنشأته. لا تغيّر السطر الذي يشير إلى TLS.KeyFile، فهذا خيار إعداد مختلف.
    • غيِّر السطر #CertURLBase = '/webpkg/cert' إلى CertURLBase = 'data:'. يشير الرمز CertURLBase إلى موقع عرض شهادة SXG . وتُستخدَم هذه المعلومات لضبط المعلَمة cert-url في العنوان Signature من SXG. في بيئات الإنتاج، يتم استخدام CertURLBase على النحو التالي: CertURLBase = 'https://mysite.com/'. ومع ذلك، في ما يتعلّق بالاختبار على الجهاز، يمكن استخدام CertURLBase = 'data:' لتوجيه webpkgserver باستخدام عنوان URL لبيانات لدمج الشهادة في الحقل cert-url. بالنسبة إلى الاختبار على الجهاز، هذه هي الطريقة الأكثر ملاءمةً لعرض شهادة SXG.
    • غيِّر السطر Domain = 'example.org' ليعكس النطاق الذي أنشأت شهادة له. إذا اتّبعت التعليمات الواردة في هذه المقالة حرفيًا، من المفترض أن يتغيّر هذا الرمز إلى example.com. لن يجلب webpkgserver المحتوى إلا من النطاق المشار إليه في webpkgserver.toml. إذا حاولت جلب صفحات من نطاق مختلف بدون تعديل webpkgserver.toml، ستعرض سجلّات webpkgserver رسالة الخطأ URL doesn't match the fetch targets.

    اختياريّ

    إذا كنت تريد تفعيل تحميل موارد فرعية مسبَقًا أو إيقافه، يمكنك استخدام خيارات الضبط webpkgserver.toml التالية:

    • لكي تُدرِج webpkgserver توجيهات لتحميل ملفات stylesheet والموارد الفرعية للنص البرمجي مسبقًا كملفّات SXG، غيِّر السطر #PreloadCSS = false إلى PreloadCSS = true. إضافةً إلى ذلك، غيِّر السطر #PreloadJS = false ليصبح PreloadJS = true.

      كبديل لاستخدام خيار الضبط هذا، يمكنك يدوياً إضافة رؤوس Link: rel="preload" وعلامات <link rel="preload"> إلى ملف HTML الخاص بالصفحة.

    • تستبدِل علامة webpkgserver تلقائيًا علامات <link rel="preload"> الحالية بعلامات <link> المكافئة اللازمة لجلب هذا المحتوى بتنسيق SXG. لتنفيذ ذلك، سيضبط webpkgserver توجيهات allowed-alt-sxg وheader-integrity حسب الحاجة، ولا يحتاج مؤلفو HTML إلى إضافتها يدويًا. لتجاوز هذا السلوك والاحتفاظ بالعمليات الحالية لتحميل المحتوى مسبقًا غير المستندة إلى SXG، غيِّر قيمة الإعداد #KeepNonSXGPreloads (default = false) إلى KeepNonSXGPreloads = true. يُرجى العِلم أنّ تفعيل هذا الخيار قد يجعل خدمة SXG غير مؤهَّلة للاستفادة من ذاكرة التخزين المؤقت لخدمة SXG من Google وفقًا لهذه المتطلبات.

  4. ابدأ webpkgserver.

    ./webpkgserver

    إذا بدأ الخادم بنجاح، من المفترض أن تظهر لك رسائل السجلّ التالية: shell Listening at 127.0.0.1:8080 Successfully retrieved valid OCSP. Writing to cache in /private/tmp/webpkg

    قد تبدو رسائل السجلّ مختلفة قليلاً. على وجه الخصوص، يختلف الدليل الذي يستخدمه webpkgserver لتخزين الشهادات مؤقتًا حسب نظام التشغيل.

    إذا لم تظهر لك هذه الرسائل، من الجيد أولاً أن تعيد التحقّق من webpkgserver.toml.

    في حال تحديث webpkgserver.toml، عليك إعادة تشغيل webpkgserver.

  5. شغِّل Chrome باستخدام الأمر التالي: shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \ --user-data-dir=/tmp/udd \ --ignore-certificate-errors-spki-list=`openssl x509 -noout -pubkey -in cert.pem | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64`

    يوجّه هذا الأمر متصفّح Chrome إلى تجاهل أخطاء الشهادة المرتبطة بـ cert.pem. يتيح ذلك اختبار ملفات SXG باستخدام ملف شهادة اختبار. إذا تم تشغيل Chrome بدون هذا الأمر، سيؤدي فحص SXG في أدوات مطوري البرامج إلى عرض الخطأ Certificate verification error: ERR_CERT_INVALID.

    ملاحظة:

    قد تحتاج إلى تعديل هذا الأمر ليعكس موقع Chrome على جهازك، بالإضافة إلى موقع cert.pem. إذا قمت بذلك بشكل صحيح، يُفترض أن ترى تحذيرًا أسفل شريط العناوين. من المفترض أن يظهر التحذير بالشكل التالي: You are using an unsupported command-line flag: --ignore-certificate-errors-spki-list=9uxADcgc6/ho0mJLRMBcOjfBaN21k0sOInoMchr9CMY=.

    إذا لم يتضمّن التحذير سلسلة تجزئة، هذا يعني أنّك لم تشير إلى موقع شهادة SXG بشكل صحيح.

  6. افتح علامة التبويب الشبكة في "أدوات مطوّري البرامج"، ثم انتقِل إلى عنوان URL التالي: http://localhost:8080/priv/doc/https://example.com.

    يؤدي هذا الإجراء إلى إرسال طلب إلى مثيل webpackager الذي يتم تشغيله على http://localhost:8080 لملف SXG الذي يتضمّن محتوى https://example.com. /priv/doc/ هي نقطة نهاية واجهة برمجة التطبيقات التلقائية التي يستخدمها webpackager.

    لقطة شاشة لعلامة التبويب &quot;الشبكة&quot; في &quot;أدوات مطوّري البرامج&quot; تعرض ملف SXG وشهادته

    يتم إدراج المراجع التالية في علامة التبويب الشبكة:

    • مورد من النوع signed-exchange هذا هو SXG.
    • مورد من النوع cert-chain+cbor هذه هي شهادة SXG. يجب أن تستخدم شهادات SXG تنسيق application/cert-chain+cbor.
    • مورد من النوع document هذا هو المحتوى الذي تم إرساله من خلال SXG.

    إذا لم تظهر لك هذه المراجع، حاوِل محو ذاكرة التخزين المؤقت للمتصفّح، ثم أعِد تحميل الصفحة http://localhost:8080/priv/doc/https://example.com.

    انقر على علامة التبويب معاينة للاطّلاع على مزيد من المعلومات عن ملف Signed Exchange وتوقيعه.

    لقطة شاشة لعلامة التبويب &quot;المعاينة&quot; تعرِض ملف SXG

عرض عمليات التبادل الموقَّعة باستخدام شهادة CanSignHttpExchanges

توضّح التعليمات الواردة في هذا القسم كيفية عرض جداول بيانات SXG باستخدام شهادة CanSignHttpExchanges. يتطلب استخدام ملفات SXG في مرحلة الإنتاج شهادة CanSignHttpExchanges.

اختصارًا، تم وضع هذه التعليمات بافتراض أنّك تفهم المفاهيم التي تمت مناقشتها في قسم إعداد عمليات Signed Exchange باستخدام شهادة موقَّعة ذاتيًا .

المتطلبات الأساسية

  • لديك شهادة CanSignHttpExchanges. تعرِض هذه الصفحة مراجع التصديق التي تقدّم هذا النوع من الشهادات.

  • إذا لم يكن لديك شهادة، يمكنك ضبط webpkgserver ل retrieving automatically retrieve certificates from your CA. يمكنك اتّباع التعليمات حول ما يجب إدخاله في الحقل webpkgserver.toml في هذه الصفحة.

  • رغم أنّ هذا الأمر ليس شرطًا، ننصحك بشدة بتشغيل "webpkgserver" خلف خادم Edge. إذا كنت لا تستخدم خادمًا طرفيًا، عليك ضبط خيارَي TLS.PEMFile وTLS.KeyFile في webpkgserver.toml. يتم تشغيل webpkgserver تلقائيًا عبر HTTP. ومع ذلك، يجب عرض شهادات SXG عبر HTTPS ليعتبرها المتصفّح صالحة. يتيح ضبط TLS.PEMFile وTLS.KeyFile لـ webpkgserver استخدام بروتوكول HTTPS وبالتالي عرض شهادة SXG مباشرةً في المتصفّح.

التعليمات

  1. أنشئ ملف PEM من خلال تسلسل شهادة SXG لموقعك الإلكتروني ثم شهادة هيئة إصدار الشهادات لموقعك الإلكتروني. يمكنك الاطّلاع على مزيد من التعليمات حول هذا الموضوع هنا.

    PEM هو تنسيق ملف يُستخدَم عادةً كسِمة "حاوية" لتخزين عدة شهادات.

  2. أنشئ ملف webpkgsever.toml جديدًا عن طريق نسخ المثال.

    cp ./webpkgserver.example.toml ./webpkgserver.toml

  3. افتح webpkgserver.toml باستخدام المحرِّر الذي تختاره واحرِص على إجراء التغييرات التالية:

    • غيِّر السطر PEMFile = cert.pem ليعكس موقع ملف PEM الذي يحتوي على سلسلة الشهادة الكاملة.
    • عليك تغيير السطر KeyFile = 'priv.key' ليعكس موقع المفتاح الخاص المقابل لملف PEM.
    • غيِّر السطر Domain = 'example.org' ليعكس موقعك الإلكتروني.
    • (اختياري) لتجديد شهادة SXG تلقائيًا كل 90 يومًا (45 يومًا في Google) من خلال webpkgserver، عليك ضبط الخيارات في قسم [SXG.ACME] من webpkgserver.toml. لا ينطبق هذا الخيار إلا على المواقع الإلكترونية التي تم إعداد حساب DigiCert أو Google ACME لها.

  4. اضبط خادم الحافة لإعادة توجيه الزيارات إلى مثيل webpkgserver .

    هناك نوعان أساسيان من الطلبات التي يعالجها webpkgserver: طلبات لخدمات SXG (التي تقدّمها نقطة النهاية /priv/doc/) وطلبات شهادة SXG (التي تقدّمها نقطة النهاية /webpkg/cert/). تختلف قواعد إعادة كتابة عناوين URL لكل نوع من أنواع الطلبات هذه بشكل طفيف. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة التشغيل من خلال خادم edge للواجهة الأمامية.

    ملاحظة:

    يعرض webpkgserver تلقائيًا شهادة SXG على العنوان /webpkg/cert/$CERT_HASH، على سبيل المثال، /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY. لإنشاء $CERT_HASH، شغِّل الأمر التالي: shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =