Rotación de claves

Robert Ferens

Demián Renzulli

En este documento, se proporciona información esencial sobre el proceso de rotación de claves para una app web aislada (IWA), incluido cuándo es necesario y los pasos que deben seguir los desarrolladores si se pierde o se vulnera una clave.

Rotación de claves para IWA

La rotación de claves es un mecanismo que permite reemplazar las claves privadas que se usan para firmar tu IWA en caso de filtración o pérdida. Este proceso mantiene la funcionalidad de la app y conserva un ID de paquete y un origen estables, lo que garantiza la continuidad de la distribución y las actualizaciones de la app.

El proceso de rotación de claves no requiere ningún cambio por parte del administrador o del usuario y, si se realiza correctamente, no será perceptible para ellos. Los canales de contacto de confianza establecidos durante el proceso inicial de inclusión en la lista de entidades permitidas son fundamentales para habilitar la rotación de claves.

La necesidad de rotar las claves

La rotación de claves es estrictamente necesaria en dos situaciones principales:

• Vulneración o filtración de la clave: Si tu clave de firma privada se vulnera o se filtra potencialmente, debes iniciar de inmediato el proceso de rotación de la clave para proteger tu aplicación. Una clave filtrada se puede usar para suplantar tu identidad, dañar a los usuarios de tu app y poner en peligro la reputación de tu empresa.
• Pérdida de la clave: Si pierdes el acceso a tu clave de firma privada y no puedes firmar actualizaciones nuevas, se requiere la rotación de claves para restablecer tu capacidad de distribuir tu aplicación.

Requisitos para desarrolladores

Antes de iniciar una rotación de claves, debes cumplir con los siguientes criterios:

• App incluida en la lista de entidades permitidas: Solo las apps incluidas en la lista de entidades permitidas pueden estar sujetas a una rotación de claves.
• Correo electrónico de confianza: Debes usar la dirección de correo electrónico de confianza que se proporcionó durante el proceso de inclusión en la lista de entidades permitidas para solicitar una rotación de claves.

Cómo volver a firmar apps alojadas y lanzar versiones nuevas

Después de rotar una clave, se bloquean todas las instancias de la app instaladas que no estén firmadas con una clave válida. Para evitar interrupciones a los usuarios, debes entregar una app firmada con la clave nueva (o con ambas claves). Los detalles técnicos para volver a firmar paquetes se encuentran en la sección Cómo firmar un paquete con varias claves. Según tu situación específica, existen diferentes situaciones:

Situación A: La clave no se perdió (por ejemplo, rotación proactiva o filtración)

Debes firmar la app con ambas claves (la anterior y la nueva) y entregárselas a los usuarios de una de las siguientes maneras:

• Lanzar una nueva versión de la app (agregar la nueva versión a los manifiestos de actualización)
• Actualiza tus archivos .swbn alojados (vinculados en tus manifiestos de actualización) para que se firmen con ambas claves. La herramienta de CLI te permite agregar otra firma al paquete swbn existente.

Esto debe hacerse antes de que Google procese la rotación de claves para garantizar que los usuarios no noten el cambio.

Nota: Si el administrador usa la fijación de versiones, debe actualizar el paquete alojado para esta versión o fijar la app a la versión que se firmó con ambas claves.

Situación B: Se perdió la llave

Dado que la app no se puede firmar con la clave perdida, este caso es más complejo. Solicita la rotación de claves y pídele a tu contacto de Google que te indique los próximos pasos. Es posible que se te solicite que agregues las firmas nuevas a tus paquetes alojados siguiendo estas instrucciones.

Nota: Si usas la fijación de versiones y lanzas una nueva versión de la app para una rotación de claves, considera cambiar la versión fijada.

Proceso de rotación de claves

El proceso de rotación de claves implica los siguientes pasos:

Paso	Acción	Detalles	Responsabilidad
1	Solicita la rotación de la clave	El socio o desarrollador se comunica con su contacto de Google (Ingeniería de socios o cualquier otro punto de contacto) a través del correo electrónico de confianza proporcionado en el proceso de inclusión en la lista de entidades permitidas y solicita las instrucciones de rotación de claves explicando el motivo. En el caso de que se haya vulnerado la clave, recomendamos adjuntar el manifiesto de actualización con los paquetes firmados con las claves anteriores y nuevas para acelerar el proceso.	Desarrollador o socio
2	Respuesta al solicitante	El contacto de Google proporciona más instrucciones y preguntas al solicitante. Este paso puede implicar algunos intercambios.	Contacto de Google
3	Proporcionar datos	El socio o desarrollador sigue las instrucciones, que, entre otras, pueden incluir lo siguiente: Se vuelven a firmar los paquetes con claves nuevas. Actualizar o proporcionar tu manifiesto de actualización con apps actualizadas Proporcionar más información Por ejemplo, detalles de la situación, peligros o detalles técnicos, como el ciclo de lanzamiento de la app de un socio. Confirmar que todo está listo para la rotación: Te sugerimos que lo hagas al menos tres días después de actualizar las apps para clientes y asegurarte de que se hayan actualizado.	Desarrollador o socio
4	Procesamiento de solicitudes y proporcionar comentarios	Google revisa la solicitud de rotación de claves y responde en el plazo de una semana hábil, ya sea aprobándola o rechazándola, o bien comunicándose con el desarrollador para hacerle más preguntas. Una vez que se aprueba la solicitud, Google rota la clave y proporciona comentarios.	Contacto de Google

Actualización del canal y la fijación de versiones

A veces, los administradores usan canales de actualización personalizados o fijación de versiones, lo que les permite administrar las versiones de las apps en sus dispositivos cliente. Después de una rotación de claves, todas las apps instaladas con claves no válidas se vuelven no válidas y se bloquean. Para evitar esto, las versiones anteriores de las apps alojadas en los vínculos proporcionados en update_manifest.json también deben actualizarse y firmarse con dos firmas antes de la rotación de claves. Si pierdes la clave anterior y la app no se puede firmar con dos claves, notifica a tu contacto de Google de inmediato. Trabajaremos contigo para mitigar la situación, de modo que la app se pueda actualizar sin interrumpir los flujos de trabajo de los usuarios.

Cómo firmar un paquete con varias claves

En esta sección, se describe cómo puedes firmar tus paquetes web con una o dos claves a través de herramientas de la CLI o la configuración de complementos de Webpack, Rollup o Vite. Las herramientas de la CLI también permiten agregar una firma más a los paquetes swbn existentes, lo que puede ser útil en casos de pérdida de claves o para actualizar los paquetes alojados anteriores.

Herramientas de la CLI

Primero, asegúrate de tener instalado el paquete wbn-sign con npm:

$ npm i wbn-sign

Agrega -g para instalar el paquete de forma global en lugar de hacerlo solo en la carpeta actual.

Cómo firmar con una clave

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

Firma con dos claves

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

Se puede omitir el argumento --web-bundle-id <id> si old_key es la primera clave con la que se firmó la versión inicial de la app. En ese caso, el ID del paquete se derivará de la clave. Puedes verificar el ID del paquete con el comando wbn-sign info signed.swbn.

Cómo agregar una firma al paquete existente

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

Usa -o si no quieres anular el paquete, sino crear uno nuevo con doble firma.

Más información sobre la herramienta de CLI

Para obtener más información sobre el uso de la herramienta de CLI, consulta la página de npm wbn-sign. Como alternativa, usa: wnb-sign help.

Complemento de Webpack

Cómo firmar con una clave

Para configurar el complemento de Webpack para firmar tu IWA con una sola clave privada, haz lo siguiente:

• Configura WebBundlePlugin para derivar automáticamente la URL base requerida directamente desde esta clave.
• Usa un solo NodeCryptoSigningStrategy para generar tu archivo .swbn firmado.

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

Firma con dos claves

Cuando necesites firmar tu aplicación dos veces durante una rotación de claves, haz lo siguiente:

• Define el webBundleId y la URL base según tu original (old_key) para garantizar que la identidad de la app siga siendo estable para tus usuarios.
• Usa un array de estrategias de firma para aplicar tus claves privadas antiguas y nuevas.

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

Complemento de Rollup o Vite

Cómo firmar con una clave

Para usar el complemento Rollup o Vite para firmar tu aplicación con una sola clave privada, de manera similar a la configuración de Webpack, el complemento usa una sola estrategia de firma y controla la derivación de la URL base a partir de la clave proporcionada para generar tu resultado firmado.

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

Firma con dos claves

Para firmar tu aplicación dos veces con Rollup o Vite, debes configurar el complemento para que acepte varias claves. Este fragmento aplica las claves privadas antiguas y nuevas con el array de estrategias. Garantiza una transición sin inconvenientes, ya que mantiene de forma explícita la URL base y webBundleId derivadas de tu clave original existente.

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

Conclusión

Administrar correctamente la rotación de claves de tu IWA es fundamental para mantener la seguridad y la continuidad de la distribución de tu aplicación. Independientemente de tu situación específica (por ejemplo, si se perdió la llave o no), seguir los pasos descritos garantiza que tus usuarios experimenten la menor interrupción posible. Si utilizas las herramientas de CLI o las configuraciones de complementos proporcionadas para Webpack, Rollup o Vite, puedes administrar de manera eficiente las firmas de tu app y navegar por el proceso de rotación de claves sin problemas. En situaciones de emergencia, recuerda comunicarte de inmediato con tu contacto de Google a través de tu correo electrónico de confianza designado.