Обновление ключей

Robert Ferens

Demián Renzulli

В этом документе представлена ​​важная информация о процессе ротации ключей для изолированного веб-приложения (IWA) , включая случаи, когда это необходимо, и шаги, которые разработчики должны предпринять в случае утери или компрометации ключа.

Ключевая ротация для IWAs

Ротация ключей — это механизм, позволяющий заменять закрытые ключи, используемые для подписи вашего IWA, в случае утечки или потери. Этот процесс обеспечивает работоспособность приложения и поддерживает стабильный идентификатор пакета и происхождение, гарантируя непрерывность распространения и обновлений вашего приложения.

Процесс ротации ключей не требует никаких изменений со стороны администратора или пользователя и, при правильном выполнении, останется для них незаметным. Для включения ротации ключей необходимы доверенные контактные каналы, установленные в процессе первоначального добавления в список разрешенных пользователей .

Необходимость ротации ключей

Смена ключевых ключа строго необходима в двух основных сценариях:

• Утечка или компрометация ключа: Если ваш закрытый ключ подписи скомпрометирован или потенциально скомпрометирован, необходимо немедленно начать процесс ротации ключей для обеспечения безопасности приложения. Утечка ключа может быть использована для выдачи себя за вас, причинения вреда пользователям вашего приложения и подрыва репутации вашей компании.
• Потеря ключа: Если вы потеряли доступ к своему закрытому ключу подписи и не можете подписывать новые обновления, потребуется ротация ключа, чтобы восстановить возможность распространения вашего приложения.

Требования к разработчику

Перед началом смены ключей необходимо выполнить следующие условия:

• Приложения из списка разрешенных: Только приложения из списка разрешенных могут быть включены в программу ротации ключей.
• Доверенный адрес электронной почты: Для запроса смены ключа необходимо использовать доверенный адрес электронной почты, указанный в процессе добавления адреса в список разрешенных.

Подписание приложений, размещенных на хостинге, и выпуск новых версий.

После смены ключа все установленные экземпляры приложения, не подписанные действительным ключом, блокируются. Чтобы избежать сбоев для пользователей, необходимо предоставить приложение, подписанное новым ключом (или обоими ключами). Технические подробности переподписи пакетов можно найти в разделе «Как подписать пакет несколькими ключами ». В зависимости от вашей конкретной ситуации возможны различные сценарии:

Сценарий А: Ключ не потерян (например, благодаря упреждающей ротации или устранению утечки).

Необходимо подписать приложение обоими ключами (старым и новым) и передать их пользователям одним из следующих способов:

• Выпуск новой версии приложения (добавление новой версии в манифесты обновлений) или
• Обновление размещенных файлов .swbn (ссылки на которые указаны в манифестах обновлений) для подписи обоими ключами. Инструмент командной строки позволяет добавить еще одну подпись к существующему пакету swbn .

Это необходимо сделать до того, как Google обработает смену ключа, чтобы пользователи не заметили изменений.

Сценарий Б: Ключ потерян

Поскольку приложение невозможно подписать утерянным ключом, этот случай более сложный. Запросите смену ключа и обратитесь к своему контактному лицу в Google за дальнейшими инструкциями. Возможно, вас попросят добавить новые подписи в ваши размещенные пакеты, следуя этим инструкциям .

Процесс вращения ключей

Процесс ротации ключей включает следующие этапы:

Обновление канала и закрепление версии

Администраторы иногда используют пользовательские каналы обновления или фиксацию версий, что позволяет им управлять версиями приложений на клиентских устройствах. После смены ключа все приложения, установленные с недействительными ключами, становятся недействительными и блокируются. Чтобы предотвратить это, более ранние версии приложений, размещенных по ссылкам, указанным в файле update_manifest.json также должны быть обновлены и подписаны двумя подписями до смены ключа. Если ваш старый ключ утерян и приложение не может быть подписано двумя ключами, немедленно сообщите об этом своему контактному лицу в Google. Мы поможем вам решить эту проблему, чтобы приложение можно было обновить без нарушения рабочих процессов ваших пользователей.

Как подписать пакет с несколькими ключами

В этом разделе описывается, как подписывать веб-пакеты одним или двумя ключами с помощью инструментов командной строки или конфигурации плагинов Webpack/Rollup/Vite. Инструменты командной строки также позволяют добавить еще одну подпись к существующим пакетам swbn , что может быть полезно в случаях утери ключа или обновления ранее размещенных пакетов.

Инструменты командной строки

Во-первых, убедитесь, что у вас установлен пакет 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 если вы не хотите перезаписывать существующий пакет, а хотите создать новый пакет с двойной подписью.

Дополнительная информация об инструменте командной строки

Для получения дополнительной информации об использовании инструмента командной строки см. страницу 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 и Base 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 имеет решающее значение для обеспечения безопасности и непрерывности распространения вашего приложения. Независимо от вашей конкретной ситуации (например, был ли утерян ключ или нет), следование описанным шагам гарантирует минимальные сбои для ваших пользователей. Используя предоставленные инструменты командной строки или конфигурации плагинов для Webpack, Rollup или Vite, вы можете эффективно управлять подписями вашего приложения и беспрепятственно проходить процесс ротации ключей. В экстренных случаях не забудьте незамедлительно связаться со своим контактным лицом в Google по указанному вами доверенному адресу электронной почты.