Keystore: cos'è, quali formati esistono e come funziona

Cos'è un Keystore

Keystore (KeyStore) è un meccanismo standard di Java Cryptography Architecture (JCA) per memorizzare chiavi crittografiche, certificati e voci attendibili. Nello sviluppo Android, il Keystore viene utilizzato per conservare la chiave privata con cui viene firmata l'app prima della pubblicazione. La firma garantisce che l'app sia stata effettivamente pubblicata dallo sviluppatore indicato e che il suo codice non sia stato alterato dopo la pubblicazione. Ogni aggiornamento dell'app deve essere firmato con la stessa chiave, altrimenti Google Play rifiuterà l'APK o l'App Bundle.

Un Keystore può contenere più voci (alias), ciascuna delle quali rappresenta una coppia di chiavi (privata e pubblica) con un certificato. Alias è un nome di voce univoco con cui l'app accede alla chiave durante la firma. In un tipico progetto Android, il Keystore contiene una voce per firmare la versione di rilascio e può contenere voci aggiuntive per firmare le build di debug. Google Play Console mostra le impronte SHA-1 e SHA-256 del certificato per ogni app caricata.

Android Studio include il supporto integrato per Keystore tramite il menu Build → Generate Signed Bundle / APK. La procedura guidata di firma di Android Studio consente di creare un nuovo Keystore o selezionarne uno esistente, specificare un alias, le password del Keystore e della chiave, nonché i dati del certificato (nome dell'organizzazione, città, paese). Questi dati vengono incorporati nel certificato e sono visibili agli utenti durante la verifica della firma APK. Google Play richiede che il certificato sia valido per almeno 25 anni; Android verifica la data di scadenza durante l'installazione dell'app.

Perché Keystore è importante per Android

Gli aggiornamenti delle app su Google Play sono possibili solo con la stessa chiave che ha firmato la prima versione. Se il Keystore viene perso, è impossibile pubblicare un aggiornamento — l'app dovrebbe essere ripubblicata con un nome pacchetto diverso. Secondo Google Play Console Help (2026), la chiave di firma dell'app può essere recuperata solo tramite Google Play App Signing, un servizio che memorizza la chiave sul lato Google. Se lo sviluppatore ha utilizzato questa opzione, la perdita del Keystore locale non è critica.

Come funziona un Keystore

Il processo di firma di un'app Android prevede la creazione di un digest (hash) del contenuto dell'APK e la sua crittografia con la chiave privata del Keystore. Android SDK Build Tools includono l'utilità apksigner, che esegue la firma utilizzando APK Signature Scheme v2 (o v3 per Android 9+). Durante l'installazione dell'app, Android verifica la firma: decifra la firma con la chiave pubblica del certificato, confronta l'hash dell'APK con l'originale — se gli hash non corrispondono, l'installazione viene rifiutata.

Android supporta diversi schemi di firma: v1 (firma JAR), v2 (APK Signature Scheme), v3 (APK Signature Scheme con supporto per la rotazione delle chiavi) e v4 (installazioni incrementali per Android 11+). Google Play richiede v2 o v3 per le nuove app. apksigner aggiunge automaticamente tutti gli schemi necessari durante la firma se la chiave supporta gli algoritmi corrispondenti. Android 11+ supporta l'installazione ADB con firma v4, che accelera il caricamento incrementale di APK di grandi dimensioni sul dispositivo.

Algoritmi: Android raccomanda di utilizzare RSA-2048 o ECDSA P-256 per la chiave di firma. Il certificato deve essere X.509 v3. Android verifica che il certificato sia valido al momento dell'installazione — se è scaduto, l'installazione viene bloccata. Ecco perché Google raccomanda di impostare il periodo di validità del certificato ad almeno 25 anni. Google Play App Signing utilizza due chiavi: la chiave di firma dell'app (app signing key) e la chiave di caricamento (upload key) — lo sviluppatore utilizza la chiave di caricamento per caricare l'APK nella Console, e Google firma l'app per gli utenti con la chiave principale.

Formati di Keystore: JKS e PKCS12

Java supporta due formati principali di Keystore: JKS (Java KeyStore), un formato proprietario di Oracle che esiste da JDK 1.2, e PKCS12, il formato standardizzato Public-Key Cryptography Standards #12 di RSA Laboratories. JKS utilizza un proprio formato di archiviazione dei dati ed è supportato solo all'interno dell'ecosistema Java. PKCS12 è uno standard aperto supportato da Java, .NET, OpenSSL, Python (cryptography) e la maggior parte delle altre librerie crittografiche.

Google Play raccomanda PKCS12 come formato preferito per i nuovi Keystore creati dopo il 2021. JDK 9 e versioni successive creano Keystore in formato PKCS12 per impostazione predefinita (in precedenza il formato predefinito era JKS). Il principale vantaggio di PKCS12 è la compatibilità: un file .p12 può essere aperto in qualsiasi ambiente non legato a Java. OpenSSL può estrarre certificati da PKCS12 e convertirli in formato PEM. I file JKS richiedono utilità JDK per la lettura e non possono essere elaborati da OpenSSL.

La conversione tra i formati viene eseguita con l'utilità keytool del JDK. Durante la migrazione da JKS a PKCS12, assicurarsi che tutti gli alias e le password siano trasferiti correttamente. Il comando keytool -importkeystore consente di importare il contenuto di un Keystore in un altro indipendentemente dal formato. Dopo la conversione, è meglio eliminare il vecchio file JKS per evitare confusione con le versioni delle chiavi. Android Studio supporta entrambi i formati durante la generazione di una build firmata.

Creare un Keystore con keytool

L'utilità keytool fa parte del JDK (Java Development Kit) e fornisce un set completo di comandi per creare, visualizzare e gestire Keystore. Per creare un nuovo Keystore con una coppia di chiavi, si utilizza il comando keytool -genkeypair specificando il formato PKCS12, l'algoritmo RSA, la dimensione della chiave e il periodo di validità del certificato. Google Play richiede una validità del certificato di almeno 25 anni (9125 giorni) — si raccomanda di specificare questo valore nel parametro -validity.

Creare un nuovo Keystore

Esempio di generazione di un Keystore in formato PKCS12 per un progetto Android. Il parametro -dname contiene il Distinguished Name X.500 del certificato. Il parametro -ext include Subject Alternative Name se necessario — per Android, Basic Constraints è sufficiente:

# Creazione di un Keystore PKCS12 per 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 richiederà la password del Keystore e la password della chiave (possono coincidere). Il parametro -storetype PKCS12 crea un file nel formato moderno. -keysize 2048 soddisfa i requisiti di Google per la dimensione minima della chiave RSA. -validity 9125 (25 anni) garantisce la compatibilità per l'intero ciclo di vita previsto dell'applicazione. Dopo aver creato il Keystore, si raccomanda di verificarne il contenuto con il comando keytool -list -v -keystore release-keystore.p12.

Visualizzare il contenuto del Keystore

Per verificare le voci del Keystore, si utilizza il comando con il flag -list. L'output include l'alias, le date di creazione e scadenza, il tipo di voce e le impronte SHA-256. Android Studio mostra le stesse informazioni nella finestra di dialogo Generate Signed Bundle / APK quando si seleziona un Keystore esistente:

# Visualizzazione delle voci del Keystore
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

Usare Keystore in CI/CD

In una pipeline CI/CD, il Keystore deve essere conservato in modo sicuro e passato all'agente di build senza rischio di compromissione. GitHub Actions fornisce Secrets per memorizzare file binari in formato base64. Il Keystore viene codificato con il comando base64, la stringa risultante viene salvata nei segreti del repository e durante la fase di build viene decodificata nuovamente in un file. GitLab CI utilizza un meccanismo simile tramite Variables di tipo File.

Un esempio di configurazione di una build CI con Keystore in GitHub Actions include la decodifica del Keystore da un segreto, la configurazione delle proprietà di Gradle e l'esecuzione di una build firmata. Gradle, il plugin Android, legge il percorso del Keystore e le password dal file keystore.properties (escluso da .gitignore per lo sviluppo locale) o dalle variabili d'ambiente del sistema CI:

// build.gradle (app) — configurazione di 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 legge le variabili d'ambiente impostate dal sistema CI. Il file Keystore dovrebbe trovarsi nella radice del modulo dell'applicazione, come specificato in storeFile. Per sicurezza, non memorizzare mai le password nel repository — utilizzare i Secrets del sistema CI. Fastlane per Android fornisce il plugin supply, che funziona con Google Play Console, ma la firma APK richiede comunque un Keystore locale sull'agente.

Un'alternativa è Google Play App Signing. Utilizzando questa opzione, lo sviluppatore carica solo la chiave di caricamento (upload key) su Google Play, e Google firma l'APK finale con la propria chiave. In questo caso, il Keystore viene utilizzato solo per creare la chiave di caricamento e la sua perdita non blocca gli aggiornamenti — una nuova chiave di caricamento può essere generata e registrata nella Console. Google Play App Signing è obbligatorio per le nuove applicazioni da agosto 2021.

Sicurezza e backup del Keystore

Perdere un Keystore è uno dei problemi più critici nello sviluppo Android. Senza un backup, è impossibile pubblicare un aggiornamento di un'applicazione esistente — Google Play rifiuta gli APK firmati con una chiave diversa. Si raccomanda di conservare almeno due copie di backup del Keystore in diversi archivi fisici o cloud: ad esempio, un file crittografato nell'archivio cloud del team e un supporto fisico nella cassaforte dell'organizzazione. Le password del Keystore e della chiave vengono conservate separatamente dal file, ad esempio in un gestore di password con controllo degli accessi.

Android Studio, quando crea un nuovo Keystore nella finestra di dialogo Generate Signed Bundle / APK, offre di ricordare i percorsi per le build future. Tuttavia, l'ambiente di sviluppo stesso non crea un backup — questa è la responsabilità dello sviluppatore. Per lo sviluppo di gruppo, si raccomanda di utilizzare Google Play App Signing con la chiave di caricamento trasmessa attraverso un canale sicuro a tutti i membri del team. Gradle può firmare automaticamente le build di debug con un debug.keystore generato, che non richiede backup — è lo stesso per tutte le installazioni di Android Studio.

Sicurezza del Keystore durante il trasferimento: i file .p12 o .jks devono essere trasferiti solo attraverso canali crittografati (SFTP, HTTPS, allegati email crittografati). Non includere mai il Keystore nel repository del codice sorgente, nemmeno privato. GitGuardian o GitHub secret scanning rilevano automaticamente la pubblicazione di credenziali, ma conservare il Keystore in un repository costituisce comunque una violazione della sicurezza. Per CI/CD, utilizzare il meccanismo dei segreti della piattaforma (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) con crittografia a livello di infrastruttura.