איך להגדיר 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/ הוא נקודת הקצה ב-API שמוגדרת כברירת מחדל, שבה משתמש 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 כדי לראות מידע נוסף על Signature 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 =