Cifrado

Capgo ofrece un cifrado de extremo a extremo robusto para tus app bundles, 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 control total sobre la seguridad de tu app, manteniendo la comodidad de los Live Updates.

Resumen

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á activado, 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 el cifrado: A diferencia de los sistemas OTA que solo firman las actualizaciones, Capgo cifra el bundle subido antes de su almacenamiento y entrega. Esto protege el contenido del bundle de accesos accidentales en el almacenamiento o tránsito y garantiza que solo quien tenga tu clave privada pueda generar una actualización cifrada válida. Esto no necesitas hace que los assets web distribuidos sean imposibles de aplicar ingeniería inversa: la clave pública que usa el cliente para descifrar actualizaciones se distribuye en la app, por lo que un atacante decidido aún podría extraerla e inspeccionar el contenido del bundle con suficiente esfuerzo.

Cuándo necesitas cifrado

Si subes un bundle sin cifrado, trátalo como un asset público. Los canales privados limitan qué dispositivos reciben una actualización, pero no hacen que el bundle subido sea confidencial. El cifrado es útil cuando buscas mejor protección en almacenamiento y tránsito, y cuando quieres que solo los poseedores de la clave privada puedan publicar actualizaciones cifradas válidas. No garantiza que el JavaScript, HTML o CSS distribuidos sean imposibles de inspeccionar.

Modelo de amenazas

El cifrado de Capgo protege contra la filtración de bundles por parte de Capgo, proveedores de almacenamiento, CDNs o cualquier persona que solo vea el artefacto de entrega cifrado. También evita que terceros generen actualizaciones cifradas válidas sin tu clave privada. Dado que la clave pública está integrada en la app distribuida para que el cliente pueda descifrar las actualizaciones, alguien que tenga el binario de tu app y suficiente motivación aún podría recuperar el material de clave necesario para inspeccionar el bundle.

Consejo

El cifrado es especialmente importante para:

• Apps que manejan datos sensibles o lógica de negocio
• Aplicaciones empresariales con requisitos de cumplimiento
• Apps desplegadas en sectores regulados
• Organizaciones con políticas de seguridad estrictas

Modelo de seguridad

Confidencialidad con respecto a Capgo

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.

Máxima confidencialidad frente a Capgo

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 hayan terminado los uploads de cualquier Builder que no deba exponer la clave, o
• Si usas Capgo Builder para Native Build, considera que el workflow ofrece una fuerte integridad (checksums firmados) pero no necesitas asumas confidencialidad de Capgo una vez que la clave pública se haya incluido en un upload de un Builder.

Encripta los delta uploads. 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 activa automáticamente para encrypted uploads en versiones 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.

Integridad

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 descifra y descomprime primero, luego verifica el checksum antes el bundle puede activarse.

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

Gestión de claves

Por cada upload de un zip completo, CLI genera un nuevo AES-128 session key 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.

Fallos y reportes

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.

Endurecimiento futuro

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.

Cómo funciona el cifrado

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

1. Generación de claves

• Clave privadaGenerado y almacenado de forma segura en tu entorno de desarrollo (usado para el cifrado)
• Clave pública: Derivado de tu clave privada y almacenado en la configuración de Capacitor de tu app (usado para el descifrado)
• Claves de sesión: Claves AES aleatorias generadas para cada bundle upload

2. Proceso de cifrado

1. Se genera una clave de sesión AES aleatoria para cada bundle upload
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.

3. Proceso de descifrado

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.

Consejo

RSA no puede cifrar grandes volúmenes de datos de forma eficiente, por lo que se usa AES para el cifrado real del bundle, mientras que RSA asegura la clave AES y proporciona verificación de integridad mediante la firma del checksum.

Capgo vs otras plataformas

Característica	Capgo	Otras plataformas OTA
Contenido del bundle	Cifrado en almacenamiento/tránsito; aún inspeccionable por un ingeniero inverso con el binario de la app	Lectura pública
Método de seguridad	Cifrado de extremo a extremo real	Solo firma de Code
Nivel de privacidad	Protección fuerte de entrega/almacenamiento; no es anti-ingeniería inversa	La plataforma puede acceder a tu code
Protección	Contenido + integridad + autenticidad	Solo integridad + autenticidad

¿Por qué es importante?:

• Firma de Code solo verifica que las actualizaciones no hayan sido manipuladas y vengan 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

Métodos de cifrado

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

Encryption V2 (Estándar actual)

• Usa RSA-4096 para mayor seguridad
• AES-256-GCM para cifrado autenticado
• Proporciona verificación de integridad
• Mejor rendimiento y seguridad

Cifrado V1 (obsoleto)

• 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

Peligro

El cifrado V1 ya no tiene soporte en el Capgo CLI actual. Si usas el cifrado V1, debes migrar a V2. Consulta la guía de migración para instrucciones detalladas.

Configuración del cifrado

Paso 1: Generar claves de cifrado

Primero, genera tus claves de cifrado usando Capgo CLI:

# 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 (usada por tu app)

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

Precaución

Notas importantes sobre el almacenamiento:

• Clave privada (.capgo_key_v2): Nunca la subas al control de versiones. Este archivo debe mantenerse seguro y usarse solo para el cifrado durante el upload de bundles.
• Clave pública (.capgo_key_v2.pub): Es seguro subirla al control de versiones, ya que es un respaldo de tu llave pública.
• Ubicación del archivo: Las llaves se crean en el directorio actual donde ejecutas el key create comando.
• Public Key en la Config: Debes ejecutar key save para guardar la llave pública en tu config de Capacitor para que la app móvil pueda usarla.

Para entornos de producción, guarda la clave privada de forma segura (variables de entorno, servicios de gestión de claves) y elimínala de tu proyecto local tras la configuración.

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

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

# 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)

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

# Sync the platform to copy config to native
npx cap sync

Precaución

Pasos requeridos:

1. El key save el comando guarda la clave pública en tu config de Capacitor
2. npx cap sync copia esta config a la capa nativa para que la app móvil pueda acceder a ella
3. Sin ambos pasos, tu app no podrá desencriptar las actualizaciones encriptadas

Cifrado de bundles

Método 1: Cifrar durante el upload

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

# Upload with automatic encryption
npx @capgo/cli@latest bundle upload --key-v2

# For external storage, you must encrypt first (see Manual Encryption Workflow below)

Método 2: Flujo de cifrado manual

Para tener más control, puedes cifrar los bundles manualmente:

1. Crea un bundle zip:

   npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2

2. Cifra el bundle:

   npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM_FROM_STEP_1

3. Sube tus archivos a tu storage (ej. S3) y regístralos en Capgo:

   # 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

Gestión de claves

Almacenamiento seguro de claves

Opciones de Private Key:

1. Basado en archivos (desarrollo local):

   # Key stored as .capgo_key_v2 file in project root
   npx @capgo/cli@latest bundle upload --key-v2

2. Variable de entorno (CI/CD):

   # 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):

# 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 el cifrado durante el upload del bundle (mantener seguro)
• Clave pública: Almacenado en la configuración de la app para el descifrado en el dispositivo (seguro para commit)

Rotar si se compromete la clave privada

Rota el par de claves si sospechas o confirmas que la clave privada ha sido comprometida. No es necesaria una rotación de calendario rutinaria. Esto es una migración de native-key, no un cambio exclusivo de OTA.

1. Genera un nuevo par de claves:

   npx @capgo/cli@latest key create

2. Guarda la nueva clave pública en tu configuración de Capacitor:

   npx @capgo/cli@latest key save --key ./.capgo_key_v2.pub

3. Sincroniza y lanza un release nativo: Ejecuta npx cap sync, luego distribuye una nueva versión de la app nativa con la nueva clave pública.

4. Apunta a la nueva versión nativa: Los dispositivos con el binario nativo antiguo no podrán desencriptar actualizaciones con la nueva clave. Usa Segmentación por versión para limitar los bundles de la nueva clave a la versión nativa actual, mientras el resto se actualiza vía store o MDM.

5. Cambia tu upload secret: En cuanto el release nativo esté live, cambia la clave privada en tu CI y sube solo bundles dirigidos a versiones nativas que contengan la nueva clave pública.

Precaución

Si la clave privada se compromete, deja de usarla de inmediato. Las instalaciones existentes con la clave pública antigua necesitan una actualización de la tienda nativa o de MDM antes de poder recibir bundles cifrados con la clave de reemplazo.

Mejores prácticas de seguridad

Seguridad de claves

• 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

Seguridad del bundle

• Verifica siempre la integridad del bundle tras la desencriptación
• Monitorear patrones de descarga inusuales o fallos
• Usa HTTPS en todas las URLs de los bundles (obligatorio en apps móviles)
• Implementa manejo de errores adecuado para fallos de desencriptación

Control de acceso

• 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

Solución de problemas de cifrado

Problemas comunes

Fallos de descifrado:

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

Errores de clave:

• Confirma que el formato de la clave privada sea correcto (formato PEM)
• Verifica que la clave no se haya corrompido al almacenarla o transferirla
• 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 o descifrarse
• Considera usar Delta updates para reducir el tamaño del bundle
• Monitorea el rendimiento del dispositivo al desencriptar

Comandos de debug

Estado de la encriptación:

npx @capgo/cli@latest app debug

Prueba el flujo de encriptación/desencriptación:

# 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

Cumplimiento y estándares

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)

Consideraciones de rendimiento

Sobrecarga de cifrado

• 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

Consejos de optimización

• 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 en dispositivos antiguos o lentos

Próximos pasos

• Aprende sobre Almacenamiento personalizado para usar cifrado con tu propia infraestructura
• Explorar Canales para gestionar bundles cifrados entre entornos
• Configura Integración CI/CD para automatizar despliegues cifrados

Sigue con el cifrado

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.