نام (NAME)

jarsigner - امضا و اعتبارسنجی فایل‌های بایگانی جاوا (JAR)

خلاصه دستور (SYNOPSIS)

jarsigner [options] jar-file alias

jarsigner -verify [options] jar-file [alias ...]

jarsigner -version

options: گزینه‌های خط فرمان. بخش Options for jarsigner را ببینید.
-verify: گزینهٔ -verify می‌تواند صفر یا چند نام مستعار (alias) در keystore را پس از نام فایل JAR بپذیرد. هنگامی که گزینهٔ -verify مشخص شود، دستور jarsigner بررسی می‌کند که گواهی استفاده‌شده برای اعتبارسنجی هر مدخل امضاشده در فایل JAR با یکی از نام‌های مستعار keystore مطابقت داشته باشد. این نام‌های مستعار در keystore مشخص‌شده توسط -keystore یا keystore پیش‌فرض تعریف شده‌اند.

اگر گزینهٔ -strict را نیز مشخص کنید و دستور jarsigner هشدارهای شدیدی را شناسایی کند، پیام "jar verified, with signer errors" نمایش داده می‌شود.

jar-file: فایل JAR که قرار است امضا شود.

اگر گزینهٔ -strict را نیز مشخص کرده باشید و دستور jarsigner هشدارهای شدیدی را شناسایی کند، پیام "jar signed, with signer errors" نمایش داده می‌شود.

alias: نام‌های مستعاری که در keystore مشخص‌شده توسط -keystore یا keystore پیش‌فرض تعریف شده‌اند.
-version: گزینهٔ -version نسخهٔ برنامهٔ jarsigner را چاپ می‌کند.

توضیحات (DESCRIPTION)

ابزار jarsigner دو هدف دارد:

امضا کردن فایل‌های بایگانی جاوا (JAR).
اعتبارسنجی امضاها و یکپارچگی فایل‌های امضاشدهٔ JAR.

قابلیت JAR امکان بسته‌بندی فایل‌های کلاس، تصاویر، صداها و سایر داده‌های دیجیتال را در یک فایل واحد برای توزیع سریع‌تر و آسان‌تر فراهم می‌کند. ابزاری به نام jar به توسعه‌دهندگان امکان تولید فایل‌های JAR را می‌دهد. (از نظر فنی، هر فایل ZIP را نیز می‌توان یک فایل JAR در نظر گرفت، هرچند هنگام ایجاد توسط دستور jar یا پردازش توسط دستور jarsigner، فایل‌های JAR حاوی یک فایل META-INF/MANIFEST.MF نیز هستند.)

امضای دیجیتال رشته‌ای از بیت‌هاست که از روی داده‌ها (داده‌هایی که امضا می‌شوند) و کلید خصوصی یک نهاد (شخص، شرکت و غیره) محاسبه می‌شود. مشابه یک امضای دست‌نویس، امضای دیجیتال ویژگی‌های سودمند بسیاری دارد:

اصالت آن را می‌توان با محاسباتی که از کلید عمومی متناظر با کلید خصوصیِ استفاده‌شده برای تولید امضا بهره می‌برد، اعتبارسنجی کرد.
با فرض محرمانه ماندن کلید خصوصی، جعل آن غیرممکن است.
تابعی از داده‌های امضاشده است و بنابراین نمی‌توان ادعا کرد که امضای داده‌های دیگر نیز هست.
داده‌های امضاشده قابل تغییر نیستند. اگر داده‌ها تغییر کنند، اصالت امضا دیگر قابل اعتبارسنجی نخواهد بود.

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

دستور jarsigner از اطلاعات کلید و گواهی موجود در یک keystore برای تولید امضاهای دیجیتال فایل‌های JAR استفاده می‌کند. یک keystore پایگاه‌داده‌ای از کلیدهای خصوصی و زنجیره‌های گواهی X.509 مرتبط با آن‌هاست که کلیدهای عمومی متناظر را تأیید می‌کنند. دستور keytool برای ایجاد و مدیریت keystoreها استفاده می‌شود.

دستور jarsigner از کلید خصوصی یک نهاد برای تولید امضا استفاده می‌کند. فایل JAR امضاشده، علاوه بر موارد دیگر، شامل رونوشتی از گواهی keystore برای کلید عمومی متناظر با کلید خصوصیِ استفاده‌شده برای امضای فایل است. دستور jarsigner می‌تواند امضای دیجیتال فایل JAR امضاشده را با استفاده از گواهی درون آن (در فایل بلوک امضای آن) اعتبارسنجی کند.

دستور jarsigner می‌تواند امضاهایی شامل برچسب زمانی (timestamp) تولید کند که به سیستم‌ها یا مستقرکنندگان امکان می‌دهد بررسی کنند آیا فایل JAR زمانی امضا شده است که گواهی امضا هنوز معتبر بوده یا خیر.

علاوه بر این، رابط‌های برنامه‌نویسی کاربردی (APIها) به برنامه‌ها امکان می‌دهند تا اطلاعات برچسب زمانی را به دست آورند.

در حال حاضر، دستور jarsigner تنها می‌تواند فایل‌های JAR ایجادشده توسط دستور jar یا فایل‌های zip را امضا کند. فایل‌های JAR مشابه فایل‌های zip هستند، با این تفاوت که دارای یک فایل META-INF/MANIFEST.MF نیز می‌باشند. هنگامی که دستور jarsigner یک فایل zip را امضا می‌کند، یک فایل META-INF/MANIFEST.MF ایجاد می‌شود.

رفتار پیش‌فرض دستور jarsigner امضای یک فایل JAR یا zip است. برای اعتبارسنجی یک فایل JAR امضاشده از گزینهٔ -verify استفاده کنید.

دستور jarsigner همچنین پس از امضا یا اعتبارسنجی تلاش می‌کند گواهی امضاکننده را تأیید اعتبار کند. در طول اعتبارسنجی، چنانچه گزینهٔ -revCheck مشخص شده باشد، وضعیت ابطال هر گواهی در زنجیرهٔ گواهی‌های امضاکننده بررسی می‌شود. اگر خطای اعتبارسنجی یا هر مشکل دیگری رخ دهد، این دستور پیام‌های هشدار تولید می‌کند. اگر گزینهٔ -strict را مشخص کنید، دستور هشدارهای شدید را به عنوان خطا در نظر می‌گیرد. بخش Errors and Warnings را ببینید..SH "نام‌های مستعار مخزن کلید (KEYSTORE ALIASES)" تمامی موجودیت‌های مخزن کلید (keystore) با نام‌های مستعار (alias) یکتا در دسترس قرار می‌گیرند.

هنگامی که از دستور jarsigner برای امضای یک فایل JAR استفاده می‌کنید، باید نام مستعار مدخلی از keystore را مشخص کنید که حاوی کلید خصوصی مورد نیاز برای تولید امضا است. اگر هیچ فایل خروجی مشخص نشود، فایل JAR اصلی با فایل JAR امضاشده بازنویسی می‌شود.

مخازن کلید با گذرواژه محافظت می‌شوند، بنابراین گذرواژه مخزن (store password) باید مشخص شود. در صورتی که آن را در خط فرمان مشخص نکنید، از شما خواسته می‌شود آن را وارد کنید. به طور مشابه، کلیدهای خصوصی در یک keystore با یک گذرواژه محافظت می‌شوند، بنابراین گذرواژه کلید خصوصی باید مشخص گردد، و چنانچه آن را در خط فرمان مشخص نکرده باشید و با گذرواژه مخزن یکسان نباشد، از شما برای وارد کردن گذرواژه درخواست خواهد شد.

مکان مخزن کلید (KEYSTORE LOCATION)

دستور jarsigner دارای گزینه -keystore برای مشخص کردن URL مخزن کلید مورد استفاده است. به‌طور پیش‌فرض، keystore در فایلی به نام .keystore در دایرکتوری خانگی کاربر، همان‌طور که توسط ویژگی سیستمی user.home تعیین می‌شود، ذخیره می‌گردد.

لینوکس و macOS: مقدار پیش‌فرض user.home، دایرکتوری خانگی کاربر است.

جریان ورودی حاصل از گزینه -keystore به متد KeyStore.load ارسال می‌شود. اگر NONE به عنوان URL مشخص شود، یک جریان تهی (null stream) به متد KeyStore.load منتقل می‌گردد. زمانی که کلاس KeyStore مبتنی بر فایل نیست، به عنوان مثال هنگامی که روی یک دستگاه توکن سخت‌افزاری قرار دارد، باید مقدار NONE مشخص شود.

پیاده‌سازی مخزن کلید (KEYSTORE IMPLEMENTATION)

کلاس KeyStore ارائه‌شده در بسته java.security چندین رابط خوش‌تعریف را برای دسترسی و تغییر اطلاعات درون یک keystore فراهم می‌کند. می‌توانید چندین پیاده‌سازی واقعی (concrete) متفاوت داشته باشید که در آن هر پیاده‌سازی برای نوع خاصی از keystore است.

در حال حاضر، دو ابزار خط فرمانی وجود دارند که از پیاده‌سازی‌های keystore استفاده می‌کنند (keytool و jarsigner).

پیاده‌سازی پیش‌فرض keystore مقدار PKCS12 است. این یک keystore چندسکویی بر پایه استاندارد RSA PKCS12 Personal Information Exchange Syntax است. این استاندارد در درجه اول برای ذخیره‌سازی یا انتقال کلیدهای خصوصی، گواهی‌ها و اسرار متفرقه کاربر در نظر گرفته شده است. پیاده‌سازی توکار دیگری نیز وجود دارد که توسط Oracle ارائه شده است. این پیاده‌سازی، keystore را به عنوان فایلی با یک نوع (قالب) اختصاصی به نام JKS پیاده‌سازی می‌کند. این قالب از هر کلید خصوصی با گذرواژه اختصاصی خودش محافظت کرده، و همچنین یکپارچگی کل keystore را با یک گذرواژه (احتمالاً متفاوت) تأمین می‌نماید.

پیاده‌سازی‌های keystore مبتنی بر ارائه‌دهنده (provider-based) هستند، به این معنی که رابط‌های کاربردی ارائه‌شده توسط کلاس KeyStore در قالب یک Service Provider Interface (SPI) پیاده‌سازی می‌شوند. یک کلاس انتزاعی متناظر به نام KeystoreSpi نیز در java.security package وجود دارد که متدهای Service Provider Interface را که ارائه‌دهندگان باید پیاده‌سازی کنند، تعریف می‌کند. اصطلاح ارائه‌دهنده (provider) به یک بسته یا مجموعه‌ای از بسته‌ها اشاره دارد که پیاده‌سازی واقعی زیرمجموعه‌ای از سرویس‌های قابل دسترس از طریق Java Security API را فراهم می‌کنند. برای ارائه یک پیاده‌سازی keystore، کلاینت‌ها باید یک provider را پیاده‌سازی کرده و پیاده‌سازی زیرکلاسی از KeystoreSpi را ارائه دهند، همان‌طور که در How to Implement a Provider in the Java Cryptography Architecture [https://www.oracle.com/pls/topic/lookup?ctx=en/java/javase&id=security_guide_implement_provider_jca] شرح داده شده است.

برنامه‌ها می‌توانند انواع مختلفی از پیاده‌سازی‌های keystore را از ارائه‌دهندگان مختلف، با استفاده از متد کارخانه‌ای getInstance در کلاس KeyStore انتخاب کنند. نوع keystore، ساختار ذخیره‌سازی و قالب داده‌های اطلاعات keystore و الگوریتم‌های مورد استفاده برای محافظت از کلیدهای خصوصی موجود در keystore و یکپارچگی خود keystore را مشخص می‌کند. پیاده‌سازی‌های انواع مختلف keystore با یکدیگر سازگار نیستند.

دستورهای jarsigner می‌توانند keystoreهای مبتنی بر فایل را از هر مکانی که با استفاده از یک URL قابل تعیین باشد، بخوانند. علاوه بر این، این دستورها می‌توانند مخازن کلید غیرمبتنی بر فایل مانند موارد ارائه‌شده توسط MSCAPI در Windows و PKCS11 در تمامی پلتفرم‌ها را بخوانند.

برای دستورهای jarsigner و keytool، می‌توانید با استفاده از گزینه -storetype نوع keystore را در خط فرمان مشخص کنید.

اگر نوع keystore را به‌صراحت مشخص نکنید، ابزارها پیاده‌سازی keystore را بر اساس مقدار ویژگی keystore.type مشخص‌شده در فایل ویژگی‌های امنیتی انتخاب می‌کنند. فایل ویژگی‌های امنیتی java.security نام دارد و در دایرکتوری ویژگی‌های امنیتی JDK یعنی java.home/conf/security قرار دارد.

هر ابزار مقدار keystore.type را دریافت کرده و سپس تمامی ارائه‌دهندگان نصب‌شده را بررسی می‌کند تا ارائه‌دهنده‌ای را بیابد که keystoreهایی از آن نوع را پیاده‌سازی می‌کند. سپس از پیاده‌سازی keystore مربوط به آن ارائه‌دهنده استفاده می‌نماید.

کلاس KeyStore یک متد ایستا به نام getDefaultType تعریف می‌کند که به برنامه‌ها امکان بازیابی مقدار ویژگی keystore.type را می‌دهد. خط کد زیر، یک نمونه از نوع پیش‌فرض keystore را بر اساس آنچه در ویژگی keystore.type مشخص شده، ایجاد می‌کند:

KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());

نوع پیش‌فرض keystore مقدار pkcs12 است، که یک مخزن کلید چندسکویی بر پایه استاندارد RSA PKCS12 Personal Information Exchange Syntax می‌باشد. این موضوع با خط زیر در فایل ویژگی‌های امنیتی مشخص شده است:

keystore.type=pkcs12

بزرگی و کوچکی حروف در نام‌گذاری نوع keystore اهمیتی ندارد. به عنوان مثال، JKS با jks یکسان است.

برای اینکه ابزارها از پیاده‌سازی دیگری از keystore به غیر از حالت پیش‌فرض استفاده کنند، می‌توانید آن خط را تغییر داده تا نوع دیگری از keystore مشخص شود. به عنوان مثال، اگر می‌خواهید از پیاده‌سازی keystore نوع jks متعلق به Oracle استفاده کنید، آن خط را به صورت زیر تغییر دهید:

keystore.type=jks به‌طور پیش‌فرض، دستور jarsigner یک فایل JAR را بسته به نوع و اندازه کلید خصوصی، با استفاده از یکی از الگوریتم‌ها و پسوندهای فایل بلوک زیر امضا می‌کند:

الگوریتم‌های امضای پیش‌فرض و پسوندهای فایل بلوک

keyalg	اندازه کلید	sigalg پیش‌فرض	پسوند فایل بلوک
DSA	هر اندازه‌ای	SHA256withDSA	.DSA
RSA	< 624	SHA256withRSA	.RSA
	<= 7680	SHA384withRSA
	> 7680	SHA512withRSA
EC	< 512	SHA384withECDSA	.EC
	>= 512	SHA512withECDSA
RSASSA-PSS[1]	< 624	RSASSA-PSS (با SHA-256)	.RSA
	<= 7680	RSASSA-PSS (با SHA-384)
	> 7680	RSASSA-PSS (با SHA-512)
EdDSA[2]		EdDSA	.EC
ML-DSA[2]		ML-DSA	.DSA

1.: اگر یک کلید RSASSA-PSS همراه با پارامترها کدگذاری شده باشد، jarsigner از همان پارامترها در امضا استفاده خواهد کرد. در غیر این صورت، jarsigner از پارامترهایی استفاده می‌کند که با توجه به اندازه کلید طبق جدول بالا تعیین می‌شوند. برای نمونه، یک کلید 3072 بیتی RSASSA-PSS از RSASSA-PSS به عنوان الگوریتم امضا و از SHA-384 به عنوان الگوریتم‌های هش و MGF1 استفاده خواهد کرد.
2.: الگوریتم‌های امضای دیجیتال مدرن مانند EdDSA و ML-DSA از نام یکسانی هم برای الگوریتم کلید و هم برای الگوریتم امضا استفاده می‌کنند. تنها الگوریتم امضایی با همان نام می‌تواند با یک الگوریتم کلید مفروض به کار گرفته شود. مجموعه پارامترهای مشخص امضا (برای نمونه، Ed25519 یا Ed448 برای EdDSA) همانند پارامترهای کلید است.

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

این الگوریتم‌های امضای پیش‌فرض را می‌توان با استفاده از گزینهٔ -sigalg بازنویسی کرد.

دستور jarsigner از ویژگی‌های امنیتی jdk.jar.disabledAlgorithms و jdk.security.legacyAlgorithms برای تعیین این‌که کدام الگوریتم‌ها یک مخاطره امنیتی به شمار می‌روند استفاده می‌کند. اگر فایل JAR با هر یک از الگوریتم‌های غیرفعال‌شده امضا شده باشد، با آن همانند یک فایل JAR امضانشده برخورد خواهد شد. اگر فایل JAR با هر یک از الگوریتم‌های قدیمی (legacy) امضا شده باشد، با آن به عنوان یک فایل امضاشده برخورد می‌شود، همراه با یک هشدار اطلاع‌رسانی برای آگاه ساختن کاربران از این‌که الگوریتم قدیمی در به‌روزرسانی‌های آینده غیرفعال خواهد شد. برای دریافت خروجی اعتبارسنجی دقیق، -J-Djava.security.debug=jar را بگنجانید. ویژگی‌های امنیتی jdk.jar.disabledAlgorithms و jdk.security.legacyAlgorithms در فایل java.security (واقع در دایرکتوری $JAVA_HOME/conf/security مربوط به JDK) تعریف شده‌اند.

نکته:

برای ارتقای امنیت در حالت پیش‌فرض (out of the box)، اندازه کلید و نام‌های الگوریتم امضای پیش‌فرض به طور دوره‌ای در هر انتشار JDK به مقادیر قوی‌تری به‌روزرسانی می‌شوند. اگر سازگاری با انتشار‌های قدیمی‌تر JDK اهمیت دارد، لطفاً مطمئن شوید که مقادیر پیش‌فرض توسط آن نسخه‌ها پشتیبانی می‌شوند، یا در غیر این صورت، با مسئولیت خودتان از گزینهٔ -sigalg برای بازنویسی مقادیر پیش‌فرض استفاده کنید..SH "فایل JAR امضاشده (THE SIGNED JAR FILE)" هنگامی که دستور jarsigner برای امضای یک فایل JAR استفاده می‌شود، فایل JAR امضاشده‌ی خروجی دقیقاً همانند فایل JAR ورودی است، با این تفاوت که دو فایل اضافی در دایرکتوری META-INF قرار می‌گیرند:

یک فایل امضا با پسوند .SF
یک فایل بلوک امضا با پسوند .DSA، .RSA یا .EC

نام پایه برای این دو فایل از مقدار گزینهٔ -sigfile گرفته می‌شود. برای مثال، هنگامی که گزینه به‌صورت -sigfile MKSIGN باشد، فایل‌ها MKSIGN.SF و MKSIGN.RSA نام‌گذاری می‌شوند. در این مستند، فرض بر این است که امضاکننده همواره از یک کلید RSA استفاده می‌کند.

اگر گزینهٔ -sigfile در خط فرمان مشخص نشود، نام پایه برای فایل .SF و فایل‌های بلوک امضا، ۸ نویسهٔ نخست نام مستعار (alias) تعیین‌شده در خط فرمان خواهد بود که همگی به حروف بزرگ تبدیل می‌شوند. اگر نام مستعار کمتر از ۸ نویسه داشته باشد، کل نام مستعار به کار می‌رود. اگر نام مستعار دارای هرگونه نویسه‌ای باشد که در نام فایل امضا مجاز نیست، هر یک از این نویسه‌ها هنگام ایجاد نام فایل به نویسهٔ خط زیر (_) تبدیل می‌شوند. نویسه‌های مجاز شامل حروف، ارقام، خط زیر و خط تیره هستند.

فایل امضا (SIGNATURE FILE)

یک فایل امضا (فایل .SF) ساختاری شبیه به فایل مانیفست دارد که همواره در زمان استفاده از دستور jarsigner برای امضای فایل، در فایل JAR گنجانده می‌شود. به ازای هر فایل مبدأ موجود در فایل JAR، فایل .SF همانند فایل مانیفست دارای دو خط است که موارد زیر را فهرست می‌کند:

نام فایل
نام الگوریتم چکیده‌ساز (SHA)
مقدار چکیدهٔ SHA

نکته:

نام الگوریتم چکیده‌ساز (SHA) و مقدار چکیدهٔ SHA در یک خط قرار دارند.

در فایل مانیفست، مقدار چکیدهٔ SHA برای هر فایل مبدأ، چکیده (هش) داده‌های باینری درون آن فایل مبدأ است. در فایل .SF، مقدار چکیده برای یک فایل مبدأ مشخص، هشِ دو خطِ مربوط به آن فایل مبدأ در فایل مانیفست است.

فایل امضا به‌طور پیش‌فرض شامل یک سرآیند (header) است که هش کل فایل مانیفست را در بر دارد. این سرآیند همچنین حاوی هش سرآیند مانیفست است. وجود این سرآیند بهینه‌سازی فرایند اعتبارسنجی را ممکن می‌سازد. بخش اعتبارسنجی فایل JAR (JAR File Verification) را ببینید.

فایل بلوک امضا (SIGNATURE BLOCK FILE)

فایل .SF امضا شده و امضا درون فایل بلوک امضا قرار می‌گیرد. این فایل همچنین حاوی گواهی یا زنجیرهٔ گواهی کدگذاری‌شده از keystore است که کلید عمومی متناظر با کلید خصوصیِ استفاده‌شده برای امضا را احراز هویت می‌کند. بسته به الگوریتم کلیدِ استفاده‌شده، این فایل دارای پسوند .DSA، .RSA یا .EC است. جدول موجود در بخش Supported Algorithms را ببینید.

برچسب زمانی امضا (SIGNATURE TIME STAMP)

دستور jarsigner در صورت استفاده با گزینه‌های زیر، هنگام امضای یک فایل JAR، یک برچسب زمانی امضا (timestamp) تولید و ذخیره می‌کند:

-tsa url
-tsacert alias
-tsapolicyid policyid
-tsadigestalg algorithm

بخش Options for jarsigner را ببینید.

اعتبارسنجی فایل JAR (JAR FILE VERIFICATION)

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

1.: اعتبارسنجی امضای فایل .SF.

این اعتبارسنجی اطمینان حاصل می‌کند که امضای ذخیره‌شده در هر فایل بلوک امضا، با استفاده از کلید خصوصی متناظر با کلید عمومی‌ای تولید شده است که گواهی (یا زنجیرهٔ گواهی) آن نیز در فایل بلوک امضا قرار دارد. همچنین اطمینان می‌دهد که امضا، یک امضای معتبر از فایل امضای متناظر (.SF) است و در نتیجه فایل .SF دستکاری نشده است.

2.: اعتبارسنجی چکیدهٔ فهرست‌شده در هر مدخل فایل .SF با بخش متناظر آن در مانیفست.

فایل .SF به‌طور پیش‌فرض شامل سرآیندی است که حاوی هش کل فایل مانیفست است. هنگامی که این سرآیند وجود دارد، اعتبارسنجی می‌تواند بررسی کند که آیا هش موجود در سرآیند با هش فایل مانیفست مطابقت دارد یا خیر. در صورت تطابق، فرایند اعتبارسنجی به مرحلهٔ بعد می‌رود.

در صورت عدم تطابق، یک اعتبارسنجی با بهینه‌سازی کمتر مورد نیاز است تا اطمینان حاصل شود که هش موجود در بخش اطلاعات هر فایل مبدأ در فایل .SF با هش بخش متناظر آن در فایل مانیفست برابر است. بخش فایل امضا (SIGNATURE FILE) را ببینید.

یک دلیل برای اینکه هش فایل مانیفست ذخیره‌شده در سرآیند فایل .SF ممکن است با هش فایل مانیفست فعلی برابر نباشد این است که مانیفست ممکن است حاوی بخش‌هایی برای فایل‌هایی باشد که پس از امضا شدن فایل، به آن اضافه شده‌اند. برای مثال، فرض کنید یک یا چند فایل (با استفاده از ابزار jar) به فایل JAR امضاشده‌ای اضافه شده‌اند که از پیش حاوی یک امضا و یک فایل .SF است. اگر فایل JAR دوباره توسط امضاکنندهٔ دیگری امضا شود، فایل مانیفست تغییر می‌کند (بخش‌هایی برای فایل‌های جدید توسط ابزار jarsigner به آن اضافه می‌شود) و یک فایل .SF جدید ایجاد می‌شود، اما فایل .SF اصلی بدون تغییر باقی می‌ماند. اگر هیچ‌یک از فایل‌هایی که در زمان ایجاد امضای اولیه در فایل JAR بودند از آن زمان تغییر نکرده باشند، اعتبارسنجی همچنان موفق در نظر گرفته می‌شود. دلیل این امر این است که هش‌های موجود در بخش‌های غیرسرآیند فایل .SF با هش‌های بخش‌های متناظر در فایل مانیفست برابر هستند.

3.: خواندن هر فایل در فایل JAR که مدخلی در فایل .SF دارد. هنگام خواندن، چکیدهٔ فایل را محاسبه کرده و نتیجه را با چکیدهٔ این فایل در بخش مانیفست مقایسه کنید. چکیده‌ها باید یکسان باشند، در غیر این صورت اعتبارسنجی با شکست مواجه می‌شود.

اگر هرگونه خطای جدی در طول فرایند اعتبارسنجی رخ دهد، فرایند متوقف شده و یک استثنای امنیتی (security exception) صادر می‌شود. دستور jarsigner این استثنا را دریافت کرده و نمایش می‌دهد.

4.: بررسی استفاده از الگوریتم‌های غیرفعال‌شده. بخش Supported Algorithms را ببینید.

نکته:

شما باید هشدارهای اضافی (یا در صورت تعیین گزینهٔ -strict، خطاها) و همچنین محتوای گواهی را (با تعیین گزینه‌های -verbose و -certs) بررسی و مطالعه کنید تا مشخص شود که آیا می‌توان به امضا اعتماد کرد یا خیر..SH "چندین امضا برای یک فایل JAR (MULTIPLE SIGNATURES FOR A JAR FILE)" یک فایل JAR می‌تواند توسط چندین نفر امضا شود؛ به این صورت که دستور jarsigner چندین بار بر روی فایل اجرا شده و هر بار نام مستعار (alias) فرد متفاوتی مشخص گردد، به شرح زیر:

jarsigner myBundle.jar susan
jarsigner myBundle.jar kevin

هنگامی که یک فایل JAR چندین بار امضا می‌شود، چندین فایل .SF و بلوک امضا در فایل JAR حاصل وجود خواهد داشت؛ یعنی یک جفت برای هر امضا. در مثال قبلی، فایل JAR خروجی شامل فایل‌هایی با نام‌های زیر است:

SUSAN.SF
SUSAN.RSA
KEVIN.SF
KEVIN.RSA

گزینه‌های JARSIGNER (OPTIONS FOR JARSIGNER)

بخش‌های زیر گزینه‌های jarsigner را شرح می‌دهند. از استانداردهای زیر آگاه باشید:

نام تمامی گزینه‌ها با یک علامت خط پیوند (-) آغاز می‌شود.
گزینه‌ها را می‌توان به هر ترتیبی ارائه داد.
مواردی که با حروف کج (ایتالیک) یا زیرخط‌دار مشخص شده‌اند (مقادیر گزینه‌ها) نشان‌دهنده مقادیر واقعی هستند که باید وارد شوند.
گزینه‌های -storepass، -keypass، -sigfile، -sigalg، -digestalg، -signedjar و گزینه‌های مرتبط با TSA فقط هنگام امضای فایل JAR کاربرد دارند؛ آن‌ها هنگام اعتبارسنجی یک فایل JAR امضاشده کاربردی ندارند. گزینه -keystore برای امضا و اعتبارسنجی فایل JAR قابل استفاده است. علاوه بر این، هنگام امضا و اعتبارسنجی فایل JAR، نام‌های مستعار نیز مشخص می‌شوند.

-keystore url: نشانی اینترنتی (URL) مکان keystore را مشخص می‌کند. مقدار پیش‌فرض آن فایل .keystore در دایرکتوری خانگی کاربر است که توسط ویژگی سیستمی user.home تعیین می‌شود.

هنگام امضا کردن، وجود یک keystore الزامی است. در صورتی که keystore پیش‌فرض وجود نداشته باشد یا بخواهید از keystore دیگری غیر از پیش‌فرض استفاده کنید، باید صریحاً آن را مشخص نمایید. هنگام اعتبارسنجی نیازی به keystore نیست، اما اگر keystore مشخص شده باشد یا پیش‌فرض موجود باشد و گزینه -verbose نیز قید شده باشد، اطلاعات بیشتری در خروجی نمایش داده می‌شود مبنی بر این‌که آیا گواهی‌های استفاده‌شده برای اعتبارسنجی فایل JAR درون آن keystore موجود هستند یا خیر. آرگومان -keystore می‌تواند به جای URL، یک نام فایل و مسیر مشخص باشد که در این صورت مانند یک URL از نوع file: با آن رفتار می‌شود؛ برای مثال موارد زیر معادل یکدیگر هستند:

-keystore filePathAndName
-keystore file:filePathAndName اگر ارائه‌دهنده Sun PKCS #11 در فایل ویژگی‌های امنیتی java.security (واقع در دایرکتوری $JAVA_HOME/conf/security متعلق به JDK) پیکربندی شده باشد، ابزارهای keytool و jarsigner می‌توانند با مشخص کردن این گزینه‌ها روی توکن PKCS #11 عمل کنند:

-keystore NONE -storetype PKCS11

برای مثال، دستور زیر محتویات توکن PKCS#11 پیکربندی‌شده را فهرست می‌کند:

keytool -keystore NONE -storetype PKCS11 -list

-storepass [:env | :file] argument: گذرواژه‌ای را که برای دسترسی به keystore لازم است مشخص می‌کند. این مورد فقط هنگام امضا کردن (نه اعتبارسنجی) یک فایل JAR مورد نیاز است. در این صورت، اگر گزینه -storepass در خط فرمان ارائه نشود، از کاربر خواسته می‌شود تا گذرواژه را وارد کند.

اگر اصلاح‌کننده env یا file مشخص نشده باشد، مقدار گذرواژه برابر با argument خواهد بود. در غیر این صورت، گذرواژه به شرح زیر بازیابی می‌شود:

env: گذرواژه را از متغیر محیطی با نام argument بازیابی می‌کند.
file: گذرواژه را از فایلی با نام argument بازیابی می‌کند. نکته: گذرواژه نباید در خط فرمان یا در یک اسکریپت مشخص شود، مگر این‌که برای اهداف آزمایشی بوده یا در یک سیستم امن قرار داشته باشید.

-storetype storetype: نوع keystore را که باید نمونه‌سازی شود مشخص می‌کند. نوع پیش‌فرض keystore مقداری است که به عنوان مقدار ویژگی keystore.type در فایل ویژگی‌های امنیتی تعیین شده است و توسط متد ایستا getDefaultType در java.security.KeyStore بازگردانده می‌شود.

پین (PIN) برای یک توکن PKCS #11 نیز می‌تواند با گزینه -storepass مشخص شود. اگر چیزی مشخص نشود، دستورهای keytool و jarsigner پین توکن را درخواست می‌کنند. اگر توکن دارای مسیر احراز هویت محافظت‌شده باشد (مانند یک صفحه کلید اختصاصی PIN یا حسگر بیومتریک)، باید گزینه -protected مشخص شود و هیچ گزینه گذرواژه‌ای نمی‌تواند تعیین گردد.

-keypass [:env | :file] argument -certchain file: گذرواژه مورد استفاده برای محافظت از کلید خصوصی مدخل keystore را که با نام مستعار مشخص‌شده در خط فرمان آدرس‌دهی می‌شود، مشخص می‌کند. هنگام استفاده از jarsigner برای امضا کردن یک فایل JAR، این گذرواژه الزامی است. اگر هیچ گذرواژه‌ای در خط فرمان ارائه نشود و گذرواژه مورد نیاز با گذرواژه keystore متفاوت باشد، از کاربر خواسته می‌شود آن را وارد کند.

اگر اصلاح‌کننده env یا file مشخص نشده باشد، مقدار گذرواژه برابر با argument خواهد بود. در غیر این صورت، گذرواژه به شرح زیر بازیابی می‌شود:

env: گذرواژه را از متغیر محیطی با نام argument بازیابی می‌کند.
file: گذرواژه را از فایلی با نام argument بازیابی می‌کند. نکته: گذرواژه نباید در خط فرمان یا در یک اسکریپت مشخص شود، مگر این‌که برای اهداف آزمایشی بوده یا در یک سیستم امن قرار داشته باشید.

-certchain file: زنجیره گواهی مورد استفاده را در زمانی که زنجیره گواهی مرتبط با کلید خصوصی مدخل keystore (که با نام مستعار ارائه‌شده در خط فرمان آدرس‌دهی شده) کامل نیست، مشخص می‌کند. این حالت زمانی رخ می‌دهد که keystore روی یک توکن سخت‌افزاری قرار داشته باشد و ظرفیت کافی برای نگهداری زنجیره گواهی کامل وجود نداشته باشد. فایل می‌تواند توالی‌ای از گواهی‌های الحاق‌شده‌ی X.509 یا یک بلوک داده با قالب PKCS#7 باشد، چه در قالب کدگذاری باینری و چه در قالب کدگذاری قابل‌چاپ (که به نام کدگذاری Base64 نیز شناخته می‌شود) آن‌گونه که توسط Internet RFC 1421 Certificate Encoding Standard [http://tools.ietf.org/html/rfc1421] تعریف شده است.
-sigfile file: نام فایل پایه‌ای را که باید برای فایل‌های .SF و بلوک امضای تولیدشده استفاده شود مشخص می‌کند. برای مثال، اگر file برابر با DUKESIGN باشد، فایل‌های .SF و بلوک امضای تولیدشده با نام‌های DUKESIGN.SF و DUKESIGN.RSA نام‌گذاری شده و در دایرکتوری META-INF فایل JAR امضاشده قرار می‌گیرند.

نویسه‌های موجود در file باید از مجموعه a-zA-Z0-9_- باشند. تنها حروف، اعداد، زیرخط و خط پیوند مجاز هستند. تمامی نویسه‌های کوچک برای نام‌های فایل‌های .SF و بلوک امضا به حروف بزرگ تبدیل می‌شوند. اگر گزینه -sigfile در خط فرمان مشخص نشود، نام فایل پایه برای فایل‌های .SF و بلوک امضا، ۸ نویسه اول نام مستعار مشخص‌شده در خط فرمان خواهد بود که همگی به حروف بزرگ تبدیل می‌شوند. اگر نام مستعار کمتر از ۸ نویسه داشته باشد، کل نام مستعار استفاده می‌شود. اگر نام مستعار شامل نویسه‌هایی باشد که در نام فایل امضا معتبر نیستند، هر یک از این نویسه‌ها برای تشکیل نام فایل به یک نویسه زیرخط (_) تبدیل می‌شوند.

-signedjar file: نام فایل JAR امضاشده را مشخص می‌کند.
-digestalg algorithm: نام الگوریتم خلاصه پیام را برای استفاده هنگام خلاصه‌سازی مدخل‌های یک فایل JAR مشخص می‌کند.

برای فهرستی از نام‌های استاندارد الگوریتم‌های خلاصه پیام، به Java Security Standard Algorithm Names Specification مراجعه کنید. اگر این گزینه مشخص نشود، از SHA-384 استفاده می‌شود. باید یا یک ارائه‌دهنده که به صورت ایستا نصب شده پیاده‌سازی الگوریتم مشخص‌شده را فراهم کند، یا کاربر باید با گزینه‌های -addprovider یا -providerClass یکی را مشخص کند؛ در غیر این صورت، دستور با موفقیت اجرا نخواهد شد. -sigalg algorithm نام الگوریتم امضا را برای استفاده جهت امضای فایل JAR مشخص می‌کند.

این الگوریتم باید با کلید خصوصی به‌کاررفته برای امضای فایل JAR سازگار باشد. اگر این گزینه مشخص نشود، از یک الگوریتم پیش‌فرض متناسب با کلید خصوصی، همان‌طور که در بخش Supported Algorithms شرح داده شده است، استفاده می‌شود. باید یا یک ارائه‌دهنده (provider) به‌صورت ایستا نصب شده باشد که پیاده‌سازی الگوریتم مشخص‌شده را ارائه دهد، یا باید ارائه‌دهنده‌ای را با گزینهٔ -addprovider یا -providerClass مشخص کنید؛ در غیر این صورت دستور با موفقیت اجرا نخواهد شد. برای مشاهدهٔ فهرستی از نام‌های استاندارد الگوریتم‌های امضا، به مشخصات Java Security Standard Algorithm Names Specification مراجعه کنید.

-verify: یک فایل JAR امضاشده را وارسی می‌کند.
-verbose[:suboptions]: هنگامی که گزینهٔ -verbose در خط فرمان مشخص شود، نشان می‌دهد که jarsigner در زمان امضا یا وارسی از حالت پرگو استفاده می‌کند، که در آن زیرگزینه‌ها میزان اطلاعات ارائه‌شده را مشخص می‌کنند. این کار باعث می‌شود که jarsigner اطلاعات بیشتری دربارهٔ روند پیشرفت امضا یا وارسی JAR ارائه دهد. زیرگزینه‌ها (suboptions) می‌توانند all، grouped یا summary باشند.

اگر گزینهٔ -certs نیز مشخص شده باشد، حالت پیش‌فرض (یا زیرگزینهٔ all) هر ورودی را در حین پردازش، و پس از آن، اطلاعات گواهی هر امضاکنندهٔ فایل JAR را نمایش می‌دهد. اگر گزینهٔ -certs و زیرگزینهٔ -verbose:grouped مشخص شده باشند، ورودی‌های دارای اطلاعات امضاکنندهٔ یکسان گروه‌بندی شده و همراه با اطلاعات گواهی‌شان با هم نمایش داده می‌شوند. اگر گزینهٔ -certs و زیرگزینهٔ -verbose:summary مشخص شده باشند، ورودی‌های دارای اطلاعات امضاکنندهٔ یکسان گروه‌بندی شده و همراه با اطلاعات گواهی‌شان نمایش داده می‌شوند. جزئیات مربوط به هر ورودی خلاصه‌سازی شده و به‌صورت one entry (and more) نمایش می‌یابد. بخش‌های Example of Verifying a Signed JAR File و Example of Verification with Certificate Information را ببینید.

-certs: اگر گزینهٔ -certs همراه با گزینه‌های -verify و -verbose در خط فرمان ظاهر شود، خروجی شامل اطلاعات گواهی برای هر امضاکنندهٔ فایل JAR خواهد بود. این اطلاعات شامل نام نوع گواهی (ذخیره‌شده در فایل بلوک امضا) است که کلید عمومی امضاکننده را تأیید می‌کند، و در صورتی که گواهی از نوع X.509 باشد (نمونه‌ای از java.security.cert.X509Certificate)، نام متمایز (distinguished name) امضاکننده را نیز در بر می‌گیرد.

مخزن کلید (keystore) نیز بررسی می‌شود. اگر هیچ مقداری برای مخزن کلید در خط فرمان تعیین نشده باشد، فایل پیش‌فرض مخزن کلید (در صورت وجود) بررسی می‌شود. اگر گواهی کلید عمومیِ یک امضاکننده با ورودی‌ای در مخزن کلید مطابقت داشته باشد، نام مستعار (alias) آن ورودی در مخزن کلید برای آن امضاکننده درون پرانتز نمایش داده می‌شود.

-revCheck: این گزینه بررسی ابطال گواهی‌ها را هنگام امضا یا وارسی یک فایل JAR فعال می‌کند. اگر گزینهٔ -revCheck در خط فرمان مشخص شده باشد، دستور jarsigner تلاش می‌کند تا برای واکشی پاسخ‌های OCSP و CRLها اتصالات شبکه‌ای برقرار کند. توجه داشته باشید که بررسی‌های ابطال فعال نمی‌شوند مگر اینکه این گزینه مشخص شده باشد.
-tsa url: اگر -tsa http://example.tsa.url در هنگام امضای یک فایل JAR در خط فرمان ظاهر شود، یک برچسب زمان (time stamp) برای امضا تولید می‌شود. نشانی اینترنتی http://example.tsa.url مکان مرجع برچسب‌گذاری زمان (TSA) را مشخص می‌کند و بر هر نشانی یافت‌شده توسط گزینهٔ -tsacert اولویت دارد. گزینهٔ -tsa نیازی به وجود گواهی کلید عمومی TSA در مخزن کلید ندارد.

برای تولید برچسب زمان، jarsigner با استفاده از پروتکل برچسب زمانی (Time-Stamp Protocol یا TSP) تعریف‌شده در RFC 3161 با TSA ارتباط برقرار می‌کند. در صورت موفقیت، توکن برچسب زمانِ بازگردانده‌شده از TSA همراه با امضا در فایل بلوک امضا ذخیره می‌شود.

-tsacert alias: هنگامی که -tsacert alias در زمان امضای یک فایل JAR در خط فرمان مشخص شود، یک برچسب زمان برای امضا تولید می‌شود. نام مستعار (alias)، گواهی کلید عمومی TSA را در مخزن کلید فعال مشخص می‌کند. گواهیِ ورودی برای یافتن افزونهٔ Subject Information Access که حاوی یک نشانی اینترنتی جهت تعیین مکان TSA است، بررسی می‌شود.

هنگام استفاده از گزینهٔ -tsacert، گواهی کلید عمومی TSA باید در مخزن کلید موجود باشد.

-tsapolicyid policyid: شناسهٔ شیء (OID) را مشخص می‌کند که شناسهٔ خط‌مشی ارسالی به کارساز TSA را تعیین می‌نماید. اگر این گزینه مشخص نشود، هیچ شناسهٔ خط‌مشی‌ای ارسال نمی‌شود و کارساز TSA یک شناسهٔ خط‌مشی پیش‌فرض را انتخاب خواهد کرد.

شناسه‌های شیء توسط X.696 تعریف شده‌اند که یک استاندارد بخش استانداردسازی مخابرات ITU (به‌اختصار ITU-T) است. این شناسه‌ها معمولاً مجموعه‌هایی از ارقام غیرمنفی جداشده با نقطه هستند؛ مانند 1.2.3.4.

-tsadigestalg algorithm: الگوریتم خلاصهٔ پیام (message digest) را که برای ایجاد نقش پیام ارسالی به کارساز TSA استفاده می‌شود، مشخص می‌کند. اگر این گزینه مشخص نشود، از SHA-384 استفاده خواهد شد.

بخش Supported Algorithms را ببینید. برای مشاهدهٔ فهرستی از نام‌های استاندارد الگوریتم‌های خلاصهٔ پیام، به مشخصات Java Security Standard Algorithm Names Specification مراجعه کنید.

-internalsf: در گذشته، فایل بلوک امضا که هنگام امضای فایل JAR تولید می‌شد، شامل یک نسخهٔ رمزگذاری‌شدهٔ کامل از فایل .SF (فایل امضا) بود که آن نیز تولید می‌شد. این رفتار تغییر یافته است. به منظور کاهش حجم کلی فایل JAR خروجی، فایل بلوک امضا به‌طور پیش‌فرض دیگر حاوی نسخه‌ای از فایل .SF نیست. اگر -internalsf در خط فرمان مشخص شود، از رفتار قدیمی استفاده خواهد شد. این گزینه برای آزمایش کاربرد دارد. در عمل، از گزینهٔ -internalsf استفاده نکنید زیرا سربار بیشتری را تحمیل می‌کند.
-sectionsonly: اگر گزینهٔ -sectionsonly در خط فرمان مشخص شود، فایل .SF (فایل امضا) که هنگام امضای فایل JAR تولید می‌شود، شامل سرآیندی که حاوی هش کل فایل مانیفست است نخواهد بود. این فایل تنها شامل اطلاعات و هش‌های مربوط به هر یک از فایل‌های مبدأ موجود در فایل JAR خواهد بود. بخش Signature File را ببینید.

به‌طور پیش‌فرض، این سرآیند جهت بهینه‌سازی افزوده می‌شود. هنگامی که سرآیند وجود دارد، هر بار که فایل JAR وارسی می‌شود، وارسی می‌تواند ابتدا بررسی کند که آیا هش موجود در سرآیند با هش کل فایل مانیفست مطابقت دارد یا خیر. در صورت تطابق، وارسی به مرحلهٔ بعد می‌رود. در صورت عدم تطابق، لازم است وارسیِ کم‌تر بهینه‌ای انجام شود تا بررسی گردد که آیا هشِ بخشِ اطلاعاتِ هر فایل مبدأ در فایل .SF با هش بخش متناظر آن در فایل مانیفست برابر است یا خیر. بخش JAR File Verification را ببینید. گزینهٔ -sectionsonly عمدتاً برای آزمایش استفاده می‌شود. این گزینه نباید برای مقاصدی غیر از آزمایش استفاده شود، زیرا استفاده از آن سربار بالاتری در پی دارد.

-protected: مقادیر می‌توانند true یا false باشند. هنگامی که گذرواژه باید از طریق یک مسیر احراز هویت محافظت‌شده مانند یک PINخوان اختصاصی مشخص شود، مقدار true را تعیین کنید.
-providerName providerName: اگر بیش از یک ارائه‌دهنده در فایل ویژگی‌های امنیتی java.security پیکربندی شده باشد، می‌توانید از گزینهٔ -providerName برای هدف قرار دادن یک نمونه ارائه‌دهندهٔ خاص استفاده کنید. آرگومان این گزینه نام ارائه‌دهنده است.

برای ارائه‌دهندهٔ Oracle PKCS #11، مقدار providerName به‌صورت SunPKCS11-TokenName است، که در آن TokenName پسوند نامی است که نمونه ارائه‌دهنده با آن پیکربندی شده است، همان‌طور که در جدول ویژگی‌های پیکربندی با جزئیات آمده است. برای نمونه، دستور زیر محتویات نمونه ارائه‌دهندهٔ مخزن کلید PKCS #11 با پسوند نام SmartCard را فهرست می‌کند: jarsigner -keystore NONE -storetype PKCS11 -providerName SunPKCS11-SmartCard -list

-addprovider name [-providerArg arg]: یک ارائه‌دهنده امنیتی را بر اساس نام (مانند SunPKCS11) و یک آرگومان پیکربندی اختیاری اضافه می‌کند. مقدار ارائه‌دهنده امنیتی، نام ارائه‌دهنده‌ای امنیتی است که در یک ماژول تعریف شده است.

در صورت استفاده به همراه گزینهٔ -providerArg ConfigFilePath، ابزارهای keytool و jarsigner ارائه‌دهنده را به‌صورت پویا نصب کرده و از ConfigFilePath برای مسیر فایل پیکربندی توکن استفاده می‌کنند. مثال زیر دستوری را برای فهرست کردن یک PKCS #11 keystore نشان می‌دهد، در شرایطی که ارائه‌دهندهٔ Oracle PKCS #11 در فایل ویژگی‌های امنیتی پیکربندی نشده باشد.

jarsigner -keystore NONE -storetype PKCS11 -addprovider SunPKCS11 -providerArg /mydir1/mydir2/token.config

-providerClass provider-class-name [-providerArg arg]: برای مشخص کردن نام فایل کلاس اصلی (master class) ارائه‌دهندهٔ خدمات رمزنگاری به کار می‌رود، در حالتی که ارائه‌دهندهٔ خدمات در فایل ویژگی‌های امنیتی java.security فهرست نشده باشد. یک ارائه‌دهنده امنیتی را با نام کامل کلاس (fully-qualified class name) و یک آرگومان پیکربندی اختیاری اضافه می‌کند.

نکته: روش ترجیحی برای بارگذاری PKCS11 استفاده از ماژول‌ها است. گزینهٔ -addprovider را ببینید.

-providerPath classpath: برای تعیین classpath ارائه‌دهندگانی که با گزینهٔ -providerClass مشخص شده‌اند استفاده می‌شود. چندین مسیر باید با نویسهٔ جداکنندهٔ مسیر وابسته به سیستم از یکدیگر جدا شوند.
-Jjavaoption: رشتهٔ javaoption مشخص‌شده را مستقیماً به مفسر Java ارسال می‌کند. دستور jarsigner یک لفاف (wrapper) برای این مفسر است. این گزینه نباید شامل هیچ فاصله‌ای باشد. این گزینه برای تنظیم محیط اجرا یا میزان حافظهٔ مصرفی مفید است. برای مشاهدهٔ فهرستی از گزینه‌های ممکن مفسر، عبارت java -h یا java -X را در خط فرمان وارد کنید.
-strict: در طول فرایند امضا یا اعتبارسنجی، ممکن است دستور پیام‌های هشداری صادر کند. اگر این گزینه را مشخص کنید، وضعیت خروج این ابزار نشان‌دهندهٔ پیام‌های هشدار شدیدی خواهد بود که این دستور با آن‌ها مواجه شده است. بخش خطاها و هشدارها (ERRORS AND WARNINGS) را ببینید.
-conf url: یک فایل گزینه‌های از پیش‌پیکربندی‌شده را مشخص می‌کند. برای جزئیات بیشتر، مستندات keytool را مطالعه کنید. کلیدهای ویژگی پشتیبانی‌شده عبارتند از: "jarsigner.all" برای تمام عملیات‌ها، "jarsigner.sign" برای امضا کردن، و "jarsigner.verify" برای اعتبارسنجی. آرگومان‌های jarsigner از جمله نام فایل JAR و نام(های) مستعار (alias) را نمی‌توان در این فایل تنظیم کرد.
-version: نسخهٔ برنامه را چاپ می‌کند.

خطاها و هشدارها (ERRORS AND WARNINGS)

در طول فرایند امضا یا اعتبارسنجی، دستور jarsigner ممکن است خطاها یا هشدارهای مختلفی صادر کند.

اگر شکستی رخ دهد، دستور jarsigner با کد ۱ خارج می‌شود. اگر شکستی در کار نباشد اما یک یا چند هشدار شدید وجود داشته باشد، چنانچه گزینهٔ -strict مشخص نشده باشد دستور jarsigner با کد ۰ خارج می‌شود، یا در صورت مشخص شدن -strict، با حاصل OR بیتیِ کدهای هشدار خارج خواهد شد. اگر تنها هشدارهای اطلاعاتی وجود داشته باشد یا اصلاً هشداری نباشد، دستور همواره با کد ۰ خارج می‌شود.

برای نمونه، اگر گواهی مورد استفاده برای امضای یک مدخل منقضی شده باشد و دارای افزونهٔ KeyUsage باشد که اجازهٔ امضای فایل را به آن ندهد، در صورت تعیین گزینهٔ -strict، دستور jarsigner با کد ۱۲ (=۴+۸) خارج می‌شود.

نکته: کدهای خروج مجدداً استفاده می‌شوند، زیرا در Linux و macOS تنها مقادیر بین ۰ تا ۲۵۵ مجاز هستند.

بخش‌های زیر نام‌ها، کدها و توضیحات مربوط به خطاها و هشدارهایی را که دستور jarsigner می‌تواند صادر کند، شرح می‌دهند..SH "شکست (FAILURE)" دلایلی که موجب شکست فرمان jarsigner می‌شوند شامل مواردی مانند خطای تجزیه خط فرمان، ناتوانی در یافتن جفت‌کلید برای امضای فایل JAR، یا شکست در اعتبارسنجی یک JAR امضاشده است (اما به این موارد محدود نمی‌شود).

failure: کد 1. عملیات امضا یا اعتبارسنجی با شکست مواجه می‌شود.

هشدارهای جدی (SEVERE WARNINGS)

نکته:

اگر گزینه -strict را مشخص کنید، هشدارهای جدی به عنوان خطا گزارش می‌شوند.

دلایلی که موجب صدور یک هشدار جدی توسط فرمان jarsigner می‌شوند شامل مواردی است مانند وجود خطا در گواهی استفاده‌شده برای امضای فایل JAR یا وجود مشکلات دیگر در فایل JAR امضاشده.

hasExpiredCert: کد 4. این JAR حاوی مدخل‌هایی است که گواهی امضاکننده آن‌ها منقضی شده است.
hasExpiredTsaCert: کد 4. برچسب زمانی منقضی شده است.
notYetValidCert: کد 4. این JAR حاوی مدخل‌هایی است که گواهی امضاکننده آن‌ها هنوز معتبر نیست.
chainNotValidated: کد 4. این JAR حاوی مدخل‌هایی است که زنجیره گواهی آن‌ها اعتبارسنجی نشده است.
tsaChainNotValidated: کد 64. برچسب زمانی نامعتبر است.
signerSelfSigned: کد 4. این JAR حاوی مدخل‌هایی است که گواهی امضاکننده آن‌ها خودامضا (self-signed) است.
disabledAlg: کد 4. الگوریتم استفاده‌شده یک خطر امنیتی به شمار رفته و غیرفعال شده است.
badKeyUsage: کد 8. این JAR حاوی مدخل‌هایی است که افزونه KeyUsage گواهی امضاکننده آن‌ها اجازه امضای کد را نمی‌دهد.
badExtendedKeyUsage: کد 8. این JAR حاوی مدخل‌هایی است که افزونه ExtendedKeyUsage گواهی امضاکننده آن‌ها اجازه امضای کد را نمی‌دهد.
badNetscapeCertType: کد 8. این JAR حاوی مدخل‌هایی است که افزونه NetscapeCertType گواهی امضاکننده آن‌ها اجازه امضای کد را نمی‌دهد.
hasUnsignedEntry: کد 16. این JAR حاوی مدخل‌های امضانشده‌ای است که یکپارچگی آن‌ها بررسی نشده است.
notSignedByAlias: کد 32. این JAR حاوی مدخل‌های امضاشده‌ای است که توسط نام(های) مستعار (alias) مشخص‌شده امضا نشده‌اند.
aliasNotInStore: کد 32. این JAR حاوی مدخل‌های امضاشده‌ای است که توسط هیچ نام مستعاری (alias) در این keystore امضا نشده‌اند.
tsaChainNotValidated: کد 64. این JAR حاوی مدخل‌هایی است که زنجیره گواهی TSA آن‌ها نامعتبر است..SH "هشدارهای اطلاعاتی (INFORMATIONAL WARNINGS)" هشدارهای اطلاعاتی شامل مواردی می‌شوند که خطا نیستند، اما به عنوان شیوه‌های نامناسب تلقی می‌شوند. این هشدارها فاقد کد هستند.
extraAttributesDetected: مجوزهای فایل POSIX و/یا ویژگی‌های پیوند نمادین (symlink) هنگام امضا یا اعتبارسنجی فایل JAR شناسایی شده‌اند. ابزار jarsigner این ویژگی‌ها را در فایل تازه امضاشده حفظ می‌کند، اما هشدار می‌دهد که این مشخصه‌ها امضا نشده‌اند و توسط امضا محافظت نمی‌شوند.
hasExpiringCert: این JAR شامل مدخل‌هایی است که گواهی امضاکنندهٔ آن‌ها ظرف شش ماه آینده منقضی می‌شود.
hasExpiringTsaCert: برچسب زمانی در تاریخ YYYY-MM-DD ظرف یک سال آینده منقضی خواهد شد.
hasMultipleManifests: این JAR حاوی چندین فایل مانیفست بود. هنگام امضا، یکی از فایل‌ها انتخاب شد و باقی کنار گذاشته شدند.
hasNonexistentEntries: این JAR شامل مدخل‌های امضاشده‌ای برای فایل‌هایی است که وجود ندارند.
internalInconsistenciesDetected: این JAR حاوی ناسازگاری‌های درونی کشف‌شده هنگام اعتبارسنجی است که ممکن است هنگام خواندن از طریق JarFile و JarInputStream منجر به دریافت محتویات متفاوتی شود.
legacyAlg: الگوریتم استفاده‌شده یک ریسک امنیتی تلقی می‌شود، اما غیرفعال نشده است.
noTimestamp: این JAR شامل امضاهایی است که فاقد برچسب زمانی هستند. بدون برچسب زمانی، کاربران ممکن است پس از تاریخ انقضای گواهی امضاکننده (YYYY-MM-DD) یا پس از هر تاریخ ابطال در آینده، قادر به اعتبارسنجی این فایل JAR نباشند.

مثال امضای یک فایل JAR (EXAMPLE OF SIGNING A JAR FILE)

برای امضای bundle.jar با کلید خصوصی کاربری که نام مستعار (alias) آن در مخزن کلید jane است، در یک مخزن کلید (keystore) با نام mystore واقع در دایرکتوری working و نام‌گذاری فایل JAR امضاشده به sbundle.jar، از دستور زیر استفاده کنید:

jarsigner -keystore /working/mystore -storepass keystore_password -keypass private_key_password -signedjar sbundle.jar bundle.jar jane

در دستور قبلی هیچ -sigfile مشخص نشده است؛ بنابراین فایل‌های تولیدشدهٔ .SF و بلوک امضا که در فایل JAR امضاشده قرار می‌گیرند، نام‌های پیش‌فرضی بر اساس نام مستعار خواهند داشت. آن‌ها JANE.SF و JANE.RSA نام‌گذاری می‌شوند.

اگر می‌خواهید برای گذرواژهٔ مخزن و گذرواژهٔ کلید خصوصی اعلان دریافت کنید (از شما پرسیده شود)، می‌توانید دستور قبلی را به شکل زیر کوتاه کنید:

jarsigner -keystore /working/mystore -signedjar sbundle.jar bundle.jar jane

اگر keystore همان مخزن کلید پیش‌فرض باشد (.keystore در پوشهٔ خانگی شما)، نیازی به تعیین یک keystore ندارید؛ به این صورت:

jarsigner -signedjar sbundle.jar bundle.jar jane

اگر می‌خواهید فایل JAR امضاشده جایگزین فایل JAR ورودی (bundle.jar) شود، نیازی به تعیین گزینهٔ -signedjar ندارید؛ به این صورت:

jarsigner bundle.jar jane برای اعتبارسنجی یک فایل JAR امضاشده جهت اطمینان از معتبر بودن امضا و دستکاری نشدن فایل JAR، از دستوری مشابه زیر استفاده کنید:

jarsigner -verify ButtonDemo.jar

هنگامی که اعتبارسنجی موفقیت‌آمیز باشد، عبارت jar verified نمایش داده می‌شود. در غیر این صورت، یک پیام خطا نمایش داده می‌شود. با استفاده از گزینهٔ -verbose می‌توانید اطلاعات بیشتری دریافت کنید. نمونه‌ای از کاربرد jarsigner با گزینهٔ -verbose در ادامه آمده است:

jarsigner -verify -verbose ButtonDemo.jar
s       866 Tue Sep 12 20:08:48 EDT 2017 META-INF/MANIFEST.MF
        825 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.SF
       7475 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.RSA
          0 Tue Sep 12 20:07:54 EDT 2017 META-INF/
          0 Tue Sep 12 20:07:16 EDT 2017 components/
          0 Tue Sep 12 20:07:16 EDT 2017 components/images/
sm      523 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo$1.class
sm     3440 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.class
sm     2346 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.jnlp
sm      172 Tue Sep 12 20:07:16 EDT 2017 components/images/left.gif
sm      235 Tue Sep 12 20:07:16 EDT 2017 components/images/middle.gif
sm      172 Tue Sep 12 20:07:16 EDT 2017 components/images/right.gif
  s = signature was verified
  m = entry is listed in manifest
  k = at least one certificate was found in keystore
- Signed by "CN="Oracle America, Inc.", OU=Software Engineering, O="Oracle America, Inc.", L=Redwood City, ST=California, C=US"
    Digest algorithm: SHA-256
    Signature algorithm: SHA256withRSA, 2048-bit key
  Timestamped by "CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US" on Tue Sep 12 20:08:49 UTC 2017
    Timestamp digest algorithm: SHA-1
    Timestamp signature algorithm: SHA1withRSA, 2048-bit key
jar verified.
The signer certificate expired on 2018-02-01. However, the JAR will be valid until the timestamp expires on 2020-12-29.

مثالی از اعتبارسنجی با اطلاعات گواهی (EXAMPLE OF VERIFICATION WITH CERTIFICATE INFORMATION)

اگر گزینهٔ -certs را به همراه گزینه‌های -verify و -verbose مشخص کنید، خروجی شامل اطلاعات گواهی برای هر یک از امضاکنندگان فایل JAR خواهد بود. این اطلاعات شامل نوع گواهی، اطلاعات نام متمایز (distinguished name) امضاکننده (زمانی که گواهی X.509 است)، و درون پرانتز، نام مستعار (alias) در keystore برای امضاکننده خواهد بود (در صورتی که گواهی کلید عمومی موجود در فایل JAR با یکی از مدخل‌های keystore مطابقت داشته باشد)؛ برای نمونه:

jarsigner -keystore $JAVA_HOME/lib/security/cacerts -verify -verbose -certs ButtonDemo.jar
s k     866 Tue Sep 12 20:08:48 EDT 2017 META-INF/MANIFEST.MF
      >>> Signer
      X.509, CN="Oracle America, Inc.", OU=Software Engineering, O="Oracle America, Inc.", L=Redwood City, ST=California, C=US
      [certificate is valid from 2017-01-30, 7:00 PM to 2018-02-01, 6:59 PM]
      X.509, CN=Symantec Class 3 SHA256 Code Signing CA, OU=Symantec Trust Network, O=Symantec Corporation, C=US
      [certificate is valid from 2013-12-09, 7:00 PM to 2023-12-09, 6:59 PM]
      X.509, CN=VeriSign Class 3 Public Primary Certification Authority - G5, OU="(c) 2006 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US (verisignclass3g5ca [jdk])
      [trusted certificate]
      >>> TSA
      X.509, CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US
      [certificate is valid from 2012-10-17, 8:00 PM to 2020-12-29, 6:59 PM]
      X.509, CN=Symantec Time Stamping Services CA - G2, O=Symantec Corporation, C=US
      [certificate is valid from 2012-12-20, 7:00 PM to 2020-12-30, 6:59 PM]
        825 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.SF
       7475 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.RSA
          0 Tue Sep 12 20:07:54 EDT 2017 META-INF/
          0 Tue Sep 12 20:07:16 EDT 2017 components/
          0 Tue Sep 12 20:07:16 EDT 2017 components/images/
smk     523 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo$1.class
      [entry was signed on 2017-09-12, 4:08 PM]
      >>> Signer
      X.509, CN="Oracle America, Inc.", OU=Software Engineering, O="Oracle America, Inc.", L=Redwood City, ST=California, C=US
      [certificate is valid from 2017-01-30, 7:00 PM to 2018-02-01, 6:59 PM]
      X.509, CN=Symantec Class 3 SHA256 Code Signing CA, OU=Symantec Trust Network, O=Symantec Corporation, C=US
      [certificate is valid from 2013-12-09, 7:00 PM to 2023-12-09, 6:59 PM]
      X.509, CN=VeriSign Class 3 Public Primary Certification Authority - G5, OU="(c) 2006 VeriSign, Inc. - For authorized use only", OU=VeriSign Trust Network, O="VeriSign, Inc.", C=US (verisignclass3g5ca [jdk])
      [trusted certificate]
      >>> TSA
      X.509, CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US
      [certificate is valid from 2012-10-17, 8:00 PM to 2020-12-29, 6:59 PM]
      X.509, CN=Symantec Time Stamping Services CA - G2, O=Symantec Corporation, C=US
      [certificate is valid from 2012-12-20, 7:00 PM to 2020-12-30, 6:59 PM]
smk    3440 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.class
...
smk    2346 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.jnlp
...
smk     172 Tue Sep 12 20:07:16 EDT 2017 components/images/left.gif
...
smk     235 Tue Sep 12 20:07:16 EDT 2017 components/images/middle.gif
...
smk     172 Tue Sep 12 20:07:16 EDT 2017 components/images/right.gif
...
  s = signature was verified
  m = entry is listed in manifest
  k = at least one certificate was found in keystore
- Signed by "CN="Oracle America, Inc.", OU=Software Engineering, O="Oracle America, Inc.", L=Redwood City, ST=California, C=US"
    Digest algorithm: SHA-256
    Signature algorithm: SHA256withRSA, 2048-bit key
  Timestamped by "CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US" on Tue Sep 12 20:08:49 UTC 2017
    Timestamp digest algorithm: SHA-1
    Timestamp signature algorithm: SHA1withRSA, 2048-bit key
jar verified.
The signer certificate expired on 2018-02-01. However, the JAR will be valid until the timestamp expires on 2020-12-29.

اگر گواهی یک امضاکننده از نوع گواهی X.509 نباشد، هیچ اطلاعاتی دربارهٔ نام متمایز (distinguished name) وجود نخواهد داشت. در این حالت، فقط نوع گواهی و نام مستعار نمایش داده می‌شوند. برای نمونه، اگر گواهی از نوع گواهی PGP باشد و نام مستعار bob باشد، خروجی به صورت PGP, (bob) خواهد بود.