Cifrado
Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este plugin.
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
Confidencialidad con respecto a Capgo
Sección titulada “Confidencialidad 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
Sección titulada “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 savesolo 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.
Integridad
Sección titulada “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 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.
Gestión de claves
Sección titulada “Gestión de claves”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.
Fallos y reportes
Sección titulada “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
Sección titulada “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
Sección titulada “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
Sección titulada “1. Generación de claves”- 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
2. Proceso de cifrado
Sección titulada “2. Proceso de cifrado”- Se genera una clave de sesión AES aleatoria para cada subida de bundle
- Tu bundle se cifra con la clave de sesión AES
- Se calcula el checksum del bundle
- Tanto la clave de sesión AES como el checksum se cifran juntos con tu clave privada RSA (creando la “firma”)
- 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
Sección titulada “3. Proceso de descifrado”- Tu app descarga el bundle cifrado y la firma cifrada
- El Capgo SDK usa tu clave pública RSA (almacenada en la app) para descifrar la firma
- Esto revela la clave de sesión AES y el checksum original
- La clave de sesión AES se usa para descifrar el bundle
- 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.
Capgo vs otras plataformas
Sección titulada “Capgo vs otras plataformas”| Característica | Capgo | Otras plataformas OTA |
|---|---|---|
| Contenido del bundle | Cifrado en almacenamiento/tránsito; aun así, un ingeniero inverso decidido puede inspeccionarlo 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 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
Métodos de cifrado
Sección titulada “Métodos de cifrado”Capgo utiliza Encryption V2 como método de cifrado estándar:
Encryption V2 (Estándar actual)
Sección titulada “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)
Sección titulada “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
Configuración del cifrado
Sección titulada “Configurar el cifrado”Paso 1: Generar claves de cifrado
Sección titulada “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 createEsto 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:
# 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 directlynpx @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:
# Sync the platform to copy config to nativenpx cap syncCifrado de bundles
Sección titulada “Cifrado de bundles”Método 1: Cifrar durante el upload
Sección titulada “Método 1: Cifrar durante la subida”La forma más sencilla es cifrar durante el proceso de subida:
# Upload with automatic encryptionnpx @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
Sección titulada “Método 2: Flujo de cifrado manual”Para un mayor control, puedes cifrar los bundles manualmente:
-
Crea un bundle zip:
Ventana de terminal npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2 -
Cifra el bundle:
Ventana de terminal npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM_FROM_STEP_1 -
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 URLnpx @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
Sección titulada “Gestión de claves”Almacenamiento seguro de claves
Sección titulada “Almacenamiento seguro de claves”Opciones de clave privada:
-
Basada en archivo (desarrollo local):
Ventana de terminal # Key stored as .capgo_key_v2 file in project rootnpx @capgo/cli@latest bundle upload --key-v2 -
Variable de entorno (CI/CD):
Ventana de terminal # Store in environment variable for CIexport 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 appnpx @capgo/cli@latest key save --key ./.capgo_key_v2.pubEntorno 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)
Rotar si se compromete la clave privada
Sección titulada «Rotar tras una filtración de la clave privada»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.
-
Genera un par de claves de reemplazo:
Ventana de terminal npx @capgo/cli@latest key create -
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 -
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. -
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.
-
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.
Mejores prácticas de seguridad
Sección titulada “Buenas prácticas de seguridad”Seguridad de claves
Sección titulada “Seguridad de las 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
Sección titulada “Seguridad del bundle”- 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
Control de acceso
Sección titulada “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
Sección titulada “Solución de problemas de cifrado”Problemas comunes
Sección titulada “Problemas comunes”Fallos de descifrado:
- Verifica que la clave privada coincida con la clave pública usada para el cifrado
- Comprueba que el
ivSessionKeyes 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
Comandos de debug
Sección titulada “Comandos de depuración”Comprueba el estado de la cifrado:
npx @capgo/cli@latest app debugPrueba el flujo de cifrado/descifrado:
# Test the complete workflow: zip → encrypt → decrypt → unzipnpx @capgo/cli@latest bundle zip com.example.app --key-v2npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM --jsonnpx @capgo/cli@latest bundle decrypt ./encrypted-bundle.zip IV_SESSION_KEYCumplimiento y estándares
Sección titulada “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
Sección titulada “Consideraciones de rendimiento”Sobrecarga de cifrado
Sección titulada “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
Sección titulada “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 del dispositivo en equipos antiguos o lentos
Próximos pasos
Sección titulada “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
Sección titulada “Continuar desde Encryption”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.