Keystore: essentie, welke formaten er zijn en hoe het werkt

Wat is Keystore

Keystore (KeyStore) — is een standaardmechanisme van Java Cryptography Architecture (JCA) voor het opslaan van cryptografische sleutels, certificaten en vertrouwde items. In Android-ontwikkeling wordt Keystore gebruikt voor het opslaan van de privésleutel waarmee de app vóór publicatie wordt ondertekend. De handtekening garandeert dat de app daadwerkelijk door de opgegeven ontwikkelaar is uitgebracht en dat de code niet is gewijzigd na publicatie. Elke update van de app moet met dezelfde sleutel worden ondertekend, anders wijst Google Play de APK of App Bundle af.

Keystore kan meerdere items (aliassen) bevatten, die elk een sleutelpaar (privé en openbaar) met een certificaat vertegenwoordigen. Alias — de unieke naam van het item waaronder de app de sleutel benadert bij het ondertekenen. In een typisch Android-project bevat Keystore één item voor het ondertekenen van de releaseversie en kan het extra items bevatten voor het ondertekenen van debug-builds. Google Play Console toont de SHA-1 en SHA-256 vingerafdrukken van het certificaat voor elke geüploade app.

Android Studio biedt ingebouwde ondersteuning voor Keystore via het menu Build → Generate Signed Bundle / APK. De ondertekeningswizard van Android Studio maakt het mogelijk een nieuwe Keystore te maken of een bestaande te selecteren, de alias, Keystore- en sleutelwachtwoorden op te geven, evenals certificeringsgegevens (organisatienaam, stad, land). Deze gegevens worden in het certificaat ingebed en zijn zichtbaar voor gebruikers bij het controleren van de APK-handtekening. Google Play vereist dat de geldigheid van het certificaat minimaal 25 jaar is — Android controleert de vervaldatum bij installatie van de app.

Waarom Keystore belangrijk is voor Android

Het bijwerken van de app in Google Play is alleen mogelijk met dezelfde sleutel waarmee de eerste versie is ondertekend. Als Keystore verloren gaat, is het onmogelijk om een update te publiceren — de app moet opnieuw worden uitgebracht onder een nieuwe pakketnaam (package name). Volgens Google Play Console Help (2026) kan de ondertekeningssleutel van de app alleen worden hersteld via Google Play App Signing — een service die de sleutel aan de kant van Google bewaart. Als de ontwikkelaar deze optie heeft gebruikt, is het verlies van de lokale Keystore niet kritiek.

Hoe werkt Keystore

Het ondertekeningsproces van een Android-app omvat het maken van een samenvatting (hash) van de APK-inhoud en het versleutelen ervan met de privésleutel uit Keystore. Android SDK Build Tools bevatten het hulpprogramma apksigner dat de ondertekening uitvoert in het formaat APK Signature Scheme v2 (of v3 voor Android 9+). Bij installatie van de app controleert Android de handtekening: het ontsleutelt de handtekening met de openbare sleutel van het certificaat, vergelijkt de hash van de APK met het origineel — als de hashes niet overeenkomen, wordt de installatie geweigerd.

Android ondersteunt meerdere ondertekeningsschema's: v1 (JAR signing), v2 (APK Signature Scheme), v3 (APK Signature Scheme met ondersteuning voor sleutelrotatie) en v4 (incrementele installaties Android 11+). Google Play vereist v2 of v3 voor nieuwe apps. apksigner voegt automatisch alle benodigde schema's toe bij het ondertekenen, als de sleutel de bijbehorende algoritmen ondersteunt. Android 11+ ondersteunt ADB-installatie met v4-handtekening, wat het incrementeel laden van grote APK-bestanden naar het apparaat versnelt.

Algoritmen: Android raadt het gebruik van RSA-2048 of ECDSA P-256 aan voor de ondertekeningssleutel. Het certificaat moet X.509 v3 zijn. Android controleert of het certificaat geldig is op het moment van installatie — als het is verlopen, wordt de installatie geblokkeerd. Daarom raadt Google aan de geldigheidsduur van het certificaat op minimaal 25 jaar in te stellen. Google Play App Signing gebruikt twee sleutels: de app-ondertekeningssleutel (app signing key) en de uploadsleutel (upload key) — de uploadsleutel wordt door de ontwikkelaar gebruikt om de APK naar de Console te uploaden, en Google ondertekent de app voor gebruikers met de hoofdsleutel.

Keystore-formaten: JKS en PKCS12

Java ondersteunt twee hoofdformaten van Keystore: JKS (Java KeyStore) — het eigen formaat van Oracle, bestaand sinds JDK 1.2, en PKCS12 — het gestandaardiseerde formaat Public-Key Cryptography Standards #12 van RSA Laboratories. JKS gebruikt zijn eigen gegevensopslagformaat en wordt alleen ondersteund in het Java-ecosysteem. PKCS12 is een open standaard die wordt ondersteund door Java, .NET, OpenSSL, Python (cryptography) en de meeste andere cryptografische bibliotheken.

Google Play beveelt PKCS12 aan als het voorkeursformaat voor nieuwe Keystores die na 2021 zijn gemaakt. JDK 9 en nieuwer maken standaard Keystore in PKCS12-formaat (voorheen was JKS de standaard). Het belangrijkste voordeel van PKCS12 is compatibiliteit: het .p12-bestand kan worden geopend in elke omgeving die niet aan Java is gebonden. OpenSSL kan certificaten uit PKCS12 extraheren en converteren naar PEM-formaat. JKS-bestanden vereisen JDK-hulpprogramma's om te lezen en kunnen niet worden verwerkt door OpenSSL.

Conversie tussen formaten wordt uitgevoerd met het hulpprogramma keytool uit JDK. Bij migratie van JKS naar PKCS12 moet u ervoor zorgen dat alle aliassen en wachtwoorden correct zijn overgedragen. Met de opdracht keytool -importkeystore kunt u de inhoud van de ene Keystore naar de andere importeren, ongeacht het formaat. Na conversie is het beter het oude JKS-bestand te verwijderen om verwarring met sleutelversies te voorkomen. Android Studio ondersteunt beide formaten bij het genereren van een ondertekende build.

Keystore maken via keytool

Het hulpprogramma keytool maakt deel uit van de JDK (Java Development Kit) en biedt een volledige reeks opdrachten voor het maken, bekijken en beheren van Keystore. Om een nieuwe Keystore met één sleutelpaar te maken, wordt de opdracht keytool -genkeypair gebruikt met specificatie van het PKCS12-formaat, RSA-algoritme, sleutelgrootte en certificaatgeldigheidsduur. Google Play vereist een certificaatgeldigheid van minimaal 25 jaar (9125 dagen) — deze waarde wordt aanbevolen in de parameter -validity.

Een nieuwe Keystore maken

Voorbeeld van het genereren van een Keystore in PKCS12-formaat voor een Android-project. De parameter -dname bevat de X.500 Distinguished Name van het certificaat. De parameter -ext activeert Subject Alternative Name, indien vereist — voor Android zijn Basic Constraints voldoende:

# PKCS12 Keystore maken voor 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 vraagt om het Keystore-wachtwoord en het sleutelwachtwoord (kunnen hetzelfde zijn). De parameter -storetype PKCS12 maakt het bestand in modern formaat. -keysize 2048 voldoet aan de vereisten van Google voor minimale RSA-sleutelgrootte. -validity 9125 (25 jaar) garandeert compatibiliteit gedurende de gehele verwachte levenscyclus van de app. Na het maken van de Keystore wordt aanbevolen de inhoud ervan te controleren met de opdracht keytool -list -v -keystore release-keystore.p12.

Inhoud van Keystore bekijken

Om de items van de Keystore te controleren, wordt de opdracht met de vlag -list gebruikt. De uitvoer bevat de alias, aanmaak- en vervaldata, het itemtype en SHA-256 vingerafdrukken. Android Studio toont dezelfde informatie in het dialoogvenster Generate Signed Bundle / APK bij het selecteren van een bestaande Keystore:

# Keystore-items bekijken
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

Keystore gebruiken in CI/CD

In de CI/CD-pijplijn moet Keystore veilig worden opgeslagen en zonder risico op compromittering naar de build-agent worden overgedragen. GitHub Actions biedt Secrets voor het opslaan van binaire bestanden in base64-formaat. Keystore wordt gecodeerd met de opdracht base64, de resulterende string wordt opgeslagen in de repositorygeheimen en in de build-fase wordt het terug gedecodeerd naar een bestand. GitLab CI gebruikt een vergelijkbaar mechanisme via Variables met het type File.

Een voorbeeld van het configureren van een CI-build met Keystore in GitHub Actions omvat het decoderen van Keystore uit het geheim, het configureren van Gradle-eigenschappen en het uitvoeren van de ondertekende build. Gradle van de Android-plugin leest het pad naar Keystore en wachtwoorden uit het bestand keystore.properties (uitgesloten van .gitignore voor lokale ontwikkeling) of uit omgevingsvariabelen van het CI-systeem:

// build.gradle (app) — ondertekeningsconfiguratie
@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 leest de omgevingsvariabelen die door het CI-systeem zijn ingesteld. Het Keystore-bestand moet zich in de hoofdmap van de app-module bevinden, zoals aangegeven in storeFile. Voor de veiligheid mag u nooit wachtwoorden in de repository opslaan — gebruik Secrets van het CI-systeem. Fastlane voor Android biedt de plug-in supply die werkt met Google Play Console, maar het ondertekenen van APK vereist nog steeds een lokale Keystore op de agent.

Een alternatief is Google Play App Signing. Bij gebruik van deze optie uploadt de ontwikkelaar alleen de uploadsleutel (upload key) naar Google Play, en Google ondertekent de uiteindelijke APK met zijn eigen sleutel. In dit geval wordt Keystore alleen gebruikt voor het maken van de uploadsleutel, en het verlies ervan blokkeert updates niet — er kan een nieuwe upload key worden gegenereerd en geregistreerd in de Console. Google Play App Signing is verplicht voor nieuwe apps sinds augustus 2021.

Beveiliging en back-up van Keystore

Verlies van Keystore is een van de meest kritieke problemen in Android-ontwikkeling. Zonder back-up van Keystore kan er geen update van de bestaande app worden uitgebracht — Google Play wijst een APK ondertekend met een andere sleutel af. Het wordt aanbevolen om ten minste twee back-ups van Keystore op te slaan in verschillende fysieke of cloudopslagplaatsen: bijvoorbeeld een versleuteld bestand in de cloudopslag van het team en een fysieke drager in de kluis van de organisatie. De wachtwoorden van Keystore en de sleutel worden apart van het bestand opgeslagen, bijvoorbeeld in een wachtwoordbeheerder met toegangscontrole.

Android Studio biedt bij het maken van een nieuwe Keystore in het dialoogvenster Generate Signed Bundle / APK aan om de paden voor toekomstige builds te onthouden. De ontwikkelomgeving zelf maakt echter geen back-up — dit is de verantwoordelijkheid van de ontwikkelaar. Voor teamontwikkeling wordt aanbevolen Google Play App Signing te gebruiken met overdracht van de upload key via een beveiligd kanaal aan alle teamleden. Gradle maakt het mogelijk debug-builds te ondertekenen met automatisch gegenereerde debug.keystore, die geen back-up vereist — deze is hetzelfde voor alle installaties van Android Studio.

Beveiliging van Keystore bij overdracht: het .p12- of .jks-bestand mag alleen via versleutelde kanalen worden overgedragen (SFTP, HTTPS, versleutelde e-mailbijlagen). Plaats Keystore nooit in de broncoderepository — zelfs niet in een privérepository. GitGuardian of GitHub secret scanning detecteren automatisch publicatie van inloggegevens, maar het opslaan van Keystore in de repository is nog steeds een beveiligingsinbreuk. Gebruik voor CI/CD het geheimenmechanisme van het platform (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) met versleuteling op infrastructureniveau.