Keystore: qué es, qué formatos existen y cómo funciona

Qué es un Keystore

Keystore (KeyStore) es un mecanismo estándar de Java Cryptography Architecture (JCA) para almacenar claves criptográficas, certificados y entradas de confianza. En el desarrollo de Android, el Keystore se utiliza para guardar la clave privada con la que se firma la aplicación antes de su publicación. La firma garantiza que la aplicación fue publicada por el desarrollador indicado y que su código no ha sido modificado después de la publicación. Cada actualización de la aplicación debe firmarse con la misma clave; de lo contrario, Google Play rechazará el APK o App Bundle.

Un Keystore puede contener varias entradas (aliases), cada una de las cuales representa un par de claves (privada y pública) con un certificado. Alias es un nombre de entrada único mediante el cual la aplicación accede a la clave durante la firma. En un proyecto típico de Android, el Keystore contiene una entrada para firmar la versión de lanzamiento y puede contener entradas adicionales para firmar compilaciones de depuración. Google Play Console muestra las huellas SHA-1 y SHA-256 del certificado para cada aplicación subida.

Android Studio incluye soporte integrado para Keystore a través del menú Build → Generate Signed Bundle / APK. El asistente de firma de Android Studio permite crear un nuevo Keystore o seleccionar uno existente, especificar un alias, contraseñas del Keystore y de la clave, así como los datos del certificado (nombre de la organización, ciudad, país). Estos datos se incrustan en el certificado y son visibles para los usuarios al verificar la firma del APK. Google Play exige que el certificado tenga una validez de al menos 25 años; Android verifica la fecha de caducidad al instalar la aplicación.

Por qué el Keystore es importante para Android

Las actualizaciones de aplicaciones en Google Play solo son posibles con la misma clave que firmó la primera versión. Si se pierde el Keystore, no es posible publicar una actualización; habría que volver a publicar la aplicación con un nombre de paquete diferente. Según Google Play Console Help (2026), la clave de firma de la aplicación solo se puede recuperar a través de Google Play App Signing, un servicio que almacena la clave en el lado de Google. Si el desarrollador usó esta opción, perder el Keystore local no es crítico.

Cómo funciona un Keystore

El proceso de firma de una aplicación Android implica crear un resumen (hash) del contenido del APK y cifrarlo con la clave privada del Keystore. Android SDK Build Tools incluyen la utilidad apksigner, que realiza la firma con APK Signature Scheme v2 (o v3 para Android 9+). Al instalar la aplicación, Android verifica la firma: descifra la firma con la clave pública del certificado, compara el hash del APK con el original; si los hashes no coinciden, la instalación se rechaza.

Android admite varios esquemas de firma: v1 (JAR signing), v2 (APK Signature Scheme), v3 (APK Signature Scheme con soporte para rotación de claves) y v4 (instalaciones incrementales para Android 11+). Google Play exige v2 o v3 para aplicaciones nuevas. apksigner agrega automáticamente todos los esquemas necesarios durante la firma si la clave admite los algoritmos correspondientes. Android 11+ admite instalación por ADB con firma v4, lo que acelera la carga incremental de APK grandes en el dispositivo.

Algoritmos: Android recomienda usar RSA-2048 o ECDSA P-256 para la clave de firma. El certificado debe ser X.509 v3. Android verifica que el certificado sea válido en el momento de la instalación; si ha caducado, la instalación se bloquea. Por eso Google recomienda establecer el período de validez del certificado en al menos 25 años. Google Play App Signing utiliza dos claves: la clave de firma de la aplicación (app signing key) y la clave de carga (upload key); el desarrollador utiliza la clave de carga para subir el APK a la Consola, y Google firma la aplicación para los usuarios con la clave principal.

Formatos de Keystore: JKS y PKCS12

Java admite dos formatos principales de Keystore: JKS (Java KeyStore), un formato propietario de Oracle que existe desde JDK 1.2, y PKCS12, el formato estandarizado Public-Key Cryptography Standards #12 de RSA Laboratories. JKS utiliza su propio formato de almacenamiento de datos y solo es compatible dentro del ecosistema Java. PKCS12 es un estándar abierto compatible con Java, .NET, OpenSSL, Python (cryptography) y la mayoría de las demás bibliotecas criptográficas.

Google Play recomienda PKCS12 como el formato preferido para nuevos Keystores creados después de 2021. JDK 9 y versiones posteriores crean Keystores en formato PKCS12 de forma predeterminada (anteriormente el formato predeterminado era JKS). La principal ventaja de PKCS12 es la compatibilidad: un archivo .p12 se puede abrir en cualquier entorno no vinculado a Java. OpenSSL puede extraer certificados de PKCS12 y convertirlos a formato PEM. Los archivos JKS requieren utilidades JDK para leerlos y no pueden ser procesados por OpenSSL.

La conversión entre formatos se realiza con la utilidad keytool de JDK. Al migrar de JKS a PKCS12, asegúrese de que todos los alias y contraseñas se transfieran correctamente. El comando keytool -importkeystore permite importar el contenido de un Keystore a otro independientemente del formato. Después de la conversión, es mejor eliminar el archivo JKS antiguo para evitar confusiones con las versiones de la clave. Android Studio admite ambos formatos al generar una compilación firmada.

Crear un Keystore con keytool

La utilidad keytool forma parte del JDK (Java Development Kit) y proporciona un conjunto completo de comandos para crear, ver y gestionar Keystores. Para crear un nuevo Keystore con un par de claves, se utiliza el comando keytool -genkeypair especificando el formato PKCS12, el algoritmo RSA, el tamaño de la clave y el período de validez del certificado. Google Play exige una validez del certificado de al menos 25 años (9125 días); se recomienda especificar este valor en el parámetro -validity.

Crear un nuevo Keystore

Ejemplo de generación de un Keystore en formato PKCS12 para un proyecto Android. El parámetro -dname contiene el nombre distinguido X.500 del certificado. El parámetro -ext incluye el Subject Alternative Name si es necesario; para Android, Basic Constraints es suficiente:

# Creación de un Keystore PKCS12 para Android
keytool -genkeypair -alias "upload_key" \
  -keyalg RSA -keysize 2048 -validity 9125 \
  -keystore "release-keystore.p12" \
  -storetype PKCS12 \
  -dname "CN=Developer,O=Company,C=RU"

Keytool solicitará la contraseña del Keystore y la contraseña de la clave (pueden coincidir). El parámetro -storetype PKCS12 crea un archivo en el formato moderno. -keysize 2048 cumple con los requisitos de Google para el tamaño mínimo de clave RSA. -validity 9125 (25 años) garantiza la compatibilidad durante todo el ciclo de vida esperado de la aplicación. Después de crear el Keystore, se recomienda verificar su contenido con el comando keytool -list -v -keystore release-keystore.p12.

Ver el contenido del Keystore

Para comprobar las entradas del Keystore, se utiliza el comando con el indicador -list. La salida incluye el alias, las fechas de creación y caducidad, el tipo de entrada y las huellas SHA-256. Android Studio muestra la misma información en el diálogo Generate Signed Bundle / APK al seleccionar un Keystore existente:

# Visualización de entradas del Keystore
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

Usar Keystore en CI/CD

En un pipeline de CI/CD, el Keystore debe almacenarse de forma segura y entregarse al agente de compilación sin riesgo de compromiso. GitHub Actions proporciona Secrets para almacenar archivos binarios en formato base64. El Keystore se codifica con el comando base64, la cadena resultante se guarda en los secretos del repositorio y, durante la compilación, se decodifica nuevamente a un archivo. GitLab CI utiliza un mecanismo similar a través de Variables de tipo File.

Un ejemplo de configuración de una compilación CI con Keystore en GitHub Actions incluye decodificar el Keystore desde un secreto, configurar las propiedades de Gradle y ejecutar una compilación firmada. Gradle, el complemento de Android, lee la ruta del Keystore y las contraseñas del archivo keystore.properties (excluido de .gitignore para el desarrollo local) o de las variables de entorno del sistema CI:

// build.gradle (app) — configuración de firma
@Override
android {
    signingConfigs {
        release {
            storeFile file("release-keystore.p12")
            storePassword System.getenv("STORE_PASSWORD")
            keyAlias System.getenv("KEY_ALIAS")
            keyPassword System.getenv("KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

Gradle lee las variables de entorno establecidas por el sistema CI. El archivo Keystore debe ubicarse en la raíz del módulo de la aplicación, como se especifica en storeFile. Por seguridad, nunca almacene contraseñas en el repositorio; utilice los Secrets del sistema CI. Fastlane para Android proporciona el complemento supply, que funciona con Google Play Console, pero la firma del APK aún requiere un Keystore local en el agente.

Una alternativa es Google Play App Signing. Al usar esta opción, el desarrollador carga solo la clave de carga (upload key) en Google Play, y Google firma el APK final con su propia clave. En este caso, el Keystore solo se utiliza para crear la clave de carga, y su pérdida no bloquea las actualizaciones; se puede generar una nueva clave de carga y registrarla en la Consola. Google Play App Signing es obligatorio para aplicaciones nuevas desde agosto de 2021.

Seguridad y copia de seguridad del Keystore

Perder un Keystore es uno de los problemas más críticos en el desarrollo de Android. Sin una copia de seguridad, es imposible publicar una actualización de una aplicación existente; Google Play rechaza los APK firmados con una clave diferente. Se recomienda mantener al menos dos copias de seguridad del Keystore en diferentes almacenamientos físicos o en la nube: por ejemplo, un archivo cifrado en el almacenamiento en la nube del equipo y un medio físico en la caja fuerte de la organización. Las contraseñas del Keystore y de la clave se almacenan por separado del archivo, por ejemplo, en un gestor de contraseñas con control de acceso.

Android Studio, al crear un nuevo Keystore en el diálogo Generate Signed Bundle / APK, ofrece recordar las rutas para compilaciones futuras. Sin embargo, el entorno de desarrollo por sí mismo no crea una copia de seguridad; esta es la responsabilidad del desarrollador. Para el desarrollo en equipo, se recomienda usar Google Play App Signing con la clave de carga transmitida a través de un canal seguro a todos los miembros del equipo. Gradle puede firmar compilaciones de depuración automáticamente con un debug.keystore generado, que no requiere copia de seguridad; es el mismo para todas las instalaciones de Android Studio.

Seguridad del Keystore durante la transferencia: los archivos .p12 o .jks solo deben transferirse a través de canales cifrados (SFTP, HTTPS, archivos adjuntos de correo electrónico cifrados). Nunca incluya el Keystore en el repositorio de código fuente, ni siquiera en uno privado. GitGuardian o GitHub secret scanning detectan automáticamente la publicación de credenciales, pero almacenar el Keystore en un repositorio sigue siendo una violación de seguridad. Para CI/CD, utilice el mecanismo de secretos de la plataforma (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) con cifrado a nivel de infraestructura.