Keystore: ماهیت، چه فرمت‌هایی دارد و چگونه کار می‌کند

Keystore چیست

Keystore (KeyStore) — یک مکانیزم استاندارد Java Cryptography Architecture (JCA) برای ذخیره کلیدهای رمزنگاری، گواهی‌ها و ورودی‌های معتمد است. در توسعه Android، Keystore برای ذخیره کلید خصوصی که برنامه قبل از انتشار با آن امضا می‌شود استفاده می‌گردد. امضا تضمین می‌کند که برنامه واقعاً توسط توسعه‌دهنده مشخص شده منتشر شده و کد آن پس از انتشار تغییر نکرده است. هر به‌روزرسانی برنامه باید با همان کلید امضا شود، در غیر این صورت Google Play فایل APK یا App Bundle را رد می‌کند.

Keystore می‌تواند چندین ورودی (alias) داشته باشد که هر کدام یک جفت کلید (خصوصی و عمومی) به همراه گواهی را نشان می‌دهد. 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 باید اطمینان حاصل کنید که همه 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 است. هنگام استفاده از این گزینه، توسعه‌دهنده فقط کلید بارگذاری (upload key) را به Google Play ارسال می‌کند و 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) با رمزنگاری در سطح زیرساخت استفاده کنید.