apksigner

ابزار apksigner که در نسخه 24.0.3 و بالاتر از ابزارهای ساخت SDK Android موجود است، به شما امکان می‌دهد فایل‌های APK را امضا کرده و تأیید کنید که امضای یک APK با موفقیت در همه نسخه‌های پلتفرم Android که توسط آن 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

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

• با استفاده از گزینه --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 چارچوب Android که apksigner برای تأیید تأیید شدن امضای APK استفاده می‌کند. مقادیر بالاتر به ابزار اجازه می‌دهد هنگام امضای برنامه از پارامترهای امنیتی قوی‌تری استفاده کند، اما در دسترس بودن APK را برای دستگاه‌هایی که نسخه‌های جدیدتر Android را اجرا می‌کنند محدود می‌کند. به طور پیش فرض، apksigner از مقدار ویژگی minSdkVersion از فایل مانیفست برنامه استفاده می کند.

--max-sdk-version <integer>

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

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

پایین‌ترین سطح API که کلید امضای چرخشی APK باید برای تولید امضای APK استفاده کند. کلید امضای اصلی (چرخش نشده) برای APK برای همه نسخه‌های پلتفرم قبلی استفاده خواهد شد. به‌طور پیش‌فرض، کلیدهای امضای چرخان که در دستگاه‌های دارای Android 13 (سطح API 33) یا بالاتر پشتیبانی می‌شوند، با بلوک امضای نسخه 3.1 استفاده می‌شوند.

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

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

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

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

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

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

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

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

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

only برای تولید امضای v4 بدون تغییر APK و هر گونه امضایی که قبل از فراخوانی داشت استفاده کنید. only در صورتی خراب می شود که APK از قبل دارای امضای v2 یا v3 نباشد یا اگر امضا از کلیدی متفاوت از کلید ارائه شده برای فراخوانی فعلی استفاده کرده باشد.

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

-v ، --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>

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

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

فرم یونیکد

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

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

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

--key-pass <input-format>

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

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

--ks-type <algorithm>

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

--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>

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

--cert <filename>

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

تأیید فرمان

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

--print-certs

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

--min-sdk-version <integer>

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

--max-sdk-version <integer>

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

-v ، --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 با هدف چرخش نسخه 28+ امضا کنید:

$ 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 با هدف چرخش نسخه 33+ امضا کنید:

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

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

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

$ apksigner verify app.apk

بررسی کنید که آیا انتظار می‌رود امضاهای APK در Android نسخه 4.0.3 (سطح API 15) و بالاتر معتبر باشند یا خیر:

$ 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