Xoay khoá

Robert Ferens

Demián Renzulli

Tài liệu này cung cấp thông tin cần thiết về quy trình xoay vòng khoá cho một Ứng dụng web riêng biệt (IWA), bao gồm cả thời điểm cần thiết và các bước mà nhà phát triển phải làm theo nếu khoá bị mất hoặc bị xâm phạm.

Thay khoá cho IWA

Xoay vòng khoá là một cơ chế cho phép thay thế các khoá riêng tư dùng để ký IWA trong trường hợp bị rò rỉ hoặc mất. Quy trình này giúp ứng dụng hoạt động và duy trì mã nhận dạng gói cũng như nguồn gốc ổn định, đảm bảo tính liên tục của việc phân phối và cập nhật ứng dụng.

Quy trình xoay vòng khoá không yêu cầu quản trị viên hoặc người dùng thực hiện bất kỳ thay đổi nào và nếu được thực hiện đúng cách, quy trình này sẽ không được họ nhận thấy. Các kênh liên lạc với người liên hệ đáng tin cậy được thiết lập trong quy trình đưa vào danh sách cho phép ban đầu là yếu tố cần thiết để bật tính năng xoay vòng khoá.

Nhu cầu thay khoá

Việc thay khoá là hoàn toàn cần thiết trong 2 trường hợp chính:

• Khoá bị lộ hoặc bị xâm nhập: Nếu khoá ký riêng tư của bạn bị xâm nhập hoặc có khả năng bị lộ, bạn phải bắt đầu ngay quy trình thay khoá để bảo mật ứng dụng. Khoá bị rò rỉ có thể được dùng để mạo danh bạn, gây hại cho người dùng ứng dụng và làm tổn hại đến danh tiếng của công ty bạn.
• Mất khoá: Nếu mất quyền truy cập vào khoá ký riêng tư và không thể ký các bản cập nhật mới, bạn cần xoay vòng khoá để lấy lại khả năng phân phối ứng dụng.

Yêu cầu đối với nhà phát triển

Trước khi bắt đầu xoay khoá, bạn phải đáp ứng các tiêu chí sau:

• Ứng dụng trong danh sách cho phép: Chỉ các ứng dụng trong danh sách cho phép mới có thể phải tuân theo quy trình thay khoá.
• Email đáng tin cậy: Bạn phải sử dụng địa chỉ email đáng tin cậy được cung cấp trong quá trình đưa vào danh sách cho phép để yêu cầu xoay vòng khoá.

Ký lại ứng dụng được lưu trữ và phát hành phiên bản mới

Sau khi thay khoá, tất cả các phiên bản ứng dụng đã cài đặt không được ký bằng khoá hợp lệ sẽ bị chặn. Để tránh gây gián đoạn cho người dùng, bạn phải phân phối một ứng dụng được ký bằng khoá mới (hoặc cả hai khoá). Bạn có thể xem thông tin kỹ thuật về việc ký lại các gói trong phần Cách ký một gói bằng nhiều khoá. Tuỳ thuộc vào tình huống cụ thể của bạn, có nhiều trường hợp như sau:

Trường hợp A: Khoá không bị mất (ví dụ: xoay vòng chủ động hoặc rò rỉ)

Bạn phải ký ứng dụng bằng cả hai khoá (khoá cũ và khoá mới) rồi gửi cho người dùng bằng một trong hai cách:

• Phát hành một phiên bản ứng dụng mới (thêm phiên bản mới vào tệp kê khai bản cập nhật), hoặc
• Cập nhật các tệp .swbn được lưu trữ (được liên kết trong bản kê khai cập nhật) để được ký bằng cả hai khoá. Công cụ CLI cho phép bạn thêm một chữ ký khác vào gói swbn hiện có.

Bạn phải thực hiện việc này trước khi Google xử lý quy trình xoay vòng khoá để đảm bảo người dùng không nhận thấy thay đổi.

Tình huống B: Chìa khoá bị mất

Trường hợp này phức tạp hơn vì ứng dụng không thể được ký bằng khoá bị mất. Yêu cầu xoay vòng khoá và hỏi đầu mối liên hệ của bạn tại Google để biết các bước tiếp theo. Bạn có thể được yêu cầu thêm chữ ký mới vào các gói được lưu trữ theo hướng dẫn này.

Quy trình xoay vòng khoá

Quy trình xoay vòng khoá bao gồm các bước sau:

Cập nhật kênh và ghim phiên bản

Đôi khi, quản trị viên sử dụng các kênh cập nhật tuỳ chỉnh hoặc ghim phiên bản để quản lý các phiên bản ứng dụng trên thiết bị của khách hàng. Sau khi thay khoá, tất cả các ứng dụng được cài đặt bằng khoá không hợp lệ sẽ trở nên không hợp lệ và bị chặn. Để ngăn chặn điều này, các phiên bản trước của ứng dụng được lưu trữ theo các đường liên kết được cung cấp trong update_manifest.json cũng phải được cập nhật và ký bằng hai chữ ký trước khi xoay vòng khoá. Nếu bạn bị mất khoá cũ và không thể ký ứng dụng bằng hai khoá, hãy thông báo ngay cho người liên hệ của bạn tại Google. Chúng tôi sẽ làm việc với bạn để giảm thiểu tình trạng này để ứng dụng có thể được cập nhật mà không làm gián đoạn quy trình làm việc của người dùng.

Cách ký một gói bằng nhiều khoá

Phần này mô tả cách bạn có thể ký các gói web bằng một hoặc hai khoá thông qua các công cụ CLI hoặc cấu hình trình bổ trợ Webpack/Rollup/Vite. Các công cụ CLI cũng cho phép thêm một chữ ký khác vào các gói swbn hiện có. Điều này có thể hữu ích trong trường hợp mất khoá hoặc cập nhật các gói được lưu trữ trước đó.

Công cụ CLI

Trước tiên, hãy đảm bảo bạn đã cài đặt gói wbn-sign bằng npm:

$ npm i wbn-sign

Thêm -g để cài đặt gói trên toàn cầu thay vì chỉ cài đặt trong thư mục hiện tại.

Ký bằng một khoá

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

Ký bằng hai khoá

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

Bạn có thể bỏ qua đối số --web-bundle-id <id> nếu old_key là khoá đầu tiên mà phiên bản ban đầu của ứng dụng được ký bằng khoá đó, thì mã nhận dạng gói sẽ được lấy từ khoá. Bạn có thể xác minh mã nhận dạng gói bằng lệnh wbn-sign info signed.swbn.

Thêm chữ ký vào gói hiện có

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

Sử dụng -o nếu bạn không muốn ghi đè gói nhưng muốn tạo một gói mới có chữ ký kép.

Thông tin khác về Công cụ CLI

Để biết thêm thông tin về cách sử dụng công cụ CLI, hãy xem trang npm wbn-sign. Hoặc sử dụng: wnb-sign help.

Trình bổ trợ Webpack

Ký bằng một khoá

Cách định cấu hình trình bổ trợ Webpack để ký IWA bằng một khoá riêng tư duy nhất:

• Thiết lập WebBundlePlugin để tự động lấy URL cơ sở bắt buộc trực tiếp từ khoá này.
• Sử dụng một NodeCryptoSigningStrategy để tạo tệp .swbn đã ký.

// 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)
    }
  })
)

Ký bằng hai khoá

Khi bạn cần ký ứng dụng hai lần trong quá trình thay khoá:

• Xác định webBundleId và URL cơ sở dựa trên (old_key) ban đầu để đảm bảo danh tính của ứng dụng luôn ổn định đối với người dùng.
• Sử dụng một loạt chiến lược ký để áp dụng cả khoá riêng tư cũ và mới.

// 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 hoặc Vite plugin

Ký bằng một khoá

Để sử dụng trình bổ trợ Rollup hoặc Vite để ký ứng dụng bằng một khoá riêng tư, tương tự như chế độ thiết lập Webpack, trình bổ trợ này sử dụng một chiến lược ký duy nhất và xử lý việc lấy URL cơ sở từ khoá được cung cấp để tạo đầu ra đã ký.

// 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'
})

Ký bằng hai khoá

Để ký kép ứng dụng bằng Rollup hoặc Vite, bạn phải định cấu hình trình bổ trợ để chấp nhận nhiều khoá. Đoạn mã này áp dụng cả khoá riêng tư cũ và mới bằng cách sử dụng mảng chiến lược. Điều này đảm bảo quá trình chuyển đổi diễn ra liền mạch bằng cách duy trì rõ ràng URL cơ sở và webBundleId bắt nguồn từ khoá hiện có ban đầu của bạn.

// 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'
})

Kết luận

Việc quản lý thành công quy trình xoay vòng khoá cho IWA là yếu tố quan trọng để duy trì tính bảo mật và tính liên tục của hoạt động phân phối ứng dụng. Bất kể tình huống cụ thể của bạn (ví dụ: liệu khoá có bị mất hay không), việc làm theo các bước được nêu sẽ đảm bảo người dùng của bạn gặp phải ít gián đoạn nhất. Bằng cách sử dụng các công cụ CLI hoặc cấu hình trình bổ trợ được cung cấp cho Webpack, Rollup hoặc Vite, bạn có thể quản lý hiệu quả các chữ ký của ứng dụng và thực hiện quy trình xoay vòng khoá một cách suôn sẻ. Trong trường hợp khẩn cấp, hãy nhớ liên hệ ngay với người liên hệ trên Google thông qua email tin cậy mà bạn chỉ định.