רוטציית מפתחות

Robert Ferens

Demián Renzulli

במסמך הזה מפורט מידע חיוני על תהליך החלפת המפתחות באפליקציית אינטרנט מבודדת (IWA), כולל מתי צריך להחליף מפתחות ומהם השלבים שמפתחים צריכים לבצע אם מפתח אבד או נפרץ.

רוטציית מפתחות עבור אפליקציות אינטרנט מתקדמות

רוטציית מפתחות היא מנגנון שמאפשר להחליף את המפתחות הפרטיים שמשמשים לחתימה על אפליקציית ה-IWA במקרה של דליפה או אובדן. התהליך הזה מאפשר לאפליקציה להמשיך לפעול, ושומר על מזהה ה-Bundle והמקור שלה יציבים, כדי להבטיח את המשכיות של הפצת האפליקציה והעדכונים שלה.

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

הצורך ברוטציית מפתחות

סיבוב חתימות נדרש בשני תרחישים עיקריים:

• דליפה או פריצה של מפתח: אם המפתח הפרטי שלכם נפרץ או שיש חשש לדליפה שלו, אתם צריכים להתחיל מיד את תהליך סיבוב המפתחות כדי לאבטח את האפליקציה. אם המפתח ידלוף, אפשר יהיה להתחזות אליכם, לפגוע במשתמשי האפליקציה ולסכן את המוניטין של החברה.
• איבוד מפתח: אם איבדתם את הגישה למפתח החתימה הפרטי ולא יכולים לחתום על עדכונים חדשים, צריך לבצע סיבוב מפתחות כדי שתוכלו להפיץ את האפליקציה.

דרישות למפתחים

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

• אפליקציה שהוספה לרשימת ההיתרים: רק אפליקציות שהוספו לרשימת ההיתרים יכולות להיות כפופות לרוטציה של מפתחות.
• כתובת אימייל מהימנה: כדי לבקש רוטציה של מפתחות, צריך להשתמש בכתובת האימייל המהימנה שצוינה במהלך תהליך הוספה לרשימת ההיתרים.

חתימה מחדש על אפליקציות מאוחסנות ופרסום גרסאות חדשות

אחרי שמבצעים רוטציה למפתח, כל המופעים המותקנים של האפליקציה שלא נחתמו באמצעות מפתח תקין נחסמים. כדי למנוע שיבושים אצל המשתמשים, צריך לספק אפליקציה שחתמתם עליה עם החתימה החדשה (או עם שתי החתימות). פרטים טכניים על חתימה מחדש של חבילות זמינים בקטע איך חותמים על חבילה באמצעות כמה מפתחות. בהתאם למצב הספציפי שלכם, יש תרחישים שונים:

תרחיש א': המפתח לא אבד (לדוגמה, רוטציה יזומה או דליפה)

אתם צריכים לחתום על האפליקציה עם שני המפתחות (הישן והחדש) ולספק אותה למשתמשים באחת מהדרכים הבאות:

• פרסום גרסה חדשה של האפליקציה (הוספת הגרסה החדשה למניפסטים של העדכון), או
• עדכון של קובצי .swbn שמתארחים (ומקושרים במניפסטים של העדכונים) כך שייחתמו באמצעות שני המפתחות. כלי ה-CLI מאפשר להוסיף חתימה נוספת לחבילת swbn הקיימת.

צריך לבצע את הפעולה הזו לפני ש-Google מעבדת את החלפת המפתחות, כדי שהמשתמשים לא יבחינו בשינוי.

תרחיש ב': המפתח אבד

המקרה הזה מורכב יותר כי אי אפשר לחתום על האפליקציה עם המפתח שאבד. מבקשים את רוטציית המפתחות ופונים לאיש הקשר שלכם ב-Google כדי לקבל מידע על השלבים הבאים. יכול להיות שתתבקשו להוסיף את החתימות החדשות לחבילות המתארחות שלכם בהתאם להוראות האלה.

תהליך רוטציית מפתחות

תהליך רוטציית המפתחות כולל את השלבים הבאים:

עדכון של ערוץ ושל גרסה מוצמדת

אדמינים משתמשים לפעמים בערוצי עדכון מותאמים אישית או בהצמדת גרסה, שמאפשרים להם לנהל את גרסאות האפליקציות במכשירי הלקוח שלהם. אחרי רוטציית מפתחות, כל האפליקציות שהותקנו עם מפתחות לא תקינים הופכות ללא תקינות ונחסמות. כדי למנוע את זה, צריך לעדכן גם גרסאות קודמות של אפליקציות שמתארחות בקישורים שמופיעים ב-update_manifest.json ולחתום עליהן בשתי חתימות לפני רוטציית המפתחות. אם המפתח הישן אבד ואי אפשר לחתום על האפליקציה עם שני מפתחות, צריך להודיע על כך מיד לאיש הקשר שלכם ב-Google. אנחנו נעבוד איתך כדי לפתור את הבעיה, כך שיהיה אפשר לעדכן את האפליקציה בלי לשבש את תהליכי העבודה של המשתמשים.

איך חותמים על חבילה עם כמה מפתחות

בקטע הזה מוסבר איך אפשר לחתום על חבילות אינטרנט באמצעות מפתח אחד או שניים דרך כלי CLI, או באמצעות הגדרת פלאגינים של Webpack/Rollup/Vite. כלי CLI מאפשרים גם להוסיף עוד חתימה לחבילות swbn קיימות, וזה יכול להיות שימושי במקרים של אובדן מפתח או לעדכון חבילות קודמות שמתארחות.

כלי CLI

קודם כול, מוודאים שהחבילה wbn-sign מותקנת באמצעות npm:

$ npm i wbn-sign

מוסיפים -g כדי להתקין את החבילה באופן גלובלי במקום רק בתיקייה הנוכחית.

חתימה עם מפתח אחד

$ wbn-sign -i unsigned.wbn -o signed.swbn -k private.pem

חתימה עם שני מפתחות

$ wbn-sign sign webbundle.wbn old_key.pem new_key.pem -o signed.swbn --web-bundle-id <your-id-from-old-private>

אפשר לדלג על הארגומנט --web-bundle-id <id> אם old_key הוא המפתח הראשון שהגרסה הראשונית של האפליקציה נחתמה איתו, ואז מזהה החבילה יופק מהמפתח. אפשר לאמת את מזהה החבילה באמצעות הפקודה wbn-sign info signed.swbn.

הוספת חתימה לחבילה קיימת

$ wbn-sign add-signature signed.swbn key3.pem --in-place

משתמשים ב--o אם לא רוצים להחליף את החבילה אלא ליצור חבילה חדשה עם חתימה כפולה.

מידע נוסף על כלי CLI

מידע נוסף על השימוש בכלי CLI זמין בדף npm wbn-sign. אפשרות אחרת: wnb-sign help.

פלאגין Webpack

חתימה עם מפתח אחד

כדי להגדיר את הפלאגין Webpack לחתימה על ה-IWA באמצעות מפתח פרטי יחיד:

• מגדירים את WebBundlePlugin כדי לגזור באופן אוטומטי את כתובת ה-URL הבסיסית הנדרשת ישירות מהמפתח הזה.
• משתמשים ב-NodeCryptoSigningStrategy אחד כדי ליצור את קובץ .swbn החתום.

// key is parsePemKey(private.pem)

plugins.push(
  new WebBundlePlugin({
    baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategy: new NodeCryptoSigningStrategy(key)
    }
  })
)

חתימה עם שני מפתחות

כשצריך לחתום על האפליקציה פעמיים במהלך סיבוב מפתחות:

• מגדירים את webBundleId ואת כתובת ה-URL הבסיסית על סמך המקורית (old_key) כדי לוודא שהזהות של האפליקציה תישאר יציבה עבור המשתמשים.
• משתמשים במערך של אסטרטגיות חתימה כדי להחיל את המפתחות הפרטיים הישנים והחדשים.

// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)

plugins.push(
  new WebBundlePlugin({
    baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public') },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategies: [
        new NodeCryptoSigningStrategy(old_key),
        new NodeCryptoSigningStrategy(new_key)
      ],
      webBundleId: new WebBundleId(old_key).serialize()
    }
  })
)

פלאגין Rollup או Vite

חתימה עם מפתח אחד

כדי להשתמש בתוסף Rollup או Vite כדי לחתום על האפליקציה באמצעות מפתח פרטי יחיד, בדומה להגדרה של Webpack, התוסף משתמש באסטרטגיית חתימה יחידה ומטפל בהפקת כתובת ה-URL הבסיסית מהמפתח שסופק כדי ליצור את הפלט החתום.

// key is parsePemKey(private.pem)

plugins.push({
  ...wbn({
    baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategy: new NodeCryptoSigningStrategy(key)
    }
  }),
  enforce: 'post'
})

חתימה עם שני מפתחות

כדי לחתום על האפליקציה באמצעות Rollup או Vite, צריך להגדיר את התוסף כך שיקבל כמה מפתחות. קטע הקוד הזה מחיל את המפתחות הפרטיים הישנים והחדשים באמצעות מערך האסטרטגיות. היא מבטיחה מעבר חלק על ידי שמירה מפורשת של כתובת ה-URL הבסיסית ושל webBundleId שנגזרת מהמפתח המקורי הקיים.

// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)

plugins.push({
  ...wbn({
    baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategies: [
        new NodeCryptoSigningStrategy(old_key),
        new NodeCryptoSigningStrategy(new_key)
      ],
      webBundleId: new WebBundleId(old_key).serialize()
    }
  }),
  enforce: 'post'
})

סיכום

ניהול מוצלח של סבב מפתחות עבור אפליקציית ה-IWA חיוני לשמירה על האבטחה וההמשכיות של הפצת האפליקציה. בלי קשר למצב הספציפי שלכם (למשל, אם המפתח אבד או לא), ביצוע השלבים שמתוארים כאן יבטיח שההפרעה למשתמשים תהיה מינימלית. בעזרת כלי ה-CLI או הגדרות הפלאגין שזמינים ל-Webpack, ל-Rollup או ל-Vite, תוכלו לנהל ביעילות את החתימות של האפליקציה ולבצע את תהליך החלפת המפתחות בצורה חלקה. במקרים של מצבי חירום, חשוב ליצור קשר עם איש הקשר שלכם ב-Google בהקדם האפשרי באמצעות כתובת האימייל המהימנה שצוינה.