การหมุนเวียนคีย์

Robert Ferens

Demián Renzulli

เอกสารนี้ให้ข้อมูลที่จำเป็นเกี่ยวกับกระบวนการหมุนเวียนคีย์สำหรับเว็บแอปที่แยกจากกัน (IWA) รวมถึงเวลาที่จำเป็นและขั้นตอนที่นักพัฒนาแอปต้องทำตามหากคีย์สูญหายหรือถูกบุกรุก

การหมุนเวียนคีย์สำหรับ IWA

การหมุนเวียนคีย์เป็นกลไกที่ช่วยให้สามารถแทนที่คีย์ส่วนตัวที่ใช้ในการลงนาม IWA ได้ในกรณีที่คีย์รั่วไหลหรือสูญหาย กระบวนการนี้ช่วยให้แอปทํางานได้และรักษา Bundle ID และแหล่งที่มาที่เสถียร เพื่อให้มั่นใจว่าการจัดจำหน่ายและการอัปเดตแอปจะดำเนินต่อไปได้

กระบวนการหมุนเวียนคีย์ไม่จำเป็นต้องมีการเปลี่ยนแปลงใดๆ จากผู้ดูแลระบบหรือผู้ใช้ และหากดำเนินการอย่างถูกต้อง ผู้ดูแลระบบหรือผู้ใช้จะไม่รับรู้ถึงการหมุนเวียนคีย์ ช่องทางติดต่อที่เชื่อถือได้ ซึ่งสร้างขึ้นระหว่างกระบวนการเพิ่มในรายการที่อนุญาตครั้งแรกมีความสำคัญต่อ การเปิดใช้การหมุนเวียนคีย์

ความจำเป็นในการหมุนเวียนคีย์

การหมุนเวียนคีย์มีความจำเป็นอย่างยิ่งใน 2 สถานการณ์หลักต่อไปนี้

• คีย์รั่วไหลหรือถูกแฮ็ก: หากคีย์การลงนามส่วนตัวถูกแฮ็กหรือ อาจรั่วไหล คุณต้องเริ่มกระบวนการหมุนเวียนคีย์ทันทีเพื่อ รักษาความปลอดภัยของแอปพลิเคชัน คีย์ที่รั่วไหลอาจถูกใช้เพื่อแอบอ้างเป็นคุณ สร้างความเสียหายให้กับผู้ใช้แอป และเป็นอันตรายต่อชื่อเสียงของบริษัท
• คีย์สูญหาย: หากคุณเสียสิทธิ์เข้าถึงคีย์การลงนามส่วนตัวและลงนามในการอัปเดตใหม่ไม่ได้ คุณจะต้องหมุนเวียนคีย์เพื่อสร้างความสามารถในการเผยแพร่แอปพลิเคชันขึ้นมาใหม่

ข้อกำหนดสำหรับนักพัฒนาแอป

ก่อนเริ่มการหมุนเวียนคีย์ คุณต้องมีคุณสมบัติตรงตามเกณฑ์ต่อไปนี้

• แอปในรายการที่อนุญาต: เฉพาะแอปในรายการที่อนุญาตเท่านั้นที่อาจมีการ การหมุนเวียนคีย์
• อีเมลที่เชื่อถือได้: คุณต้องใช้อีเมลที่เชื่อถือได้ซึ่งระบุไว้ในระหว่าง กระบวนการเพิ่มในรายการที่อนุญาตเพื่อขอการหมุนเวียนคีย์

การลงนามแอปที่โฮสต์และเผยแพร่เวอร์ชันใหม่

หลังจากหมุนเวียนคีย์แล้ว ระบบจะบล็อกอินสแตนซ์ของแอปที่ติดตั้งทั้งหมดซึ่งไม่ได้ลงนามด้วย คีย์ที่ถูกต้อง คุณต้องส่งแอปที่ลงนามด้วยคีย์ใหม่ (หรือทั้ง 2 คีย์) เพื่อป้องกันไม่ให้ผู้ใช้ได้รับผลกระทบ ดูรายละเอียดทางเทคนิคของการ ลงนามในชุดได้ที่ส่วน วิธีลงนามในชุดด้วยคีย์หลายรายการ สถานการณ์ต่างๆ จะแตกต่างกันไปตามสถานการณ์เฉพาะของคุณ ดังนี้

สถานการณ์ A: คีย์ไม่ได้สูญหาย (เช่น การหมุนเวียนเชิงรุกหรือการรั่วไหล)

คุณต้องลงนามในแอปด้วยคีย์ทั้ง 2 คีย์ (คีย์เก่าและคีย์ใหม่) และส่งคีย์เหล่านั้น ให้ผู้ใช้โดยทำอย่างใดอย่างหนึ่งต่อไปนี้

• การเผยแพร่แอปเวอร์ชันใหม่ (การเพิ่มเวอร์ชันใหม่ลงในไฟล์ Manifest ของการอัปเดต) หรือ
• อัปเดตไฟล์ .swbn ที่โฮสต์ (ลิงก์ในไฟล์ Manifest ของการอัปเดต) ให้ลงนามด้วยคีย์ทั้ง 2 รายการ เครื่องมือ CLI ช่วยให้คุณเพิ่ม ลายเซ็นอีกรายการลงในแพ็กเกจ swbn ที่มีอยู่ได้

คุณต้องดำเนินการนี้ก่อนที่ Google จะประมวลผลการหมุนเวียนคีย์เพื่อให้มั่นใจว่าผู้ใช้จะไม่สังเกตเห็นการเปลี่ยนแปลง

หมายเหตุ: หากผู้ดูแลระบบใช้การตรึงเวอร์ชัน ผู้ดูแลระบบจะต้องอัปเดต แพ็กเกจที่โฮสต์สำหรับเวอร์ชันนี้ หรือตรึงแอปไว้กับเวอร์ชันที่ลงนามด้วยคีย์ทั้ง 2 รายการ

สถานการณ์ ข: กุญแจหาย

เนื่องจากลงนามในแอปด้วยคีย์ที่สูญหายไม่ได้ กรณีนี้จึงมีความซับซ้อนมากขึ้น ขอการหมุนเวียนคีย์และสอบถามขั้นตอนเพิ่มเติมจากผู้ติดต่อที่ Google คุณอาจได้รับแจ้งให้เพิ่มลายเซ็นใหม่ลงในแพ็กเกจที่โฮสต์โดยทำตามวิธีการเหล่านี้

หมายเหตุ: หากคุณใช้การตรึงเวอร์ชันและเผยแพร่แอปเวอร์ชันใหม่สำหรับการหมุนเวียนคีย์ ให้พิจารณาเปลี่ยนเวอร์ชันที่ตรึงไว้

กระบวนการหมุนเวียนคีย์

กระบวนการหมุนเวียนคีย์มีขั้นตอนดังนี้

ขั้นตอน	การดำเนินการ	รายละเอียด	รับผิดชอบ
1	ขอการหมุนเวียนคีย์	นักพัฒนาแอป/พาร์ทเนอร์ติดต่อผู้ติดต่อของตนใน Google (วิศวกรรมพาร์ทเนอร์หรือผู้ติดต่ออื่นๆ) ผ่านอีเมลที่เชื่อถือได้ ซึ่งระบุไว้ในกระบวนการเพิ่มในรายการที่อนุญาต และขอวิธีการหมุนเวียนคีย์พร้อมอธิบายเหตุผล ในกรณีที่คีย์ถูกบุกรุก เราขอแนะนำให้แนบไฟล์ Manifest การอัปเดตพร้อมกับแพ็กเกจที่ลงนามด้วยคีย์เก่าและใหม่เพื่อเร่งกระบวนการ	นักพัฒนาแอป / พาร์ทเนอร์
2	การตอบกลับผู้ขอ	ตัวแทนของ Google จะแจ้งวิธีการเพิ่มเติมและถามคำถามกับผู้ขอ ขั้นตอนนี้อาจต้องมีการโต้ตอบกัน 2-3 ครั้ง	รายชื่อติดต่อ Google
3	ระบุข้อมูล	นักพัฒนาแอป/พาร์ทเนอร์ทำตามวิธีการ ซึ่งอาจรวมถึงการดำเนินการต่อไปนี้ ลงนามในชุดแอปอีกครั้งด้วยคีย์ใหม่ อัปเดตหรือระบุไฟล์ Manifest การอัปเดตพร้อมแอปที่อัปเดตแล้ว ให้ข้อมูลเพิ่มเติม เช่น รายละเอียดสถานการณ์ อันตราย หรือรายละเอียดทางเทคนิค เช่น วงจรการเปิดตัวแอปของพาร์ทเนอร์ การรับทราบความพร้อมในการหมุนเวียน: เราขอแนะนำให้ดำเนินการหลังจากผ่านไปอย่างน้อย 3 วันหลังจากอัปเดตแอปไคลเอ็นต์และตรวจสอบว่าแอปได้รับการอัปเดตแล้ว	นักพัฒนาแอป / พาร์ทเนอร์
4	การประมวลผลคำขอและ การแสดงความคิดเห็น	Google จะตรวจสอบคำขอการหมุนเวียนคีย์และตอบกลับภายใน 1 สัปดาห์ทำการ โดยอาจอนุมัติ ปฏิเสธ หรือติดต่อกับนักพัฒนาแอปเพื่อสอบถามเพิ่มเติม เมื่อได้รับอนุมัติ Google จะหมุนเวียนคีย์และแสดงความคิดเห็น	รายชื่อติดต่อ Google

อัปเดตการปักหมุดช่องและเวอร์ชัน

บางครั้งผู้ดูแลระบบจะใช้ช่องการอัปเดตที่กำหนดเองหรือการตรึงเวอร์ชัน ซึ่งช่วยให้ผู้ดูแลระบบ จัดการเวอร์ชันของแอปในอุปกรณ์ไคลเอ็นต์ได้ หลังจากการหมุนเวียนคีย์ แอปทั้งหมดที่ติดตั้งด้วยคีย์ที่ไม่ถูกต้องจะกลายเป็นไม่ถูกต้องและถูกบล็อก หากต้องการป้องกันปัญหานี้ คุณต้องอัปเดตและลงชื่อแอปเวอร์ชันก่อนหน้าซึ่งโฮสต์ภายใต้ลิงก์ที่ระบุไว้ในupdate_manifest.jsonด้วยลายเซ็น 2 รายการก่อนที่จะหมุนเวียนคีย์ หากคีย์เก่าสูญหายและลงนามในแอปด้วยคีย์ 2 คีย์ไม่ได้ โปรดแจ้งผู้ติดต่อของ Google ทันที เราจะทำงานร่วมกับคุณ เพื่อลดผลกระทบจากสถานการณ์นี้ เพื่อให้แอปได้รับการอัปเดตโดยไม่รบกวนเวิร์กโฟลว์ของผู้ใช้

วิธีลงนามในแพ็กเกจด้วยคีย์หลายรายการ

ส่วนนี้จะอธิบายวิธีลงนามใน Web Bundle ด้วยคีย์ 1 หรือ 2 รายการ ผ่านเครื่องมือ CLI หรือการกำหนดค่าปลั๊กอิน Webpack/Rollup/Vite นอกจากนี้ เครื่องมือ CLI ยังช่วยให้คุณ เพิ่มลายเซ็นอีก 1 รายการลงในswbn บันเดิลที่มีอยู่ได้ ซึ่งอาจมีประโยชน์ ในกรณีที่คีย์สูญหายหรือเมื่ออัปเดตบันเดิลที่โฮสต์ก่อนหน้านี้

เครื่องมือ CLI

ก่อนอื่น ตรวจสอบว่าคุณได้ติดตั้งแพ็กเกจ wbn-sign ด้วย npm แล้ว

$ npm i wbn-sign

เพิ่ม -g เพื่อติดตั้งแพ็กเกจทั่วโลกแทนที่จะติดตั้งเฉพาะในโฟลเดอร์ปัจจุบัน

การลงนามด้วยคีย์เดียว

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

การลงนามด้วยคีย์ 2 รายการ

$ 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 เป็นคีย์แรกที่ใช้ลงนามแอปเวอร์ชันเริ่มต้น จากนั้นระบบจะสร้างรหัส Bundle จากคีย์ คุณยืนยัน Bundle ID ได้ด้วยคำสั่ง wbn-sign info signed.swbn

การเพิ่มลายเซ็นลงในแพ็กเกจที่มีอยู่

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

ใช้ -o หากไม่ต้องการลบล้าง Bundle แต่ต้องการสร้าง double-signed ใหม่

ข้อมูลเพิ่มเติมเกี่ยวกับเครื่องมือ 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)
    }
  })
)

การลงนามด้วยคีย์ 2 รายการ

เมื่อคุณต้องลงนามในแอปพลิเคชัน 2 ครั้งในระหว่างการหมุนเวียนคีย์ ให้ทำดังนี้

• กำหนด webBundleId และ URL ฐานตาม 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'
})

การลงนามด้วยคีย์ 2 รายการ

หากต้องการลงนามในแอปพลิเคชัน 2 ครั้งโดยใช้ 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 โดยทันทีผ่านอีเมลที่เชื่อถือได้ซึ่งคุณระบุไว้