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

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

Katie Hempenius
Katie Hempenius
X

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

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

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

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

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

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

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

التعليمات

  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'

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

    يؤدي الأمر أعلاه إلى إنشاء طلب توقيع شهادة لمؤسسة تحمل اسم 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")

    يستخدم هذا الأمر المفتاح الخاص وCSR الذي تم إنشاؤه في الخطوتين 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 في توجيهات التحميل المُسبق لورقة الأنماط والموارد الفرعية للنص البرمجي كملفات 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; تظهر فيها آلية 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;Preview&quot; (معاينة) تعرض SXG

عرض تنسيقات Signed Exchange باستخدام شهادة CanSignHttpExchanges

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

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

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

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

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

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

التعليمات

  1. يمكنك إنشاء ملف PEM من خلال ربط شهادة SXG لموقعك الإلكتروني متبوعة بشهادة CA لموقعك الإلكتروني. يمكنك الاطّلاع على مزيد من التعليمات حول هذا الموضوع هنا.

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

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

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

  3. افتح webpkgserver.toml باستخدام المحرِّر الذي تريده وأدخِل التغييرات التالية:

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

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

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

    ملاحظة:

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