Keystore: същност, какви формати има и как работи

Какво е Keystore

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

Keystore може да съдържа няколко записа (alias), всеки от които представлява чифт ключове (частен и публичен) със сертификат. Alias — уникалното име на записа, под което приложението има достъп до ключа при подписване. В типичен Android проект Keystore съдържа един запис за подписване на версията за пускане и може да съдържа допълнителни за подписване на debug компилации. 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 приложение включва създаване на резюме (хeш) на съдържанието на APK и неговото криптиране с частния ключ от Keystore. Android SDK Build Tools включват инструмента apksigner, който извършва подписване във формат APK Signature Scheme v2 (или v3 за Android 9+). При инсталиране на приложението Android проверява подписа: декриптира подписа с публичния ключ на сертификата, сравнява хeша на APK с оригинала — ако хeшовете не съвпадат, инсталирането се отхвърля.

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 трябва да се уверите, че всички alias и пароли са правилно прехвърлени. Командата 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, криптирани имейл прикачени файлове). Никога не включвайте Keystore в хранилището на изходния код — дори частно. GitGuardian или GitHub secret scanning автоматично откриват публикуване на идентификационни данни, но съхраняването на Keystore в хранилището все пак представлява нарушение на сигурността. За CI/CD използвайте механизма за тайни на платформата (GitHub Actions Secrets, GitLab CI Variables, Jenkins Credentials) с криптиране на ниво инфраструктура.