איך מציגים חילופי מודעות חתומות (SXG) באמצעות Web Packager
החלפה חתומה (SXG) היא מנגנון העברה שמאפשר לאמת את המקור של משאב ללא קשר לאופן שבו הוא הועבר.
בהוראות הבאות מוסבר איך להגדיר Signed Exchanges באמצעות Web Packager. ההוראות כוללות גם אישורים בחתימה עצמית וגם אישורי CanSignHttpExchanges
.
הצגת קובצי SXG באמצעות אישור עם חתימה עצמית
השימוש באישור עם חתימה עצמית להצגת קובצי SXG משמש בעיקר למטרות הדגמה ובדיקה. קובצי SXG שנחתמו באמצעות אישור בחתימה עצמית יגרמו להצגת הודעות שגיאה בדפדפן אם משתמשים בהם מחוץ לסביבות הבדיקה, ואין להציג אותם לסורקרים.
דרישות מוקדמות
כדי לפעול לפי ההוראות האלה, צריך להתקין את openssl ואת Go בסביבת הפיתוח.
יצירת אישור בחתימה עצמית
בקטע הזה מוסבר איך ליצור אישור עם חתימה עצמית שאפשר להשתמש בו בהחלפות חתומות.
הוראות
יוצרים מפתח פרטי.
openssl ecparam -out priv.key -name prime256v1 -genkey
המפתח הפרטי יישמר כקובץ בשם
priv.key
.יוצרים בקשת חתימה על אישור (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 בסביבת ייצור, זה יהיה אתר בבעלותכם. עם זאת, בסביבת בדיקה כמו זו שמתוארת בהוראות האלה, אפשר להשתמש בכל אתר.
יוצרים אישור עם התוסף
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 לבדיקה
דרישות מוקדמות
מתקינים את Web Packager.
git clone https://github.com/google/webpackager.git
גרסת build
webpkgserver
.cd webpackager/cmd/webpkgserver go build .
webpkgserver
הוא קובץ בינארי ספציפי בפרויקט Web Packager.מוודאים ש-
webpkgserver
הותקן בצורה תקינה../webpkgserver --help
הפקודה הזו אמורה להחזיר מידע על השימוש ב-
webpkgserver
. אם זה לא עובד, שלב ראשון טוב לפתרון בעיות הוא לוודא ש-GOPATH מוגדר בצורה נכונה.
הוראות
עוברים לספרייה
webpkgserver
(יכול להיות שאתם כבר נמצאים בספרייה הזו).cd /path/to/cmd/webpkgserver
יוצרים קובץ
webpkgsever.toml
על ידי העתקת הדוגמה.cp ./webpkgserver.example.toml ./webpkgserver.toml
הקובץ הזה מכיל את אפשרויות התצורה של
webpkgserver
.פותחים את הקובץ
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
, תופיע הודעת השגיאהURL doesn't match the fetch targets
ביומניwebpkgserver
.
אופציונלי
אם רוצים להפעיל או להשבית טעינה מראש של משאבי משנה, אפשר להשתמש באפשרויות ההגדרה הבאות של
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, כפי שמפורט בדרישות האלה.
- משנים את השורה
מפעילים את
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
.מפעילים את 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 ב-DevTools תוצג השגיאה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.
פותחים את הכרטיסייה Network (רשת) בכלי הפיתוח, ולאחר מכן נכנסים לכתובת ה-URL הבאה:
http://localhost:8080/priv/doc/https://example.com
.הפעולה הזו שולחת בקשה למכונה
webpackager
שפועלת ב-http://localhost:8080
לקבלת קובץ SXG שמכיל את התוכן שלhttps://example.com
./priv/doc/
היא נקודת הקצה (endpoint) שמוגדרת כברירת מחדל ל-webpackager
.המשאבים הבאים מפורטים בכרטיסייה Network:
- משאב מסוג
signed-exchange
. זהו ה-SXG. - משאב מסוג
cert-chain+cbor
. זהו אישור ה-SXG. אישורי SXG חייבים להיות בפורמטapplication/cert-chain+cbor
. - משאב מסוג
document
. זהו התוכן שנשלח באמצעות SXG.
אם המשאבים האלה לא מופיעים, נסו לנקות את המטמון של הדפדפן ואז לטעון מחדש את
http://localhost:8080/priv/doc/https://example.com
.לוחצים על הכרטיסייה Preview כדי לראות מידע נוסף על Signed Exchange ועל החתימה שלו.
- משאב מסוג
הצגת חילופי נתונים חתומות באמצעות אישור CanSignHttpExchanges
ההוראות שבקטע הזה מוסבר איך להציג קובצי SXG באמצעות אישור CanSignHttpExchanges
. כדי להשתמש ב-SXG בסביבת ייצור, נדרש אישור CanSignHttpExchanges
.
כדי לקצר את ההוראות, הנחנו שאתם מבינים את המושגים שמפורטים בקטע הגדרת Signed Exchanges באמצעות אישור בחתימה עצמית.
דרישות מוקדמות
יש לך אישור
CanSignHttpExchanges
. בדף הזה מפורטות רשויות האישורים שמציעות את סוג האישור הזה.אם אין לכם אישור, תוכלו להגדיר את webpkgserver לאחזר אישורים באופן אוטומטי מרשות האישורים. בדף הזה מוסבר מה צריך להיכנס לשדה
webpkgserver.toml
.אין צורך לעשות זאת, אבל מומלץ מאוד להריץ את
webpkgserver
מאחורי שרת קצה. אם אתם לא משתמשים בשרת קצה, תצטרכו להגדיר את האפשרויותTLS.PEMFile
ו-TLS.KeyFile
בקובץwebpkgserver.toml
. כברירת מחדל,webpkgserver
פועל באמצעות HTTP. עם זאת, כדי שהדפדפן יכיר בתוקף של אישורי SXG, הם צריכים להישלח באמצעות HTTPS. הגדרתTLS.PEMFile
ו-TLS.KeyFile
מאפשרת ל-webpkgserver
להשתמש ב-HTTPS, ולכן להציג את אישור ה-SXG ישירות בדפדפן.
הוראות
יוצרים קובץ PEM על ידי שרשור של אישור ה-SXG של האתר ואחריו אישור ה-CA של האתר. הוראות נוספות זמינות כאן.
PEM הוא פורמט קובץ שמשמש בדרך כלל כ'קונטיינר' לאחסון כמה אישורים.
יוצרים קובץ
webpkgsever.toml
חדש על ידי העתקת הדוגמה.cp ./webpkgserver.example.toml ./webpkgserver.toml
פותחים את הקובץ
webpkgserver.toml
בכלי העריכה שבחרתם ומבצעים את השינויים הבאים:- משנים את השורה
PEMFile = cert.pem
כך שתשקף את המיקום של קובץ ה-PEM שמכיל את שרשרת האישורים המלאה. - משנים את השורה
KeyFile = 'priv.key'
כך שתשקף את המיקום של המפתח הפרטי התואם לקובץ ה-PEM. - משנים את הקו
Domain = 'example.org'
כך שישקף את האתר שלכם. - (אופציונלי) כדי ש-
webpkgserver
יחדש באופן אוטומטי את אישור ה-SXG כל 90 יום (45 יום ל-Google), מגדירים את האפשרויות בקטע[SXG.ACME]
ב-webpkgserver.toml
. האפשרות הזו רלוונטית רק לאתרים שהוגדרו בהם חשבון DigiCert או חשבון ACME של Google.
- משנים את השורה
מגדירים את שרת הקצה להעברת תנועה למכונה
webpkgserver
.יש שני סוגים עיקריים של בקשות שמטופלות על ידי
webpkgserver
: בקשות ל-SXG (שמוצגות על ידי נקודת הקצה/priv/doc/
) ובקשות לאישור SXG (שמוצגות על ידי נקודת הקצה/webpkg/cert/
). כללי הכתיבה מחדש של כתובות ה-URL משתנים מעט בהתאם לכל סוג של בקשה. למידע נוסף, ראו הפעלה מאחורי שרת קצה של קצה חזית.הערה:
כברירת מחדל,
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 =