jdk

1
.\" Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights reserved.
2
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3
.\"
4
.\" This code is free software; you can redistribute it and/or modify it
5
.\" under the terms of the GNU General Public License version 2 only, as
6
.\" published by the Free Software Foundation.
7
.\"
8
.\" This code is distributed in the hope that it will be useful, but WITHOUT
9
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
11
.\" version 2 for more details (a copy is included in the LICENSE file that
12
.\" accompanied this code).
13
.\"
14
.\" You should have received a copy of the GNU General Public License version
15
.\" 2 along with this work; if not, write to the Free Software Foundation,
16
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17
.\"
18
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
19
.\" or visit www.oracle.com if you need additional information or have any
20
.\" questions.
21
.\"
22
'\" t
23
.\" Automatically generated by Pandoc 2.19.2
24
.\"
25
.\" Define V font for inline verbatim, using C font in formats
26
.\" that render this, and otherwise B font.
27
.ie "\f[CB]x\f[R]"x" \{\
28
. ftr V B
29
. ftr VI BI
30
. ftr VB B
31
. ftr VBI BI
32
.\}
33
.el \{\
34
. ftr V CR
35
. ftr VI CI
36
. ftr VB CB
37
. ftr VBI CBI
38
.\}
39
.TH "JARSIGNER" "1" "2025" "JDK 24-ea" "JDK Commands"
40
.hy
41
.SH NAME
42
.PP
43
jarsigner - sign and verify Java Archive (JAR) files
44
.SH SYNOPSIS
45
.PP
46
\f[V]jarsigner\f[R] [\f[I]options\f[R]] \f[I]jar-file\f[R]
47
\f[I]alias\f[R]
48
.PP
49
\f[V]jarsigner\f[R] \f[V]-verify\f[R] [\f[I]options\f[R]]
50
\f[I]jar-file\f[R] [\f[I]alias\f[R] ...]
51
.PP
52
\f[V]jarsigner\f[R] \f[V]-version\f[R]
53
.TP
54
\f[I]options\f[R]
55
The command-line options.
56
See \f[B]Options for jarsigner\f[R].
57
.TP
58
\f[V]-verify\f[R]
59
The \f[V]-verify\f[R] option can take zero or more keystore alias names
60
after the JAR file name.
61
When the \f[V]-verify\f[R] option is specified, the \f[V]jarsigner\f[R]
62
command checks that the certificate used to verify each signed entry in
63
the JAR file matches one of the keystore aliases.
64
The aliases are defined in the keystore specified by \f[V]-keystore\f[R]
65
or the default keystore.
66
.RS
67
.PP
68
If you also specify the \f[V]-strict\f[R] option, and the
69
\f[V]jarsigner\f[R] command detects severe warnings, the message,
70
\[dq]jar verified, with signer errors\[dq] is displayed.
71
.RE
72
.TP
73
\f[I]jar-file\f[R]
74
The JAR file to be signed.
75
.RS
76
.PP
77
If you also specified the \f[V]-strict\f[R] option, and the
78
\f[V]jarsigner\f[R] command detected severe warnings, the message,
79
\[dq]jar signed, with signer errors\[dq] is displayed.
80
.RE
81
.TP
82
\f[I]alias\f[R]
83
The aliases are defined in the keystore specified by \f[V]-keystore\f[R]
84
or the default keystore.
85
.TP
86
\f[V]-version\f[R]
87
The \f[V]-version\f[R] option prints the program version of
88
\f[V]jarsigner\f[R].
89
.SH DESCRIPTION
90
.PP
91
The \f[V]jarsigner\f[R] tool has two purposes:
92
.IP \[bu] 2
93
To sign Java Archive (JAR) files.
94
.IP \[bu] 2
95
To verify the signatures and integrity of signed JAR files.
96
.PP
97
The JAR feature enables the packaging of class files, images, sounds,
98
and other digital data in a single file for faster and easier
99
distribution.
100
A tool named \f[V]jar\f[R] enables developers to produce JAR files.
101
(Technically, any ZIP file can also be considered a JAR file, although
102
when created by the \f[V]jar\f[R] command or processed by the
103
\f[V]jarsigner\f[R] command, JAR files also contain a
104
\f[V]META-INF/MANIFEST.MF\f[R] file.)
105
.PP
106
A digital signature is a string of bits that is computed from some data
107
(the data being signed) and the private key of an entity (a person,
108
company, and so on).
109
Similar to a handwritten signature, a digital signature has many useful
110
characteristics:
111
.IP \[bu] 2
112
Its authenticity can be verified by a computation that uses the public
113
key corresponding to the private key used to generate the signature.
114
.IP \[bu] 2
115
It can\[aq]t be forged, assuming the private key is kept secret.
116
.IP \[bu] 2
117
It is a function of the data signed and thus can\[aq]t be claimed to be
118
the signature for other data as well.
119
.IP \[bu] 2
120
The signed data can\[aq]t be changed.
121
If the data is changed, then the signature can\[aq]t be verified as
122
authentic.
123
.PP
124
To generate an entity\[aq]s signature for a file, the entity must first
125
have a public/private key pair associated with it and one or more
126
certificates that authenticate its public key.
127
A certificate is a digitally signed statement from one entity that says
128
that the public key of another entity has a particular value.
129
.PP
130
The \f[V]jarsigner\f[R] command uses key and certificate information
131
from a keystore to generate digital signatures for JAR files.
132
A keystore is a database of private keys and their associated X.509
133
certificate chains that authenticate the corresponding public keys.
134
The \f[V]keytool\f[R] command is used to create and administer
135
keystores.
136
.PP
137
The \f[V]jarsigner\f[R] command uses an entity\[aq]s private key to
138
generate a signature.
139
The signed JAR file contains, among other things, a copy of the
140
certificate from the keystore for the public key corresponding to the
141
private key used to sign the file.
142
The \f[V]jarsigner\f[R] command can verify the digital signature of the
143
signed JAR file using the certificate inside it (in its signature block
144
file).
145
.PP
146
The \f[V]jarsigner\f[R] command can generate signatures that include a
147
time stamp that enables a systems or deployer to check whether the JAR
148
file was signed while the signing certificate was still valid.
149
.PP
150
In addition, APIs allow applications to obtain the timestamp
151
information.
152
.PP
153
At this time, the \f[V]jarsigner\f[R] command can only sign JAR files
154
created by the \f[V]jar\f[R] command or zip files.
155
JAR files are the same as zip files, except they also have a
156
\f[V]META-INF/MANIFEST.MF\f[R] file.
157
A \f[V]META-INF/MANIFEST.MF\f[R] file is created when the
158
\f[V]jarsigner\f[R] command signs a zip file.
159
.PP
160
The default \f[V]jarsigner\f[R] command behavior is to sign a JAR or zip
161
file.
162
Use the \f[V]-verify\f[R] option to verify a signed JAR file.
163
.PP
164
The \f[V]jarsigner\f[R] command also attempts to validate the
165
signer\[aq]s certificate after signing or verifying.
166
During validation, it checks the revocation status of each certificate
167
in the signer\[aq]s certificate chain when the \f[V]-revCheck\f[R]
168
option is specified.
169
If there is a validation error or any other problem, the command
170
generates warning messages.
171
If you specify the \f[V]-strict\f[R] option, then the command treats
172
severe warnings as errors.
173
See \f[B]Errors and Warnings\f[R].
174
.SH KEYSTORE ALIASES
175
.PP
176
All keystore entities are accessed with unique aliases.
177
.PP
178
When you use the \f[V]jarsigner\f[R] command to sign a JAR file, you
179
must specify the alias for the keystore entry that contains the private
180
key needed to generate the signature.
181
If no output file is specified, it overwrites the original JAR file with
182
the signed JAR file.
183
.PP
184
Keystores are protected with a password, so the store password must be
185
specified.
186
You are prompted for it when you don\[aq]t specify it on the command
187
line.
188
Similarly, private keys are protected in a keystore with a password, so
189
the private key\[aq]s password must be specified, and you are prompted
190
for the password when you don\[aq]t specify it on the command line and
191
it isn\[aq]t the same as the store password.
192
.SH KEYSTORE LOCATION
193
.PP
194
The \f[V]jarsigner\f[R] command has a \f[V]-keystore\f[R] option for
195
specifying the URL of the keystore to be used.
196
The keystore is by default stored in a file named \f[V].keystore\f[R] in
197
the user\[aq]s home directory, as determined by the \f[V]user.home\f[R]
198
system property.
199
.PP
200
\f[B]Linux and macOS:\f[R] \f[V]user.home\f[R] defaults to the
201
user\[aq]s home directory.
202
.PP
203
The input stream from the \f[V]-keystore\f[R] option is passed to the
204
\f[V]KeyStore.load\f[R] method.
205
If \f[V]NONE\f[R] is specified as the URL, then a null stream is passed
206
to the \f[V]KeyStore.load\f[R] method.
207
\f[V]NONE\f[R] should be specified when the \f[V]KeyStore\f[R] class
208
isn\[aq]t file based, for example, when it resides on a hardware token
209
device.
210
.SH KEYSTORE IMPLEMENTATION
211
.PP
212
The \f[V]KeyStore\f[R] class provided in the \f[V]java.security\f[R]
213
package supplies a number of well-defined interfaces to access and
214
modify the information in a keystore.
215
You can have multiple different concrete implementations, where each
216
implementation is for a particular type of keystore.
217
.PP
218
Currently, there are two command-line tools that use keystore
219
implementations (\f[V]keytool\f[R] and \f[V]jarsigner\f[R]).
220
.PP
221
The default keystore implementation is \f[V]PKCS12\f[R].
222
This is a cross platform keystore based on the RSA PKCS12 Personal
223
Information Exchange Syntax Standard.
224
This standard is primarily meant for storing or transporting a
225
user\[aq]s private keys, certificates, and miscellaneous secrets.
226
There is another built-in implementation, provided by Oracle.
227
It implements the keystore as a file with a proprietary keystore type
228
(format) named \f[V]JKS\f[R].
229
It protects each private key with its individual password, and also
230
protects the integrity of the entire keystore with a (possibly
231
different) password.
232
.PP
233
Keystore implementations are provider-based, which means the application
234
interfaces supplied by the \f[V]KeyStore\f[R] class are implemented in
235
terms of a Service Provider Interface (SPI).
236
There is a corresponding abstract \f[V]KeystoreSpi\f[R] class, also in
237
the \f[V]java.security package\f[R], that defines the Service Provider
238
Interface methods that providers must implement.
239
The term provider refers to a package or a set of packages that supply a
240
concrete implementation of a subset of services that can be accessed by
241
the Java Security API.
242
To provide a keystore implementation, clients must implement a provider
243
and supply a \f[V]KeystoreSpi\f[R] subclass implementation, as described
244
in \f[B]How to Implement a Provider in the Java Cryptography
245
Architecture\f[R]
246
[https://www.oracle.com/pls/topic/lookup?ctx=en/java/javase&id=security_guide_implement_provider_jca].
247
.PP
248
Applications can choose different types of keystore implementations from
249
different providers, with the \f[V]getInstance\f[R] factory method in
250
the \f[V]KeyStore\f[R] class.
251
A keystore type defines the storage and data format of the keystore
252
information and the algorithms used to protect private keys in the
253
keystore and the integrity of the keystore itself.
254
Keystore implementations of different types aren\[aq]t compatible.
255
.PP
256
The \f[V]jarsigner\f[R] commands can read file-based keystores from any
257
location that can be specified using a URL.
258
In addition, these commands can read non-file-based keystores such as
259
those provided by MSCAPI on Windows and PKCS11 on all platforms.
260
.PP
261
For the \f[V]jarsigner\f[R] and \f[V]keytool\f[R] commands, you can
262
specify a keystore type at the command line with the
263
\f[V]-storetype\f[R] option.
264
.PP
265
If you don\[aq]t explicitly specify a keystore type, then the tools
266
choose a keystore implementation based on the value of the
267
\f[V]keystore.type\f[R] property specified in the security properties
268
file.
269
The security properties file is called \f[V]java.security\f[R], and it
270
resides in the JDK security properties directory,
271
\f[V]java.home/conf/security\f[R].
272
.PP
273
Each tool gets the \f[V]keystore.type\f[R] value and then examines all
274
the installed providers until it finds one that implements keystores of
275
that type.
276
It then uses the keystore implementation from that provider.
277
.PP
278
The \f[V]KeyStore\f[R] class defines a static method named
279
\f[V]getDefaultType\f[R] that lets applications retrieve the value of
280
the \f[V]keystore.type\f[R] property.
281
The following line of code creates an instance of the default keystore
282
type as specified in the \f[V]keystore.type\f[R] property:
283
.RS
284
.PP
285
\f[V]KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());\f[R]
286
.RE
287
.PP
288
The default keystore type is \f[V]pkcs12\f[R], which is a cross platform
289
keystore based on the RSA PKCS12 Personal Information Exchange Syntax
290
Standard.
291
This is specified by the following line in the security properties file:
292
.RS
293
.PP
294
\f[V]keystore.type=pkcs12\f[R]
295
.RE
296
.PP
297
Case doesn\[aq]t matter in keystore type designations.
298
For example, \f[V]JKS\f[R] is the same as \f[V]jks\f[R].
299
.PP
300
To have the tools utilize a keystore implementation other than the
301
default, you can change that line to specify a different keystore type.
302
For example, if you want to use the Oracle\[aq]s \f[V]jks\f[R] keystore
303
implementation, then change the line to the following:
304
.RS
305
.PP
306
\f[V]keystore.type=jks\f[R]
307
.RE
308
.SH SUPPORTED ALGORITHMS
309
.PP
310
By default, the \f[V]jarsigner\f[R] command signs a JAR file using one
311
of the following algorithms and block file extensions depending on the
312
type and size of the private key:
313
.PP
314
Default Signature Algorithms and Block File Extensions
315
.TS
316
tab(@);
317
l l l l.
318
T{
319
keyalg
320
T}@T{
321
key size
322
T}@T{
323
default sigalg
324
T}@T{
325
block file extension
326
T}
327
_
328
T{
329
DSA
330
T}@T{
331
any size
332
T}@T{
333
SHA256withDSA
334
T}@T{
335
\&.DSA
336
T}
337
T{
338
RSA
339
T}@T{
340
< 624
341
T}@T{
342
SHA256withRSA
343
T}@T{
344
\&.RSA
345
T}
346
T{
347
T}@T{
348
<= 7680
349
T}@T{
350
SHA384withRSA
351
T}@T{
352
T}
353
T{
354
T}@T{
355
> 7680
356
T}@T{
357
SHA512withRSA
358
T}@T{
359
T}
360
T{
361
EC
362
T}@T{
363
< 512
364
T}@T{
365
SHA384withECDSA
366
T}@T{
367
\&.EC
368
T}
369
T{
370
T}@T{
371
>= 512
372
T}@T{
373
SHA512withECDSA
374
T}@T{
375
T}
376
T{
377
RSASSA-PSS
378
T}@T{
379
< 624
380
T}@T{
381
RSASSA-PSS (with SHA-256)
382
T}@T{
383
\&.RSA
384
T}
385
T{
386
T}@T{
387
<= 7680
388
T}@T{
389
RSASSA-PSS (with SHA-384)
390
T}@T{
391
T}
392
T{
393
T}@T{
394
> 7680
395
T}@T{
396
RSASSA-PSS (with SHA-512)
397
T}@T{
398
T}
399
T{
400
EdDSA
401
T}@T{
402
255
403
T}@T{
404
Ed25519
405
T}@T{
406
\&.EC
407
T}
408
T{
409
T}@T{
410
448
411
T}@T{
412
Ed448
413
T}@T{
414
T}
415
.TE
416
.IP \[bu] 2
417
If an RSASSA-PSS key is encoded with parameters, then jarsigner will use
418
the same parameters in the signature.
419
Otherwise, jarsigner will use parameters that are determined by the size
420
of the key as specified in the table above.
421
For example, an 3072-bit RSASSA-PSS key will use RSASSA-PSS as the
422
signature algorithm and SHA-384 as the hash and MGF1 algorithms.
423
.IP \[bu] 2
424
If a key algorithm is not listed in this table, the \f[V].DSA\f[R]
425
extension is used when signing a JAR file.
426
.PP
427
These default signature algorithms can be overridden by using the
428
\f[V]-sigalg\f[R] option.
429
.PP
430
The \f[V]jarsigner\f[R] command uses the
431
\f[V]jdk.jar.disabledAlgorithms\f[R] and
432
\f[V]jdk.security.legacyAlgorithms\f[R] security properties to determine
433
which algorithms are considered a security risk.
434
If the JAR file was signed with any algorithms that are disabled, it
435
will be treated as an unsigned JAR file.
436
If the JAR file was signed with any legacy algorithms, it will be
437
treated as signed with an informational warning to inform users that the
438
legacy algorithm will be disabled in a future update.
439
For detailed verification output, include
440
\f[V]-J-Djava.security.debug=jar\f[R].
441
The \f[V]jdk.jar.disabledAlgorithms\f[R] and
442
\f[V]jdk.security.legacyAlgorithms\f[R] security properties are defined
443
in the \f[V]java.security\f[R] file (located in the JDK\[aq]s
444
\f[V]$JAVA_HOME/conf/security\f[R] directory).
445
.PP
446
\f[B]Note:\f[R]
447
.PP
448
In order to improve out of the box security, default key size and
449
signature algorithm names are periodically updated to stronger values
450
with each release of the JDK.
451
If interoperability with older releases of the JDK is important, please
452
make sure the defaults are supported by those releases, or alternatively
453
use the \f[V]-sigalg\f[R] option to override the default values at your
454
own risk.
455
.SH THE SIGNED JAR FILE
456
.PP
457
When the \f[V]jarsigner\f[R] command is used to sign a JAR file, the
458
output signed JAR file is exactly the same as the input JAR file, except
459
that it has two additional files placed in the META-INF directory:
460
.IP \[bu] 2
461
A signature file with an \f[V].SF\f[R] extension
462
.IP \[bu] 2
463
A signature block file with a \f[V].DSA\f[R], \f[V].RSA\f[R], or
464
\f[V].EC\f[R] extension
465
.PP
466
The base file names for these two files come from the value of the
467
\f[V]-sigfile\f[R] option.
468
For example, when the option is \f[V]-sigfile MKSIGN\f[R], the files are
469
named \f[V]MKSIGN.SF\f[R] and \f[V]MKSIGN.RSA\f[R].
470
In this document, we assume the signer always uses an RSA key.
471
.PP
472
If no \f[V]-sigfile\f[R] option appears on the command line, then the
473
base file name for the \f[V].SF\f[R] and the signature block files is
474
the first 8 characters of the alias name specified on the command line,
475
all converted to uppercase.
476
If the alias name has fewer than 8 characters, then the full alias name
477
is used.
478
If the alias name contains any characters that aren\[aq]t allowed in a
479
signature file name, then each such character is converted to an
480
underscore (_) character in forming the file name.
481
Valid characters include letters, digits, underscores, and hyphens.
482
.SH SIGNATURE FILE
483
.PP
484
A signature file (\f[V].SF\f[R] file) looks similar to the manifest file
485
that is always included in a JAR file when the \f[V]jarsigner\f[R]
486
command is used to sign the file.
487
For each source file included in the JAR file, the \f[V].SF\f[R] file
488
has two lines, such as in the manifest file, that list the following:
489
.IP \[bu] 2
490
File name
491
.IP \[bu] 2
492
Name of the digest algorithm (SHA)
493
.IP \[bu] 2
494
SHA digest value
495
.PP
496
\f[B]Note:\f[R]
497
.PP
498
The name of the digest algorithm (SHA) and the SHA digest value are on
499
the same line.
500
.PP
501
In the manifest file, the SHA digest value for each source file is the
502
digest (hash) of the binary data in the source file.
503
In the \f[V].SF\f[R] file, the digest value for a specified source file
504
is the hash of the two lines in the manifest file for the source file.
505
.PP
506
The signature file, by default, includes a header with a hash of the
507
whole manifest file.
508
The header also contains a hash of the manifest header.
509
The presence of the header enables verification optimization.
510
See \f[B]JAR File Verification\f[R].
511
.SH SIGNATURE BLOCK FILE
512
.PP
513
The \f[V].SF\f[R] file is signed and the signature is placed in the
514
signature block file.
515
This file also contains, encoded inside it, the certificate or
516
certificate chain from the keystore that authenticates the public key
517
corresponding to the private key used for signing.
518
The file has the extension \f[V].DSA\f[R], \f[V].RSA\f[R], or
519
\f[V].EC\f[R], depending on the key algorithm used.
520
See the table in \f[B]Supported Algorithms\f[R].
521
.SH SIGNATURE TIME STAMP
522
.PP
523
The \f[V]jarsigner\f[R] command used with the following options
524
generates and stores a signature time stamp when signing a JAR file:
525
.IP \[bu] 2
526
\f[V]-tsa\f[R] \f[I]url\f[R]
527
.IP \[bu] 2
528
\f[V]-tsacert\f[R] \f[I]alias\f[R]
529
.IP \[bu] 2
530
\f[V]-tsapolicyid\f[R] \f[I]policyid\f[R]
531
.IP \[bu] 2
532
\f[V]-tsadigestalg\f[R] \f[I]algorithm\f[R]
533
.PP
534
See \f[B]Options for jarsigner\f[R].
535
.SH JAR FILE VERIFICATION
536
.PP
537
A successful JAR file verification occurs when the signatures are valid,
538
and none of the files that were in the JAR file when the signatures were
539
generated have changed since then.
540
JAR file verification involves the following steps:
541
.IP "1." 3
542
Verify the signature of the \f[V].SF\f[R] file.
543
.RS 4
544
.PP
545
The verification ensures that the signature stored in each signature
546
block file was generated using the private key corresponding to the
547
public key whose certificate (or certificate chain) also appears in the
548
signature block file.
549
It also ensures that the signature is a valid signature of the
550
corresponding signature (\f[V].SF\f[R]) file, and thus the \f[V].SF\f[R]
551
file wasn\[aq]t tampered with.
552
.RE
553
.IP "2." 3
554
Verify the digest listed in each entry in the \f[V].SF\f[R] file with
555
each corresponding section in the manifest.
556
.RS 4
557
.PP
558
The \f[V].SF\f[R] file by default includes a header that contains a hash
559
of the entire manifest file.
560
When the header is present, the verification can check to see whether or
561
not the hash in the header matches the hash of the manifest file.
562
If there is a match, then verification proceeds to the next step.
563
.PP
564
If there is no match, then a less optimized verification is required to
565
ensure that the hash in each source file information section in the
566
\f[V].SF\f[R] file equals the hash of its corresponding section in the
567
manifest file.
568
See Signature File.
569
.PP
570
One reason the hash of the manifest file that is stored in the
571
\f[V].SF\f[R] file header might not equal the hash of the current
572
manifest file is that it might contain sections for newly added files
573
after the file was signed.
574
For example, suppose one or more files were added to the signed JAR file
575
(using the \f[V]jar\f[R] tool) that already contains a signature and a
576
\f[V].SF\f[R] file.
577
If the JAR file is signed again by a different signer, then the manifest
578
file is changed (sections are added to it for the new files by the
579
\f[V]jarsigner\f[R] tool) and a new \f[V].SF\f[R] file is created, but
580
the original \f[V].SF\f[R] file is unchanged.
581
A verification is still considered successful if none of the files that
582
were in the JAR file when the original signature was generated have been
583
changed since then.
584
This is because the hashes in the non-header sections of the
585
\f[V].SF\f[R] file equal the hashes of the corresponding sections in the
586
manifest file.
587
.RE
588
.IP "3." 3
589
Read each file in the JAR file that has an entry in the \f[V].SF\f[R]
590
file.
591
While reading, compute the file\[aq]s digest and compare the result with
592
the digest for this file in the manifest section.
593
The digests should be the same or verification fails.
594
.RS 4
595
.PP
596
If any serious verification failures occur during the verification
597
process, then the process is stopped and a security exception is thrown.
598
The \f[V]jarsigner\f[R] command catches and displays the exception.
599
.RE
600
.IP "4." 3
601
Check for disabled algorithm usage.
602
See \f[B]Supported Algorithms\f[R].
603
.PP
604
\f[B]Note:\f[R]
605
.PP
606
You should read any addition warnings (or errors if you specified the
607
\f[V]-strict\f[R] option), as well as the content of the certificate (by
608
specifying the \f[V]-verbose\f[R] and \f[V]-certs\f[R] options) to
609
determine if the signature can be trusted.
610
.SH MULTIPLE SIGNATURES FOR A JAR FILE
611
.PP
612
A JAR file can be signed by multiple people by running the
613
\f[V]jarsigner\f[R] command on the file multiple times and specifying
614
the alias for a different person each time, as follows:
615
.IP
616
.nf
617
\f[CB]
618
jarsigner myBundle.jar susan
619
jarsigner myBundle.jar kevin
620
\f[R]
621
.fi
622
.PP
623
When a JAR file is signed multiple times, there are multiple
624
\f[V].SF\f[R] and signature block files in the resulting JAR file, one
625
pair for each signature.
626
In the previous example, the output JAR file includes files with the
627
following names:
628
.IP
629
.nf
630
\f[CB]
631
SUSAN.SF
632
SUSAN.RSA
633
KEVIN.SF
634
KEVIN.RSA
635
\f[R]
636
.fi
637
.SH OPTIONS FOR JARSIGNER
638
.PP
639
The following sections describe the options for the \f[V]jarsigner\f[R].
640
Be aware of the following standards:
641
.IP \[bu] 2
642
All option names are preceded by a hyphen sign (-).
643
.IP \[bu] 2
644
The options can be provided in any order.
645
.IP \[bu] 2
646
Items that are in italics or underlined (option values) represent the
647
actual values that must be supplied.
648
.IP \[bu] 2
649
The \f[V]-storepass\f[R], \f[V]-keypass\f[R], \f[V]-sigfile\f[R],
650
\f[V]-sigalg\f[R], \f[V]-digestalg\f[R], \f[V]-signedjar\f[R], and
651
TSA-related options are only relevant when signing a JAR file; they
652
aren\[aq]t relevant when verifying a signed JAR file.
653
The \f[V]-keystore\f[R] option is relevant for signing and verifying a
654
JAR file.
655
In addition, aliases are specified when signing and verifying a JAR
656
file.
657
.TP
658
\f[V]-keystore\f[R] \f[I]url\f[R]
659
Specifies the URL that tells the keystore location.
660
This defaults to the file \f[V].keystore\f[R] in the user\[aq]s home
661
directory, as determined by the \f[V]user.home\f[R] system property.
662
.RS
663
.PP
664
A keystore is required when signing.
665
You must explicitly specify a keystore when the default keystore
666
doesn\[aq]t exist or if you want to use one other than the default.
667
.PP
668
A keystore isn\[aq]t required when verifying, but if one is specified or
669
the default exists and the \f[V]-verbose\f[R] option was also specified,
670
then additional information is output regarding whether or not any of
671
the certificates used to verify the JAR file are contained in that
672
keystore.
673
.PP
674
The \f[V]-keystore\f[R] argument can be a file name and path
675
specification rather than a URL, in which case it is treated the same as
676
a file: URL, for example, the following are equivalent:
677
.IP \[bu] 2
678
\f[V]-keystore\f[R] \f[I]filePathAndName\f[R]
679
.IP \[bu] 2
680
\f[V]-keystore file:\f[R]\f[I]filePathAndName\f[R]
681
.PP
682
If the Sun PKCS #11 provider was configured in the
683
\f[V]java.security\f[R] security properties file (located in the
684
JDK\[aq]s \f[V]$JAVA_HOME/conf/security\f[R] directory), then the
685
\f[V]keytool\f[R] and \f[V]jarsigner\f[R] tools can operate on the PKCS
686
#11 token by specifying these options:
687
.RS
688
.PP
689
\f[V]-keystore NONE -storetype PKCS11\f[R]
690
.RE
691
.PP
692
For example, the following command lists the contents of the configured
693
PKCS#11 token:
694
.RS
695
.PP
696
\f[V]keytool -keystore NONE -storetype PKCS11 -list\f[R]
697
.RE
698
.RE
699
.TP
700
\f[V]-storepass\f[R] [\f[V]:env\f[R] | \f[V]:file\f[R]] \f[I]argument\f[R]
701
Specifies the password that is required to access the keystore.
702
This is only needed when signing (not verifying) a JAR file.
703
In that case, if a \f[V]-storepass\f[R] option isn\[aq]t provided at the
704
command line, then the user is prompted for the password.
705
.RS
706
.PP
707
If the modifier \f[V]env\f[R] or \f[V]file\f[R] isn\[aq]t specified,
708
then the password has the value \f[V]argument\f[R].
709
Otherwise, the password is retrieved as follows:
710
.IP \[bu] 2
711
\f[V]env\f[R]: Retrieve the password from the environment variable named
712
\f[I]argument\f[R].
713
.IP \[bu] 2
714
\f[V]file\f[R]: Retrieve the password from the file named
715
\f[I]argument\f[R].
716
.PP
717
\f[B]Note:\f[R]
718
.PP
719
The password shouldn\[aq]t be specified on the command line or in a
720
script unless it is for testing purposes, or you are on a secure system.
721
.RE
722
.TP
723
\f[V]-storetype\f[R] \f[I]storetype\f[R]
724
Specifies the type of keystore to be instantiated.
725
The default keystore type is the one that is specified as the value of
726
the \f[V]keystore.type\f[R] property in the security properties file,
727
which is returned by the static \f[V]getDefaultType\f[R] method in
728
\f[V]java.security.KeyStore\f[R].
729
.RS
730
.PP
731
The PIN for a PKCS #11 token can also be specified with the
732
\f[V]-storepass\f[R] option.
733
If none is specified, then the \f[V]keytool\f[R] and \f[V]jarsigner\f[R]
734
commands prompt for the token PIN.
735
If the token has a protected authentication path (such as a dedicated
736
PIN-pad or a biometric reader), then the \f[V]-protected\f[R] option
737
must be specified and no password options can be specified.
738
.RE
739
.TP
740
\f[V]-keypass\f[R] [\f[V]:env\f[R] | \f[V]:file\f[R]] \f[I]argument\f[R] \f[V]-certchain\f[R] \f[I]file\f[R]
741
Specifies the password used to protect the private key of the keystore
742
entry addressed by the alias specified on the command line.
743
The password is required when using \f[V]jarsigner\f[R] to sign a JAR
744
file.
745
If no password is provided on the command line, and the required
746
password is different from the store password, then the user is prompted
747
for it.
748
.RS
749
.PP
750
If the modifier \f[V]env\f[R] or \f[V]file\f[R] isn\[aq]t specified,
751
then the password has the value \f[V]argument\f[R].
752
Otherwise, the password is retrieved as follows:
753
.IP \[bu] 2
754
\f[V]env\f[R]: Retrieve the password from the environment variable named
755
\f[I]argument\f[R].
756
.IP \[bu] 2
757
\f[V]file\f[R]: Retrieve the password from the file named
758
\f[I]argument\f[R].
759
.PP
760
\f[B]Note:\f[R]
761
.PP
762
The password shouldn\[aq]t be specified on the command line or in a
763
script unless it is for testing purposes, or you are on a secure system.
764
.RE
765
.TP
766
\f[V]-certchain\f[R] \f[I]file\f[R]
767
Specifies the certificate chain to be used when the certificate chain
768
associated with the private key of the keystore entry that is addressed
769
by the alias specified on the command line isn\[aq]t complete.
770
This can happen when the keystore is located on a hardware token where
771
there isn\[aq]t enough capacity to hold a complete certificate chain.
772
The file can be a sequence of concatenated X.509 certificates, or a
773
single PKCS#7 formatted data block, either in binary encoding format or
774
in printable encoding format (also known as Base64 encoding) as defined
775
by \f[B]Internet RFC 1421 Certificate Encoding Standard\f[R]
776
[http://tools.ietf.org/html/rfc1421].
777
.TP
778
\f[V]-sigfile\f[R] \f[I]file\f[R]
779
Specifies the base file name to be used for the generated \f[V].SF\f[R]
780
and signature block files.
781
For example, if file is \f[V]DUKESIGN\f[R], then the generated
782
\f[V].SF\f[R] and signature block files are named \f[V]DUKESIGN.SF\f[R]
783
and \f[V]DUKESIGN.RSA\f[R], and placed in the \f[V]META-INF\f[R]
784
directory of the signed JAR file.
785
.RS
786
.PP
787
The characters in the file must come from the set \f[V]a-zA-Z0-9_-\f[R].
788
Only letters, numbers, underscore, and hyphen characters are allowed.
789
All lowercase characters are converted to uppercase for the
790
\f[V].SF\f[R] and signature block file names.
791
.PP
792
If no \f[V]-sigfile\f[R] option appears on the command line, then the
793
base file name for the \f[V].SF\f[R] and signature block files is the
794
first 8 characters of the alias name specified on the command line, all
795
converted to upper case.
796
If the alias name has fewer than 8 characters, then the full alias name
797
is used.
798
If the alias name contains any characters that aren\[aq]t valid in a
799
signature file name, then each such character is converted to an
800
underscore (_) character to form the file name.
801
.RE
802
.TP
803
\f[V]-signedjar\f[R] \f[I]file\f[R]
804
Specifies the name of signed JAR file.
805
.TP
806
\f[V]-digestalg\f[R] \f[I]algorithm\f[R]
807
Specifies the name of the message digest algorithm to use when digesting
808
the entries of a JAR file.
809
.RS
810
.PP
811
For a list of standard message digest algorithm names, see the Java
812
Security Standard Algorithm Names Specification.
813
.PP
814
If this option isn\[aq]t specified, then \f[V]SHA-384\f[R] is used.
815
There must either be a statically installed provider supplying an
816
implementation of the specified algorithm or the user must specify one
817
with the \f[V]-addprovider\f[R] or \f[V]-providerClass\f[R] options;
818
otherwise, the command will not succeed.
819
.RE
820
.TP
821
\f[V]-sigalg\f[R] \f[I]algorithm\f[R]
822
Specifies the name of the signature algorithm to use to sign the JAR
823
file.
824
.RS
825
.PP
826
This algorithm must be compatible with the private key used to sign the
827
JAR file.
828
If this option isn\[aq]t specified, then use a default algorithm
829
matching the private key as described in the \f[B]Supported
830
Algorithms\f[R] section.
831
There must either be a statically installed provider supplying an
832
implementation of the specified algorithm or you must specify one with
833
the \f[V]-addprovider\f[R] or \f[V]-providerClass\f[R] option;
834
otherwise, the command doesn\[aq]t succeed.
835
.PP
836
For a list of standard signature algorithm names, see the Java Security
837
Standard Algorithm Names Specification.
838
.RE
839
.TP
840
\f[V]-verify\f[R]
841
Verifies a signed JAR file.
842
.TP
843
\f[V]-verbose\f[R][\f[V]:\f[R]\f[I]suboptions\f[R]]
844
When the \f[V]-verbose\f[R] option appears on the command line, it
845
indicates that the \f[V]jarsigner\f[R] use the verbose mode when signing
846
or verifying with the suboptions determining how much information is
847
shown.
848
This causes the , which causes \f[V]jarsigner\f[R] to output extra
849
information about the progress of the JAR signing or verification.
850
The \f[I]suboptions\f[R] can be \f[V]all\f[R], \f[V]grouped\f[R], or
851
\f[V]summary\f[R].
852
.RS
853
.PP
854
If the \f[V]-certs\f[R] option is also specified, then the default mode
855
(or suboption \f[V]all\f[R]) displays each entry as it is being
856
processed, and after that, the certificate information for each signer
857
of the JAR file.
858
.PP
859
If the \f[V]-certs\f[R] and the \f[V]-verbose:grouped\f[R] suboptions
860
are specified, then entries with the same signer info are grouped and
861
displayed together with their certificate information.
862
.PP
863
If \f[V]-certs\f[R] and the \f[V]-verbose:summary\f[R] suboptions are
864
specified, then entries with the same signer information are grouped and
865
displayed together with their certificate information.
866
.PP
867
Details about each entry are summarized and displayed as \f[I]one entry
868
(and more)\f[R].
869
See \f[B]Example of Verifying a Signed JAR File\f[R] and \f[B]Example of
870
Verification with Certificate Information\f[R].
871
.RE
872
.TP
873
\f[V]-certs\f[R]
874
If the \f[V]-certs\f[R] option appears on the command line with the
875
\f[V]-verify\f[R] and \f[V]-verbose\f[R] options, then the output
876
includes certificate information for each signer of the JAR file.
877
This information includes the name of the type of certificate (stored in
878
the signature block file) that certifies the signer\[aq]s public key,
879
and if the certificate is an X.509 certificate (an instance of the
880
\f[V]java.security.cert.X509Certificate\f[R]), then the distinguished
881
name of the signer.
882
.RS
883
.PP
884
The keystore is also examined.
885
If no keystore value is specified on the command line, then the default
886
keystore file (if any) is checked.
887
If the public key certificate for a signer matches an entry in the
888
keystore, then the alias name for the keystore entry for that signer is
889
displayed in parentheses.
890
.RE
891
.TP
892
\f[V]-revCheck\f[R]
893
This option enables revocation checking of certificates when signing or
894
verifying a JAR file.
895
The \f[V]jarsigner\f[R] command attempts to make network connections to
896
fetch OCSP responses and CRLs if the \f[V]-revCheck\f[R] option is
897
specified on the command line.
898
Note that revocation checks are not enabled unless this option is
899
specified.
900
.TP
901
\f[V]-tsa\f[R] \f[I]url\f[R]
902
If \f[V]-tsa http://example.tsa.url\f[R] appears on the command line
903
when signing a JAR file then a time stamp is generated for the
904
signature.
905
The URL, \f[V]http://example.tsa.url\f[R], identifies the location of
906
the Time Stamping Authority (TSA) and overrides any URL found with the
907
\f[V]-tsacert\f[R] option.
908
The \f[V]-tsa\f[R] option doesn\[aq]t require the TSA public key
909
certificate to be present in the keystore.
910
.RS
911
.PP
912
To generate the time stamp, \f[V]jarsigner\f[R] communicates with the
913
TSA with the Time-Stamp Protocol (TSP) defined in RFC 3161.
914
When successful, the time stamp token returned by the TSA is stored with
915
the signature in the signature block file.
916
.RE
917
.TP
918
\f[V]-tsacert\f[R] \f[I]alias\f[R]
919
When \f[V]-tsacert\f[R] \f[I]alias\f[R] appears on the command line when
920
signing a JAR file, a time stamp is generated for the signature.
921
The alias identifies the TSA public key certificate in the keystore that
922
is in effect.
923
The entry\[aq]s certificate is examined for a Subject Information Access
924
extension that contains a URL identifying the location of the TSA.
925
.RS
926
.PP
927
The TSA public key certificate must be present in the keystore when
928
using the \f[V]-tsacert\f[R] option.
929
.RE
930
.TP
931
\f[V]-tsapolicyid\f[R] \f[I]policyid\f[R]
932
Specifies the object identifier (OID) that identifies the policy ID to
933
be sent to the TSA server.
934
If this option isn\[aq]t specified, no policy ID is sent and the TSA
935
server will choose a default policy ID.
936
.RS
937
.PP
938
Object identifiers are defined by X.696, which is an ITU
939
Telecommunication Standardization Sector (ITU-T) standard.
940
These identifiers are typically period-separated sets of non-negative
941
digits like \f[V]1.2.3.4\f[R], for example.
942
.RE
943
.TP
944
\f[V]-tsadigestalg\f[R] \f[I]algorithm\f[R]
945
Specifies the message digest algorithm that is used to generate the
946
message imprint to be sent to the TSA server.
947
If this option isn\[aq]t specified, SHA-384 will be used.
948
.RS
949
.PP
950
See \f[B]Supported Algorithms\f[R].
951
.PP
952
For a list of standard message digest algorithm names, see the Java
953
Security Standard Algorithm Names Specification.
954
.RE
955
.TP
956
\f[V]-internalsf\f[R]
957
In the past, the signature block file generated when a JAR file was
958
signed included a complete encoded copy of the \f[V].SF\f[R] file
959
(signature file) also generated.
960
This behavior has been changed.
961
To reduce the overall size of the output JAR file, the signature block
962
file by default doesn\[aq]t contain a copy of the \f[V].SF\f[R] file
963
anymore.
964
If \f[V]-internalsf\f[R] appears on the command line, then the old
965
behavior is utilized.
966
This option is useful for testing.
967
In practice, don\[aq]t use the \f[V]-internalsf\f[R] option because it
968
incurs higher overhead.
969
.TP
970
\f[V]-sectionsonly\f[R]
971
If the \f[V]-sectionsonly\f[R] option appears on the command line, then
972
the \f[V].SF\f[R] file (signature file) generated when a JAR file is
973
signed doesn\[aq]t include a header that contains a hash of the whole
974
manifest file.
975
It contains only the information and hashes related to each individual
976
source file included in the JAR file.
977
See Signature File.
978
.RS
979
.PP
980
By default, this header is added, as an optimization.
981
When the header is present, whenever the JAR file is verified, the
982
verification can first check to see whether the hash in the header
983
matches the hash of the whole manifest file.
984
When there is a match, verification proceeds to the next step.
985
When there is no match, it is necessary to do a less optimized
986
verification that the hash in each source file information section in
987
the \f[V].SF\f[R] file equals the hash of its corresponding section in
988
the manifest file.
989
See \f[B]JAR File Verification\f[R].
990
.PP
991
The \f[V]-sectionsonly\f[R] option is primarily used for testing.
992
It shouldn\[aq]t be used other than for testing because using it incurs
993
higher overhead.
994
.RE
995
.TP
996
\f[V]-protected\f[R]
997
Values can be either \f[V]true\f[R] or \f[V]false\f[R].
998
Specify \f[V]true\f[R] when a password must be specified through a
999
protected authentication path such as a dedicated PIN reader.
1000
.TP
1001
\f[V]-providerName\f[R] \f[I]providerName\f[R]
1002
If more than one provider was configured in the \f[V]java.security\f[R]
1003
security properties file, then you can use the \f[V]-providerName\f[R]
1004
option to target a specific provider instance.
1005
The argument to this option is the name of the provider.
1006
.RS
1007
.PP
1008
For the Oracle PKCS #11 provider, \f[I]providerName\f[R] is of the form
1009
\f[V]SunPKCS11-\f[R]\f[I]TokenName\f[R], where \f[I]TokenName\f[R] is
1010
the name suffix that the provider instance has been configured with, as
1011
detailed in the configuration attributes table.
1012
For example, the following command lists the contents of the
1013
\f[V]PKCS #11\f[R] keystore provider instance with name suffix
1014
\f[V]SmartCard\f[R]:
1015
.RS
1016
.PP
1017
\f[V]jarsigner -keystore NONE -storetype PKCS11 -providerName SunPKCS11-SmartCard -list\f[R]
1018
.RE
1019
.RE
1020
.TP
1021
\f[V]-addprovider\f[R] \f[I]name\f[R] [\f[V]-providerArg\f[R] \f[I]arg\f[R]]
1022
Adds a security provider by name (such as SunPKCS11) and an optional
1023
configure argument.
1024
The value of the security provider is the name of a security provider
1025
that is defined in a module.
1026
.RS
1027
.PP
1028
Used with the \f[V]-providerArg ConfigFilePath\f[R] option, the
1029
\f[V]keytool\f[R] and \f[V]jarsigner\f[R] tools install the provider
1030
dynamically and use \f[V]ConfigFilePath\f[R] for the path to the token
1031
configuration file.
1032
The following example shows a command to list a \f[V]PKCS #11\f[R]
1033
keystore when the Oracle PKCS #11 provider wasn\[aq]t configured in the
1034
security properties file.
1035
.RS
1036
.PP
1037
\f[V]jarsigner -keystore NONE -storetype PKCS11 -addprovider SunPKCS11 -providerArg /mydir1/mydir2/token.config\f[R]
1038
.RE
1039
.RE
1040
.TP
1041
\f[V]-providerClass\f[R] \f[I]provider-class-name\f[R] [\f[V]-providerArg\f[R] \f[I]arg\f[R]]
1042
Used to specify the name of cryptographic service provider\[aq]s master
1043
class file when the service provider isn\[aq]t listed in the
1044
\f[V]java.security\f[R] security properties file.
1045
Adds a security provider by fully-qualified class name and an optional
1046
configure argument.
1047
.RS
1048
.PP
1049
\f[B]Note:\f[R]
1050
.PP
1051
The preferred way to load PKCS11 is by using modules.
1052
See \f[V]-addprovider\f[R].
1053
.RE
1054
.TP
1055
\f[V]-providerPath\f[R] \f[I]classpath\f[R]
1056
Used to specify the classpath for providers specified by the
1057
\f[V]-providerClass\f[R] option.
1058
Multiple paths should be separated by the system-dependent
1059
path-separator character.
1060
.TP
1061
\f[V]-J\f[R]\f[I]javaoption\f[R]
1062
Passes through the specified \f[I]javaoption\f[R] string directly to the
1063
Java interpreter.
1064
The \f[V]jarsigner\f[R] command is a wrapper around the interpreter.
1065
This option shouldn\[aq]t contain any spaces.
1066
It is useful for adjusting the execution environment or memory usage.
1067
For a list of possible interpreter options, type \f[V]java -h\f[R] or
1068
\f[V]java -X\f[R] at the command line.
1069
.TP
1070
\f[V]-strict\f[R]
1071
During the signing or verifying process, the command may issue warning
1072
messages.
1073
If you specify this option, the exit code of the tool reflects the
1074
severe warning messages that this command found.
1075
See \f[B]Errors and Warnings\f[R].
1076
.TP
1077
\f[V]-conf\f[R] \f[I]url\f[R]
1078
Specifies a pre-configured options file.
1079
Read the \f[B]keytool documentation\f[R] for details.
1080
The property keys supported are \[dq]jarsigner.all\[dq] for all actions,
1081
\[dq]jarsigner.sign\[dq] for signing, and \[dq]jarsigner.verify\[dq] for
1082
verification.
1083
\f[V]jarsigner\f[R] arguments including the JAR file name and alias
1084
name(s) cannot be set in this file.
1085
.TP
1086
\f[V]-version\f[R]
1087
Prints the program version.
1088
.SH ERRORS AND WARNINGS
1089
.PP
1090
During the signing or verifying process, the \f[V]jarsigner\f[R] command
1091
may issue various errors or warnings.
1092
.PP
1093
If there is a failure, the \f[V]jarsigner\f[R] command exits with code
1094
1.
1095
If there is no failure, but there are one or more severe warnings, the
1096
\f[V]jarsigner\f[R] command exits with code 0 when the \f[V]-strict\f[R]
1097
option is \f[B]not\f[R] specified, or exits with the OR-value of the
1098
warning codes when the \f[V]-strict\f[R] is specified.
1099
If there is only informational warnings or no warning at all, the
1100
command always exits with code 0.
1101
.PP
1102
For example, if a certificate used to sign an entry is expired and has a
1103
KeyUsage extension that doesn\[aq]t allow it to sign a file, the
1104
\f[V]jarsigner\f[R] command exits with code 12 (=4+8) when the
1105
\f[V]-strict\f[R] option is specified.
1106
.PP
1107
\f[B]Note:\f[R] Exit codes are reused because only the values from 0 to
1108
255 are legal on Linux and macOS.
1109
.PP
1110
The following sections describes the names, codes, and descriptions of
1111
the errors and warnings that the \f[V]jarsigner\f[R] command can issue.
1112
.SH FAILURE
1113
.PP
1114
Reasons why the \f[V]jarsigner\f[R] command fails include (but
1115
aren\[aq]t limited to) a command line parsing error, the inability to
1116
find a keypair to sign the JAR file, or the verification of a signed JAR
1117
fails.
1118
.TP
1119
failure
1120
Code 1.
1121
The signing or verifying fails.
1122
.SH SEVERE WARNINGS
1123
.PP
1124
\f[B]Note:\f[R]
1125
.PP
1126
Severe warnings are reported as errors if you specify the
1127
\f[V]-strict\f[R] option.
1128
.PP
1129
Reasons why the \f[V]jarsigner\f[R] command issues a severe warning
1130
include the certificate used to sign the JAR file has an error or the
1131
signed JAR file has other problems.
1132
.TP
1133
hasExpiredCert
1134
Code 4.
1135
This JAR contains entries whose signer certificate has expired.
1136
.TP
1137
hasExpiredTsaCert
1138
Code 4.
1139
The timestamp has expired.
1140
.TP
1141
notYetValidCert
1142
Code 4.
1143
This JAR contains entries whose signer certificate isn\[aq]t yet valid.
1144
.TP
1145
chainNotValidated
1146
Code 4.
1147
This JAR contains entries whose certificate chain isn\[aq]t validated.
1148
.TP
1149
tsaChainNotValidated
1150
Code 64.
1151
The timestamp is invalid.
1152
.TP
1153
signerSelfSigned
1154
Code 4.
1155
This JAR contains entries whose signer certificate is self signed.
1156
.TP
1157
disabledAlg
1158
Code 4.
1159
An algorithm used is considered a security risk and is disabled.
1160
.TP
1161
badKeyUsage
1162
Code 8.
1163
This JAR contains entries whose signer certificate\[aq]s KeyUsage
1164
extension doesn\[aq]t allow code signing.
1165
.TP
1166
badExtendedKeyUsage
1167
Code 8.
1168
This JAR contains entries whose signer certificate\[aq]s
1169
ExtendedKeyUsage extension doesn\[aq]t allow code signing.
1170
.TP
1171
badNetscapeCertType
1172
Code 8.
1173
This JAR contains entries whose signer certificate\[aq]s
1174
NetscapeCertType extension doesn\[aq]t allow code signing.
1175
.TP
1176
hasUnsignedEntry
1177
Code 16.
1178
This JAR contains unsigned entries which haven\[aq]t been
1179
integrity-checked.
1180
.TP
1181
notSignedByAlias
1182
Code 32.
1183
This JAR contains signed entries which aren\[aq]t signed by the
1184
specified alias(es).
1185
.TP
1186
aliasNotInStore
1187
Code 32.
1188
This JAR contains signed entries that aren\[aq]t signed by alias in this
1189
keystore.
1190
.TP
1191
tsaChainNotValidated
1192
Code 64.
1193
This JAR contains entries whose TSA certificate chain is invalid.
1194
.SH INFORMATIONAL WARNINGS
1195
.PP
1196
Informational warnings include those that aren\[aq]t errors but regarded
1197
as bad practice.
1198
They don\[aq]t have a code.
1199
.TP
1200
extraAttributesDetected
1201
The POSIX file permissions and/or symlink attributes are detected during
1202
signing or verifying a JAR file.
1203
The \f[V]jarsigner\f[R] tool preserves these attributes in the newly
1204
signed file but warns that these attributes are unsigned and not
1205
protected by the signature.
1206
.TP
1207
hasExpiringCert
1208
This JAR contains entries whose signer certificate expires within six
1209
months.
1210
.TP
1211
hasExpiringTsaCert
1212
The timestamp will expire within one year on \f[V]YYYY-MM-DD\f[R].
1213
.TP
1214
legacyAlg
1215
An algorithm used is considered a security risk but not disabled.
1216
.TP
1217
noTimestamp
1218
This JAR contains signatures that doesn\[aq]t include a timestamp.
1219
Without a timestamp, users may not be able to validate this JAR file
1220
after the signer certificate\[aq]s expiration date
1221
(\f[V]YYYY-MM-DD\f[R]) or after any future revocation date.
1222
.SH EXAMPLE OF SIGNING A JAR FILE
1223
.PP
1224
Use the following command to sign \f[V]bundle.jar\f[R] with the private
1225
key of a user whose keystore alias is \f[V]jane\f[R] in a keystore named
1226
\f[V]mystore\f[R] in the \f[V]working\f[R] directory and name the signed
1227
JAR file \f[V]sbundle.jar\f[R]:
1228
.RS
1229
.PP
1230
\f[V]jarsigner -keystore /working/mystore -storepass\f[R]
1231
\f[I]keystore_password\f[R] \f[V]-keypass\f[R]
1232
\f[I]private_key_password\f[R]
1233
\f[V]-signedjar sbundle.jar bundle.jar jane\f[R]
1234
.RE
1235
.PP
1236
There is no \f[V]-sigfile\f[R] specified in the previous command so the
1237
generated \f[V].SF\f[R] and signature block files to be placed in the
1238
signed JAR file have default names based on the alias name.
1239
They are named \f[V]JANE.SF\f[R] and \f[V]JANE.RSA\f[R].
1240
.PP
1241
If you want to be prompted for the store password and the private key
1242
password, then you could shorten the previous command to the following:
1243
.RS
1244
.PP
1245
\f[V]jarsigner -keystore /working/mystore -signedjar sbundle.jar bundle.jar jane\f[R]
1246
.RE
1247
.PP
1248
If the \f[V]keystore\f[R] is the default \f[V]keystore\f[R]
1249
(\f[V].keystore\f[R] in your home directory), then you don\[aq]t need to
1250
specify a \f[V]keystore\f[R], as follows:
1251
.RS
1252
.PP
1253
\f[V]jarsigner -signedjar sbundle.jar bundle.jar jane\f[R]
1254
.RE
1255
.PP
1256
If you want the signed JAR file to overwrite the input JAR file
1257
(\f[V]bundle.jar\f[R]), then you don\[aq]t need to specify a
1258
\f[V]-signedjar\f[R] option, as follows:
1259
.RS
1260
.PP
1261
\f[V]jarsigner bundle.jar jane\f[R]
1262
.RE
1263
.SH EXAMPLE OF VERIFYING A SIGNED JAR FILE
1264
.PP
1265
To verify a signed JAR file to ensure that the signature is valid and
1266
the JAR file wasn\[aq]t been tampered with, use a command such as the
1267
following:
1268
.RS
1269
.PP
1270
\f[V]jarsigner -verify ButtonDemo.jar\f[R]
1271
.RE
1272
.PP
1273
When the verification is successful, \f[V]jar verified\f[R] is
1274
displayed.
1275
Otherwise, an error message is displayed.
1276
You can get more information when you use the \f[V]-verbose\f[R] option.
1277
A sample use of \f[V]jarsigner\f[R] with the \f[V]-verbose\f[R] option
1278
follows:
1279
.IP
1280
.nf
1281
\f[CB]
1282
jarsigner -verify -verbose ButtonDemo.jar
1283

1284
s       866 Tue Sep 12 20:08:48 EDT 2017 META-INF/MANIFEST.MF
1285
        825 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.SF
1286
       7475 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.RSA
1287
          0 Tue Sep 12 20:07:54 EDT 2017 META-INF/
1288
          0 Tue Sep 12 20:07:16 EDT 2017 components/
1289
          0 Tue Sep 12 20:07:16 EDT 2017 components/images/
1290
sm      523 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo$1.class
1291
sm     3440 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.class
1292
sm     2346 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.jnlp
1293
sm      172 Tue Sep 12 20:07:16 EDT 2017 components/images/left.gif
1294
sm      235 Tue Sep 12 20:07:16 EDT 2017 components/images/middle.gif
1295
sm      172 Tue Sep 12 20:07:16 EDT 2017 components/images/right.gif
1296

1297
  s = signature was verified
1298
  m = entry is listed in manifest
1299
  k = at least one certificate was found in keystore
1300

1301
- Signed by \[dq]CN=\[dq]Oracle America, Inc.\[dq], OU=Software Engineering, O=\[dq]Oracle America, Inc.\[dq], L=Redwood City, ST=California, C=US\[dq]
1302
    Digest algorithm: SHA-256
1303
    Signature algorithm: SHA256withRSA, 2048-bit key
1304
  Timestamped by \[dq]CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US\[dq] on Tue Sep 12 20:08:49 UTC 2017
1305
    Timestamp digest algorithm: SHA-1
1306
    Timestamp signature algorithm: SHA1withRSA, 2048-bit key
1307

1308
jar verified.
1309

1310
The signer certificate expired on 2018-02-01. However, the JAR will be valid until the timestamp expires on 2020-12-29.
1311
\f[R]
1312
.fi
1313
.SH EXAMPLE OF VERIFICATION WITH CERTIFICATE INFORMATION
1314
.PP
1315
If you specify the \f[V]-certs\f[R] option with the \f[V]-verify\f[R]
1316
and \f[V]-verbose\f[R] options, then the output includes certificate
1317
information for each signer of the JAR file.
1318
The information includes the certificate type, the signer distinguished
1319
name information (when it is an X.509 certificate), and in parentheses,
1320
the keystore alias for the signer when the public key certificate in the
1321
JAR file matches the one in a keystore entry, for example:
1322
.IP
1323
.nf
1324
\f[CB]
1325
jarsigner -keystore $JAVA_HOME/lib/security/cacerts -verify -verbose -certs ButtonDemo.jar
1326

1327
s k     866 Tue Sep 12 20:08:48 EDT 2017 META-INF/MANIFEST.MF
1328

1329
      >>> Signer
1330
      X.509, CN=\[dq]Oracle America, Inc.\[dq], OU=Software Engineering, O=\[dq]Oracle America, Inc.\[dq], L=Redwood City, ST=California, C=US
1331
      [certificate is valid from 2017-01-30, 7:00 PM to 2018-02-01, 6:59 PM]
1332
      X.509, CN=Symantec Class 3 SHA256 Code Signing CA, OU=Symantec Trust Network, O=Symantec Corporation, C=US
1333
      [certificate is valid from 2013-12-09, 7:00 PM to 2023-12-09, 6:59 PM]
1334
      X.509, CN=VeriSign Class 3 Public Primary Certification Authority - G5, OU=\[dq](c) 2006 VeriSign, Inc. - For authorized use only\[dq], OU=VeriSign Trust Network, O=\[dq]VeriSign, Inc.\[dq], C=US (verisignclass3g5ca [jdk])
1335
      [trusted certificate]
1336
      >>> TSA
1337
      X.509, CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US
1338
      [certificate is valid from 2012-10-17, 8:00 PM to 2020-12-29, 6:59 PM]
1339
      X.509, CN=Symantec Time Stamping Services CA - G2, O=Symantec Corporation, C=US
1340
      [certificate is valid from 2012-12-20, 7:00 PM to 2020-12-30, 6:59 PM]
1341

1342
        825 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.SF
1343
       7475 Tue Sep 12 20:08:48 EDT 2017 META-INF/ORACLE_C.RSA
1344
          0 Tue Sep 12 20:07:54 EDT 2017 META-INF/
1345
          0 Tue Sep 12 20:07:16 EDT 2017 components/
1346
          0 Tue Sep 12 20:07:16 EDT 2017 components/images/
1347
smk     523 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo$1.class
1348

1349
      [entry was signed on 2017-09-12, 4:08 PM]
1350
      >>> Signer
1351
      X.509, CN=\[dq]Oracle America, Inc.\[dq], OU=Software Engineering, O=\[dq]Oracle America, Inc.\[dq], L=Redwood City, ST=California, C=US
1352
      [certificate is valid from 2017-01-30, 7:00 PM to 2018-02-01, 6:59 PM]
1353
      X.509, CN=Symantec Class 3 SHA256 Code Signing CA, OU=Symantec Trust Network, O=Symantec Corporation, C=US
1354
      [certificate is valid from 2013-12-09, 7:00 PM to 2023-12-09, 6:59 PM]
1355
      X.509, CN=VeriSign Class 3 Public Primary Certification Authority - G5, OU=\[dq](c) 2006 VeriSign, Inc. - For authorized use only\[dq], OU=VeriSign Trust Network, O=\[dq]VeriSign, Inc.\[dq], C=US (verisignclass3g5ca [jdk])
1356
      [trusted certificate]
1357
      >>> TSA
1358
      X.509, CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US
1359
      [certificate is valid from 2012-10-17, 8:00 PM to 2020-12-29, 6:59 PM]
1360
      X.509, CN=Symantec Time Stamping Services CA - G2, O=Symantec Corporation, C=US
1361
      [certificate is valid from 2012-12-20, 7:00 PM to 2020-12-30, 6:59 PM]
1362

1363
smk    3440 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.class
1364
\&...
1365
smk    2346 Tue Sep 12 20:07:16 EDT 2017 components/ButtonDemo.jnlp
1366
\&...
1367
smk     172 Tue Sep 12 20:07:16 EDT 2017 components/images/left.gif
1368
\&...
1369
smk     235 Tue Sep 12 20:07:16 EDT 2017 components/images/middle.gif
1370
\&...
1371
smk     172 Tue Sep 12 20:07:16 EDT 2017 components/images/right.gif
1372
\&...
1373

1374
  s = signature was verified
1375
  m = entry is listed in manifest
1376
  k = at least one certificate was found in keystore
1377

1378
- Signed by \[dq]CN=\[dq]Oracle America, Inc.\[dq], OU=Software Engineering, O=\[dq]Oracle America, Inc.\[dq], L=Redwood City, ST=California, C=US\[dq]
1379
    Digest algorithm: SHA-256
1380
    Signature algorithm: SHA256withRSA, 2048-bit key
1381
  Timestamped by \[dq]CN=Symantec Time Stamping Services Signer - G4, O=Symantec Corporation, C=US\[dq] on Tue Sep 12 20:08:49 UTC 2017
1382
    Timestamp digest algorithm: SHA-1
1383
    Timestamp signature algorithm: SHA1withRSA, 2048-bit key
1384

1385
jar verified.
1386

1387
The signer certificate expired on 2018-02-01. However, the JAR will be valid until the timestamp expires on 2020-12-29.
1388
\f[R]
1389
.fi
1390
.PP
1391
If the certificate for a signer isn\[aq]t an X.509 certificate, then
1392
there is no distinguished name information.
1393
In that case, just the certificate type and the alias are shown.
1394
For example, if the certificate is a PGP certificate, and the alias is
1395
\f[V]bob\f[R], then you would get: \f[V]PGP, (bob)\f[R].
1396