Keystore: esența, ce formate există și cum funcționează

Ce este Keystore

Keystore (KeyStore) — este un mecanism standard al Java Cryptography Architecture (JCA) pentru stocarea cheilor criptografice, certificatelor și înregistrărilor de încredere. În dezvoltarea Android, Keystore este utilizat pentru stocarea cheii private cu care se semnează aplicația înainte de publicare. Semnătura garantează că aplicația a fost lansată într-adevăr de dezvoltatorul specificat și că codul său nu a fost modificat după publicare. Fiecare actualizare a aplicației trebuie să fie semnată cu aceeași cheie, altfel Google Play va respinge APK-ul sau App Bundle-ul.

Keystore poate conține mai multe înregistrări (aliasuri), fiecare reprezentând o pereche de chei (privată și publică) cu un certificat. Alias — numele unic al înregistrării sub care aplicația accesează cheia la semnare. Într-un proiect Android tipic, Keystore conține o înregistrare pentru semnarea versiunii de release și poate conține altele pentru semnarea build-urilor de debug. Google Play Console afișează amprentele SHA-1 și SHA-256 ale certificatului pentru fiecare aplicație încărcată.

Android Studio include suport integrat pentru Keystore prin meniul Build → Generate Signed Bundle / APK. Expertul de semnare Android Studio permite crearea unui nou Keystore sau selectarea unuia existent, specificarea aliasului, parolelor Keystore și cheii, precum și a datelor de certificare (numele organizației, orașul, țara). Aceste date sunt încorporate în certificat și sunt vizibile utilizatorilor la verificarea semnăturii APK. Google Play cere ca valabilitatea certificatului să fie de cel puțin 25 de ani — Android verifică data expirării la instalarea aplicației.

De ce este important Keystore pentru Android

Actualizarea aplicației în Google Play este posibilă doar cu aceeași cheie cu care a fost semnată prima versiune. Dacă Keystore este pierdut, publicarea unei actualizări este imposibilă — aplicația va trebui relansată sub un nou nume de pachet (package name). Potrivit Google Play Console Help (2026), cheia de semnare a aplicației poate fi recuperată doar prin Google Play App Signing — un serviciu care stochează cheia pe partea Google. Dacă dezvoltatorul a folosit această opțiune, pierderea Keystore-ului local nu este critică.

Cum funcționează Keystore

Procesul de semnare a unei aplicații Android include crearea unui rezumat (hash) al conținutului APK și criptarea acestuia cu cheia privată din Keystore. Android SDK Build Tools includ utilitarul apksigner care efectuează semnarea în formatul APK Signature Scheme v2 (sau v3 pentru Android 9+). La instalarea aplicației, Android verifică semnătura: decriptează semnătura cu cheia publică a certificatului, compară hash-ul APK cu originalul — dacă hash-urile nu coincid, instalarea este respinsă.

Android suportă mai multe scheme de semnare: v1 (JAR signing), v2 (APK Signature Scheme), v3 (APK Signature Scheme cu suport pentru rotația cheilor) și v4 (instalări incrementale Android 11+). Google Play cere v2 sau v3 pentru aplicații noi. apksigner adaugă automat toate schemele necesare la semnare, dacă cheia suportă algoritmii corespunzători. Android 11+ suportă instalarea ADB cu semnătură v4, ceea ce accelerează încărcarea incrementală a fișierelor APK mari pe dispozitiv.

Algoritmi: Android recomandă utilizarea RSA-2048 sau ECDSA P-256 pentru cheia de semnare. Certificatul trebuie să fie X.509 v3. Android verifică dacă certificatul este valabil la momentul instalării — dacă a expirat, instalarea este blocată. Tocmai de aceea Google recomandă setarea perioadei de valabilitate a certificatului la cel puțin 25 de ani. Google Play App Signing utilizează două chei: cheia aplicației (app signing key) și cheia de încărcare (upload key) — cheia de încărcare este folosită de dezvoltator pentru a încărca APK-ul în Console, iar Google semnează aplicația pentru utilizatori cu cheia principală.

Formate Keystore: JKS și PKCS12

Java suportă două formate principale de Keystore: JKS (Java KeyStore) — formatul proprietar Oracle, existent din JDK 1.2, și PKCS12 — formatul standardizat Public-Key Cryptography Standards #12 de la RSA Laboratories. JKS utilizează propriul format de stocare a datelor și este suportat doar în ecosistemul Java. PKCS12 este un standard deschis suportat de Java, .NET, OpenSSL, Python (cryptography) și majoritatea celorlalte biblioteci criptografice.

Google Play recomandă PKCS12 ca format preferat pentru Keystore-uri noi create după 2021. JDK 9 și versiunile mai noi creează implicit Keystore în format PKCS12 (anterior implicit era JKS). Principalul avantaj al PKCS12 este compatibilitatea: fișierul .p12 poate fi deschis în orice mediu nelegat de Java. OpenSSL poate extrage certificate din PKCS12 și le poate converti în format PEM. Fișierele JKS necesită utilitare JDK pentru citire și nu pot fi procesate de OpenSSL.

Conversia între formate se realizează cu utilitarul keytool din JDK. La migrarea de la JKS la PKCS12, trebuie să vă asigurați că toate aliasurile și parolele au fost transferate corect. Comanda keytool -importkeystore permite importarea conținutului unui Keystore în altul, indiferent de format. După conversie, fișierul JKS vechi este mai bine să fie șters pentru a evita confuzia cu versiunile cheii. Android Studio suportă ambele formate la generarea unui build semnat.

Crearea Keystore prin keytool

Utilitarul keytool face parte din JDK (Java Development Kit) și oferă un set complet de comenzi pentru crearea, vizualizarea și gestionarea Keystore. Pentru a crea un nou Keystore cu o pereche de chei, se utilizează comanda keytool -genkeypair cu specificarea formatului PKCS12, algoritmului RSA, dimensiunii cheii și perioadei de valabilitate a certificatului. Google Play cere valabilitatea certificatului de cel puțin 25 de ani (9125 zile) — această valoare este recomandată a fi specificată în parametrul -validity.

Crearea unui nou Keystore

Exemplu de generare a unui Keystore în format PKCS12 pentru un proiect Android. Parametrul -dname conține X.500 Distinguished Name al certificatului. Parametrul -ext va activa Subject Alternative Name, dacă este necesar — pentru Android sunt suficiente Basic Constraints:

# Crearea PKCS12 Keystore pentru 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 va solicita parola Keystore și parola cheii (pot fi aceleași). Parametrul -storetype PKCS12 creează fișierul în format modern. -keysize 2048 corespunde cerințelor Google privind dimensiunea minimă a cheii RSA. -validity 9125 (25 de ani) asigură compatibilitatea pe întreg ciclul de viață preconizat al aplicației. După crearea Keystore, se recomandă verificarea conținutului său cu comanda keytool -list -v -keystore release-keystore.p12.

Vizualizarea conținutului Keystore

Pentru verificarea înregistrărilor Keystore se utilizează comanda cu flag-ul -list. Rezultatul include aliasul, datele de creare și expirare, tipul înregistrării și amprentele SHA-256. Android Studio afișează aceleași informații în dialogul Generate Signed Bundle / APK la selectarea unui Keystore existent:

# Vizualizarea înregistrărilor Keystore
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

Utilizarea Keystore în CI/CD

În pipeline-ul CI/CD, Keystore trebuie stocat în siguranță și transmis agentului de build fără riscul de compromitere. GitHub Actions oferă Secrets pentru stocarea fișierelor binare în format base64. Keystore este codat cu comanda base64, șirul rezultat este stocat în secretele repository-ului, iar în etapa de build este decodat înapoi în fișier. GitLab CI utilizează un mecanism similar prin Variables cu tipul File.

Un exemplu de configurare a build-ului CI cu Keystore în GitHub Actions include decodarea Keystore-ului din secret, configurarea proprietăților Gradle și executarea build-ului semnat. Gradle plugin-ului Android citește calea către Keystore și parolele din fișierul keystore.properties (exclus din .gitignore pentru dezvoltarea locală) sau din variabilele de mediu ale sistemului CI:

// build.gradle (app) — configurarea semnării
@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 citește variabilele de mediu setate de sistemul CI. Fișierul Keystore trebuie să fie localizat în rădăcina modulului aplicației, așa cum este specificat în storeFile. Pentru securitate, nu stocați niciodată parolele în repository — utilizați Secrets ale sistemului CI. Fastlane pentru Android oferă pluginul supply care funcționează cu Google Play Console, dar semnarea APK necesită totuși un Keystore local pe agent.

Alternativa este Google Play App Signing. La utilizarea acestei opțiuni, dezvoltatorul încarcă în Google Play doar cheia de încărcare (upload key), iar Google semnează APK-ul final cu propria cheie. În acest caz, Keystore este utilizat doar pentru crearea cheii de încărcare, iar pierderea sa nu blochează actualizările — se poate genera o nouă upload key și se poate înregistra în Console. Google Play App Signing este obligatoriu pentru aplicații noi din august 2021.

Securitatea și backup-ul Keystore

Pierderea Keystore-ului este una dintre cele mai critice probleme în dezvoltarea Android. Fără o copie de backup Keystore, nu se poate lansa o actualizare a aplicației existente — Google Play respinge APK-ul semnat cu o altă cheie. Se recomandă stocarea a cel puțin două copii de backup ale Keystore-ului în depozite fizice sau în cloud diferite: de exemplu, un fișier criptat în stocarea cloud a echipei și un suport fizic în seiful organizației. Parolele Keystore și ale cheii se stochează separat de fișier, de exemplu într-un manager de parole cu control al accesului.

Android Studio la crearea unui nou Keystore în dialogul Generate Signed Bundle / APK oferă să rețină căile pentru build-uri viitoare. Cu toate acestea, mediul de dezvoltare în sine nu creează o copie de backup — aceasta este responsabilitatea dezvoltatorului. Pentru dezvoltarea în echipă, se recomandă utilizarea Google Play App Signing cu transmiterea upload key-ului prin canal securizat tuturor membrilor echipei. Gradle permite semnarea build-urilor de debug (debug) cu debug.keystore generat automat, care nu necesită backup — este același pentru toate instalările Android Studio.

Securitatea Keystore-ului la transmitere: fișierul .p12 sau .jks trebuie transmis doar prin canale criptate (SFTP, HTTPS, atașamente de e-mail criptate). Nu includeți niciodată Keystore-ul în repository-ul de cod sursă — nici măcar privat. GitGuardian sau GitHub secret scanning detectează automat publicarea credențialelor, dar stocarea Keystore-ului în repository constituie totuși o încălcare a securității. Pentru CI/CD, utilizați mecanismul de secrete al platformei (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) cu criptare la nivel de infrastructură.