Saltar al contenido

Cifrado

Capgo ofrece una cifrado de extremo a extremo robusto para tus bundles de la app, garantizando que tu code de JavaScript y tus assets estén protegidos durante la transmisión y el almacenamiento. Este sistema de cifrado está diseñado para darte el control total sobre la seguridad de tu app, manteniendo la comodidad de las actualizaciones en vivo.

El sistema de cifrado de Capgo utiliza métodos criptográficos estándar de la industria para proteger tus bundles de accesos no autorizados. Cuando el cifrado está habilitado, tus bundles se cifran antes de salir de tu entorno de desarrollo y permanecen cifrados hasta que tu app los descifra en el dispositivo del usuario.

Qué protege realmente la cifrado: A diferencia de los sistemas OTA que solo firman las actualizaciones, Capgo cifra el bundle cargado antes de su almacenamiento y entrega. Esto protege el contenido del bundle de accesos casuales en el almacenamiento o en tránsito y garantiza que solo quien tenga tu clave privada pueda generar una actualización cifrada válida. No necesitas hace imposible el ingeniería inversa de los activos web enviados: la clave pública que usa el cliente para descifrar las actualizaciones se distribuye en la app, por lo que un atacante determinado aún puede extraerla e inspeccionar el contenido del bundle con suficiente esfuerzo.

Modelo de seguridad

Tu clave privada RSA se genera y mantiene en tu máquina. Capgo CLI nunca transmite tu clave privada, y Capgo no la almacena. Capgo tampoco almacena tu clave pública RSA completa: los uploads incluyen solo un fragmento corto key_id (los primeros 20 caracteres del cuerpo PEM) para que los canales puedan coincidir con el par de claves que usaste.

Los bundles completos cifrados se almacenan y se entregan como texto cifrado AES-128-CBC. Los servicios de Capgo, el CDN, el almacenamiento de objetos y cualquiera en la ruta de entrega que solo vea los artefactos alojados no podrán leer tu JavaScript, HTML o assets sin tu clave privada.

El cifrado predeterminado ya protege el bundle contenido confidencial en el almacenamiento de Capgo y en tránsito. Si además quieres reducir lo que Capgo podría llegar a saber al vincular tu canal de actualizaciones a un binario de tienda concreto, usa la siguiente guía.

Usa un app ID dedicado de Capgo. Configurar plugins.CapacitorUpdater.appId (tu Capgo app_id) a un valor que sea necesitas el mismo que tu iOS bundle ID o Android application ID. Las builds de Store y MDM incrustan tu clave pública RSA en capacitor.config. Cuando el Capgo app_id coincide con el nombre del paquete de la tienda, es más fácil asociar la app Capgo con un binario publicado que contenga esa clave pública. Un ID de app Capgo independiente evita ese vínculo directo.

Capgo Builder y la clave pública. Las subidas de Capgo Builder comprimen tu proyecto con capacitor.config (y el árbol nativo), incluyendo plugins.CapacitorUpdater.publicKey después de key savePara evitar que la clave pública se incluya en las subidas de Builder:

  • Haz builds nativas localmente o en tu propio CI cuando la confidencialidad frente a Capgo sea crítica, y evita subir esos árboles mediante Capgo Builder mientras la clave pública esté en la config, o
  • Añade la clave pública con key save solo después de que se hayan completado las subidas a Builder que no deben exponer la clave, o
  • Si dependes de Capgo Builder para builds nativos, considera que el flujo proporciona una fuerte integridad (sumas de verificación firmadas) pero no necesitas asumas confidencialidad de Capgo una vez que la clave pública se haya incluido en una subida a Builder.

Cifra las subidas delta. Los cuerpos de archivos delta (parciales) son texto plano a menos que uses @capgo/capacitor-updater 6.14.4 o superior (el cifrado parcial se habilita automáticamente para subidas cifradas en versiones de updater compatibles) o pases --encrypt-partial en bundle upload. Incluso con cifrado parcial, nombres de archivo listados en los delta manifests no están cifrados; solo los hashes por archivo están protegidos con RSA.

Tras el descifrado, el updater calcula el SHA-256 del bundle y lo compara con el checksum recuperado de la firma envuelta con RSA. Si no coinciden, el bundle se elimina y nunca se activa:

  • Android verifica el checksum tras el descifrado y antes descomprimiendo el archivo.
  • iOS desencripta y descomprime primero, luego verifica el checksum antes el bundle puede activarse.

Cuando se configura una clave pública, se rechazan los checksums faltantes o que no tengan la firma RSA correcta.

Por cada upload de un zip completo, CLI genera una nueva AES-128 session key aleatoria y IV de 16 bytes, cifra el bundle con AES-128-CBC, y cifra la clave de sesión con tu RSA-2048 clave privada usando padding PKCS#1 v1.5 tipo 1 . Los dispositivos recuperan la clave AES con la clave pública RSA integrada en la app. Las claves y los IV no se reutilizan entre distintos uploads de bundles de CLI. En un mismo upload delta, todos los archivos parciales cifrados comparten la clave de sesión y el IV de ese upload.

La clave pública usada para descifrar está integrada en tu app distribuida. El contenido del bundle en texto plano está disponible en los dispositivos que ejecutan tu app mediante la misma ruta de descifrado que usa el updater, de forma similar a otros assets del paquete de la app.

Los fallos de descifrado y de checksum se reportan como eventos de stats (download_fail, checksum_fail, decrypt_fail) al endpoint de stats de Capgo o a tu handler de estadísticas self-hosted. Las estadísticas se envían desde el dispositivo; no se reporta nada a los hosts de bundles de terceros según el éxito o fallo del descifrado. Cada intento suele ser una descarga completa iniciada por el dispositivo, por lo que los sondeos tipo padding-oracle son poco prácticos, y el texto plano modificado seguirá fallando el checksum firmado.

Una futura versión mayor podría añadir un formato versionado con AES-GCM y RSA-PSS sobre el hash como defensa en profundidad junto con el diseño actual. Sería un paso de endurecimiento incremental, no un parche de seguridad de emergencia para el formato actual.

Capgo utiliza un enfoque de cifrado híbrido que combina RSA y AES para una seguridad y rendimiento óptimos:

Flujo de cifrado de Capgo

  • Clave privada: Generada y almacenada de forma segura en tu entorno de desarrollo (usada para el cifrado)
  • Clave pública: Derivada de tu clave privada y almacenada en la configuración de Capacitor de tu app (usada para el descifrado)
  • Claves de sesión: Claves AES aleatorias generadas para cada subida de bundle
  1. Se genera una clave de sesión AES aleatoria para cada subida de bundle
  2. Tu bundle se cifra con la clave de sesión AES
  3. Se calcula el checksum del bundle
  4. Tanto la clave de sesión AES como el checksum se cifran juntos con tu clave privada RSA (creando la “firma”)
  5. Se almacenan el bundle cifrado y la firma cifrada

El checksum se cifra junto a la clave AES para evitar manipulaciones. Como solo tu clave privada RSA puede crear esta firma, y solo la clave pública correspondiente puede descifrarla, esto garantiza que tanto la clave de sesión AES como el checksum esperado sean auténticos y no hayan sido modificados por un atacante.

  1. Tu app descarga el bundle cifrado y la firma cifrada
  2. El Capgo SDK usa tu clave pública RSA (almacenada en la app) para descifrar la firma
  3. Esto revela la clave de sesión AES y el checksum original
  4. La clave de sesión AES se usa para descifrar el bundle
  5. Se calcula el checksum del bundle descifrado y se compara con el original para verificar su integridad

Este proceso garantiza que, aunque un atacante intercepte el bundle cifrado, no pueda modificar la clave de sesión AES ni proporcionar un checksum falso, ya que necesitaría tu clave privada para crear una firma válida que la clave pública pueda descifrar.

CaracterísticaCapgoOtras plataformas OTA
Contenido del bundleCifrado en almacenamiento/tránsito; aun así, un ingeniero inverso decidido puede inspeccionarlo con el binario de la appLectura pública
Método de seguridadCifrado de extremo a extremo realSolo firma de Code
Nivel de privacidadProtección fuerte de entrega/almacenamiento; no es anti-ingeniería inversaLa plataforma puede acceder a tu code
ProtecciónContenido + integridad + autenticidadSolo integridad + autenticidad

Por qué es importante:

  • Firma de Code solo verifica que las actualizaciones no hayan sido manipuladas y provienen de la fuente correcta
  • Cifrado de Capgo protege el bundle mientras se almacena y se entrega, y hace mucho más difíciles las actualizaciones cifradas falsificadas, ya que el atacante necesitaría tu clave privada
  • La ingeniería inversa sigue siendo posible una vez lanzada la app, ya que el cliente contiene la clave pública necesaria para descifrar y cargar la actualización

Capgo utiliza Encryption V2 como método de cifrado estándar:

  • Usa RSA-4096 para mayor seguridad
  • AES-256-GCM para cifrado autenticado
  • Proporciona verificación de integridad
  • Mejor rendimiento y seguridad
  • Usa RSA-2048 para cifrar las claves
  • AES-256-CBC para el cifrado de bundles
  • Ya no está disponible en el CLI actual
  • Las apps legacy que usan V1 deben migrar a V2

Primero, genera tus claves de cifrado usando Capgo CLI:

Ventana de terminal
# Generate new encryption keys (creates files in current directory)
npx @capgo/cli@latest key create

Esto crea:

  • .capgo_key_v2: Tu clave privada (¡mantenla segura!)
  • .capgo_key_v2.pub: Tu clave pública (la usa tu app)

Estos archivos se crean en el directorio actual donde ejecutas el comando.

Paso 2: Guardar la clave pública en la config de Capacitor (Obligatorio)

Sección titulada “Paso 2: Guarda tu clave pública en la configuración de Capacitor (Obligatorio)”

Usted usar guarda tu clave pública en la configuración de Capacitor para que tu app móvil pueda descifrar los bundles:

Ventana de terminal
# Save public key from file to Capacitor config (required)
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub
# Or save public key data directly
npx @capgo/cli@latest key save --key-data "$CAPGO_PUBLIC_KEY"

Paso 3: Sincronizar la plataforma Capacitor (Obligatorio)

Sección titulada “Paso 3: Sincroniza la plataforma de Capacitor (Obligatorio)”

Después de guardar la clave pública, usar sincroniza la plataforma Capacitor para copiar la configuración actualizada a la capa nativa:

Ventana de terminal
# Sync the platform to copy config to native
npx cap sync

La forma más sencilla es cifrar durante el proceso de subida:

Ventana de terminal
# Upload with automatic encryption
npx @capgo/cli@latest bundle upload --key-v2
# For external storage, you must encrypt first (see Manual Encryption Workflow below)

Para un mayor control, puedes cifrar los bundles manualmente:

  1. Crea un bundle zip:

    Ventana de terminal
    npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2
  2. Cifra el bundle:

    Ventana de terminal
    npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM_FROM_STEP_1
  3. Sube a tu almacenamiento (p. ej., S3) y regístralo en Capgo:

    Ventana de terminal
    # First upload the encrypted bundle to your storage (e.g., AWS S3)
    aws s3 cp ./encrypted-bundle.zip s3://your-bucket/encrypted-bundle.zip
    # Then register with Capgo using the external URL
    npx @capgo/cli@latest bundle upload --external https://your-storage.com/encrypted-bundle.zip --iv-session-key IV_SESSION_KEY_FROM_STEP_2

Opciones de clave privada:

  1. Basada en archivo (desarrollo local):

    Ventana de terminal
    # Key stored as .capgo_key_v2 file in project root
    npx @capgo/cli@latest bundle upload --key-v2
  2. Variable de entorno (CI/CD):

    Ventana de terminal
    # Store in environment variable for CI
    export CAPGO_PRIVATE_KEY="$(cat .capgo_key_v2)"
    npx @capgo/cli@latest bundle upload --key-data-v2 "$CAPGO_PRIVATE_KEY"

Configuración de la clave pública (obligatoria):

Ventana de terminal
# Must save public key to Capacitor config for mobile app
npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

Entorno de producción:

  • Guarda las claves privadas en servicios seguros de gestión de claves (AWS KMS, Azure Key Vault, etc.)
  • Usa la gestión de secretos de CI/CD para las claves privadas
  • Nunca subas claves privadas al control de versiones

Uso de claves:

  • Clave privada: Usado por CLI para cifrar durante la subida del bundle (máxima seguridad)
  • Clave pública: Guardado en la configuración de la app para descifrar en el dispositivo (seguro de commit)

Rota el par de claves si se sospecha o confirma que la clave privada ha sido comprometida. No se requiere una rotación rutinaria por calendario. Esta es una migración de clave nativa, no solo un cambio OTA.

  1. Genera un par de claves de reemplazo:

    Ventana de terminal
    npx @capgo/cli@latest key create
  2. Guarda la clave pública de reemplazo en tu configuración de Capacitor:

    Ventana de terminal
    npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub
  3. Sincroniza y publica un release nativo: Ejecuta npx cap sync, luego distribuye una nueva versión de la app nativa con la clave pública de reemplazo.

  4. Apunta a la nueva versión nativa: Los dispositivos que aún ejecutan el binario nativo antiguo no pueden descifrar las actualizaciones cifradas con la clave de reemplazo. Usa Segmentación por versión para restringir los bundles de replacement-key a la nueva versión nativa mientras el resto de la flota se actualiza mediante la tienda o MDM.

  5. Cambia tu upload secret: En cuanto ese release nativo esté publicado, reemplaza la clave privada en CI y sube solo los bundles dirigidos a las versiones nativas que contengan la clave pública de reemplazo.

  • Nunca compartas claves privadas entre entornos o miembros del equipo
  • Usa claves distintas para entornos distintos (dev, staging, production)
  • Rota tras un compromiso: reemplaza el par de claves si se sospecha o confirma que la clave privada está comprometida; no se requiere una rotación rutinaria por calendario
  • Almacena las claves de forma segura usando sistemas de gestión de claves adecuados
  • Verifica siempre la integridad del bundle tras la descifrado
  • Monitorear patrones de descarga o fallos inusuales
  • Usa HTTPS para todas las URLs del bundle (obligatorio para apps móviles)
  • Implementa manejo de errores adecuado para fallos de descifrado
  • Limitar el acceso a las claves de cifrado solo al personal autorizado
  • Usa acceso basado en roles para operaciones de gestión de claves
  • Auditar uso y acceso regular a las llaves
  • Implementa procedimientos adecuados de backup y recuperación

Fallos de descifrado:

  • Verifica que la clave privada coincida con la clave pública usada para el cifrado
  • Comprueba que el ivSessionKey es correcto
  • Asegúrate de que usas Encryption V2 (V1 ya no es compatible)

Errores relacionados con claves:

  • Confirma que el formato de la clave privada es correcto (formato PEM)
  • Verifica que la clave no se haya corrompido durante el almacenamiento o la transferencia
  • Comprueba que la clave tenga los permisos adecuados en la configuración de tu app

Problemas de rendimiento:

  • Los bundles grandes pueden tardar más en cifrarse/descifrarse
  • Considera usar actualizaciones Delta para reducir el tamaño de los bundles
  • Monitorea el rendimiento del dispositivo durante la descifrado

Comprueba el estado de la cifrado:

Ventana de terminal
npx @capgo/cli@latest app debug

Prueba el flujo de cifrado/descifrado:

Ventana de terminal
# Test the complete workflow: zip → encrypt → decrypt → unzip
npx @capgo/cli@latest bundle zip com.example.app --key-v2
npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM --json
npx @capgo/cli@latest bundle decrypt ./encrypted-bundle.zip IV_SESSION_KEY

La implementación de cifrado de Capgo sigue los estándares de la industria:

  • AES-256: Algoritmo de cifrado aprobado por FIPS 140-2
  • RSA-4096: Cifrado asimétrico robusto para la protección de claves
  • Modo GCM: Proporciona confidencialidad y autenticidad
  • Generación aleatoria segura: Generación de números aleatorios criptográficamente seguros

Esto hace que Capgo sea adecuado para apps que necesiten cumplir con:

  • RGPD (Reglamento General de Protección de Datos)
  • HIPAA (Ley de Portabilidad y Responsabilidad de Seguros Médicos)
  • SOC 2 (Service Organization Control 2)
  • ISO 27001 (Gestión de la Seguridad de la Información)
  • Tamaño del bundle: Los bundles cifrados son ligeramente mayores (~1-2% de sobrecarga)
  • Tiempo de procesamiento: El cifrado/descifrado añade una latencia mínima
  • Uso de memoria: Incremento temporal durante las operaciones de cifrado/descifrado
  • Usa Delta updates para minimizar la transferencia de datos cifrados
  • Optimiza el tamaño de tu bundle convirtiendo imágenes a formato WebP
  • Minimiza los archivos JavaScript y CSS antes del bundling
  • Elimina dependencias no utilizadas y code
  • Monitorea el rendimiento del dispositivo en equipos antiguos o lentos

Si estás usando Cifrado para planificar la seguridad y el cumplimiento, conéctalo con Cumplimiento para los detalles de implementación en Cumplimiento, Escáner de seguridad de Capgo para el flujo de trabajo del producto en Capgo Security Scanner, Seguridad de Capgo para el flujo de trabajo del producto en Capgo Security, Centro de confianza de Capgo para el flujo de trabajo del producto en Capgo Trust Center, y Seguridad de la organización para el detalle de implementación en Organization Security.