איך להגדיר Signed Exchanges באמצעות Web Packager

איך מציגים חילופי מודעות חתומות (SXG) באמצעות Web Packager

Katie Hempenius
Katie Hempenius
X

החלפה חתומה (SXG) היא מנגנון העברה שמאפשר לאמת את המקור של משאב ללא קשר לאופן שבו הוא הועבר. בהוראות הבאות מוסבר איך להגדיר Signed Exchanges באמצעות 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")

    הפקודה הזו משתמשת במפתח הפרטי וב-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. גרסת build 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, תופיע הודעת השגיאה URL doesn't match the fetch targets ביומני webpkgserver.

    אופציונלי

    אם רוצים להפעיל או להשבית טעינה מראש של משאבי משנה, אפשר להשתמש באפשרויות ההגדרה הבאות של 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 ב-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.

  6. פותחים את הכרטיסייה Network (רשת) בכלי הפיתוח, ולאחר מכן נכנסים לכתובת ה-URL הבאה: http://localhost:8080/priv/doc/https://example.com.

    הפעולה הזו שולחת בקשה למכונה webpackager שפועלת ב-http://localhost:8080 לקבלת קובץ SXG שמכיל את התוכן של https://example.com. /priv/doc/ היא נקודת הקצה (endpoint) שמוגדרת כברירת מחדל ל-webpackager.

    צילום מסך של הכרטיסייה &#39;רשת&#39; בכלי הפיתוח, שבו מוצג קובץ SXG ואישור שלו.

    המשאבים הבאים מפורטים בכרטיסייה 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 ועל החתימה שלו.

    צילום מסך של כרטיסיית התצוגה המקדימה שמוצג בו קובץ SXG

הצגת חילופי נתונים חתומות באמצעות אישור 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 ישירות בדפדפן.

הוראות

  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 או חשבון ACME של Google.

  4. מגדירים את שרת הקצה להעברת תנועה למכונה 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 =