איך להגדיר Signed Exchanges באמצעות 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). לא צריך לבקש אישור מ-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, תופיע ביומני 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 לא יהיה כשיר לשמירה במטמון של Google SXG בהתאם לדרישות האלה.

  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=.

    אם האזהרה לא כוללת מחרוזת גיבוב (hash), לא ציינתם בצורה נכונה את המיקום של אישור ה-SXG.

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

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

    צילום מסך של הכרטיסייה DevTools Network (רשת כלי הפיתוח) שמציגה SXG והאישור שלו.

    המשאבים הבאים מפורטים בכרטיסייה רשת:

    • משאב מסוג 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 ועל החתימה שלו.

    צילום מסך של כרטיסיית Preview (תצוגה מקדימה) של SXG

הצג החלפות חתומות באמצעות אישור CanSignHttpExchanges

בקטע הזה מוסבר איך להציג מפתחות SXG באמצעות אישור של CanSignHttpExchanges. כדי להשתמש ב-SXG בסביבת ייצור, נדרש אישור של CanSignHttpExchanges.

לשם קיצור, ההוראות האלה נכתבות מתוך הנחה שהבנתם את המושגים שעליהם מתוארת בקטע הגדרת המרות חתומות באמצעות אישור בחתימה עצמית.

דרישות מוקדמות

  • יש לך אישור של CanSignHttpExchanges. בדף הזה מופיעה רשימה של רשויות האישורים שמציעות אישור מהסוג הזה.

  • אם אין לך אישור, אפשר להגדיר את שרת ה-webpkgserver כך שיאחזר אישורים באופן אוטומטי מ-CA. ניתן לך לעקוב אחר ההוראות לגבי מה שמופיע ב-webpkgserver.toml בדף הזה.

  • זו לא דרישה, אבל מומלץ מאוד להריץ את webpkgserver מאחורי שרת קצה. אם אתם לא משתמשים בשרת קצה, תצטרכו להגדיר את האפשרויות TLS.PEMFile ו-TLS.KeyFile ב-webpkgserver.toml. כברירת מחדל, הפקודה webpkgserver פועלת על HTTP. עם זאת, צריך להציג אישורי SXG ב-HTTPS כדי שהדפדפן יתייחס אליהם כאישורי SXG. הגדרה של 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 לכל אחד מסוגי הבקשות האלה משתנים מעט. למידע נוסף, קרא את המאמר הפעלה מאחורי שרת קצה קצה.

    הערה:

    כברירת מחדל, 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 =