apksigner

ابزار apksigner که در نسخه 24.0.3 و بالاتر از ابزارهای ساخت SDK اندروید موجود است، به شما امکان می‌دهد فایل‌های APK را امضا کنید و تأیید کنید که امضای یک APK با موفقیت در تمام نسخه‌های پلتفرم اندروید پشتیبانی شده توسط آن APK تأیید می‌شود.

این صفحه یک راهنمای کوتاه برای استفاده از این ابزار ارائه می‌دهد و به عنوان مرجعی برای گزینه‌های مختلف خط فرمان که این ابزار پشتیبانی می‌کند، عمل می‌کند. برای توضیحات کامل‌تر در مورد نحوه استفاده از ابزار apksigner برای امضای APKهای شما، به بخش «امضای برنامه» مراجعه کنید.

احتیاط: اگر فایل APK خود را با استفاده apksigner امضا کنید و تغییرات بیشتری در APK ایجاد کنید، امضای APK نامعتبر می‌شود. اگر zipalign برای تراز کردن APK خود استفاده می‌کنید، قبل از امضای APK از آن استفاده کنید.

کاربرد

APK را امضا کنید

نحو امضای APK با استفاده از ابزار apksigner به شرح زیر است:

apksigner sign --ks keystore.jks |
  --key key.pk8 --cert cert.x509.pem
  [signer_options] app-name.apk

وقتی با استفاده از ابزار apksigner یک APK را امضا می‌کنید، باید کلید خصوصی و گواهی امضاکننده را ارائه دهید. می‌توانید این اطلاعات را به دو روش وارد کنید:

• با استفاده از گزینه --ks یک فایل KeyStore مشخص کنید.
• فایل کلید خصوصی و فایل گواهی را به ترتیب با استفاده از گزینه‌های --key و --cert به طور جداگانه مشخص کنید. فایل کلید خصوصی باید از فرمت PKCS #8 و فایل گواهی باید از فرمت X.509 استفاده کند.

معمولاً، شما یک APK را فقط با استفاده از یک امضاکننده امضا می‌کنید. اگر نیاز دارید که یک APK را با استفاده از چندین امضاکننده امضا کنید، از گزینه --next-signer برای جدا کردن مجموعه گزینه‌های عمومی که برای هر امضاکننده اعمال می‌شود، استفاده کنید:

apksigner sign [signer_1_options] --next-signer [signer_2_options] app-name.apk

امضای یک APK را تأیید کنید

نحو تأیید تأیید موفقیت‌آمیز امضای APK در پلتفرم‌های پشتیبانی‌شده به شرح زیر است:

apksigner verify [options] app-name.apk

چرخاندن کلیدهای امضا

نحو چرخش دودمان گواهی امضا یا یک توالی جدید از امضاها به شرح زیر است:

$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file \
  --old-signer --ks old-signer-jks \
  --new-signer --ks new-signer-jks

گزینه‌ها

لیست‌های زیر شامل مجموعه‌ای از گزینه‌ها برای هر دستوری است که ابزار apksigner از آن پشتیبانی می‌کند.

دستور امضا

دستور apksigner sign گزینه‌های زیر را دارد.

گزینه‌های عمومی

گزینه‌های زیر تنظیمات اولیه‌ای را که باید برای امضاکننده اعمال شود، مشخص می‌کنند:

--out <apk-filename>

مکانی که می‌خواهید APK امضا شده در آن ذخیره شود. اگر این گزینه به صراحت ارائه نشده باشد، بسته APK در محل امضا می‌شود که فایل APK ورودی را رونویسی می‌کند.

--min-sdk-version <integer>

پایین‌ترین سطح API چارچوب اندروید که apksigner برای تأیید تأیید امضای APK از آن استفاده می‌کند. مقادیر بالاتر به ابزار اجازه می‌دهد هنگام امضای برنامه از پارامترهای امنیتی قوی‌تری استفاده کند، اما دسترسی به APK را برای دستگاه‌هایی که نسخه‌های جدیدتر اندروید را اجرا می‌کنند محدود می‌کند. به طور پیش‌فرض، apksigner از مقدار ویژگی minSdkVersion از فایل مانیفست برنامه استفاده می‌کند.

--max-sdk-version <integer>

بالاترین سطح API چارچوب اندروید که apksigner برای تأیید تأیید امضای APK از آن استفاده می‌کند. به طور پیش‌فرض، این ابزار از بالاترین سطح API ممکن استفاده می‌کند.

--rotation-min-sdk-version <integer>

پایین‌ترین سطح API که کلید امضای چرخشی APK باید برای تولید امضای APK از آن استفاده کند. کلید امضای اصلی (چرخش نیافته) برای APK برای همه نسخه‌های قبلی پلتفرم استفاده خواهد شد. به طور پیش‌فرض، کلیدهای امضای چرخشی، که در دستگاه‌هایی که اندروید ۱۳ (سطح API ۳۳) یا بالاتر را اجرا می‌کنند پشتیبانی می‌شوند، با بلوک امضای v3.1 استفاده می‌شوند.

توجه: اگر برنامه شما توسط یک کلید امضای چرخشی در دستگاهی که اندروید ۱۲L (سطح API 32) یا پایین‌تر را اجرا می‌کند، امضا شده است، باید از --rotation-min-sdk-version 28 برای ادامه امضای برنامه خود با کلید امضای چرخشی برای اندروید ۹ (سطح API 28) استفاده کنید.

--v1-signing-enabled <true | false>

تعیین می‌کند که آیا apksigner بسته APK داده شده را با استفاده از طرح امضای سنتی مبتنی بر JAR امضا می‌کند یا خیر. به طور پیش‌فرض، این ابزار از مقادیر --min-sdk-version و --max-sdk-version برای تصمیم‌گیری در مورد زمان اعمال این طرح امضا استفاده می‌کند.

--v2-signing-enabled <true | false>

تعیین می‌کند که آیا apksigner بسته APK داده شده را با استفاده از طرح امضای APK نسخه ۲ امضا می‌کند یا خیر. به طور پیش‌فرض، این ابزار از مقادیر --min-sdk-version و --max-sdk-version برای تصمیم‌گیری در مورد زمان اعمال این طرح امضا استفاده می‌کند.

--v3-signing-enabled <true | false>

تعیین می‌کند که آیا apksigner بسته APK داده شده را با استفاده از طرح امضای APK نسخه ۳ امضا می‌کند یا خیر. به طور پیش‌فرض، این ابزار از مقادیر --min-sdk-version و --max-sdk-version برای تصمیم‌گیری در مورد زمان اعمال این طرح امضا استفاده می‌کند.

--v4-signing-enabled <true | false | only>

تعیین می‌کند که آیا apksigner بسته APK داده شده را با استفاده از طرح امضای APK نسخه ۴ امضا می‌کند یا خیر. این طرح یک امضا در یک فایل جداگانه ( apk-name .apk.idsig ) تولید می‌کند. اگر true و APK امضا نشده باشد، یک امضای نسخه ۲ یا ۳ بر اساس مقادیر --min-sdk-version و --max-sdk-version ایجاد می‌شود. سپس این دستور فایل .idsig را بر اساس محتوای APK امضا شده تولید می‌کند.

only برای تولید امضای نسخه ۴ بدون تغییر APK و هرگونه امضایی که قبل از فراخوانی داشته است، استفاده می‌شود. only در صورتی ناموفق است که APK از قبل امضای نسخه ۲ یا ۳ نداشته باشد یا اگر امضا از کلید متفاوتی نسبت به کلید ارائه شده برای فراخوانی فعلی استفاده کرده باشد.

به طور پیش‌فرض، این ابزار از مقادیر --min-sdk-version و --max-sdk-version برای تصمیم‌گیری در مورد زمان اعمال این طرح امضا استفاده می‌کند.

-v , --verbose

از حالت خروجی verbose استفاده کنید.

گزینه‌های مربوط به هر امضاکننده

گزینه‌های زیر پیکربندی یک امضاکننده‌ی خاص را مشخص می‌کنند. اگر برنامه‌ی خود را فقط با استفاده از یک امضاکننده امضا می‌کنید، این گزینه‌ها ضروری نیستند.

--next-signer <signer-options>

برای تعیین گزینه‌های عمومی مختلف برای هر امضاکننده استفاده می‌شود.

--v1-signer-name <basename>

نام پایه برای فایل‌هایی که امضای مبتنی بر JAR را برای امضاکننده فعلی تشکیل می‌دهند. به طور پیش‌فرض، apksigner از نام مستعار کلید KeyStore یا نام پایه فایل کلید برای این امضاکننده استفاده می‌کند.

گزینه‌های کلید و گواهی

گزینه‌های زیر کلید خصوصی و گواهی امضاکننده را مشخص می‌کنند:

--ks <filename>

کلید خصوصی و زنجیره گواهی امضاکننده در فایل KeyStore مبتنی بر جاوا قرار دارد. اگر نام فایل روی "NONE" تنظیم شده باشد، KeyStore حاوی کلید و گواهی نیازی به مشخص کردن فایل ندارد، که این مورد برای برخی از KeyStoreهای PKCS #11 صدق می‌کند.

--ks-key-alias <alias>

نام مستعاری که نشان‌دهنده‌ی کلید خصوصی و داده‌های گواهی امضاکننده در KeyStore است. اگر KeyStore مرتبط با امضاکننده شامل چندین کلید باشد، باید این گزینه را مشخص کنید.

--ks-pass <input-format>

رمز عبور KeyStore که حاوی کلید خصوصی و گواهی امضاکننده است. برای باز کردن KeyStore باید رمز عبور ارائه دهید. ابزار apksigner از فرمت‌های زیر پشتیبانی می‌کند:

• pass:<password> – رمز عبوری که به صورت درون‌خطی با بقیه دستور apksigner sign ارائه می‌شود.
• env:<name> – رمز عبور در متغیر محیطی داده شده ذخیره می‌شود.
• file:<filename> – رمز عبور به صورت یک خط در فایل داده شده ذخیره می‌شود.
• stdin - رمز عبور به صورت یک خط در جریان ورودی استاندارد ارائه می‌شود. این رفتار پیش‌فرض برای --ks-pass است.

توجه: اگر چندین رمز عبور را در یک فایل قرار می‌دهید، آنها را در خطوط جداگانه مشخص کنید. ابزار apksigner رمزهای عبور را بر اساس ترتیبی که شما امضاکنندگان را مشخص می‌کنید، با امضاکنندگان APK مرتبط می‌کند. اگر برای یک امضاکننده دو رمز عبور ارائه داده باشید، apksigner رمز عبور اول را به عنوان رمز عبور KeyStore و رمز عبور دوم را به عنوان رمز عبور کلید تفسیر می‌کند.

--pass-encoding <charset>

هنگام تلاش برای مدیریت رمزهای عبور حاوی کاراکترهای غیر ASCII، کدگذاری‌های کاراکتر مشخص شده، مانند ibm437 یا utf-8 را شامل می‌شود.

Keytool اغلب با تبدیل رمز عبور با استفاده از مجموعه کاراکتر پیش‌فرض کنسول، keystoreها را رمزگذاری می‌کند. به طور پیش‌فرض، apksigner سعی می‌کند با استفاده از چندین شکل رمز عبور رمزگشایی کند:

فرم یونیکد

فرم با استفاده از مجموعه کاراکتر پیش‌فرض JVM کدگذاری شده است

در جاوا ۸ و بالاتر، فرم با استفاده از مجموعه کاراکتر پیش‌فرض کنسول کدگذاری می‌شود.

در جاوا ۹، apksigner نمی‌تواند مجموعه کاراکتر کنسول را تشخیص دهد. ممکن است لازم باشد هنگام استفاده از رمز عبور غیر ASCII، --pass-encoding را مشخص کنید. همچنین ممکن است لازم باشد این گزینه را با KeyStores که ابزار keytool در یک سیستم عامل یا زبان دیگر ایجاد کرده است، مشخص کنید.

--key-pass <input-format>

رمز عبور کلید خصوصی امضاکننده، که در صورت محافظت از کلید خصوصی با رمز عبور، مورد نیاز است. ابزار apksigner از قالب‌های زیر پشتیبانی می‌کند:

• pass:<password> – رمز عبور به صورت درون خطی با بقیه دستور apksigner sign ارائه می‌شود.
• env:<name> – رمز عبور در متغیر محیطی داده شده ذخیره می‌شود.
• file:<filename> – رمز عبور به صورت یک خط در فایل داده شده ذخیره می‌شود.
• stdin - رمز عبور به صورت یک خط در جریان ورودی استاندارد ارائه می‌شود. این رفتار پیش‌فرض برای --key-pass است.

--ks-type <algorithm>

نوع یا الگوریتم مرتبط با KeyStore که شامل کلید خصوصی و گواهی امضاکننده است. به طور پیش‌فرض، apksigner از نوعی که به عنوان ثابت keystore.type در فایل ویژگی‌های امنیتی تعریف شده است، استفاده می‌کند.

--ks-provider-name <name>

نام ارائه‌دهنده JCA که هنگام درخواست پیاده‌سازی KeyStore امضاکننده از آن استفاده می‌شود. به طور پیش‌فرض، apksigner از ارائه‌دهنده با بالاترین اولویت استفاده می‌کند.

--ks-provider-class <class-name>

نام کلاس کاملاً واجد شرایط ارائه‌دهنده JCA که هنگام درخواست پیاده‌سازی KeyStore امضاکننده از آن استفاده می‌شود. این گزینه به عنوان جایگزینی برای --ks-provider-name عمل می‌کند. به طور پیش‌فرض، apksigner از ارائه‌دهنده‌ای که با گزینه --ks-provider-name مشخص شده است، استفاده می‌کند.

--ks-provider-arg <value>

یک مقدار رشته‌ای که به عنوان آرگومان برای سازنده‌ی کلاس JCA Provider ارسال می‌شود؛ خود کلاس با گزینه‌ی --ks-provider-class تعریف شده است. به طور پیش‌فرض، apksigner از سازنده‌ی بدون آرگومان کلاس استفاده می‌کند.

--key <filename>

نام فایلی که حاوی کلید خصوصی امضاکننده است. این فایل باید از فرمت DER با پسوند PKCS #8 استفاده کند. اگر کلید با رمز عبور محافظت شده باشد، apksigner با استفاده از ورودی استاندارد، رمز عبور را درخواست می‌کند، مگر اینکه نوع دیگری از فرمت ورودی را با استفاده از گزینه --key-pass مشخص کنید.

--cert <filename>

نام فایلی که حاوی زنجیره گواهی امضاکننده است. این فایل باید از فرمت X.509 PEM یا DER استفاده کند.

دستور را تأیید کنید

دستور تأیید apksigner گزینه‌های زیر را دارد.

--print-certs

اطلاعات مربوط به گواهی‌های امضای APK را نمایش دهید.

--print-certs-pem

اطلاعات مربوط به گواهی‌های امضای APK را نمایش داده و کدگذاری PEM هر گواهی امضا را در خروجی استاندارد چاپ می‌کند.

--min-sdk-version <integer>

پایین‌ترین سطح API چارچوب اندروید که apksigner برای تأیید تأیید امضای APK از آن استفاده می‌کند. مقادیر بالاتر به ابزار اجازه می‌دهد هنگام امضای برنامه از پارامترهای امنیتی قوی‌تری استفاده کند، اما دسترسی به APK را برای دستگاه‌هایی که نسخه‌های جدیدتر اندروید را اجرا می‌کنند محدود می‌کند. به طور پیش‌فرض، apksigner از مقدار ویژگی minSdkVersion از فایل مانیفست برنامه استفاده می‌کند.

--max-sdk-version <integer>

بالاترین سطح API چارچوب اندروید که apksigner برای تأیید تأیید امضای APK از آن استفاده می‌کند. به طور پیش‌فرض، این ابزار از بالاترین سطح API ممکن استفاده می‌کند.

-v , --verbose

از حالت خروجی verbose استفاده کنید.

-Werr

هشدارها را به عنوان خطا در نظر بگیرید.

مثال‌ها

در ادامه مثال‌هایی با استفاده از apksigner آمده است.

APK را امضا کنید

یک APK را با استفاده از release.jks امضا کنید، که تنها کلید موجود در KeyStore است:

$ apksigner sign --ks release.jks app.apk

امضای یک APK با استفاده از کلید خصوصی و گواهی ذخیره شده به صورت فایل‌های جداگانه:

$ apksigner sign --key release.pk8 --cert release.x509.pem app.apk

امضای APK با استفاده از دو کلید:

$ apksigner sign --ks first-release-key.jks --next-signer --ks second-release-key.jks app.apk

امضای یک APK با کلید امضای چرخشی و SDK با هدف چرخشی نسخه ۲۸+:

$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk \
  --rotation-min-sdk-version 28

امضای یک APK با کلید امضای چرخشی و SDK با هدف چرخشی نسخه ۳۳+:

$ apksigner sign --ks release.jks --next-signer --ks release2.jks \
  --lineage /path/to/signing/history/lineage app.apk

امضای یک APK را تأیید کنید

بررسی کنید که آیا انتظار می‌رود امضاهای APK در تمام پلتفرم‌های اندرویدی که APK از آنها پشتیبانی می‌کند، معتبر باشند یا خیر:

$ apksigner verify app.apk

بررسی کنید که آیا انتظار می‌رود امضاهای APK در اندروید ۴.۰.۳ (سطح API ۱۵) و بالاتر معتبر باشند یا خیر:

$ apksigner verify --min-sdk-version 15 app.apk

چرخاندن کلیدهای امضا

فعال کردن یک دودمان گواهی امضا که از چرخش کلید پشتیبانی می‌کند:

$ apksigner rotate --out /path/to/new/file --old-signer \
    --ks release.jks --new-signer --ks release2.jks

کلیدهای امضای خود را دوباره بچرخانید:

$ apksigner rotate --in /path/to/existing/lineage \
  --out /path/to/new/file --old-signer --ks release2.jks \
  --new-signer --ks release3.jks