Keystore: що це таке, які бувають формати та як працює

Що таке Keystore

Keystore (KeyStore) — це стандартний механізм Java Cryptography Architecture (JCA) для зберігання криптографічних ключів, сертифікатів та довірених записів. В Android-розробці Keystore використовується для зберігання закритого ключа, яким підписується додаток перед публікацією. Підпис гарантує, що додаток дійсно випущений зазначеним розробником і його код не був змінений після публікації. Кожне оновлення додатка має бути підписано тим же ключем, інакше Google Play відхилить APK або App Bundle.

Keystore може містити кілька записів (aliases), кожен з яких представляє пару ключів (закритий та відкритий) з сертифікатом. Alias — унікальне ім'я запису, за яким додаток звертається до ключа при підписі. У типовому Android-проєкті Keystore містить один запис для підпису релізної версії та може містити додаткові для підпису налагоджувальних збірок. Google Play Console відображає SHA-1 та SHA-256 відбитки сертифіката для кожного завантаженого додатка.

Android Studio включає вбудовану підтримку Keystore через меню Build → Generate Signed Bundle / APK. Майстер підпису Android Studio дозволяє створити новий Keystore або вибрати існуючий, вказати alias, паролі Keystore та ключа, а також сертифікаційні дані (ім'я організації, місто, країну). Ці дані вбудовуються в сертифікат і видимі користувачам при перевірці підпису APK. Google Play вимагає, щоб термін дії сертифіката становив щонайменше 25 років — Android перевіряє дату закінчення при встановленні додатка.

Чому Keystore важливий для Android

Оновлення додатка в Google Play можливе лише тим же ключем, яким підписана перша версія. Якщо Keystore втрачено, неможливо опублікувати оновлення — додаток доведеться перевипускати під новим пакетним ім'ям (package name). За даними Google Play Console Help (2026), ключ підпису додатка можна відновити лише через Google Play App Signing — сервіс, який зберігає ключ на стороні Google. Якщо розробник використав цю опцію, втрата локального Keystore не критична.

Як працює Keystore

Процес підпису Android-додатка включає створення дайджесту (хеша) вмісту APK та його шифрування закритим ключем з Keystore. Android SDK Build Tools включають утиліту apksigner, яка виконує підпис у форматі APK Signature Scheme v2 (або v3 для Android 9+). При встановленні додатка Android перевіряє підпис: розшифровує підпис відкритим ключем сертифіката, порівнює хеш APK з оригіналом — якщо хеші не збігаються, встановлення відхиляється.

Android підтримує кілька схем підпису: v1 (JAR signing), v2 (APK Signature Scheme), v3 (APK Signature Scheme з підтримкою ротації ключів) та v4 (інкрементальні встановлення Android 11+). Google Play вимагає v2 або v3 для нових додатків. apksigner автоматично додає всі необхідні схеми при підписі, якщо ключ підтримує відповідні алгоритми. Android 11+ підтримує ADB-встановлення з v4 підписом, що прискорює інкрементальне завантаження великих APK на пристрій.

Алгоритми: Android рекомендує використовувати RSA-2048 або ECDSA P-256 для ключа підпису. Сертифікат має бути X.509 v3. Android перевіряє, що сертифікат дійсний на момент встановлення — якщо термін минув, встановлення блокується. Саме тому Google рекомендує встановлювати термін дії сертифіката щонайменше на 25 років. Google Play App Signing використовує два ключі: ключ додатка (app signing key) та ключ завантаження (upload key) — завантажувальний ключ використовується розробником для завантаження APK в Console, а Google підписує додаток для користувачів основним ключем.

Формати Keystore: JKS та PKCS12

Java підтримує два основні формати Keystore: JKS (Java KeyStore) — пропрієтарний формат Oracle, що існує з JDK 1.2, та PKCS12 — стандартизований формат Public-Key Cryptography Standards #12 від RSA Laboratories. JKS використовує власний формат зберігання даних і підтримується лише в Java-екосистемі. PKCS12 — відкритий стандарт, що підтримується Java, .NET, OpenSSL, Python (cryptography) та більшістю інших криптографічних бібліотек.

Google Play рекомендує PKCS12 як кращий формат для нових Keystore, створених після 2021 року. JDK 9 та новіші за замовчуванням створюють Keystore у форматі PKCS12 (раніше за замовчуванням був JKS). Основна перевага PKCS12 — сумісність: файл .p12 можна відкрити в будь-якому середовищі, не прив'язаному до Java. OpenSSL може витягувати сертифікати з PKCS12 та конвертувати їх у PEM-формат. JKS-файли вимагають JDK-утиліт для читання і не можуть бути оброблені OpenSSL.

Конвертація між форматами виконується утилітою keytool з JDK. При міграції з JKS на PKCS12 необхідно переконатися, що всі aliases та паролі коректно перенесені. Команда keytool -importkeystore дозволяє імпортувати вміст одного Keystore в інший незалежно від формату. Після конвертації старий JKS-файл краще видалити, щоб уникнути плутанини з версіями ключа. Android Studio підтримує обидва формати при генерації підписаного білда.

Створення Keystore через keytool

Утиліта keytool входить до складу JDK (Java Development Kit) та надає повний набір команд для створення, перегляду та управління Keystore. Для створення нового Keystore з однією парою ключів використовується команда keytool -genkeypair із зазначенням формату PKCS12, алгоритму RSA, розміру ключа та терміну дії сертифіката. Google Play вимагає дійсність сертифіката не менше 25 років (9125 днів) — це значення рекомендується вказувати в параметрі -validity.

Створення нового Keystore

Приклад генерації Keystore у форматі PKCS12 для Android-проєкту. Параметр -dname містить X.500 Distinguished Name сертифіката. Параметр -ext включить Subject Alternative Name, якщо він потрібен — для Android достатньо Basic Constraints:

# Створення PKCS12 Keystore для 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 запитає пароль Keystore та пароль ключа (можна збігатися). Параметр -storetype PKCS12 створює файл у сучасному форматі. -keysize 2048 відповідає вимогам Google до мінімального розміру RSA-ключа. -validity 9125 (25 років) забезпечує сумісність на весь очікуваний життєвий цикл додатка. Після створення Keystore рекомендується перевірити його вміст командою keytool -list -v -keystore release-keystore.p12.

Перегляд вмісту Keystore

Для перевірки записів Keystore використовується команда з прапорцем -list. Вивід включає alias, дати створення та закінчення, тип запису та відбитки SHA-256. Android Studio відображає цю ж інформацію в діалозі Generate Signed Bundle / APK при виборі існуючого Keystore:

# Перегляд записів Keystore
keytool -list -v -keystore "release-keystore.p12" \
  -storetype PKCS12

Використання Keystore в CI/CD

В CI/CD-пайплайні Keystore необхідно зберігати в захищеному вигляді та передавати на агент збірки без ризику компрометації. GitHub Actions надає Secrets для зберігання бінарних файлів у форматі base64. Keystore кодується командою base64, отриманий рядок зберігається в секретах репозиторію, а на етапі збірки декодується назад у файл. GitLab CI використовує аналогічний механізм через Variables з типом File.

Приклад налаштування CI-збірки з Keystore в GitHub Actions включає декодування Keystore з секрету, налаштування Gradle властивостей та виконання підписаної збірки. Gradle Android-плагіна читає шлях до Keystore та паролі з файлу keystore.properties (виключений з .gitignore для локальної розробки) або з змінних оточення CI-системи:

// build.gradle (app) — конфігурація підпису
@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 читає змінні оточення, встановлені CI-системою. Файл Keystore має бути розташований в корені модуля додатка, як зазначено в storeFile. Для безпеки ніколи не зберігайте паролі в репозиторії — використовуйте Secrets CI-системи. Fastlane для Android надає плагін supply, який працює з Google Play Console, але підпис APK все одно вимагає локального Keystore на агенті.

Альтернатива — Google Play App Signing. При використанні цієї опції розробник завантажує в Google Play лише ключ завантаження (upload key), а Google підписує фінальний APK своїм ключем. В цьому випадку Keystore використовується лише для створення ключа завантаження, і його втрата не блокує оновлення — можна згенерувати новий upload key та зареєструвати його в Console. Google Play App Signing обов'язковий для нових додатків з серпня 2021 року.

Безпека та резервне копіювання Keystore

Втрата Keystore — одна з найкритичніших проблем в Android-розробці. Без резервної копії Keystore неможливо випустити оновлення існуючого додатка — Google Play відхиляє APK, підписаний іншим ключем. Рекомендується зберігати щонайменше дві резервні копії Keystore в різних фізичних або хмарних сховищах: наприклад, зашифрований файл в хмарному сховищі команди та фізичний носій в сейфі організації. Паролі Keystore та ключа зберігаються окремо від файлу, наприклад в менеджері паролів з контролем доступу.

Android Studio при створенні нового Keystore в діалозі Generate Signed Bundle / APK пропонує запам'ятати шляхи для майбутніх збірок. Однак сама середа розробки не створює резервну копію — це відповідальність розробника. Для командної розробки рекомендується використовувати Google Play App Signing з передачею upload key через захищений канал всім учасникам команди. Gradle дозволяє підписувати налагоджувальні збірки (debug) автоматично згенерованим debug.keystore, який не вимагає резервування — він однаковий для всіх встановлень Android Studio.

Безпека Keystore при передачі: файл .p12 або .jks має передаватися лише через зашифровані канали (SFTP, HTTPS, зашифровані email-вкладення). Ніколи не включайте Keystore в репозиторій вихідного коду — навіть в приватний. GitGuardian або GitHub secret scanning автоматично детектять публікацію облікових даних, але зберігання Keystore в репозиторії все одно є порушенням безпеки. Для CI/CD використовуйте механізм секретів платформи (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) з шифруванням на рівні інфраструктури.